{"id":29625196,"url":"https://github.com/novartis/cellxgene-gateway","last_synced_at":"2025-07-21T06:07:37.891Z","repository":{"id":37243575,"uuid":"204782560","full_name":"Novartis/cellxgene-gateway","owner":"Novartis","description":"Cellxgene Gateway allows you to use the Cellxgene Server provided by the Chan Zuckerberg Institute (https://github.com/chanzuckerberg/cellxgene) with multiple datasets.","archived":false,"fork":false,"pushed_at":"2024-03-10T13:36:17.000Z","size":208,"stargazers_count":64,"open_issues_count":13,"forks_count":34,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-07-20T05:47:33.790Z","etag":null,"topics":["dataviz","h5ad","rna-seq","scientific","scrna-seq","transcriptomics","visualization"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Novartis.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-27T20:12:25.000Z","updated_at":"2025-05-06T17:56:52.000Z","dependencies_parsed_at":"2023-01-30T16:05:13.035Z","dependency_job_id":"d39af4d9-521b-4231-81fb-c113a05ac958","html_url":"https://github.com/Novartis/cellxgene-gateway","commit_stats":{"total_commits":187,"total_committers":14,"mean_commits":"13.357142857142858","dds":"0.49732620320855614","last_synced_commit":"9d10932b069037b0868b1718e616b1c21b2fcd07"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/Novartis/cellxgene-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Novartis%2Fcellxgene-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Novartis%2Fcellxgene-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Novartis%2Fcellxgene-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Novartis%2Fcellxgene-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Novartis","download_url":"https://codeload.github.com/Novartis/cellxgene-gateway/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Novartis%2Fcellxgene-gateway/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266248501,"owners_count":23899056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dataviz","h5ad","rna-seq","scientific","scrna-seq","transcriptomics","visualization"],"created_at":"2025-07-21T06:07:36.820Z","updated_at":"2025-07-21T06:07:37.875Z","avatar_url":"https://github.com/Novartis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Overview\n\nCellxgene Gateway allows you to use the Cellxgene Server provided by the Chan Zuckerberg Institute (https://github.com/chanzuckerberg/cellxgene) with multiple datasets. It displays an index of available h5ad (anndata) files. When a user clicks on a file name, it launches a Cellxgene Server instance that loads that particular data file and once it is available  proxies requests to that server.\n\n[![codecov](https://codecov.io/gh/Novartis/cellxgene-gateway/branch/master/graph/badge.svg?token=ndEFSzRKJn)](https://codecov.io/gh/Novartis/cellxgene-gateway) [![PyPI](https://img.shields.io/pypi/v/cellxgene-gateway)](https://pypi.org/project/cellxgene-gateway/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/cellxgene-gateway)](https://pypistats.org/packages/cellxgene-gateway)\n\n# Running locally\n\n## Prequisites\n\n1. This project requires python 3.6 or higher. Please check your version with\n\n```bash\n$ python --version\n```\n\n2. It is also a good idea to set up a venv\n\n```bash\npython -m venv .cellxgene-gateway\nsource .cellxgene-gateway/bin/activate # type `deactivate` to deactivate the venv\n```\n\n## Install cellxgene-gateway\n\n### Option 1: Pip Install from Github\n\n```bash\npip install git+https://github.com/Novartis/cellxgene-gateway\n```\nNote: you may need to downgrade h5py with `pip install h5py==2.9.0` due to an [issue](https://github.com/theislab/scanpy/issues/832) in a dependency.\n### Option 2: Install from PyPI\n\n```bash\npip install cellxgene-gateway\n```\n\n## Running cellxgene gateway\n\n1. Prepare a folder with .h5ad files, for example\n\n```bash\nmkdir ../cellxgene_data\nwget https://raw.githubusercontent.com/chanzuckerberg/cellxgene/master/example-dataset/pbmc3k.h5ad -O ../cellxgene_data/pbmc3k.h5ad\n```\n\n\n2. Set your environment variables correctly:\n\n```bash\nexport CELLXGENE_DATA=../cellxgene_data  # change this directory if you put data in a different place.\nexport CELLXGENE_LOCATION=`which cellxgene`\n```\n\n3. Now, execute the cellxgene gateway:\n\n```bash\ncellxgene-gateway\n```\n\nHere's what the environment variables mean:\n\n* `CELLXGENE_LOCATION` - the location of the cellxgene executable, e.g. `~/anaconda2/envs/cellxgene/bin/cellxgene`\n\nAt least one of the following is required:\n* `CELLXGENE_DATA` - a directory that can contain subdirectories with `.h5ad` data files, *without* trailing slash, e.g. `/mnt/cellxgene_data`\n* `CELLXGENE_BUCKET` - an s3 bucket that can contain keys with `.h5ad` data files, e.g. `my-cellxgene-data-bucket`\nCellxgene Gateway is designed to make it easy to add additional data sources, please see the source code for gateway.py and the ItemSource interface in items/item_source.py\n\nOptional environment variables:\n* `CELLXGENE_ARGS` - catch-all variable that can be used to pass additional command line args to cellxgene server\n* `EXTERNAL_HOST` - the hostname and port from the perspective of the web browser, typically `localhost:5005` if running locally. Defaults to \"localhost:{GATEWAY_PORT}\"\n* `EXTERNAL_PROTOCOL` - typically http when running locally, can be https when deployed if the gateway is behind a load balancer or reverse proxy that performs https termination. Default value \"http\"\n* `GATEWAY_IP` - ip addess of instance gateway is running on, mostly used to display SSH instructions. Defaults to `socket.gethostbyname(socket.gethostname())`\n* `GATEWAY_PORT` - local port that the gateway should bind to, defaults to 5005\n* `GATEWAY_EXPIRE_SECONDS` - time in seconds that a cellxgene process will remain idle before being terminated. Defaults to 3600 (one hour)\n* `GATEWAY_EXTRA_SCRIPTS` - JSON array of script paths, will be embedded into each page and forwarded with `--scripts` to cellxgene server\n* `GATEWAY_ENABLE_ANNOTATIONS` - Set to `true` or to `1` to enable cellxgene annotations and gene sets.\n* `GATEWAY_ENABLE_BACKED_MODE` - Set to `true` or to `1` to load AnnData in file-backed mode. This saves memory and speeds up launch time but may reduce overall performance.\n* `GATEWAY_LOG_LEVEL` - default is `INFO`. set to `DEBUG` to increase logging and to `WARNING` to decrease logging.\n* `S3_ENABLE_LISTINGS_CACHE` - Set to `true` or to `1` to cache listings of S3 folders for performance. If the cache becomes stale, set `filecrawl.html?refresh=true` query parameter to refresh the cache.\n\nIf any of the following optional variables are set, [ProxyFix](https://werkzeug.palletsprojects.com/en/1.0.x/middleware/proxy_fix/) will be used.\n* `PROXY_FIX_FOR` - Number of upstream proxies setting X-Forwarded-For\n* `PROXY_FIX_PROTO` - Number of upstream proxies setting X-Forwarded-Proto\n* `PROXY_FIX_HOST` - Number of upstream proxies setting X-Forwarded-Host\n* `PROXY_FIX_PORT` - Number of upstream proxies setting X-Forwarded-Port\n* `PROXY_FIX_PREFIX` - Number of upstream proxies setting X-Forwarded-Prefix\n\nThe defaults should be fine if you set up a venv and cellxgene_data folder as above.\n\n## Running cellxgene-gateway with Docker\n\nFirst, build Docker image:\n\n```bash\ndocker build -t cellxgene-gateway .\n```\n\nThen, cellxgene-gateway can be launched as such:\n\n```bash\ndocker run -it --rm \\\n-v \u003clocal_data_dir\u003e:/cellxgene-data \\\n-p 5005:5005 \\\ncellxgene-gateway\n```\n\nAdditional environment variables can be provided with the `-e` parameter:\n\n```bash\ndocker run -it --rm \\\n-v ../cellxgene_data:/cellxgene-data \\\n-e GATEWAY_PORT=8080 \\\n-p 8080:8080 \\\ncellxgene-gateway\n```\n\n# Customization\n\nThe current paradigm for customization is to modify files during a build or deployment phase:\n\n* To modify CSS or JS on particular gateway pages, overwrite or append to the templates\n* To add script tags such as for user analytics to all pages, set GATEWAY_EXTRA_SCRIPTS\n  * these scripts will also be run on the pages served by cellxgene server via the --scripts parameter\n  * See https://github.com/chanzuckerberg/cellxgene/pull/680 for details on --scripts parameter\n\nCurrently we use a bash script that copies the gateway to a \"build\" directory before modifying templates with sed and the like. There is probably a better way.\n\n# Development\n\nWe’re actively developing.  Please see the \"future work\" section of the [wiki](https://github.com/Novartis/cellxgene-gateway/wiki#future-work). If you’re interested in being a contributor please reach out to [@alokito](https://github.com/alokito).\n\n## Developer Install\n\nIf you want to develop the code, you will need to clone the repo. Make sure you have the prequesite listed above, then:\n\n1. Clone the repo\n\n```bash\n    git clone https://github.com/Novartis/cellxgene-gateway.git\n    cd cellxgene-gateway\n```\n\n2. Install requirements with\n\n```bash\npip install -r requirements.txt\n```\n\n3. Install the gateway in developer mode\n\n```bash\npython setup.py develop\n```\n\nFor convenience, the code repo includes a `run.sh.example` shell script to run the gateway.\n\n4. Install pre-commit hooks\n\n```bash\nconda install -c conda-forge pre-commit\npre-commit install\n```\n\n\n## Running Tests\n\n[![Build Status](https://travis-ci.org/Novartis/cellxgene-gateway.svg?branch=master)](https://travis-ci.org/Novartis/cellxgene-gateway)\n\n```bash\n    python -m unittest discover tests\n```\n\n## Code Coverage\n```bash\n    coverage run -m unittest discover tests\n    coverage html\n```\n\n## Running Linters\n\npip install isort flake8 black\n\n```bash\nisort -rc . # rc means recursive, and was deprecated in dev version of isort\nblack .\n```\n\n# Getting Help\n\nIf you need help for any reason, please make a github ticket. One of the contributors should help you out.\n\n# Releasing New Versions\n\n## How to prepare for release\n\n- Update Changelog.md and version number in __init__.py\n- Cut a release on github\n\t- Go to your project homepage on GitHub\n\t- On right side, you will see [Releases](https://github.com/Novartis/cellxgene-gateway/releases) link. Click on it.\n\t- Click on Draft a new release\n\t- Fill in all the details\n\t\t- Tag version should be the version number of your package release\n\t\t- Release Title can be anything you want, but we use v0.3.11 (the same as the tag to be created on publish)\n\t\t- Description should be changelog\n\t- Click Publish release at the bottom of the page\n\t- Now under Releases you can view all of your releases.\n\t- Copy the download link (tar.gz) and save it somewhere\n\n## How to publish to PyPI\n\nMake sure your `.pypirc` is set up for testpypi and pypi index servers.\n \n\n```bash\nrm -rf dist\npython setup.py sdist bdist_wheel\npython -m twine upload --repository testpypi dist/*\npython -m twine upload dist/*\n```\n\n# Contributors\n\n* Niket Patel - https://github.com/NiketPatel9\n* Alok Saldanha - https://github.com/alokito\n* Yohann Potier - https://github.com/ypotier\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnovartis%2Fcellxgene-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnovartis%2Fcellxgene-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnovartis%2Fcellxgene-gateway/lists"}