diff --git a/README.md b/README.md index 7bfa58ed..865651d2 100644 --- a/README.md +++ b/README.md @@ -21,41 +21,108 @@ Started in the context of the Human Cell Atlas Consortium, cellxgene hopes to bo - OS: OSX, Windows, Linux - python 3.6 - npm -- Google Chrome +- Google Chrome -**Clone project** - - git clone https://github.com/chanzuckerberg/cellxgene.git +**Clone project** + + git clone https://github.com/chanzuckerberg/cellxgene.git + +**Install client** -**Install client** - cd cellxgene - ./bin/build-client + ./bin/build-client -**To use with virtual env for python** -(optional, but recommended) - - ENV_NAME=cellxgene - python3 -m venv ${ENV_NAME} - source ${ENV_NAME}/bin/activate +**To use with virtual env for python** +(optional, but recommended) -**Install server** - - pip install -e . + ENV_NAME=cellxgene + python3 -m venv ${ENV_NAME} + source ${ENV_NAME}/bin/activate + +**Install server** + + + pip install -e . + +**Run (with demo data)** -**Run (with demo data)** - cellxgene --title PBMC3K scanpy example-dataset/ -*In google chrome, navigate to the viewer via the web address printed in your console. +*In google chrome, navigate to the viewer via the web address printed in your console. E.g.,* `Running on http://0.0.0.0:5005/` **Help** - + cellxgene --help -_For help with the scanpy engine_ - +_For help with the scanpy engine_ + cellxgene scanpy --help +## Using your own data + +### Scanpy + +To prepare your data you will need to format your data into AnnData format using scanpy and calculate PCA and nearest neighbors and save in h5ad format. + +1. [Load data into scanpy](https://scanpy.readthedocs.io/en/latest/api/index.html#reading) + + - Ensure that `obs`'s index is the cell names: `print(data.obs_names)` should show your cell indices. If it shows gene names, you may need to just call `data.transpose()`. + +2. Calculate PCA + + sc.pp.pca(data) ## sc is scanpy.api + +3. Calculate nearest neighbors (depending on layout algorithm) + + ``` + # For umap layout algorithm, you need to use the "umap" method for neighbors + sc.pp.neighbors(data, method="umap", metric="euclidean", use_rep="X_pca") + + # For tsne layout algorithm, you can use either "umap" or "gauss"; we recommend "gauss" + sc.pp.neighbors(data, method="gauss", metric="euclidean", use_rep="X_pca") + ``` + +4. Save file + + ``` + # cellxgene requires file to be named data.h5ad + data.write("data.h5ad") + ``` + +5. Create config file (optional) + + If you do not have a config file, the schema (metadata names, types, and categorical/continuous) will be inferred from the observations in the data file. Config file is required to be named 'data_schema.json' and located in the same directory as data file. + - The config file is a JSON format file with information on the metadata associated with the cells. The key is the column name in obs. The value is an object + ``` + type: string, int, or float (what type the values are), + variabletype: categorical or continuous (categorical values are displayed as checkboxes, continuous values are displayed as a histogram) + displayname: (what the heading should be displayed as) + include: True/False (whether to display values on web interface) + ``` + + ``` + Example + { + "CellName": { + "type": "string", + "variabletype": "categorical", + "displayname": "Name", + "include": true + }, + "clusters": { + "type": "string", + "variabletype": "categorical", + "displayname": "Clusters", + "include": true + }, + "num_genes": { + "type": "int", + "variabletype": "continuous", + "displayname": "Number Genes", + "include": true + } + } + ``` + ## Contributing We warmly welcome contributions from the community. Please submit any bug reports and feature requests through github issues. Please submit any direct contributions via a branch + pull request. diff --git a/client/package.json b/client/package.json index 7467ebb5..e27bbc87 100644 --- a/client/package.json +++ b/client/package.json @@ -2,6 +2,7 @@ "name": "cellxgene", "version": "0.0.1", "license": "MIT", + "description": "cellxgene is a web application for the interactive exploration of single cell sequence data.", "repository": "https://github.com/chanzuckerberg/cellxgene", "scripts": { "build": "npm run clean && webpack --config configuration/webpack/webpack.config.prod.js", @@ -29,16 +30,13 @@ "dependencies": { "canvas-fit": "^1.5.0", "d3": "^4.10.0", - "deck.gl": "^4.1.2", "express": "^4.14.0", "font-color-contrast": "^1.0.3", "gl-mat4": "^1.1.4", "gl-matrix": "^2.7.1", - "halogen": "^0.2.0", "hsv2rgb": "^1.1.0", "key-pressed": "0.0.1", "lodash": "^4.17.4", - "luma.gl": "^4.0.3", "mouse-position": "^2.0.1", "mouse-pressed": "^1.0.0", "orbit-camera": "^1.0.0", @@ -50,7 +48,6 @@ "react-hot-loader": "^3.0.0-beta.7", "react-icons": "^2.2.7", "react-redux": "^5.0.6", - "react-router-dom": "4.1.2", "redux": "^3.7.2", "redux-thunk": "^2.2.0", "regl": "^1.3.1", @@ -81,12 +78,12 @@ "cross-env": "^3.1.4", "css-loader": "^0.26.1", "css-modules-require-hook": "^4.0.1", - "enzyme": "^2.4.1", + "enzyme": "^3.3.0", "eslint": "^4.18.2", "eslint-loader": "^1.5.0", "eslint-plugin-filenames": "^1.1.0", "eslint-plugin-import": "^2.2.0", - "eslint-plugin-jsx-a11y": "^3.0.2", + "eslint-plugin-jsx-a11y": "^6.1.1", "eslint-plugin-react": "^6.0.0", "extract-text-webpack-plugin": "^2.0.0-beta.3", "file-loader": "^0.9.0", @@ -97,7 +94,8 @@ "jest": "^23.4.1", "jsdom": "^9.4.1", "json-loader": "^0.5.4", - "nyc": "^10.0.0", + "nyc": "^13.0.1", + "postcss": "^6.0.0", "postcss-loader": "^1.2.2", "promise": "^7.1.1", "react-addons-test-utils": "^15.3.0",