From 014b6d3a60503cc126f865d31f28c8eb964add55 Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 18:05:28 +0000 Subject: [PATCH 01/12] docs update --- README.md | 44 ++++++++++++---------------- docs/source/index.rst | 11 ++++--- docs/source/modules/installation.rst | 13 ++++++-- 3 files changed, 35 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 766e593..00bfc60 100644 --- a/README.md +++ b/README.md @@ -2,37 +2,29 @@ This codebase contains the Python client library for using Cellarium Cell Annotation Service (CAS). # Installation +The cellarium-cas package officially supports Python versions between 3.7 and 3.10. We recommend using Python 3.10. +You can install CAS from PyPI using `pip`. To install the latest version, please run the following command: ``` $ pip install cellarium-cas ``` -# Usage -To use Cellarium CAS, create a client instance with your API token: - -```python3 -from cellarium.cas import CASClient - -api_token = "a_very_long_string_with_some_symbols" -cas = CASClient( - api_token=api_token, - api_url="" -) +To install a specific version `version_number`, you can use the following command: ``` - -## Annotation -You can annotate 10x Cell Ranger h5 matrices from local disk: -```python3 - -response = cas.annotate_10x_h5_file(filepath="your_path_to_local_h5_file.h5") +$ pip install cellarium-cas== ``` -or an anndata file from local disk: -```python3 -response = cas.annotate_anndata_file(filepath="your_path_to_local_h5_file.h5ad") +If you wish to use visualization features, you can install the package with the visualization extras: +``` +$ pip install cellarium-cas[vis] ``` -or a previously loaded (unnormalized) anndata object: -```python3 -import anndata +# Obtaining an API Token +You need an API token to use CAS. We are offerring a free public beta for a limited time to try CAS and explore ways it can enhance your cell biology research. To obtain your unique API token to join the public beta release, please navigate to [https://cellarium.ai/tool/cellarium-cell-annotation-service-cas/](cellarium.ai), scroll to the bottom of the page, and [sign up](https://cellarium.ai/cell-annotation-service-cas-access/). We will contact you shortly as soon as the public beta is available with your unique API key. -adata = anndata.read("you_anndata_file.h5ad") -response = cas.annotate_anndata(adata) -``` +# Quickstart Tutorial +The fastest way to get started with using CAS is to follow the quickstart tutorial: +[Click here to open the quickstart tutorial on GitHub](notebooks/quickstart_tutorial.ipynb) + +It is even easier to go through the quickstart tutorial on Google Colab. Remember, you still need an API key to successfully run through the tutorial: +[Click here to open the quickstart tutorial on Google Colab](https://colab.research.google.com/drive/1m9zgqP5n7E4pGGCg5RjfvlCnS6uqUdSa) + +# Documentation +Please visit the project's [ReadTheDocs page](https://cellarium-cas.readthedocs.io/) for additional documentation. diff --git a/docs/source/index.rst b/docs/source/index.rst index 4a6e28c..880ebcc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,7 +4,9 @@ Cellarium Cell Annotation Service ################################# -**What's Cell Annotation Service (CAS)?** CAS is a software library for rapid querying of single-cell omics data relying on ML algorithms. +**What is Cell Annotation Service (CAS)?** CAS is a cloud-native software for rapid querying of single-cell omics data leveraging information-rich and compact vector representations and approximate nearest neighbor search engienes. This documentation refers to the client library for CAS, which provides a simple interface for querying the CAS backend and visualizing the results. + +**Hoes does CAS work?** CAS leverages a vast repository of public single-cell data, enriched with metadata such as cell type, disease, tissue, etc. to provide robust annotations for newly generated datasets. As more reference data becomes available and added to the Cellarium DataStore, CAS aims to contextualize new datasets against this accumulated knowledge, addressing a critical bottleneck in single-cell analysis. This approach is akin to how search engines have indexed and made vast amounts of internet data findable and easily accessible. Understanding the mechanisms underlying diseases critically depends on identifying similarities and differences between cellular measurements in various contexts. CAS simplifies this process by identifying similar reference cells and then providing streamlined, community-consensus annotations directly based the context of each queried cell. .. toctree:: :maxdepth: 1 @@ -23,7 +25,8 @@ Cellarium Cell Annotation Service automodules/visualization -Other Tools -=========== - * `Machine Learning library Cellarium ML `_ +Related Projects +================ + * `Cellarium ML Library `_ + * `Cellarium Cloud (Backend) `_ diff --git a/docs/source/modules/installation.rst b/docs/source/modules/installation.rst index 9cb35db..2c8268d 100644 --- a/docs/source/modules/installation.rst +++ b/docs/source/modules/installation.rst @@ -8,12 +8,19 @@ Prerequisites The cellarium-cas package officially supports Python versions between 3.7 and 3.10. We recommend using Python 3.10. -From github repository -++++++++++++++++++++++ +From PyPI repository +++++++++++++++++++++ -Install the latest alpha version using `pip` with a specified version: +Install the latest version using `pip` with a specified version: .. code-block:: bash :substitutions: pip install cellarium-cas==|version| + +If you wish to use visualization features, you can install the package with the visualization extras: + +.. code-block:: bash + :substitutions: + + pip install cellarium-cas[vis]==|version| From 07b63480c849646f11174203e53053a90f2418ad Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 19:13:53 +0000 Subject: [PATCH 02/12] add logo to readme --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 00bfc60..e3af45f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# Cellarium Cell Annotation Service (CAS) Client +![Cellarium Logo](https://cellarium.ai/wp-content/uploads/2024/07/cellarium-logo-medium.png) +# Cellarium Cell Annotation Service (CAS) Client Library This codebase contains the Python client library for using Cellarium Cell Annotation Service (CAS). # Installation @@ -17,7 +18,7 @@ $ pip install cellarium-cas[vis] ``` # Obtaining an API Token -You need an API token to use CAS. We are offerring a free public beta for a limited time to try CAS and explore ways it can enhance your cell biology research. To obtain your unique API token to join the public beta release, please navigate to [https://cellarium.ai/tool/cellarium-cell-annotation-service-cas/](cellarium.ai), scroll to the bottom of the page, and [sign up](https://cellarium.ai/cell-annotation-service-cas-access/). We will contact you shortly as soon as the public beta is available with your unique API key. +You need an API token to use CAS. We are offerring a free public beta for a limited time to try CAS and explore ways it can enhance your cell biology research. To obtain your unique API token to join the public beta release, please navigate to [cellarium.ai](https://cellarium.ai/tool/cellarium-cell-annotation-service-cas/), scroll to the bottom of the page, and [sign up](https://cellarium.ai/cell-annotation-service-cas-access/). We will contact you shortly as soon as the public beta is available with your unique API key. # Quickstart Tutorial The fastest way to get started with using CAS is to follow the quickstart tutorial: From b5269cc90f98c505bd67535b798adfcbc6feee67 Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 19:15:03 +0000 Subject: [PATCH 03/12] add logo to readme (html) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e3af45f..8f73a55 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Cellarium Logo](https://cellarium.ai/wp-content/uploads/2024/07/cellarium-logo-medium.png) +Cellarium Logo # Cellarium Cell Annotation Service (CAS) Client Library This codebase contains the Python client library for using Cellarium Cell Annotation Service (CAS). From cd9fc5dc866e558af0bb5c452cf7cdf42a7777ae Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 19:15:58 +0000 Subject: [PATCH 04/12] logo size --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8f73a55..af02883 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -Cellarium Logo +Cellarium Logo + # Cellarium Cell Annotation Service (CAS) Client Library This codebase contains the Python client library for using Cellarium Cell Annotation Service (CAS). From 80914a57440a5613b551d91920bcc031f0eb04d7 Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 20:07:22 +0000 Subject: [PATCH 05/12] update docs --- README.md | 2 +- docs/source/conf.py | 19 ++++++++++++-- docs/source/index.rst | 37 ++++++++++++++++++++++++---- docs/source/modules/installation.rst | 12 +++++++-- docs/source/modules/usage.rst | 11 +++++---- requirements/docs.txt | 3 ++- 6 files changed, 68 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index af02883..45f4a49 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ $ pip install cellarium-cas[vis] ``` # Obtaining an API Token -You need an API token to use CAS. We are offerring a free public beta for a limited time to try CAS and explore ways it can enhance your cell biology research. To obtain your unique API token to join the public beta release, please navigate to [cellarium.ai](https://cellarium.ai/tool/cellarium-cell-annotation-service-cas/), scroll to the bottom of the page, and [sign up](https://cellarium.ai/cell-annotation-service-cas-access/). We will contact you shortly as soon as the public beta is available with your unique API key. +You need an API token to use CAS. We are offerring a free public beta program for a limited time to try CAS and explore ways it can enhance your cell biology research. To obtain your unique API token to join the public beta program, please navigate to the CAS webpage at [cellarium.ai](https://cellarium.ai/tool/cellarium-cell-annotation-service-cas/), scroll to the bottom of the page, and [sign up](https://cellarium.ai/cell-annotation-service-cas-access/). We will contact you with your unique API key as soon as the public beta is available. # Quickstart Tutorial The fastest way to get started with using CAS is to follow the quickstart tutorial: diff --git a/docs/source/conf.py b/docs/source/conf.py index 960425f..5ea90b0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -2,6 +2,9 @@ # # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import os +import shutil +import glob import time from setuptools_git_versioning import get_tag @@ -10,8 +13,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = "Cellarium CAS" -copyright = f"{time.strftime('%Y')}, Cellarium AI" -author = "Cellarium AI" +copyright = f"{time.strftime('%Y')}, Cellarium AI Lab" +author = "Cellarium AI Lab" version = get_tag() or "" release = get_tag() or "" @@ -19,6 +22,10 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ + 'nbsphinx', + 'sphinx.ext.mathjax', + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', "sphinx_rtd_theme", "sphinx.ext.autodoc", "sphinx.ext.napoleon", @@ -28,6 +35,8 @@ "sphinxcontrib.autodoc_pydantic", ] +exclude_patterns = ['_build', '**.ipynb_checkpoints'] + # Provide substitutions for common values rst_prolog = f""" .. |project| replace:: {project} @@ -60,3 +69,9 @@ # The JSON schema is a bit much in the docs autodoc_pydantic_model_show_json = False + +if not os.path.exists("notebooks"): + os.makedirs("notebooks") + +for src_file in glob.glob("../../notebooks/*.ipynb"): + shutil.copy(src_file, "notebooks/") diff --git a/docs/source/index.rst b/docs/source/index.rst index 880ebcc..89039b2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,22 +1,49 @@ :tocdepth: 3 -Cellarium Cell Annotation Service -################################# +Cellarium Cell Annotation Service (CAS) Documentation +##################################################### -**What is Cell Annotation Service (CAS)?** CAS is a cloud-native software for rapid querying of single-cell omics data leveraging information-rich and compact vector representations and approximate nearest neighbor search engienes. This documentation refers to the client library for CAS, which provides a simple interface for querying the CAS backend and visualizing the results. +Overview +++++++++ + +**What is the Cell Annotation Service (CAS)?** +The Cell Annotation Service (CAS) is a cloud-native platform designed for rapid and efficient querying of single-cell omics data. It utilizes compact and information-rich vector representations combined with approximate nearest neighbor search engines to enable seamless exploration of vast single-cell datasets. This documentation focuses on the CAS client library, which offers a user-friendly interface for querying the CAS backend and visualizing the results. + +**Hows does CAS work?** +CAS operates by building a vector search index derived from low-dimensional embeddings of a comprehensive repository of publicly available single-cell transcriptomics data. Currently, the CAS reference dataset comprises the entire `CZI CELLxGENE `_ data catalog. This reference database includes rich metadata such as cell type, disease state, tissue origin, and more. In future iterations, the reference catalog will be expanded to incorporate additional datasets. + +When a user queries CAS with their single-cell transcriptomics data, the system maps the input data into the same vector space as the reference dataset. It then performs an approximate nearest neighbor search to identify similar cells within the reference database. Based on these similar reference cells, CAS generates label summary statistics, providing comprehensive annotations for each query cell. The methodology employed by CAS is comparable to how inverse search engines (such as image search techniques) index and retrieve information from vast amounts of internet data, making it accessible and interpretable. The embeddings used by CAS are generated using distributed machine learning models implemented in the `Cellarium ML Library `_ + +Understanding the similarities and differences between cellular measurements in various contexts is crucial for unraveling disease mechanisms. CAS streamlines this process by leveraging its reference context to provide community-consensus annotations for the queried cells, helping researchers gain deeper insights into their data. + +Funding ++++++++ + +Cellarium CAS was co-developed by 10x Genomics and Cellarium AI Lab at the Data Sciences Platform, Broad Institute. The project was funded by 10x Genomics, NIH Grant UM1 MH130966, and additional support from Broad Institute. + +Future Plans +++++++++++++ + +At present, CAS outputs annotations exclusively for cell types. In upcoming updates, we plan to extend the service to include a broader range of informative metadata such as disease status, developmental stage, tissue origin, and other relevant biological contexts, thereby providing users with a more comprehensive annotation framework for their single-cell data. -**Hoes does CAS work?** CAS leverages a vast repository of public single-cell data, enriched with metadata such as cell type, disease, tissue, etc. to provide robust annotations for newly generated datasets. As more reference data becomes available and added to the Cellarium DataStore, CAS aims to contextualize new datasets against this accumulated knowledge, addressing a critical bottleneck in single-cell analysis. This approach is akin to how search engines have indexed and made vast amounts of internet data findable and easily accessible. Understanding the mechanisms underlying diseases critically depends on identifying similarities and differences between cellular measurements in various contexts. CAS simplifies this process by identifying similar reference cells and then providing streamlined, community-consensus annotations directly based the context of each queried cell. .. toctree:: :maxdepth: 1 - :caption: General Info + :caption: General Usage modules/installation modules/usage modules/workflow modules/changelog +.. toctree:: + :maxdepth: 1 + :caption: Tutorials + + Quickstart Tutorial (on Google Colab) + Quickstart Tutorial (static) + .. toctree:: :maxdepth: 1 :caption: Codebase Documentation diff --git a/docs/source/modules/installation.rst b/docs/source/modules/installation.rst index 2c8268d..2d3fe03 100644 --- a/docs/source/modules/installation.rst +++ b/docs/source/modules/installation.rst @@ -11,14 +11,22 @@ The cellarium-cas package officially supports Python versions between 3.7 and 3. From PyPI repository ++++++++++++++++++++ -Install the latest version using `pip` with a specified version: +Install the latest version using `pip` by running the following command: + +.. code-block:: bash + :substitutions: + + pip install cellarium-cas + +If you wish to install a specific version, you can specify the version number: .. code-block:: bash :substitutions: pip install cellarium-cas==|version| -If you wish to use visualization features, you can install the package with the visualization extras: + +Finally, if you wish to use visualization features, you can install the package with the visualization extras: .. code-block:: bash :substitutions: diff --git a/docs/source/modules/usage.rst b/docs/source/modules/usage.rst index 7b0967a..743d917 100644 --- a/docs/source/modules/usage.rst +++ b/docs/source/modules/usage.rst @@ -3,11 +3,12 @@ Usage ##### -API Token and the CAS Early Access Program ------------------------------------------- -In order to use the CAS API, you will need to join the Cell Annotation Service Early Access program. To join the program, -please fill out the form at https://cellarium.ai/cell-annotation-service-cas-early-access/ and we will notify you -when your account is created, and provide you with an API token to use with the CAS API. +API Token and the CAS Public Beta Program +----------------------------------------- +In order to use the CAS API, you will need to join the CAS Public Beta program. To obtain your unique API token to join +the public beta program, please navigate to the CAS webpage at `cellarium.ai `_, +scroll to the bottom of the page, and `sign up `_. We will contact +you with your unique API key as soon as the public beta is available. Initialization -------------- diff --git a/requirements/docs.txt b/requirements/docs.txt index df3e15a..bc682d7 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -4,4 +4,5 @@ sphinx_gallery~=0.14 sphinx_rtd_theme~=2.0 sphinx_substitution_extensions==2024.8.6 setuptools-git-versioning==2.0.0 -autodoc_pydantic==2.2.0 \ No newline at end of file +autodoc_pydantic==2.2.0 +nbsphinx From 6d215d0e35a709ee2f2e6d2bf191dd3485fe94bd Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 16:18:51 -0400 Subject: [PATCH 06/12] Update main-workflow.yaml Added pandoc installation step to unit tests. --- .github/workflows/main-workflow.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/main-workflow.yaml b/.github/workflows/main-workflow.yaml index 2c3699d..3eb1482 100644 --- a/.github/workflows/main-workflow.yaml +++ b/.github/workflows/main-workflow.yaml @@ -26,6 +26,8 @@ jobs: python-version: [ '3.7', '3.8', '3.9', '3.10' ] steps: - uses: actions/checkout@v4 + - name: Install pandoc + run: sudo apt-get update && sudo apt-get install -y pandoc - uses: ./.github/actions/unit-tests env: TEST_API_TOKEN: ${{ secrets.TEST_API_TOKEN }} From 88562b8a9b5621301cf9b49a7778e243be00818a Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 18:05:28 +0000 Subject: [PATCH 07/12] docs update --- README.md | 44 ++++++++++++---------------- docs/source/index.rst | 11 ++++--- docs/source/modules/installation.rst | 13 ++++++-- 3 files changed, 35 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 766e593..00bfc60 100644 --- a/README.md +++ b/README.md @@ -2,37 +2,29 @@ This codebase contains the Python client library for using Cellarium Cell Annotation Service (CAS). # Installation +The cellarium-cas package officially supports Python versions between 3.7 and 3.10. We recommend using Python 3.10. +You can install CAS from PyPI using `pip`. To install the latest version, please run the following command: ``` $ pip install cellarium-cas ``` -# Usage -To use Cellarium CAS, create a client instance with your API token: - -```python3 -from cellarium.cas import CASClient - -api_token = "a_very_long_string_with_some_symbols" -cas = CASClient( - api_token=api_token, - api_url="" -) +To install a specific version `version_number`, you can use the following command: ``` - -## Annotation -You can annotate 10x Cell Ranger h5 matrices from local disk: -```python3 - -response = cas.annotate_10x_h5_file(filepath="your_path_to_local_h5_file.h5") +$ pip install cellarium-cas== ``` -or an anndata file from local disk: -```python3 -response = cas.annotate_anndata_file(filepath="your_path_to_local_h5_file.h5ad") +If you wish to use visualization features, you can install the package with the visualization extras: +``` +$ pip install cellarium-cas[vis] ``` -or a previously loaded (unnormalized) anndata object: -```python3 -import anndata +# Obtaining an API Token +You need an API token to use CAS. We are offerring a free public beta for a limited time to try CAS and explore ways it can enhance your cell biology research. To obtain your unique API token to join the public beta release, please navigate to [https://cellarium.ai/tool/cellarium-cell-annotation-service-cas/](cellarium.ai), scroll to the bottom of the page, and [sign up](https://cellarium.ai/cell-annotation-service-cas-access/). We will contact you shortly as soon as the public beta is available with your unique API key. -adata = anndata.read("you_anndata_file.h5ad") -response = cas.annotate_anndata(adata) -``` +# Quickstart Tutorial +The fastest way to get started with using CAS is to follow the quickstart tutorial: +[Click here to open the quickstart tutorial on GitHub](notebooks/quickstart_tutorial.ipynb) + +It is even easier to go through the quickstart tutorial on Google Colab. Remember, you still need an API key to successfully run through the tutorial: +[Click here to open the quickstart tutorial on Google Colab](https://colab.research.google.com/drive/1m9zgqP5n7E4pGGCg5RjfvlCnS6uqUdSa) + +# Documentation +Please visit the project's [ReadTheDocs page](https://cellarium-cas.readthedocs.io/) for additional documentation. diff --git a/docs/source/index.rst b/docs/source/index.rst index 4a6e28c..880ebcc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,7 +4,9 @@ Cellarium Cell Annotation Service ################################# -**What's Cell Annotation Service (CAS)?** CAS is a software library for rapid querying of single-cell omics data relying on ML algorithms. +**What is Cell Annotation Service (CAS)?** CAS is a cloud-native software for rapid querying of single-cell omics data leveraging information-rich and compact vector representations and approximate nearest neighbor search engienes. This documentation refers to the client library for CAS, which provides a simple interface for querying the CAS backend and visualizing the results. + +**Hoes does CAS work?** CAS leverages a vast repository of public single-cell data, enriched with metadata such as cell type, disease, tissue, etc. to provide robust annotations for newly generated datasets. As more reference data becomes available and added to the Cellarium DataStore, CAS aims to contextualize new datasets against this accumulated knowledge, addressing a critical bottleneck in single-cell analysis. This approach is akin to how search engines have indexed and made vast amounts of internet data findable and easily accessible. Understanding the mechanisms underlying diseases critically depends on identifying similarities and differences between cellular measurements in various contexts. CAS simplifies this process by identifying similar reference cells and then providing streamlined, community-consensus annotations directly based the context of each queried cell. .. toctree:: :maxdepth: 1 @@ -23,7 +25,8 @@ Cellarium Cell Annotation Service automodules/visualization -Other Tools -=========== - * `Machine Learning library Cellarium ML `_ +Related Projects +================ + * `Cellarium ML Library `_ + * `Cellarium Cloud (Backend) `_ diff --git a/docs/source/modules/installation.rst b/docs/source/modules/installation.rst index 9cb35db..2c8268d 100644 --- a/docs/source/modules/installation.rst +++ b/docs/source/modules/installation.rst @@ -8,12 +8,19 @@ Prerequisites The cellarium-cas package officially supports Python versions between 3.7 and 3.10. We recommend using Python 3.10. -From github repository -++++++++++++++++++++++ +From PyPI repository +++++++++++++++++++++ -Install the latest alpha version using `pip` with a specified version: +Install the latest version using `pip` with a specified version: .. code-block:: bash :substitutions: pip install cellarium-cas==|version| + +If you wish to use visualization features, you can install the package with the visualization extras: + +.. code-block:: bash + :substitutions: + + pip install cellarium-cas[vis]==|version| From c529e02883882557c34d1709a032471a0f5b2040 Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 19:13:53 +0000 Subject: [PATCH 08/12] add logo to readme --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 00bfc60..e3af45f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# Cellarium Cell Annotation Service (CAS) Client +![Cellarium Logo](https://cellarium.ai/wp-content/uploads/2024/07/cellarium-logo-medium.png) +# Cellarium Cell Annotation Service (CAS) Client Library This codebase contains the Python client library for using Cellarium Cell Annotation Service (CAS). # Installation @@ -17,7 +18,7 @@ $ pip install cellarium-cas[vis] ``` # Obtaining an API Token -You need an API token to use CAS. We are offerring a free public beta for a limited time to try CAS and explore ways it can enhance your cell biology research. To obtain your unique API token to join the public beta release, please navigate to [https://cellarium.ai/tool/cellarium-cell-annotation-service-cas/](cellarium.ai), scroll to the bottom of the page, and [sign up](https://cellarium.ai/cell-annotation-service-cas-access/). We will contact you shortly as soon as the public beta is available with your unique API key. +You need an API token to use CAS. We are offerring a free public beta for a limited time to try CAS and explore ways it can enhance your cell biology research. To obtain your unique API token to join the public beta release, please navigate to [cellarium.ai](https://cellarium.ai/tool/cellarium-cell-annotation-service-cas/), scroll to the bottom of the page, and [sign up](https://cellarium.ai/cell-annotation-service-cas-access/). We will contact you shortly as soon as the public beta is available with your unique API key. # Quickstart Tutorial The fastest way to get started with using CAS is to follow the quickstart tutorial: From 1b29d05e5643ad031efde13c226aea313eeb4d7b Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 19:15:03 +0000 Subject: [PATCH 09/12] add logo to readme (html) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e3af45f..8f73a55 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Cellarium Logo](https://cellarium.ai/wp-content/uploads/2024/07/cellarium-logo-medium.png) +Cellarium Logo # Cellarium Cell Annotation Service (CAS) Client Library This codebase contains the Python client library for using Cellarium Cell Annotation Service (CAS). From 2daee989a6349408e84f9e4c86dd555f730509c9 Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 19:15:58 +0000 Subject: [PATCH 10/12] logo size --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8f73a55..af02883 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -Cellarium Logo +Cellarium Logo + # Cellarium Cell Annotation Service (CAS) Client Library This codebase contains the Python client library for using Cellarium Cell Annotation Service (CAS). From 8f678384c31df67c87b8a426f3193121a15e9a73 Mon Sep 17 00:00:00 2001 From: Mehrtash Babadi Date: Mon, 7 Oct 2024 20:07:22 +0000 Subject: [PATCH 11/12] update docs --- README.md | 2 +- docs/source/conf.py | 19 ++++++++++++-- docs/source/index.rst | 37 ++++++++++++++++++++++++---- docs/source/modules/installation.rst | 12 +++++++-- docs/source/modules/usage.rst | 11 +++++---- requirements/docs.txt | 3 ++- 6 files changed, 68 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index af02883..45f4a49 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ $ pip install cellarium-cas[vis] ``` # Obtaining an API Token -You need an API token to use CAS. We are offerring a free public beta for a limited time to try CAS and explore ways it can enhance your cell biology research. To obtain your unique API token to join the public beta release, please navigate to [cellarium.ai](https://cellarium.ai/tool/cellarium-cell-annotation-service-cas/), scroll to the bottom of the page, and [sign up](https://cellarium.ai/cell-annotation-service-cas-access/). We will contact you shortly as soon as the public beta is available with your unique API key. +You need an API token to use CAS. We are offerring a free public beta program for a limited time to try CAS and explore ways it can enhance your cell biology research. To obtain your unique API token to join the public beta program, please navigate to the CAS webpage at [cellarium.ai](https://cellarium.ai/tool/cellarium-cell-annotation-service-cas/), scroll to the bottom of the page, and [sign up](https://cellarium.ai/cell-annotation-service-cas-access/). We will contact you with your unique API key as soon as the public beta is available. # Quickstart Tutorial The fastest way to get started with using CAS is to follow the quickstart tutorial: diff --git a/docs/source/conf.py b/docs/source/conf.py index 960425f..5ea90b0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -2,6 +2,9 @@ # # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import os +import shutil +import glob import time from setuptools_git_versioning import get_tag @@ -10,8 +13,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = "Cellarium CAS" -copyright = f"{time.strftime('%Y')}, Cellarium AI" -author = "Cellarium AI" +copyright = f"{time.strftime('%Y')}, Cellarium AI Lab" +author = "Cellarium AI Lab" version = get_tag() or "" release = get_tag() or "" @@ -19,6 +22,10 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ + 'nbsphinx', + 'sphinx.ext.mathjax', + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', "sphinx_rtd_theme", "sphinx.ext.autodoc", "sphinx.ext.napoleon", @@ -28,6 +35,8 @@ "sphinxcontrib.autodoc_pydantic", ] +exclude_patterns = ['_build', '**.ipynb_checkpoints'] + # Provide substitutions for common values rst_prolog = f""" .. |project| replace:: {project} @@ -60,3 +69,9 @@ # The JSON schema is a bit much in the docs autodoc_pydantic_model_show_json = False + +if not os.path.exists("notebooks"): + os.makedirs("notebooks") + +for src_file in glob.glob("../../notebooks/*.ipynb"): + shutil.copy(src_file, "notebooks/") diff --git a/docs/source/index.rst b/docs/source/index.rst index 880ebcc..89039b2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,22 +1,49 @@ :tocdepth: 3 -Cellarium Cell Annotation Service -################################# +Cellarium Cell Annotation Service (CAS) Documentation +##################################################### -**What is Cell Annotation Service (CAS)?** CAS is a cloud-native software for rapid querying of single-cell omics data leveraging information-rich and compact vector representations and approximate nearest neighbor search engienes. This documentation refers to the client library for CAS, which provides a simple interface for querying the CAS backend and visualizing the results. +Overview +++++++++ + +**What is the Cell Annotation Service (CAS)?** +The Cell Annotation Service (CAS) is a cloud-native platform designed for rapid and efficient querying of single-cell omics data. It utilizes compact and information-rich vector representations combined with approximate nearest neighbor search engines to enable seamless exploration of vast single-cell datasets. This documentation focuses on the CAS client library, which offers a user-friendly interface for querying the CAS backend and visualizing the results. + +**Hows does CAS work?** +CAS operates by building a vector search index derived from low-dimensional embeddings of a comprehensive repository of publicly available single-cell transcriptomics data. Currently, the CAS reference dataset comprises the entire `CZI CELLxGENE `_ data catalog. This reference database includes rich metadata such as cell type, disease state, tissue origin, and more. In future iterations, the reference catalog will be expanded to incorporate additional datasets. + +When a user queries CAS with their single-cell transcriptomics data, the system maps the input data into the same vector space as the reference dataset. It then performs an approximate nearest neighbor search to identify similar cells within the reference database. Based on these similar reference cells, CAS generates label summary statistics, providing comprehensive annotations for each query cell. The methodology employed by CAS is comparable to how inverse search engines (such as image search techniques) index and retrieve information from vast amounts of internet data, making it accessible and interpretable. The embeddings used by CAS are generated using distributed machine learning models implemented in the `Cellarium ML Library `_ + +Understanding the similarities and differences between cellular measurements in various contexts is crucial for unraveling disease mechanisms. CAS streamlines this process by leveraging its reference context to provide community-consensus annotations for the queried cells, helping researchers gain deeper insights into their data. + +Funding ++++++++ + +Cellarium CAS was co-developed by 10x Genomics and Cellarium AI Lab at the Data Sciences Platform, Broad Institute. The project was funded by 10x Genomics, NIH Grant UM1 MH130966, and additional support from Broad Institute. + +Future Plans +++++++++++++ + +At present, CAS outputs annotations exclusively for cell types. In upcoming updates, we plan to extend the service to include a broader range of informative metadata such as disease status, developmental stage, tissue origin, and other relevant biological contexts, thereby providing users with a more comprehensive annotation framework for their single-cell data. -**Hoes does CAS work?** CAS leverages a vast repository of public single-cell data, enriched with metadata such as cell type, disease, tissue, etc. to provide robust annotations for newly generated datasets. As more reference data becomes available and added to the Cellarium DataStore, CAS aims to contextualize new datasets against this accumulated knowledge, addressing a critical bottleneck in single-cell analysis. This approach is akin to how search engines have indexed and made vast amounts of internet data findable and easily accessible. Understanding the mechanisms underlying diseases critically depends on identifying similarities and differences between cellular measurements in various contexts. CAS simplifies this process by identifying similar reference cells and then providing streamlined, community-consensus annotations directly based the context of each queried cell. .. toctree:: :maxdepth: 1 - :caption: General Info + :caption: General Usage modules/installation modules/usage modules/workflow modules/changelog +.. toctree:: + :maxdepth: 1 + :caption: Tutorials + + Quickstart Tutorial (on Google Colab) + Quickstart Tutorial (static) + .. toctree:: :maxdepth: 1 :caption: Codebase Documentation diff --git a/docs/source/modules/installation.rst b/docs/source/modules/installation.rst index 2c8268d..2d3fe03 100644 --- a/docs/source/modules/installation.rst +++ b/docs/source/modules/installation.rst @@ -11,14 +11,22 @@ The cellarium-cas package officially supports Python versions between 3.7 and 3. From PyPI repository ++++++++++++++++++++ -Install the latest version using `pip` with a specified version: +Install the latest version using `pip` by running the following command: + +.. code-block:: bash + :substitutions: + + pip install cellarium-cas + +If you wish to install a specific version, you can specify the version number: .. code-block:: bash :substitutions: pip install cellarium-cas==|version| -If you wish to use visualization features, you can install the package with the visualization extras: + +Finally, if you wish to use visualization features, you can install the package with the visualization extras: .. code-block:: bash :substitutions: diff --git a/docs/source/modules/usage.rst b/docs/source/modules/usage.rst index 7b0967a..743d917 100644 --- a/docs/source/modules/usage.rst +++ b/docs/source/modules/usage.rst @@ -3,11 +3,12 @@ Usage ##### -API Token and the CAS Early Access Program ------------------------------------------- -In order to use the CAS API, you will need to join the Cell Annotation Service Early Access program. To join the program, -please fill out the form at https://cellarium.ai/cell-annotation-service-cas-early-access/ and we will notify you -when your account is created, and provide you with an API token to use with the CAS API. +API Token and the CAS Public Beta Program +----------------------------------------- +In order to use the CAS API, you will need to join the CAS Public Beta program. To obtain your unique API token to join +the public beta program, please navigate to the CAS webpage at `cellarium.ai `_, +scroll to the bottom of the page, and `sign up `_. We will contact +you with your unique API key as soon as the public beta is available. Initialization -------------- diff --git a/requirements/docs.txt b/requirements/docs.txt index 1fc767c..bab6292 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -4,4 +4,5 @@ sphinx_gallery~=0.14 sphinx_rtd_theme~=2.0 sphinx_substitution_extensions==2024.8.6 setuptools-git-versioning==2.0.0 -autodoc_pydantic==2.2.0 \ No newline at end of file +autodoc_pydantic==2.2.0 +nbsphinx From c8ea33d244054ad968ace40f0078d866d3c1ad47 Mon Sep 17 00:00:00 2001 From: nmalfroy Date: Wed, 9 Oct 2024 10:24:03 -0400 Subject: [PATCH 12/12] Include missing dependencies --- docs/source/conf.py | 1 + requirements/docs.txt | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 5ea90b0..cb34637 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -33,6 +33,7 @@ "sphinx.ext.intersphinx", "sphinx_substitution_extensions", "sphinxcontrib.autodoc_pydantic", + "IPython.sphinxext.ipython_console_highlighting", ] exclude_patterns = ['_build', '**.ipynb_checkpoints'] diff --git a/requirements/docs.txt b/requirements/docs.txt index bab6292..7b3f440 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -6,3 +6,4 @@ sphinx_substitution_extensions==2024.8.6 setuptools-git-versioning==2.0.0 autodoc_pydantic==2.2.0 nbsphinx +IPython