From 9c09ee63299179bdd03341d5ed93ea0596097626 Mon Sep 17 00:00:00 2001 From: Sidney Bell Date: Tue, 26 Nov 2019 16:09:59 -0800 Subject: [PATCH] Update readme and other repo MD files (#1063) * Update readme * Move roadmap to main docs site * Avoid duplication by just putting a pointer to the actual docs --- CONTRIBUTING.md | 50 ++-------------------------- README.md | 86 ++++++++++++++++++++++--------------------------- ROADMAP.md | 46 -------------------------- 3 files changed, 41 insertions(+), 141 deletions(-) delete mode 100644 ROADMAP.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d2e65b327..fbbc0f1e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,49 +1,3 @@ -# contributing to cellxgene +We warmly welcome contributions from the community! -We warmly welcome contributions from the community! Please submit any bug reports and feature requests through [Github issues](https://github.com/chanzuckerberg/cellxgene/issues). Please submit any direct contributions by forking the repository, creating a branch, and submitting a Pull Request. It'd be great for PRs to include test cases and documentation updates where relevant, though we know the core test suite is itself still a work in progress. - -All code contributions and dependencies must be compatible with the project's [open-source license (MIT)](LICENSE.txt). - -This project adheres to the Contributor Covenant -[code of conduct](https://github.com/chanzuckerberg/.github/tree/master/CODE_OF_CONDUCT.md). -By participating, you are expected to uphold this code. Please report unacceptable behavior -to opensource@chanzuckerberg.com. - -And finally, if you have any questions about any of this stuff, just ask! :) - -## developer guide - -This project has made a few key design choices - -- The front-end is built with [`regl`](https://github.com/regl-project/regl) (a webgl library), [`react`](https://reactjs.org/), [`redux`](https://redux.js.org/), [`d3`](https://github.com/d3/d3), and [`blueprint`](https://blueprintjs.com/docs/#core) to handle rendering large numbers of cells with lots of complex interactivity -- The app is designed with a client-server model that can support a range of existing analysis packages for backend computational tasks (currently built for [scanpy](https://github.com/theislab/scanpy)) -- The client uses fast cross-filtering to handle selections and comparisons across subsets of data - -Depending on your background and interests, you might want to contribute to the frontend, or backend, or both! - -If you are interested in working on `cellxgene` development, we recommend cloning the project from Gitub. First you'll need the following installed on your machine - -- python 3.6+ -- node and npm (we recommend using [nvm](https://github.com/creationix/nvm) if this is your first time with node) - -Then clone the project - -``` -git clone https://github.com/chanzuckerberg/cellxgene.git -``` - -Build the client web assets by calling `make` from inside the `cellxgene` folder - -``` -make -``` - -Install all requirements (we recommend doing this inside a virtual environment) - -``` -pip install -e . -``` - -You can start the app while developing either by calling `cellxgene` or by calling `python -m server`. We recommend using the `--debug` flag to see more output, which you can include when reporting bugs. - -If you have any questions about developing or contributing, come hang out with us by joining the [CZI Science Slack](https://join-cellxgene-users.herokuapp.com/) and posting in the `#cellxgene-dev` channel. +Whether you want to contribute ideas, requests, documentation, or code, you can get started by visiting our [contribution guide](https://chanzuckerberg.github.io/cellxgene/posts/contribute). diff --git a/README.md b/README.md index 6333da77b..a14284bb3 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - + _an interactive explorer for single-cell transcriptomics data_ @@ -6,48 +6,62 @@ _an interactive explorer for single-cell transcriptomics data_ cellxgene (pronounced "cell-by-gene") is an interactive data explorer for single-cell transcriptomics datasets, such as those coming from the [Human Cell Atlas](https://humancellatlas.org). Leveraging modern web development techniques to enable fast visualizations of at least 1 million cells, we hope to enable biologists and computational researchers to explore their data. - +Whether you need to visualize one thousand cells or one million, cellxgene helps you gain insight into your single-cell data. -- Want to install and use cellxgene? Visit the [cellxgene docs](https://chanzuckerberg.github.io/cellxgene/). -- Want to see where we are going? Check out [our roadmap](https://github.com/chanzuckerberg/cellxgene/blob/master/ROADMAP.md). -- Want to contribute? See our [contributors guide](https://github.com/chanzuckerberg/cellxgene/blob/master/CONTRIBUTING.md). + -## quick start +# Getting started +### The comprehensive guide to cellxgene +[The cellxgene documentation is your one-stop-shop for information about cellxgene](https://chanzuckerberg.github.io/cellxgene/)! You may be particularly interested in: +* Seeing [what cellxgene can do](https://chanzuckerberg.github.io/cellxgene/posts/gallery) +* Learning more about cellxgene [installation](https://chanzuckerberg.github.io/cellxgene/posts/install) and [usage](https://chanzuckerberg.github.io/cellxgene/posts/launch) +* [Preparing your own data](https://chanzuckerberg.github.io/cellxgene/posts/prepare) for use in cellxgene +* Checking out [our roadmap](https://chanzuckerberg.github.io/cellxgene/posts/roadmap) for future development +* [Contributing](https://chanzuckerberg.github.io/cellxgene/posts/contribute) to cellxgene -To install cellxgene you need Python 3.6+. We recommend [installing cellxgene into a conda or virtual environment.](https://chanzuckerberg.github.io/cellxgene/faq.html#how-do-i-create-a-python-36-environment-for-cellxgene) +### Quick start -Install the package. +To install cellxgene you need Python 3.6+. We recommend [installing cellxgene into a conda or virtual environment.](https://chanzuckerberg.github.io/cellxgene/posts/install) -```bash +Install the package. +``` bash pip install cellxgene ``` -Download an example [anndata](https://anndata.readthedocs.io/en/latest/) file +Launch cellxgene with an example [anndata](https://anndata.readthedocs.io/en/latest/) file -```bash -curl -O https://cellxgene-example-data.czi.technology/pbmc3k.h5ad.zip -unzip pbmc3k.h5ad +``` bash +cellxgene launch https://cellxgene-example-data.czi.technology/pbmc3k.h5ad ``` -Launch cellxgene - -```bash -cellxgene launch pbmc3k.h5ad --open -``` +To explore more datasets already formatted for cellxgene, check out the [Demo data](https://chanzuckerberg.github.io/cellxgene/posts/demo-data) or +see [Preparing your data](https://chanzuckerberg.github.io/cellxgene/posts/prepare) to learn more about formatting your own +data for cellxgene. -To learn more about what you can do with cellxgene, see the [Getting Started](https://chanzuckerberg.github.io/cellxgene/getting-started.html) guide. +### Finding help -## get in touch +We'd love to hear from you! +For questions, suggestions, or accolades, [join the `#cellxgene-users` channel on the CZI Science Slack](https://join-cellxgene-users.herokuapp.com/) and say "hi!". -Have questions, suggestions, or comments? You can come hang out with us by joining the [CZI Science Slack](https://join-cellxgene-users.herokuapp.com/) and posting in the `#cellxgene-users` channel. Have feature requests or bugs? Please submit these as [Github issues](https://github.com/chanzuckerberg/cellxgene/issues). We'd love to hear from you! +For any errors, [report bugs on Github](https://github.com/chanzuckerberg/cellxgene/issues). -## contributing +# Developing with cellxgene -We warmly welcome contributions from the community! Please see our [contributing guide](https://github.com/chanzuckerberg/cellxgene/blob/master/CONTRIBUTING.md) and don't hesitate to open an issue or send a pull request to improve cellxgene. +### Contributing +We warmly welcome contributions from the community! Please see our [contributing guide](https://chanzuckerberg.github.io/cellxgene/posts/contribute) and don't hesitate to open an issue or send a pull request to improve cellxgene. This project adheres to the Contributor Covenant [code of conduct](https://github.com/chanzuckerberg/.github/blob/master/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com. -## core team +### Reuse + +This project was started with the sole goal of empowering the scientific community to explore and understand their data. As such, we encourage other scientific tool builders in academia or industry to adopt the patterns, tools, and code from this project, and reach out to us with ideas or questions. All code is freely available for reuse under the [MIT license](https://opensource.org/licenses/MIT). + +### Security + +If you believe you have found a security issue, we would appreciate notification. Please send email to . + +# About +### Core team The current core team: @@ -61,21 +75,7 @@ We would also like to gratefully acknowledge contributions from past core team m - Charlotte Weaver, software engineer -## where we are going - -Our goal is to enable teams of computational and experimental -biologists to collaboratively gain insight into their single-cell RNA-seq data. - -There are 4 key features we plan to implement in the near term. - -- Click install and launch -- Manual annotation workflows -- Toggle embeddings -- Gene information - -For more detail on these features and where we are going, see [our roadmap](https://github.com/chanzuckerberg/cellxgene/blob/master/ROADMAP.md). - -## inspiration +### Inspiration We've been heavily inspired by several other related single-cell visualization projects, including the [UCSC Cell Browswer](http://cells.ucsc.edu/), [Cytoscape](http://www.cytoscape.org/), [Xena](https://xena.ucsc.edu/), [ASAP](https://asap.epfl.ch/), [Gene Pattern](http://genepattern-notebook.org/), and many others. We hope to explore collaborations where useful as this community works together on improving interactive visualization for single-cell data. @@ -84,11 +84,3 @@ We were inspired by Mike Bostock and the [crossfilter](https://github.com/crossf We have been working closely with the [scanpy](https://github.com/theislab/scanpy) team to integrate with their awesome analysis tools. Special thanks to Alex Wolf, Fabian Theis, and the rest of the team for their help during development and for providing an example dataset. We are eager to explore integrations with other computational backends such as [Seurat](https://github.com/satijalab/seurat) or [Bioconductor](https://github.com/Bioconductor) - -## reuse - -This project was started with the sole goal of empowering the scientific community to explore and understand their data. As such, we encourage other scientific tool builders in academia or industry to adopt the patterns, tools, and code from this project, and reach out to us with ideas or questions. All code is freely available for reuse under the [MIT license](https://opensource.org/licenses/MIT). - -## security - -If you believe you have found a security issue, we would appreciate notification. Please send email to . diff --git a/ROADMAP.md b/ROADMAP.md deleted file mode 100644 index b56987e43..000000000 --- a/ROADMAP.md +++ /dev/null @@ -1,46 +0,0 @@ -# cellxgene roadmap - -cellxgene makes it easier for biologists to collaboratively explore and understand their single-cell RNA-seq data. -In the near term, we are focused on continuing to enable fast, interactive exploration of single-cell data, supporting collaborative workflows in single-cell analysis, and improving user support. -If you have questions or feedback about this roadmap, please submit an issue on GitHub. -Please note: this roadmap is subject to change. - -Last updated: June 25, 2019 - -## Fast, interactive exploration of single-cell data - -### Exposing Relationships Between Metadata and Data -Biologists need to understand how variables (stored in metadata) are associated with one another and how they relate to changes in gene expression. -Building upon visualization features that reveal categorical metadata relationships (cluster occupancy) and gene expression relationships (scatterplot), we plan to add exploratory visualization components that enable investigation of relationships between metadata and gene expression. -See [issue #616](https://github.com/chanzuckerberg/cellxgene/issues/616) for more details. - -### Contextualizing Genes -While exploring a transcriptomics dataset, scientists need to understand the biological context of genes. -This context may be provided by user-defined gene metadata or publicly available gene databases. -We plan to support augmenting gene names with additional information that is useful to biologists. -See [issue #96](https://github.com/chanzuckerberg/cellxgene/issues/96) for more detail. - -## Support collaborative workflows in single-cell analysis - -### Manual Annotations -cellxgene offers exploratory visualizations that are critical for manual annotation workflows, especially in collaborative environments. -We plan to support manually annotating cells with labels (i.e., cell type or QC flags), and their easy export for downstream analysis. -See [issue #524](https://github.com/chanzuckerberg/cellxgene/issues/524) for more details. - -### Simple Click to Launch - -Many biologists prefer not to interact with the command line and need an OS-native experience when using cellxgene. -We plan to implement a point-and-click installation and launch experience so that users can easily load data into cellxgene. -See [issue #687](https://github.com/chanzuckerberg/cellxgene/issues/687) for details. - -### Python API -For computational biologists, saving h5ad files then loading them into cellxgene is a point of friction. -We plan to support importing cellxgene as a Python package so that users can launch cellxgene directly from an interactive environment (such as Jupyter, IPython, or Spyder), and pass data to and from the cellxgene UI. - -## Improving user support - -### Improved documentation -cellxgene has some specific expectations about how data is stored. -We want to ensure that new users can get started easily and learn how to use cellxgene with their own data. -We plan to improve documentation on getting started, installation, data, and contributing. -See [issue #533](https://github.com/chanzuckerberg/cellxgene/issues/533) for more details.