update docs

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:

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,15 +13,19 @@
 # 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 "<no version>"
 release = get_tag() or "<no release>"
 
 # -- General configuration ---------------------------------------------------
 # 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/")

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 <https://cellxgene.cziscience.com/>`_ 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 <https://cellarium-ai.github.io/cellarium-ml/index.html>`_
+
+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) <https://colab.research.google.com/drive/1m9zgqP5n7E4pGGCg5RjfvlCnS6uqUdSa>
+   Quickstart Tutorial (static) <notebooks/quickstart_tutorial.ipynb>
+
 .. toctree::
    :maxdepth: 1
    :caption: Codebase Documentation

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:

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

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
+autodoc_pydantic==2.2.0
+nbsphinx