README.md 6.13 KB
Newer Older
1
# Overview
Alok Saldanha's avatar
Alok Saldanha committed
2
3
4

Cellxgene 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.

5
# Running locally
Alok Saldanha's avatar
Alok Saldanha committed
6

7
## Prequisites
Eric Ma's avatar
Eric Ma committed
8

9
1. This project requires python 3.6 or higher. Please check your version with
Alokito's avatar
Alokito committed
10

11
12
13
```bash
$ python --version
```
Alokito's avatar
Alokito committed
14

15
2. It is also a good idea to set up a venv
16
17

```bash
Alokito's avatar
Alokito committed
18
python -m venv .cellxgene-gateway
19
source .cellxgene-gateway/bin/activate # type `deactivate` to deactivate the venv
Alokito's avatar
Alokito committed
20
```
21

22
## Install cellxgene-gateway
23

Alokito's avatar
Alokito committed
24
### Option 1: Pip Install from Github
Eric Ma's avatar
Eric Ma committed
25
26

```bash
27
pip install git+https://github.com/Novartis/cellxgene-gateway
Eric Ma's avatar
Eric Ma committed
28
```
Alok Saldanha's avatar
Alok Saldanha committed
29
Note: 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.
Alokito's avatar
Alokito committed
30
### Option 2: Install from PyPI
Eric Ma's avatar
Eric Ma committed
31
32

```bash
Alok Saldanha's avatar
Alok Saldanha committed
33
pip install cellxgene-gateway
Eric Ma's avatar
Eric Ma committed
34
35
```

36
37
## Running cellxgene gateway

38
39
40
41
1. Prepare a folder with .h5ad files, for example

```bash
mkdir ../cellxgene_data
42
wget https://raw.githubusercontent.com/chanzuckerberg/cellxgene/master/example-dataset/pbmc3k.h5ad -O ../cellxgene_data/pbmc3k.h5ad
43
44
45
46
```


2. Set your environment variables correctly:
47
48

```bash
Eric Ma's avatar
Eric Ma committed
49
export CELLXGENE_DATA=../cellxgene_data  # change this directory if you put data in a different place.
50
export CELLXGENE_LOCATION=`which cellxgene`
Alokito's avatar
Alokito committed
51
```
52

53
3. Now, execute the cellxgene gateway:
Alok Saldanha's avatar
Alok Saldanha committed
54

Eric Ma's avatar
Eric Ma committed
55
56
57
```bash
cellxgene-gateway
```
Alok Saldanha's avatar
Alok Saldanha committed
58

Eric Ma's avatar
Eric Ma committed
59
60
61
Here's what the environment variables mean:

* `CELLXGENE_LOCATION` - the location of the cellxgene executable, e.g. `~/anaconda2/envs/cellxgene/bin/cellxgene`
62
63

At least one of the following is required:
Eric Ma's avatar
Eric Ma committed
64
* `CELLXGENE_DATA` - a directory that can contain subdirectories with `.h5ad` data files, *without* trailing slash, e.g. `/mnt/cellxgene_data`
65
66
* `CELLXGENE_BUCKET` - an s3 bucket that can contain keys with `.h5ad` data files, e.g. `my-cellxgene-data-bucket`
Cellxgene 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
67

68
Optional environment variables:
69
* `CELLXGENE_ARGS` - catch-all variable that can be used to pass additional command line args to cellxgene server
70
71
72
73
* `EXTERNAL_HOST` - the hostname and port from the perspective of the web browser, typically `localhost:5005` if running locally. Defaults to "localhost:{GATEWAY_PORT}"
* `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"
* `GATEWAY_IP` - ip addess of instance gateway is running on, mostly used to display SSH instructions. Defaults to `socket.gethostbyname(socket.gethostname())`
* `GATEWAY_PORT` - local port that the gateway should bind to, defaults to 5005
74
* `GATEWAY_EXTRA_SCRIPTS` - JSON array of script paths, will be embedded into each page and forwarded with `--scripts` to cellxgene server
75
* `GATEWAY_ENABLE_ANNOTATIONS` - Set to `true` or to `1` to enable cellxgene annotations. 
76
77
78
79
80
81
82
83
* `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.

If any of the following optional variables are set, [ProxyFix](https://werkzeug.palletsprojects.com/en/1.0.x/middleware/proxy_fix/) will be used.
* `PROXY_FIX_FOR` - Number of upstream proxies setting X-Forwarded-For
* `PROXY_FIX_PROTO` - Number of upstream proxies setting X-Forwarded-Proto
* `PROXY_FIX_HOST` - Number of upstream proxies setting X-Forwarded-Host
* `PROXY_FIX_PORT` - Number of upstream proxies setting X-Forwarded-Port
* `PROXY_FIX_PREFIX` - Number of upstream proxies setting X-Forwarded-Prefix
Eric Ma's avatar
Eric Ma committed
84
85

The defaults should be fine if you set up a venv and cellxgene_data folder as above.
86
87

# Customization
Alok Saldanha's avatar
Alok Saldanha committed
88
89
90
91

The current paradigm for customization is to modify files during a build or deployment phase:

* To modify CSS or JS on particular gateway pages, overwrite or append to the templates
Alok Saldanha's avatar
Alok Saldanha committed
92
* To add script tags such as for user analytics to all pages, set GATEWAY_EXTRA_SCRIPTS
Alok Saldanha's avatar
Alok Saldanha committed
93
94
95
  * these scripts will also be run on the pages served by cellxgene server via the --scripts parameter
  * See https://github.com/chanzuckerberg/cellxgene/pull/680 for details on --scripts parameter

Alok Saldanha's avatar
Alok Saldanha committed
96
Currently 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.
Alok Saldanha's avatar
Alok Saldanha committed
97

Eric Ma's avatar
Eric Ma committed
98
# Development
Alok Saldanha's avatar
Alok Saldanha committed
99

100
101
We’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).

102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
## Developer Install

If you want to develop the code, you will need to clone the repo. Make sure you have the prequesite listed above, then:

1. Clone the repo

```bash
    git clone https://github.com/Novartis/cellxgene-gateway.git
    cd cellxgene-gateway
```

2. Install requirements with

```bash
pip install -r requirements.txt
```

3. Install the gateway in developer mode

```bash
python setup.py develop
```

For convenience, the code repo includes a `run.sh.example` shell script to run the gateway.

127
128
129
130
131
132
133
134
4. Install pre-commit hooks

```bash
conda install -c conda-forge pre-commit
pre-commit install
```


Alok Saldanha's avatar
Alok Saldanha committed
135
136
## Running Tests

Alokito's avatar
Alokito committed
137
138
[![Build Status](https://travis-ci.org/Novartis/cellxgene-gateway.svg?branch=master)](https://travis-ci.org/Novartis/cellxgene-gateway)

Alok Saldanha's avatar
Alok Saldanha committed
139
140
141
142
```bash
    python -m unittest discover tests
```

143
144
145
146
147
148
## Code Coverage
```bash
    coverage run -m unittest discover tests
    coverage html
```

Eric Ma's avatar
Eric Ma committed
149
## Running Linters
Alok Saldanha's avatar
Alok Saldanha committed
150
151
152

pip install isort flake8 black

Eric Ma's avatar
Eric Ma committed
153
```bash
154
155
isort -rc . # rc means recursive, and was deprecated in dev version of isort
black .
Alok Saldanha's avatar
Alok Saldanha committed
156
157
```

Eric Ma's avatar
Eric Ma committed
158
# Getting Help
Alok Saldanha's avatar
Alok Saldanha committed
159
160
161

If you need help for any reason, please make a github ticket. One of the contributors should help you out.

Eric Ma's avatar
Eric Ma committed
162
# Contributors
Alok Saldanha's avatar
Alok Saldanha committed
163
164
165
166

* Niket Patel - https://github.com/NiketPatel9
* Alok Saldanha - https://github.com/alokito
* Yohann Potier - https://github.com/ypotier