examples/cshl.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "pzxiMjjkjzPN"
   },
   "source": [
    "# CELLxGENE Discover Census Workshop - CSHL Single-Cell Analysis 2023\n",
    "\n",
    "This notebook is a step-by-step walkthrough of the CELLxGENE Discover Census Workshop at CSHL's Single-Cell Analysis, 2023.\n",
    "\n",
    "Original Colab notebook: https://colab.research.google.com/drive/1QgZQRF_ZM9q5oKbynnD9ToklVFdui7pq\n",
    "\n",
    "## License\n",
    "\n",
    "MIT License\n",
    "\n",
    "Copyright (c) 2022-2023 Chan Zuckerberg Initiative Foundation.\n",
    "\n",
    "Permission is hereby granted, free of charge, to any person obtaining a copy\n",
    "of this software and associated documentation files (the \"Software\"), to deal\n",
    "in the Software without restriction, including without limitation the rights\n",
    "to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n",
    "copies of the Software, and to permit persons to whom the Software is\n",
    "furnished to do so, subject to the following conditions:\n",
    "\n",
    "The above copyright notice and this permission notice shall be included in all\n",
    "copies or substantial portions of the Software.\n",
    "\n",
    "THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n",
    "IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n",
    "FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n",
    "AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n",
    "LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n",
    "OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n",
    "SOFTWARE.\n",
    "\n",
    "## Workshop\n",
    "\n",
    "### Installation\n",
    "\n",
    "To install the Census API on your laptop, follow the [installation instructions](https://chanzuckerberg.github.io/cellxgene-census/cellxgene_census_docsite_installation.html) in the documentation site.\n",
    "\n",
    "To install required dependencies:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "id": "nMzIa7U5jJkU"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Package                   Version        Editable project location\n",
      "------------------------- -------------- -------------------------------------\n",
      "aiobotocore               2.14.0\n",
      "aiohappyeyeballs          2.4.0\n",
      "aiohttp                   3.10.5\n",
      "aioitertools              0.12.0\n",
      "aiosignal                 1.3.1\n",
      "anndata                   0.10.9\n",
      "ansicolors                1.1.8\n",
      "anyio                     4.4.0\n",
      "argon2-cffi               23.1.0\n",
      "argon2-cffi-bindings      21.2.0\n",
      "array_api_compat          1.8\n",
      "arrow                     1.3.0\n",
      "asttokens                 2.4.1\n",
      "async-lru                 2.0.4\n",
      "async-timeout             4.0.3\n",
      "attrs                     24.2.0\n",
      "babel                     2.16.0\n",
      "beautifulsoup4            4.12.3\n",
      "bleach                    6.1.0\n",
      "botocore                  1.35.7\n",
      "cellxgene-census          1.15.0\n",
      "certifi                   2024.8.30\n",
      "cffi                      1.17.1\n",
      "charset-normalizer        3.3.2\n",
      "click                     8.1.7\n",
      "cloudpickle               2.2.1\n",
      "colorama                  0.4.6\n",
      "comm                      0.2.2\n",
      "contourpy                 1.3.0\n",
      "cycler                    0.12.1\n",
      "debugpy                   1.8.5\n",
      "decorator                 5.1.1\n",
      "defusedxml                0.7.1\n",
      "entrypoints               0.4\n",
      "exceptiongroup            1.2.2\n",
      "executing                 2.1.0\n",
      "fastjsonschema            2.20.0\n",
      "filelock                  3.16.0\n",
      "fonttools                 4.53.1\n",
      "fqdn                      1.5.1\n",
      "frozenlist                1.4.1\n",
      "fsspec                    2024.9.0\n",
      "get-annotations           0.1.2\n",
      "gitdb                     4.0.11\n",
      "GitPython                 3.1.43\n",
      "h11                       0.14.0\n",
      "h5py                      3.11.0\n",
      "httpcore                  1.0.5\n",
      "httpx                     0.27.2\n",
      "idna                      3.8\n",
      "importlib_metadata        8.4.0\n",
      "importlib_resources       6.4.5\n",
      "ipykernel                 6.29.5\n",
      "ipython                   8.18.1\n",
      "ipywidgets                8.1.5\n",
      "isoduration               20.11.0\n",
      "jedi                      0.19.1\n",
      "Jinja2                    3.1.4\n",
      "jmespath                  1.0.1\n",
      "joblib                    1.4.2\n",
      "json5                     0.9.25\n",
      "jsonpointer               3.0.0\n",
      "jsonschema                4.23.0\n",
      "jsonschema-specifications 2023.12.1\n",
      "jupyter                   1.1.1\n",
      "jupyter_client            8.6.2\n",
      "jupyter-console           6.6.3\n",
      "jupyter_core              5.7.2\n",
      "jupyter-events            0.10.0\n",
      "jupyter-lsp               2.2.5\n",
      "jupyter_server            2.14.2\n",
      "jupyter-server-mathjax    0.2.6\n",
      "jupyter_server_terminals  0.5.3\n",
      "jupyterlab                4.2.5\n",
      "jupyterlab_pygments       0.3.0\n",
      "jupyterlab_server         2.27.3\n",
      "jupyterlab_widgets        3.0.13\n",
      "kiwisolver                1.4.7\n",
      "legacy-api-wrap           1.4\n",
      "llvmlite                  0.43.0\n",
      "MarkupSafe                2.1.5\n",
      "matplotlib                3.9.2\n",
      "matplotlib-inline         0.1.7\n",
      "mistune                   3.0.2\n",
      "mpmath                    1.3.0\n",
      "multidict                 6.1.0\n",
      "natsort                   8.4.0\n",
      "nbclient                  0.10.0\n",
      "nbconvert                 7.16.4\n",
      "nbdime                    4.0.2\n",
      "nbformat                  5.10.4\n",
      "nest-asyncio              1.6.0\n",
      "networkx                  3.2.1\n",
      "notebook                  7.2.2\n",
      "notebook_shim             0.2.4\n",
      "numba                     0.60.0\n",
      "numpy                     1.26.4\n",
      "nvidia-cublas-cu12        12.1.3.1\n",
      "nvidia-cuda-cupti-cu12    12.1.105\n",
      "nvidia-cuda-nvrtc-cu12    12.1.105\n",
      "nvidia-cuda-runtime-cu12  12.1.105\n",
      "nvidia-cudnn-cu12         9.1.0.70\n",
      "nvidia-cufft-cu12         11.0.2.54\n",
      "nvidia-curand-cu12        10.3.2.106\n",
      "nvidia-cusolver-cu12      11.4.5.107\n",
      "nvidia-cusparse-cu12      12.1.0.106\n",
      "nvidia-nccl-cu12          2.20.5\n",
      "nvidia-nvjitlink-cu12     12.6.68\n",
      "nvidia-nvtx-cu12          12.1.105\n",
      "overrides                 7.7.0\n",
      "packaging                 24.1\n",
      "pandas                    1.5.3\n",
      "pandocfilters             1.5.1\n",
      "papermill                 2.6.0\n",
      "parso                     0.8.4\n",
      "patsy                     0.5.6\n",
      "pexpect                   4.9.0\n",
      "pillow                    10.4.0\n",
      "pip                       24.2\n",
      "platformdirs              4.3.2\n",
      "prometheus_client         0.20.0\n",
      "prompt_toolkit            3.0.47\n",
      "psutil                    6.0.0\n",
      "ptyprocess                0.7.0\n",
      "pure_eval                 0.2.3\n",
      "pyarrow                   17.0.0\n",
      "pyarrow-hotfix            0.6\n",
      "pycparser                 2.22\n",
      "Pygments                  2.18.0\n",
      "pynndescent               0.5.13\n",
      "pyparsing                 3.1.4\n",
      "python-dateutil           2.9.0.post0\n",
      "python-json-logger        2.0.7\n",
      "pytz                      2024.1\n",
      "PyYAML                    6.0.2\n",
      "pyzmq                     26.2.0\n",
      "referencing               0.35.1\n",
      "requests                  2.32.3\n",
      "rfc3339-validator         0.1.4\n",
      "rfc3986-validator         0.1.1\n",
      "rpds-py                   0.20.0\n",
      "s3fs                      2024.9.0\n",
      "scanpy                    1.9.2\n",
      "scikit-learn              1.5.1\n",
      "scikit-misc               0.3.1\n",
      "scipy                     1.13.1\n",
      "scverse-workshop          0.1            /home/ubuntu/scverse-ml-workshop-2024\n",
      "seaborn                   0.13.2\n",
      "Send2Trash                1.8.3\n",
      "session_info              1.0.0\n",
      "setuptools                58.1.0\n",
      "six                       1.16.0\n",
      "smmap                     5.0.1\n",
      "sniffio                   1.3.1\n",
      "somacore                  1.0.11\n",
      "soupsieve                 2.6\n",
      "stack-data                0.6.3\n",
      "statsmodels               0.14.2\n",
      "stdlb                     0.0.4\n",
      "stdlib-list               0.10.0\n",
      "sympy                     1.13.2\n",
      "tblib                     1.7.0\n",
      "tenacity                  9.0.0\n",
      "terminado                 0.18.1\n",
      "threadpoolctl             3.5.0\n",
      "tiledb                    0.29.1\n",
      "tiledb-cloud              0.12.23\n",
      "tiledbsoma                1.11.4\n",
      "tinycss2                  1.3.0\n",
      "tomli                     2.0.1\n",
      "torch                     2.4.1\n",
      "torchdata                 0.8.0\n",
      "tornado                   6.4.1\n",
      "tqdm                      4.66.5\n",
      "traitlets                 5.14.3\n",
      "triton                    3.0.0\n",
      "types-python-dateutil     2.9.0.20240906\n",
      "typing_extensions         4.12.2\n",
      "tzdata                    2024.1\n",
      "umap-learn                0.5.6\n",
      "uri-template              1.3.0\n",
      "urllib3                   1.26.20\n",
      "utz                       0.7.2\n",
      "wcwidth                   0.2.13\n",
      "webcolors                 24.8.0\n",
      "webencodings              0.5.1\n",
      "websocket-client          1.8.0\n",
      "widgetsnbextension        4.0.13\n",
      "wrapt                     1.16.0\n",
      "yarl                      1.11.1\n",
      "zipp                      3.20.1\n"
     ]
    }
   ],
   "source": [
    "!pip install -r ../requirements-nb.txt > /dev/null\n",
    "!pip list"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "fxGSU7epkxsh"
   },
   "source": [
    "### Census Hello World\n",
    "\n",
    "Let's load the necessary libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "id": "oqXUoKWXjjXd"
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/ubuntu/.pyenv/versions/scverse-ml-workshop-2024-3.9.19/lib/python3.9/site-packages/tiledb/cloud/config.py:96: UserWarning: You must first login before you can run commands. Please run tiledb.cloud.login.\n",
      "  warnings.warn(\n"
     ]
    }
   ],
   "source": [
    "import cellxgene_census\n",
    "import tiledbsoma\n",
    "import scipy\n",
    "import numpy\n",
    "import scanpy as sc\n",
    "import pandas"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "JX3zqHPbbsFQ"
   },
   "source": [
    "Let's also set some configuration settings for SOMA. This allows us to set the size of data we stream at any given time, as this will be relevant when we cover SOMA iterators."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "id": "7yjZrONbQnBE"
   },
   "outputs": [],
   "source": [
    "# Default: 1GB\n",
    "# Google colab runs well with 1MB\n",
    "# TileDB-Cloud can run default, but recommended for workshop is 10MB\n",
    "config = {\n",
    "    \"vfs.s3.region\": \"us-west-2\",\n",
    "    \"vfs.s3.no_sign_request\": \"true\",\n",
    "    \"py.init_buffer_bytes\": 0.001 * 1024**3, #1MB\n",
    "    \"soma.init_buffer_bytes\": 0.001 * 1024**3, #1MB\n",
    "}\n",
    "\n",
    "ctx = tiledbsoma.options.SOMATileDBContext()\n",
    "ctx = ctx.replace(tiledb_config=config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "ahd1v8DWllux"
   },
   "source": [
    "#### Finding Census versions available\n",
    "\n",
    "Let's first take a look at the data releases available in S3. There are two types of releases:\n",
    "- **Long-term supported (LTS) data releases** published every six months to be avalialbe for up to 5 years.\n",
    "- **Weekly releases** to be available for up to 6 weeks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "H6lQ02vRnDC5"
   },
   "source": [
    "To see a list of all available releases and their version aliases, we can do the following"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "LFImTFw1opde",
    "outputId": "904d987c-246f-4134-8c66-88fa1eb9306c"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OrderedDict([('stable',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-07-01',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-07-01/soma/',\n",
       "                'relative_uri': '/cell-census/2024-07-01/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-07-01/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-07-01/h5ads/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'flags': {'lts': True}}),\n",
       "             ('latest',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-09-02',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/',\n",
       "                'relative_uri': '/cell-census/2024-09-02/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-09-02/h5ads/',\n",
       "                's3_region': 'us-west-2'}}),\n",
       "             ('2024-09-02',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-09-02',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/',\n",
       "                'relative_uri': '/cell-census/2024-09-02/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-09-02/h5ads/',\n",
       "                's3_region': 'us-west-2'}}),\n",
       "             ('2024-08-26',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-08-26',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-08-26/soma/',\n",
       "                'relative_uri': '/cell-census/2024-08-26/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-08-26/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-08-26/h5ads/',\n",
       "                's3_region': 'us-west-2'}}),\n",
       "             ('2024-08-19',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-08-19',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-08-19/soma/',\n",
       "                'relative_uri': '/cell-census/2024-08-19/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-08-19/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-08-19/h5ads/',\n",
       "                's3_region': 'us-west-2'}}),\n",
       "             ('2024-08-12',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-08-12',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-08-12/soma/',\n",
       "                'relative_uri': '/cell-census/2024-08-12/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-08-12/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-08-12/h5ads/',\n",
       "                's3_region': 'us-west-2'}}),\n",
       "             ('2024-08-05',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-08-05',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-08-05/soma/',\n",
       "                'relative_uri': '/cell-census/2024-08-05/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-08-05/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-08-05/h5ads/',\n",
       "                's3_region': 'us-west-2'}}),\n",
       "             ('2024-07-01',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-07-01',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-07-01/soma/',\n",
       "                'relative_uri': '/cell-census/2024-07-01/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-07-01/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-07-01/h5ads/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'flags': {'lts': True}}),\n",
       "             ('2024-05-20',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-05-20',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-05-20/soma/',\n",
       "                'relative_uri': '/cell-census/2024-05-20/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-05-20/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-05-20/h5ads/',\n",
       "                's3_region': 'us-west-2'}}),\n",
       "             ('2023-12-15',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2023-12-15',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-12-15/soma/',\n",
       "                'relative_uri': '/cell-census/2023-12-15/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-12-15/h5ads/',\n",
       "                'relative_uri': '/cell-census/2023-12-15/h5ads/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'flags': {'lts': True}}),\n",
       "             ('2023-07-25',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2023-07-25',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-07-25/soma/',\n",
       "                'relative_uri': '/cell-census/2023-07-25/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-07-25/h5ads/',\n",
       "                'relative_uri': '/cell-census/2023-07-25/h5ads/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'flags': {'lts': True}}),\n",
       "             ('2023-05-15',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2023-05-15',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-05-15/soma/',\n",
       "                'relative_uri': '/cell-census/2023-05-15/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-05-15/h5ads/',\n",
       "                'relative_uri': '/cell-census/2023-05-15/h5ads/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'flags': {'lts': True}})])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cellxgene_census.get_census_version_directory()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "OT-oy0h9o3tX",
    "outputId": "cd018e0d-21cc-4296-af7d-4dc27122ddcf"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OrderedDict([('stable',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-07-01',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-07-01/soma/',\n",
       "                'relative_uri': '/cell-census/2024-07-01/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-07-01/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-07-01/h5ads/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'flags': {'lts': True}}),\n",
       "             ('2024-07-01',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2024-07-01',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-07-01/soma/',\n",
       "                'relative_uri': '/cell-census/2024-07-01/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2024-07-01/h5ads/',\n",
       "                'relative_uri': '/cell-census/2024-07-01/h5ads/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'flags': {'lts': True}}),\n",
       "             ('2023-12-15',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2023-12-15',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-12-15/soma/',\n",
       "                'relative_uri': '/cell-census/2023-12-15/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-12-15/h5ads/',\n",
       "                'relative_uri': '/cell-census/2023-12-15/h5ads/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'flags': {'lts': True}}),\n",
       "             ('2023-07-25',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2023-07-25',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-07-25/soma/',\n",
       "                'relative_uri': '/cell-census/2023-07-25/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-07-25/h5ads/',\n",
       "                'relative_uri': '/cell-census/2023-07-25/h5ads/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'flags': {'lts': True}}),\n",
       "             ('2023-05-15',\n",
       "              {'release_date': None,\n",
       "               'release_build': '2023-05-15',\n",
       "               'soma': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-05-15/soma/',\n",
       "                'relative_uri': '/cell-census/2023-05-15/soma/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'h5ads': {'uri': 's3://cellxgene-census-public-us-west-2/cell-census/2023-05-15/h5ads/',\n",
       "                'relative_uri': '/cell-census/2023-05-15/h5ads/',\n",
       "                's3_region': 'us-west-2'},\n",
       "               'flags': {'lts': True}})])"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cellxgene_census.get_census_version_directory(lts=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "cklactWoB2e2"
   },
   "source": [
    "#### Opening a Census version\n",
    "\n",
    "Now we can get a handle to the Census object hosted in S3. Remember that we can specify the data release to use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "id": "P4Jq5ovIorcf"
   },
   "outputs": [],
   "source": [
    "# For the latest LTS use \"stable\", other options are \"latest\" for the latest\n",
    "# weekly, or specific version\n",
    "\n",
    "version = \"latest\"\n",
    "\n",
    "# equivalent\n",
    "# version = \"2023-07-25\"\n",
    "\n",
    "census = cellxgene_census.open_soma(census_version=version, context=ctx)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "y3tGaPQrEyRL"
   },
   "source": [
    "#### Inspecting the Census object\n",
    "\n",
    "These are the types of SOMA objects used by Census:\n",
    "\n",
    "- `SparseNDArray` is the same as DenseNDArray but sparse, and supports point indexing (disjoint index access).\n",
    "- `DataFrame` is a multi-column table with user-defined columns names and value types, with support for point indexing.\n",
    "- `Collection` is a persistent container of named SOMA objects, similar to a dictionary.\n",
    "- `Experiment` is a class that represents a single-cell experiment. It always contains two objects:\n",
    "   - `obs`: a `DataFrame` with primary annotations on the observation axis.\n",
    "   - `ms`: a `Collection` of measurements, each composed of `X` matrices and axis annotation matrices or data frames (e.g. `var`, `varm`, `obsm`, etc).\n",
    "\n",
    "The parent Census object is a SOMA `Collection`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "oDDcosbj_h9D",
    "outputId": "a50d4c1e-62b2-4fc3-fe37-e7d23eaa4849"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Collection 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/' (open for 'r') (2 items)\n",
       "    'census_info': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info' (unopened)\n",
       "    'census_data': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_data' (unopened)>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "ygGpjcpj_d56"
   },
   "source": [
    "You can access items of a collection with square brackets.\n",
    "\n",
    "- `\"census_data\"` has the Census single-cell data, will explore it in a momemnt.\n",
    "- `\"census_info\"` has high-level summary information about Census\n",
    "\n",
    "Let's take a look at `\"census_info\"`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "6zr_yAnH_ZJV",
    "outputId": "5906fd63-ffcf-47f2-ca14-929e3c932ab2"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Collection 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info' (open for 'r') (4 items)\n",
       "    'datasets': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info/datasets' (unopened)\n",
       "    'summary_cell_counts': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info/summary_cell_counts' (unopened)\n",
       "    'summary': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info/summary' (unopened)\n",
       "    'organisms': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info/organisms' (unopened)>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census[\"census_info\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "CX61uvdLAdRv"
   },
   "source": [
    "There are three items in this collection:\n",
    "\n",
    "- `\"summary\"`: A data frame with high-level information of this Census, e.g. build date, total cell count, etc.\n",
    "- `\"summary_cell_counts\"`: A data frame with cell counts stratified by relevant cell metadata\n",
    "- `\"datasets\"`: A data frame with all datasets from CELLxGENE Discover used to create the Census."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "i87SDNOpCvz3"
   },
   "source": [
    "Now let's take a look at `\"census_data\"`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "t_4gewQ9AT46",
    "outputId": "5bcb1bc5-6c2d-48e1-e4c0-51b7258f9466"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Collection 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_data' (open for 'r') (2 items)\n",
       "    'homo_sapiens': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_data/homo_sapiens' (unopened)\n",
       "    'mus_musculus': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_data/mus_musculus' (unopened)>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census[\"census_data\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "vrx1KwN4Bimu"
   },
   "source": [
    "These two are SOMA `Experiment` objects which are a specialized form of a `Collection`. Each of these store a data matrix (cells by genes), cell metadata, gene metadata, and some other useful components."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "mqOefkzOJkH2"
   },
   "source": [
    "### Reading Data Frames"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "amEMnNCjVtB6"
   },
   "source": [
    "\n",
    "#### Reading cell metadata\n",
    "\n",
    "Let's take a deeper dive into the single-cell data. As mentioned earlier, an `Experiment` always has an `obs` atrribute that can be accessed via `.obs`.\n",
    "\n",
    "Let's take a look at the human `Experiment`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "zZXy-Bt3I28i",
    "outputId": "82a4694b-60b1-44c2-f4e9-14a3332db9a3"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Experiment 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_data/homo_sapiens' (open for 'r') (2 items)\n",
       "    'obs': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_data/homo_sapiens/obs' (unopened)\n",
       "    'ms': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_data/homo_sapiens/ms' (unopened)>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census[\"census_data\"][\"homo_sapiens\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "8kNlAnIGKB3r",
    "outputId": "6dc6ca62-2e9a-42e1-f9ae-3ee51a9db176"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<DataFrame 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_data/homo_sapiens/obs' (open for 'r')>"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census[\"census_data\"][\"homo_sapiens\"].obs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "fi2sDGuIMEP_"
   },
   "source": [
    "We can take a look at the columns available in a data frame with the `keys()` method, which shows the types of metadata available for each cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "X1CQfbGmMDcf",
    "outputId": "11be0a5e-a79c-4fc2-d3d8-be16aa796163"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('soma_joinid',\n",
       " 'dataset_id',\n",
       " 'assay',\n",
       " 'assay_ontology_term_id',\n",
       " 'cell_type',\n",
       " 'cell_type_ontology_term_id',\n",
       " 'development_stage',\n",
       " 'development_stage_ontology_term_id',\n",
       " 'disease',\n",
       " 'disease_ontology_term_id',\n",
       " 'donor_id',\n",
       " 'is_primary_data',\n",
       " 'observation_joinid',\n",
       " 'self_reported_ethnicity',\n",
       " 'self_reported_ethnicity_ontology_term_id',\n",
       " 'sex',\n",
       " 'sex_ontology_term_id',\n",
       " 'suspension_type',\n",
       " 'tissue',\n",
       " 'tissue_ontology_term_id',\n",
       " 'tissue_type',\n",
       " 'tissue_general',\n",
       " 'tissue_general_ontology_term_id',\n",
       " 'raw_sum',\n",
       " 'nnz',\n",
       " 'raw_mean_nnz',\n",
       " 'raw_variance_nnz',\n",
       " 'n_measured_vars')"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census[\"census_data\"][\"homo_sapiens\"].obs.keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "UujuxKAW3LhM"
   },
   "source": [
    "Let's read two columns of the data frame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 423
    },
    "id": "WD8zL10AKFv3",
    "outputId": "c2b801b2-7065-43c8-8d8f-2102a6e8d935"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>suspension_type</th>\n",
       "      <th>tissue_general</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>cell</td>\n",
       "      <td>liver</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>cell</td>\n",
       "      <td>liver</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>cell</td>\n",
       "      <td>liver</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>cell</td>\n",
       "      <td>liver</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>cell</td>\n",
       "      <td>liver</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>77665794</th>\n",
       "      <td>nucleus</td>\n",
       "      <td>brain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>77665795</th>\n",
       "      <td>nucleus</td>\n",
       "      <td>brain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>77665796</th>\n",
       "      <td>nucleus</td>\n",
       "      <td>brain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>77665797</th>\n",
       "      <td>nucleus</td>\n",
       "      <td>brain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>77665798</th>\n",
       "      <td>nucleus</td>\n",
       "      <td>brain</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>77665799 rows × 2 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "         suspension_type tissue_general\n",
       "0                   cell          liver\n",
       "1                   cell          liver\n",
       "2                   cell          liver\n",
       "3                   cell          liver\n",
       "4                   cell          liver\n",
       "...                  ...            ...\n",
       "77665794         nucleus          brain\n",
       "77665795         nucleus          brain\n",
       "77665796         nucleus          brain\n",
       "77665797         nucleus          brain\n",
       "77665798         nucleus          brain\n",
       "\n",
       "[77665799 rows x 2 columns]"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census[\"census_data\"][\"homo_sapiens\"].obs.read(column_names=[\"suspension_type\", \"tissue_general\"]).concat().to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "I5YBE9lhBlPx"
   },
   "source": [
    "The line above retrieved the suspension type and tissue values for all human cells in Census. Let's dissect step-by-step to see what happened there:\n",
    "\n",
    "1. `.read(column_names = [\"suspension_type\", \"tissue_general\"])` - creates an iterator of Arrow tables that can be used for chunked-based data streaming.\n",
    "2. `.concat()` - retrieves all the results of the iterator and concatenates them into a single Arrow table.\n",
    "3. `.to_pandas()` - converts the Arrow table into a Pandas data frame.\n",
    "\n",
    "Let's do each step one more time and inspect the intermediate objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "KWw45mP-Besz",
    "outputId": "cd38a4e9-fcf1-4bfd-92bc-4e0dfa0bcf93"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<tiledbsoma._read_iters.TableReadIter at 0x72fd4807ff40>"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Create iterator of Arrow tables\n",
    "iterator = census[\"census_data\"][\"homo_sapiens\"].obs.read(column_names=[\"suspension_type\", \"tissue_general\"])\n",
    "iterator"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "BIiTYQ0USqTt",
    "outputId": "6692f7a5-e085-4829-e291-74bc51147e82"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "pyarrow.Table\n",
       "suspension_type: dictionary<values=string, indices=int8, ordered=0>\n",
       "tissue_general: dictionary<values=string, indices=int8, ordered=0>\n",
       "----\n",
       "suspension_type: [  -- dictionary:\n",
       "[\"cell\",\"nucleus\"]  -- indices:\n",
       "[0,0,0,0,0,...,0,0,0,0,0]]\n",
       "tissue_general: [  -- dictionary:\n",
       "[\"adipose tissue\",\"adrenal gland\",\"axilla\",\"bladder organ\",\"blood\",...,\"tongue\",\"ureter\",\"uterus\",\"vasculature\",\"yolk sac\"]  -- indices:\n",
       "[27,27,27,27,27,...,39,39,39,39,39]]"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# We can get individual chunks\n",
    "table_chunk = next(iterator)\n",
    "table_chunk"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "Yn48LNCPTVfN",
    "outputId": "cc4e3e02-8799-46f2-dfd4-d8b383df74d9"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>suspension_type</th>\n",
       "      <th>tissue_general</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>cell</td>\n",
       "      <td>liver</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>cell</td>\n",
       "      <td>liver</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>cell</td>\n",
       "      <td>liver</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>cell</td>\n",
       "      <td>liver</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>cell</td>\n",
       "      <td>liver</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1073736</th>\n",
       "      <td>cell</td>\n",
       "      <td>pleural fluid</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1073737</th>\n",
       "      <td>cell</td>\n",
       "      <td>pleural fluid</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1073738</th>\n",
       "      <td>cell</td>\n",
       "      <td>pleural fluid</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1073739</th>\n",
       "      <td>cell</td>\n",
       "      <td>pleural fluid</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1073740</th>\n",
       "      <td>cell</td>\n",
       "      <td>pleural fluid</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>1073741 rows × 2 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "        suspension_type tissue_general\n",
       "0                  cell          liver\n",
       "1                  cell          liver\n",
       "2                  cell          liver\n",
       "3                  cell          liver\n",
       "4                  cell          liver\n",
       "...                 ...            ...\n",
       "1073736            cell  pleural fluid\n",
       "1073737            cell  pleural fluid\n",
       "1073738            cell  pleural fluid\n",
       "1073739            cell  pleural fluid\n",
       "1073740            cell  pleural fluid\n",
       "\n",
       "[1073741 rows x 2 columns]"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "table_chunk.to_pandas()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 423
    },
    "id": "_6fjIQKzDM5q",
    "outputId": "f6254612-5386-4ba7-fba8-92700deefff9"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>suspension_type</th>\n",
       "      <th>tissue_general</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>cell</td>\n",
       "      <td>pleural fluid</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>cell</td>\n",
       "      <td>pleural fluid</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>cell</td>\n",
       "      <td>pleural fluid</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>cell</td>\n",
       "      <td>pleural fluid</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>cell</td>\n",
       "      <td>pleural fluid</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>76592053</th>\n",
       "      <td>nucleus</td>\n",
       "      <td>brain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>76592054</th>\n",
       "      <td>nucleus</td>\n",
       "      <td>brain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>76592055</th>\n",
       "      <td>nucleus</td>\n",
       "      <td>brain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>76592056</th>\n",
       "      <td>nucleus</td>\n",
       "      <td>brain</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>76592057</th>\n",
       "      <td>nucleus</td>\n",
       "      <td>brain</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>76592058 rows × 2 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "         suspension_type tissue_general\n",
       "0                   cell  pleural fluid\n",
       "1                   cell  pleural fluid\n",
       "2                   cell  pleural fluid\n",
       "3                   cell  pleural fluid\n",
       "4                   cell  pleural fluid\n",
       "...                  ...            ...\n",
       "76592053         nucleus          brain\n",
       "76592054         nucleus          brain\n",
       "76592055         nucleus          brain\n",
       "76592056         nucleus          brain\n",
       "76592057         nucleus          brain\n",
       "\n",
       "[76592058 rows x 2 columns]"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Or concatenate the remaining results into a single Arrow Table,\n",
    "# and the convert to a Pandas DataFrame\n",
    "table = iterator.concat()\n",
    "pandas_obs = table.to_pandas()\n",
    "pandas_obs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "5QhtRerLDduB",
    "outputId": "f6d350d2-9310-4a81-ee49-9dd6d478e8f7"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "suspension_type  tissue_general \n",
       "nucleus          brain              23787347\n",
       "cell             blood              11092030\n",
       "                 lung                6921814\n",
       "                 breast              5390966\n",
       "nucleus          eye                 3579187\n",
       "                                      ...   \n",
       "                 endocrine gland       10961\n",
       "cell             gallbladder            9769\n",
       "                 spinal cord            5916\n",
       "nucleus          skin of body           5327\n",
       "cell             ureter                 2390\n",
       "Length: 76, dtype: int64"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# And you can perform pandas operations useful for your analysis\n",
    "pandas_obs.value_counts()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "gPif5zy3L0NB"
   },
   "source": [
    "#### Summary info and dataset table\n",
    "\n",
    "The same reading operations can be applied to any SOMA data frame in Census. Let's take a look back at the items of `\"census_info\"`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "LwN7a0v3L66V",
    "outputId": "82f82f6b-19d9-49f2-d71b-12bbac3c2963"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Collection 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info' (open for 'r') (4 items)\n",
       "    'datasets': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info/datasets' (unopened)\n",
       "    'summary_cell_counts': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info/summary_cell_counts' (unopened)\n",
       "    'summary': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info/summary' (unopened)\n",
       "    'organisms': 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info/organisms' (unopened)>"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census[\"census_info\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "evjIzkJXMVIK"
   },
   "source": [
    "`\"summary\"` is a data frame with high-level information of this data release."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "ii_tRiOYLFt_",
    "outputId": "26c44b95-431e-4f1d-913a-925620e6495e"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<DataFrame 's3://cellxgene-census-public-us-west-2/cell-census/2024-09-02/soma/census_info/summary' (open for 'r')>"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census[\"census_info\"][\"summary\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 268
    },
    "id": "gtH3rMBIMUWI",
    "outputId": "6d6cc401-4948-4ee3-f2b2-0262c33e56e9"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_joinid</th>\n",
       "      <th>label</th>\n",
       "      <th>value</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0</td>\n",
       "      <td>census_schema_version</td>\n",
       "      <td>2.1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1</td>\n",
       "      <td>census_build_date</td>\n",
       "      <td>2024-09-02</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>2</td>\n",
       "      <td>dataset_schema_version</td>\n",
       "      <td>5.1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>3</td>\n",
       "      <td>total_cell_count</td>\n",
       "      <td>120108090</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>unique_cell_count</td>\n",
       "      <td>64161082</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>5</td>\n",
       "      <td>number_donors_homo_sapiens</td>\n",
       "      <td>19993</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>6</td>\n",
       "      <td>number_donors_mus_musculus</td>\n",
       "      <td>4698</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   soma_joinid                       label       value\n",
       "0            0       census_schema_version       2.1.0\n",
       "1            1           census_build_date  2024-09-02\n",
       "2            2      dataset_schema_version       5.1.0\n",
       "3            3            total_cell_count   120108090\n",
       "4            4           unique_cell_count    64161082\n",
       "5            5  number_donors_homo_sapiens       19993\n",
       "6            6  number_donors_mus_musculus        4698"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census[\"census_info\"][\"summary\"].read().concat().to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "jFf2vxR5Mkqw"
   },
   "source": [
    "And `\"datasets\"` is data frame listing all of the datasets whose single-cell data is contained in this Census release.\n",
    "\n",
    "**🚨 NOTE:** the column `dataset_id` is also present in the cell metadata for joining"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 947
    },
    "id": "54lUHIYeMgwL",
    "outputId": "7209ceab-ea20-440a-d239-e2deb72054cb"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_joinid</th>\n",
       "      <th>citation</th>\n",
       "      <th>collection_id</th>\n",
       "      <th>collection_name</th>\n",
       "      <th>collection_doi</th>\n",
       "      <th>collection_doi_label</th>\n",
       "      <th>dataset_id</th>\n",
       "      <th>dataset_version_id</th>\n",
       "      <th>dataset_title</th>\n",
       "      <th>dataset_h5ad_path</th>\n",
       "      <th>dataset_total_cell_count</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0</td>\n",
       "      <td>Publication: https://doi.org/10.1002/hep4.1854...</td>\n",
       "      <td>44531dd9-1388-4416-a117-af0a99de2294</td>\n",
       "      <td>Single-Cell, Single-Nucleus, and Spatial RNA S...</td>\n",
       "      <td>10.1002/hep4.1854</td>\n",
       "      <td>Andrews et al. (2022) Hepatology Communications</td>\n",
       "      <td>0895c838-e550-48a3-a777-dbcd35d30272</td>\n",
       "      <td>aaab3abd-624a-442e-b62b-3f2edb10b45e</td>\n",
       "      <td>Healthy human liver: B cells</td>\n",
       "      <td>0895c838-e550-48a3-a777-dbcd35d30272.h5ad</td>\n",
       "      <td>146</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1</td>\n",
       "      <td>Publication: https://doi.org/10.1126/sciimmuno...</td>\n",
       "      <td>3a2af25b-2338-4266-aad3-aa8d07473f50</td>\n",
       "      <td>Single-cell analysis of human B cell maturatio...</td>\n",
       "      <td>10.1126/sciimmunol.abe6291</td>\n",
       "      <td>King et al. (2021) Sci. Immunol.</td>\n",
       "      <td>00ff600e-6e2e-4d76-846f-0eec4f0ae417</td>\n",
       "      <td>50c1d621-995d-4386-9fcb-5c70fcdf8d66</td>\n",
       "      <td>Human tonsil nonlymphoid cells scRNA</td>\n",
       "      <td>00ff600e-6e2e-4d76-846f-0eec4f0ae417.h5ad</td>\n",
       "      <td>363</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>2</td>\n",
       "      <td>Publication: https://doi.org/10.1038/s41593-02...</td>\n",
       "      <td>180bff9c-c8a5-4539-b13b-ddbc00d643e6</td>\n",
       "      <td>Molecular characterization of selectively vuln...</td>\n",
       "      <td>10.1038/s41593-020-00764-7</td>\n",
       "      <td>Leng et al. (2021) Nat Neurosci</td>\n",
       "      <td>bdacc907-7c26-419f-8808-969eab3ca2e8</td>\n",
       "      <td>e95b54b1-8656-4fe8-9f53-6fdd97f397ba</td>\n",
       "      <td>Molecular characterization of selectively vuln...</td>\n",
       "      <td>bdacc907-7c26-419f-8808-969eab3ca2e8.h5ad</td>\n",
       "      <td>3799</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>3</td>\n",
       "      <td>Publication: https://doi.org/10.1038/s41467-02...</td>\n",
       "      <td>bf325905-5e8e-42e3-933d-9a9053e9af80</td>\n",
       "      <td>Single-cell Atlas of common variable immunodef...</td>\n",
       "      <td>10.1038/s41467-022-29450-x</td>\n",
       "      <td>Rodríguez-Ubreva et al. (2022) Nat Commun</td>\n",
       "      <td>a5d95a42-0137-496f-8a60-101e17f263c8</td>\n",
       "      <td>d6e742c5-f6e5-42f4-8064-622783542f6b</td>\n",
       "      <td>Steady-state B cells - scRNA-seq</td>\n",
       "      <td>a5d95a42-0137-496f-8a60-101e17f263c8.h5ad</td>\n",
       "      <td>1324</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>Publication: https://doi.org/10.1038/s41590-02...</td>\n",
       "      <td>93eebe82-d8c3-41bc-a906-63b5b5f24a9d</td>\n",
       "      <td>Single-cell proteo-genomic reference maps of t...</td>\n",
       "      <td>10.1038/s41590-021-01059-0</td>\n",
       "      <td>Triana et al. (2021) Nat Immunol</td>\n",
       "      <td>d3566d6a-a455-4a15-980f-45eb29114cab</td>\n",
       "      <td>61f15353-e598-43b5-bb5a-80ac44a0cf0b</td>\n",
       "      <td>blood and bone marrow from a healthy young donor</td>\n",
       "      <td>d3566d6a-a455-4a15-980f-45eb29114cab.h5ad</td>\n",
       "      <td>15502</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>895</th>\n",
       "      <td>895</td>\n",
       "      <td>Publication: https://doi.org/10.1038/s41586-02...</td>\n",
       "      <td>45d5d2c3-bc28-4814-aed6-0bb6f0e11c82</td>\n",
       "      <td>A single-cell transcriptional timelapse of mou...</td>\n",
       "      <td>10.1038/s41586-024-07069-w</td>\n",
       "      <td>Qiu et al. (2024) Nature</td>\n",
       "      <td>0bce33ed-455c-4e12-93f8-b7b04a2de4a1</td>\n",
       "      <td>fa49086f-0e18-4f4b-908d-beefdb00ac3e</td>\n",
       "      <td>Whole dataset: Normalized subset 2</td>\n",
       "      <td>0bce33ed-455c-4e12-93f8-b7b04a2de4a1.h5ad</td>\n",
       "      <td>2863559</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>896</th>\n",
       "      <td>896</td>\n",
       "      <td>Publication: https://doi.org/10.1101/2023.05.0...</td>\n",
       "      <td>1ca90a2d-2943-483d-b678-b809bf464c30</td>\n",
       "      <td>SEA-AD: Seattle Alzheimer’s Disease Brain Cell...</td>\n",
       "      <td>10.1101/2023.05.08.539485</td>\n",
       "      <td>Gabitto et al. (2023) bioRxiv</td>\n",
       "      <td>c2876b1b-06d8-4d96-a56b-5304f815b99a</td>\n",
       "      <td>291ce735-8d18-4a2f-a6bc-98f75f8d6bc0</td>\n",
       "      <td>Whole Taxonomy - MTG: Seattle Alzheimer's Dise...</td>\n",
       "      <td>c2876b1b-06d8-4d96-a56b-5304f815b99a.h5ad</td>\n",
       "      <td>1226855</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>897</th>\n",
       "      <td>897</td>\n",
       "      <td>Publication: https://doi.org/10.1101/2023.05.0...</td>\n",
       "      <td>1ca90a2d-2943-483d-b678-b809bf464c30</td>\n",
       "      <td>SEA-AD: Seattle Alzheimer’s Disease Brain Cell...</td>\n",
       "      <td>10.1101/2023.05.08.539485</td>\n",
       "      <td>Gabitto et al. (2023) bioRxiv</td>\n",
       "      <td>6f7fd0f1-a2ed-4ff1-80d3-33dde731cbc3</td>\n",
       "      <td>e9bffe1d-9f07-4467-9230-c080b362e737</td>\n",
       "      <td>Whole Taxonomy - DLPFC: Seattle Alzheimer's Di...</td>\n",
       "      <td>6f7fd0f1-a2ed-4ff1-80d3-33dde731cbc3.h5ad</td>\n",
       "      <td>1309414</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>898</th>\n",
       "      <td>898</td>\n",
       "      <td>Publication: https://doi.org/10.1038/s41586-02...</td>\n",
       "      <td>45d5d2c3-bc28-4814-aed6-0bb6f0e11c82</td>\n",
       "      <td>A single-cell transcriptional timelapse of mou...</td>\n",
       "      <td>10.1038/s41586-024-07069-w</td>\n",
       "      <td>Qiu et al. (2024) Nature</td>\n",
       "      <td>dcfa2614-7ca7-4d82-814c-350626eccb26</td>\n",
       "      <td>b8cfe635-1cf6-4a6d-8bc0-5059477b9a8c</td>\n",
       "      <td>Major cell cluster: Mesoderm</td>\n",
       "      <td>dcfa2614-7ca7-4d82-814c-350626eccb26.h5ad</td>\n",
       "      <td>3267338</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>899</th>\n",
       "      <td>899</td>\n",
       "      <td>Publication: https://doi.org/10.1038/s41586-02...</td>\n",
       "      <td>45d5d2c3-bc28-4814-aed6-0bb6f0e11c82</td>\n",
       "      <td>A single-cell transcriptional timelapse of mou...</td>\n",
       "      <td>10.1038/s41586-024-07069-w</td>\n",
       "      <td>Qiu et al. (2024) Nature</td>\n",
       "      <td>dcfd4feb-18a3-4b30-81d7-1b0c544a8ab3</td>\n",
       "      <td>2d4c483c-0495-4747-8ab5-c21a955852f8</td>\n",
       "      <td>Whole dataset: Raw counts only</td>\n",
       "      <td>dcfd4feb-18a3-4b30-81d7-1b0c544a8ab3.h5ad</td>\n",
       "      <td>11441407</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>900 rows × 11 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "     soma_joinid                                           citation  \\\n",
       "0              0  Publication: https://doi.org/10.1002/hep4.1854...   \n",
       "1              1  Publication: https://doi.org/10.1126/sciimmuno...   \n",
       "2              2  Publication: https://doi.org/10.1038/s41593-02...   \n",
       "3              3  Publication: https://doi.org/10.1038/s41467-02...   \n",
       "4              4  Publication: https://doi.org/10.1038/s41590-02...   \n",
       "..           ...                                                ...   \n",
       "895          895  Publication: https://doi.org/10.1038/s41586-02...   \n",
       "896          896  Publication: https://doi.org/10.1101/2023.05.0...   \n",
       "897          897  Publication: https://doi.org/10.1101/2023.05.0...   \n",
       "898          898  Publication: https://doi.org/10.1038/s41586-02...   \n",
       "899          899  Publication: https://doi.org/10.1038/s41586-02...   \n",
       "\n",
       "                            collection_id  \\\n",
       "0    44531dd9-1388-4416-a117-af0a99de2294   \n",
       "1    3a2af25b-2338-4266-aad3-aa8d07473f50   \n",
       "2    180bff9c-c8a5-4539-b13b-ddbc00d643e6   \n",
       "3    bf325905-5e8e-42e3-933d-9a9053e9af80   \n",
       "4    93eebe82-d8c3-41bc-a906-63b5b5f24a9d   \n",
       "..                                    ...   \n",
       "895  45d5d2c3-bc28-4814-aed6-0bb6f0e11c82   \n",
       "896  1ca90a2d-2943-483d-b678-b809bf464c30   \n",
       "897  1ca90a2d-2943-483d-b678-b809bf464c30   \n",
       "898  45d5d2c3-bc28-4814-aed6-0bb6f0e11c82   \n",
       "899  45d5d2c3-bc28-4814-aed6-0bb6f0e11c82   \n",
       "\n",
       "                                       collection_name  \\\n",
       "0    Single-Cell, Single-Nucleus, and Spatial RNA S...   \n",
       "1    Single-cell analysis of human B cell maturatio...   \n",
       "2    Molecular characterization of selectively vuln...   \n",
       "3    Single-cell Atlas of common variable immunodef...   \n",
       "4    Single-cell proteo-genomic reference maps of t...   \n",
       "..                                                 ...   \n",
       "895  A single-cell transcriptional timelapse of mou...   \n",
       "896  SEA-AD: Seattle Alzheimer’s Disease Brain Cell...   \n",
       "897  SEA-AD: Seattle Alzheimer’s Disease Brain Cell...   \n",
       "898  A single-cell transcriptional timelapse of mou...   \n",
       "899  A single-cell transcriptional timelapse of mou...   \n",
       "\n",
       "                 collection_doi  \\\n",
       "0             10.1002/hep4.1854   \n",
       "1    10.1126/sciimmunol.abe6291   \n",
       "2    10.1038/s41593-020-00764-7   \n",
       "3    10.1038/s41467-022-29450-x   \n",
       "4    10.1038/s41590-021-01059-0   \n",
       "..                          ...   \n",
       "895  10.1038/s41586-024-07069-w   \n",
       "896   10.1101/2023.05.08.539485   \n",
       "897   10.1101/2023.05.08.539485   \n",
       "898  10.1038/s41586-024-07069-w   \n",
       "899  10.1038/s41586-024-07069-w   \n",
       "\n",
       "                                collection_doi_label  \\\n",
       "0    Andrews et al. (2022) Hepatology Communications   \n",
       "1                   King et al. (2021) Sci. Immunol.   \n",
       "2                    Leng et al. (2021) Nat Neurosci   \n",
       "3          Rodríguez-Ubreva et al. (2022) Nat Commun   \n",
       "4                   Triana et al. (2021) Nat Immunol   \n",
       "..                                               ...   \n",
       "895                         Qiu et al. (2024) Nature   \n",
       "896                    Gabitto et al. (2023) bioRxiv   \n",
       "897                    Gabitto et al. (2023) bioRxiv   \n",
       "898                         Qiu et al. (2024) Nature   \n",
       "899                         Qiu et al. (2024) Nature   \n",
       "\n",
       "                               dataset_id  \\\n",
       "0    0895c838-e550-48a3-a777-dbcd35d30272   \n",
       "1    00ff600e-6e2e-4d76-846f-0eec4f0ae417   \n",
       "2    bdacc907-7c26-419f-8808-969eab3ca2e8   \n",
       "3    a5d95a42-0137-496f-8a60-101e17f263c8   \n",
       "4    d3566d6a-a455-4a15-980f-45eb29114cab   \n",
       "..                                    ...   \n",
       "895  0bce33ed-455c-4e12-93f8-b7b04a2de4a1   \n",
       "896  c2876b1b-06d8-4d96-a56b-5304f815b99a   \n",
       "897  6f7fd0f1-a2ed-4ff1-80d3-33dde731cbc3   \n",
       "898  dcfa2614-7ca7-4d82-814c-350626eccb26   \n",
       "899  dcfd4feb-18a3-4b30-81d7-1b0c544a8ab3   \n",
       "\n",
       "                       dataset_version_id  \\\n",
       "0    aaab3abd-624a-442e-b62b-3f2edb10b45e   \n",
       "1    50c1d621-995d-4386-9fcb-5c70fcdf8d66   \n",
       "2    e95b54b1-8656-4fe8-9f53-6fdd97f397ba   \n",
       "3    d6e742c5-f6e5-42f4-8064-622783542f6b   \n",
       "4    61f15353-e598-43b5-bb5a-80ac44a0cf0b   \n",
       "..                                    ...   \n",
       "895  fa49086f-0e18-4f4b-908d-beefdb00ac3e   \n",
       "896  291ce735-8d18-4a2f-a6bc-98f75f8d6bc0   \n",
       "897  e9bffe1d-9f07-4467-9230-c080b362e737   \n",
       "898  b8cfe635-1cf6-4a6d-8bc0-5059477b9a8c   \n",
       "899  2d4c483c-0495-4747-8ab5-c21a955852f8   \n",
       "\n",
       "                                         dataset_title  \\\n",
       "0                         Healthy human liver: B cells   \n",
       "1                 Human tonsil nonlymphoid cells scRNA   \n",
       "2    Molecular characterization of selectively vuln...   \n",
       "3                     Steady-state B cells - scRNA-seq   \n",
       "4     blood and bone marrow from a healthy young donor   \n",
       "..                                                 ...   \n",
       "895                 Whole dataset: Normalized subset 2   \n",
       "896  Whole Taxonomy - MTG: Seattle Alzheimer's Dise...   \n",
       "897  Whole Taxonomy - DLPFC: Seattle Alzheimer's Di...   \n",
       "898                       Major cell cluster: Mesoderm   \n",
       "899                     Whole dataset: Raw counts only   \n",
       "\n",
       "                             dataset_h5ad_path  dataset_total_cell_count  \n",
       "0    0895c838-e550-48a3-a777-dbcd35d30272.h5ad                       146  \n",
       "1    00ff600e-6e2e-4d76-846f-0eec4f0ae417.h5ad                       363  \n",
       "2    bdacc907-7c26-419f-8808-969eab3ca2e8.h5ad                      3799  \n",
       "3    a5d95a42-0137-496f-8a60-101e17f263c8.h5ad                      1324  \n",
       "4    d3566d6a-a455-4a15-980f-45eb29114cab.h5ad                     15502  \n",
       "..                                         ...                       ...  \n",
       "895  0bce33ed-455c-4e12-93f8-b7b04a2de4a1.h5ad                   2863559  \n",
       "896  c2876b1b-06d8-4d96-a56b-5304f815b99a.h5ad                   1226855  \n",
       "897  6f7fd0f1-a2ed-4ff1-80d3-33dde731cbc3.h5ad                   1309414  \n",
       "898  dcfa2614-7ca7-4d82-814c-350626eccb26.h5ad                   3267338  \n",
       "899  dcfd4feb-18a3-4b30-81d7-1b0c544a8ab3.h5ad                  11441407  \n",
       "\n",
       "[900 rows x 11 columns]"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "census[\"census_info\"][\"datasets\"].read().concat().to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "ihxvtyH4Vz2B"
   },
   "source": [
    "#### Reading gene metadata\n",
    "\n",
    "Reading gene metadata is similar to reading cell metadata. However the location of this data frame is inside the soma Measurement. This was designed to allow for multi-modal data, whereby the same observation (cell) can have a different set of features for each type of measurement (e.g. genes, proteins).\n",
    "\n",
    "To read the gene metadata:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 423
    },
    "id": "wsskajc-VAtD",
    "outputId": "ca82e9ee-5a03-446f-a3c5-b91baec7055d"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_joinid</th>\n",
       "      <th>feature_id</th>\n",
       "      <th>feature_name</th>\n",
       "      <th>feature_length</th>\n",
       "      <th>nnz</th>\n",
       "      <th>n_measured_obs</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0</td>\n",
       "      <td>ENSG00000000003</td>\n",
       "      <td>TSPAN6</td>\n",
       "      <td>4530</td>\n",
       "      <td>4811135</td>\n",
       "      <td>77128603</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1</td>\n",
       "      <td>ENSG00000000005</td>\n",
       "      <td>TNMD</td>\n",
       "      <td>1476</td>\n",
       "      <td>269136</td>\n",
       "      <td>64017621</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>2</td>\n",
       "      <td>ENSG00000000419</td>\n",
       "      <td>DPM1</td>\n",
       "      <td>9276</td>\n",
       "      <td>18420588</td>\n",
       "      <td>77502438</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>3</td>\n",
       "      <td>ENSG00000000457</td>\n",
       "      <td>SCYL3</td>\n",
       "      <td>6883</td>\n",
       "      <td>9268173</td>\n",
       "      <td>76952827</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>ENSG00000000460</td>\n",
       "      <td>C1orf112</td>\n",
       "      <td>5970</td>\n",
       "      <td>6484239</td>\n",
       "      <td>76979490</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60532</th>\n",
       "      <td>60532</td>\n",
       "      <td>ENSG00000288718</td>\n",
       "      <td>ENSG00000288718.1</td>\n",
       "      <td>1070</td>\n",
       "      <td>4</td>\n",
       "      <td>1248980</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60533</th>\n",
       "      <td>60533</td>\n",
       "      <td>ENSG00000288719</td>\n",
       "      <td>ENSG00000288719.1</td>\n",
       "      <td>4252</td>\n",
       "      <td>2826</td>\n",
       "      <td>1248980</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60534</th>\n",
       "      <td>60534</td>\n",
       "      <td>ENSG00000288724</td>\n",
       "      <td>ENSG00000288724.1</td>\n",
       "      <td>625</td>\n",
       "      <td>36</td>\n",
       "      <td>1248980</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60535</th>\n",
       "      <td>60535</td>\n",
       "      <td>ENSG00000290735</td>\n",
       "      <td>ENSG00000290735.1</td>\n",
       "      <td>4103</td>\n",
       "      <td>128</td>\n",
       "      <td>49359</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60536</th>\n",
       "      <td>60536</td>\n",
       "      <td>ENSG00000289810</td>\n",
       "      <td>ENSG00000289810.1</td>\n",
       "      <td>1205</td>\n",
       "      <td>82</td>\n",
       "      <td>48478</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>60537 rows × 6 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "       soma_joinid       feature_id       feature_name  feature_length  \\\n",
       "0                0  ENSG00000000003             TSPAN6            4530   \n",
       "1                1  ENSG00000000005               TNMD            1476   \n",
       "2                2  ENSG00000000419               DPM1            9276   \n",
       "3                3  ENSG00000000457              SCYL3            6883   \n",
       "4                4  ENSG00000000460           C1orf112            5970   \n",
       "...            ...              ...                ...             ...   \n",
       "60532        60532  ENSG00000288718  ENSG00000288718.1            1070   \n",
       "60533        60533  ENSG00000288719  ENSG00000288719.1            4252   \n",
       "60534        60534  ENSG00000288724  ENSG00000288724.1             625   \n",
       "60535        60535  ENSG00000290735  ENSG00000290735.1            4103   \n",
       "60536        60536  ENSG00000289810  ENSG00000289810.1            1205   \n",
       "\n",
       "            nnz  n_measured_obs  \n",
       "0       4811135        77128603  \n",
       "1        269136        64017621  \n",
       "2      18420588        77502438  \n",
       "3       9268173        76952827  \n",
       "4       6484239        76979490  \n",
       "...         ...             ...  \n",
       "60532         4         1248980  \n",
       "60533      2826         1248980  \n",
       "60534        36         1248980  \n",
       "60535       128           49359  \n",
       "60536        82           48478  \n",
       "\n",
       "[60537 rows x 6 columns]"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Build iterator\n",
    "iterator = census[\"census_data\"][\"homo_sapiens\"].ms[\"RNA\"].var.read()\n",
    "\n",
    "# Grab first chunk\n",
    "table_chunk=next(iterator)\n",
    "\n",
    "# Convert to pandas\n",
    "table_chunk.to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "M_0EEQmnNh_6"
   },
   "source": [
    "#### Reading a Data Frame with row filters\n",
    "\n",
    "SOMA makes it easy and efficient to only select a subset of rows based on a query filter. This helps when you want to grab data or metadata only for specific set of cells or genes based on the columns available in these data frames.\n",
    "\n",
    "For example if you want to get the all the the *primary cells* you can add the following.\n",
    "\n",
    "**🚨 NOTE:** cells annotated as `is_primary_data = True` are those marked as the original contribution, as some cells are represented more than once in Census due to their inclusion in multiple datasets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 964
    },
    "id": "2UuuVnlgNnGg",
    "outputId": "a63eabcb-5221-4fa9-d970-896fa9e519d4"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_joinid</th>\n",
       "      <th>dataset_id</th>\n",
       "      <th>assay</th>\n",
       "      <th>assay_ontology_term_id</th>\n",
       "      <th>cell_type</th>\n",
       "      <th>cell_type_ontology_term_id</th>\n",
       "      <th>development_stage</th>\n",
       "      <th>development_stage_ontology_term_id</th>\n",
       "      <th>disease</th>\n",
       "      <th>disease_ontology_term_id</th>\n",
       "      <th>...</th>\n",
       "      <th>tissue</th>\n",
       "      <th>tissue_ontology_term_id</th>\n",
       "      <th>tissue_type</th>\n",
       "      <th>tissue_general</th>\n",
       "      <th>tissue_general_ontology_term_id</th>\n",
       "      <th>raw_sum</th>\n",
       "      <th>nnz</th>\n",
       "      <th>raw_mean_nnz</th>\n",
       "      <th>raw_variance_nnz</th>\n",
       "      <th>n_measured_vars</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>4308</td>\n",
       "      <td>a5d95a42-0137-496f-8a60-101e17f263c8</td>\n",
       "      <td>Smart-seq2</td>\n",
       "      <td>EFO:0008931</td>\n",
       "      <td>naive B cell</td>\n",
       "      <td>CL:0000788</td>\n",
       "      <td>26-year-old human stage</td>\n",
       "      <td>HsapDv:0000120</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>blood</td>\n",
       "      <td>UBERON:0000178</td>\n",
       "      <td>tissue</td>\n",
       "      <td>blood</td>\n",
       "      <td>UBERON:0000178</td>\n",
       "      <td>17691.0</td>\n",
       "      <td>1199</td>\n",
       "      <td>14.754796</td>\n",
       "      <td>624.620960</td>\n",
       "      <td>19149</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>4309</td>\n",
       "      <td>a5d95a42-0137-496f-8a60-101e17f263c8</td>\n",
       "      <td>Smart-seq2</td>\n",
       "      <td>EFO:0008931</td>\n",
       "      <td>naive B cell</td>\n",
       "      <td>CL:0000788</td>\n",
       "      <td>26-year-old human stage</td>\n",
       "      <td>HsapDv:0000120</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>blood</td>\n",
       "      <td>UBERON:0000178</td>\n",
       "      <td>tissue</td>\n",
       "      <td>blood</td>\n",
       "      <td>UBERON:0000178</td>\n",
       "      <td>13612.0</td>\n",
       "      <td>841</td>\n",
       "      <td>16.185493</td>\n",
       "      <td>1394.944123</td>\n",
       "      <td>19149</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>4310</td>\n",
       "      <td>a5d95a42-0137-496f-8a60-101e17f263c8</td>\n",
       "      <td>Smart-seq2</td>\n",
       "      <td>EFO:0008931</td>\n",
       "      <td>naive B cell</td>\n",
       "      <td>CL:0000788</td>\n",
       "      <td>26-year-old human stage</td>\n",
       "      <td>HsapDv:0000120</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>blood</td>\n",
       "      <td>UBERON:0000178</td>\n",
       "      <td>tissue</td>\n",
       "      <td>blood</td>\n",
       "      <td>UBERON:0000178</td>\n",
       "      <td>126774.0</td>\n",
       "      <td>1683</td>\n",
       "      <td>75.326203</td>\n",
       "      <td>42215.146798</td>\n",
       "      <td>19149</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>4311</td>\n",
       "      <td>a5d95a42-0137-496f-8a60-101e17f263c8</td>\n",
       "      <td>Smart-seq2</td>\n",
       "      <td>EFO:0008931</td>\n",
       "      <td>naive B cell</td>\n",
       "      <td>CL:0000788</td>\n",
       "      <td>26-year-old human stage</td>\n",
       "      <td>HsapDv:0000120</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>blood</td>\n",
       "      <td>UBERON:0000178</td>\n",
       "      <td>tissue</td>\n",
       "      <td>blood</td>\n",
       "      <td>UBERON:0000178</td>\n",
       "      <td>14370.0</td>\n",
       "      <td>371</td>\n",
       "      <td>38.733154</td>\n",
       "      <td>4639.990763</td>\n",
       "      <td>19149</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4312</td>\n",
       "      <td>a5d95a42-0137-496f-8a60-101e17f263c8</td>\n",
       "      <td>Smart-seq2</td>\n",
       "      <td>EFO:0008931</td>\n",
       "      <td>naive B cell</td>\n",
       "      <td>CL:0000788</td>\n",
       "      <td>26-year-old human stage</td>\n",
       "      <td>HsapDv:0000120</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>blood</td>\n",
       "      <td>UBERON:0000178</td>\n",
       "      <td>tissue</td>\n",
       "      <td>blood</td>\n",
       "      <td>UBERON:0000178</td>\n",
       "      <td>13738.0</td>\n",
       "      <td>507</td>\n",
       "      <td>27.096647</td>\n",
       "      <td>3874.079574</td>\n",
       "      <td>19149</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>107369</th>\n",
       "      <td>286422</td>\n",
       "      <td>dc30c3ec-46d6-4cd8-8ec1-b544a3d0f503</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>neuron</td>\n",
       "      <td>CL:0000540</td>\n",
       "      <td>44-year-old human stage</td>\n",
       "      <td>HsapDv:0000138</td>\n",
       "      <td>multiple sclerosis</td>\n",
       "      <td>MONDO:0005301</td>\n",
       "      <td>...</td>\n",
       "      <td>brain</td>\n",
       "      <td>UBERON:0000955</td>\n",
       "      <td>tissue</td>\n",
       "      <td>brain</td>\n",
       "      <td>UBERON:0000955</td>\n",
       "      <td>2105.0</td>\n",
       "      <td>1357</td>\n",
       "      <td>1.551216</td>\n",
       "      <td>4.489447</td>\n",
       "      <td>20383</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>107370</th>\n",
       "      <td>286423</td>\n",
       "      <td>dc30c3ec-46d6-4cd8-8ec1-b544a3d0f503</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>neuron</td>\n",
       "      <td>CL:0000540</td>\n",
       "      <td>44-year-old human stage</td>\n",
       "      <td>HsapDv:0000138</td>\n",
       "      <td>multiple sclerosis</td>\n",
       "      <td>MONDO:0005301</td>\n",
       "      <td>...</td>\n",
       "      <td>brain</td>\n",
       "      <td>UBERON:0000955</td>\n",
       "      <td>tissue</td>\n",
       "      <td>brain</td>\n",
       "      <td>UBERON:0000955</td>\n",
       "      <td>1791.0</td>\n",
       "      <td>1168</td>\n",
       "      <td>1.533390</td>\n",
       "      <td>2.197684</td>\n",
       "      <td>20383</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>107371</th>\n",
       "      <td>286424</td>\n",
       "      <td>dc30c3ec-46d6-4cd8-8ec1-b544a3d0f503</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>neuron</td>\n",
       "      <td>CL:0000540</td>\n",
       "      <td>44-year-old human stage</td>\n",
       "      <td>HsapDv:0000138</td>\n",
       "      <td>multiple sclerosis</td>\n",
       "      <td>MONDO:0005301</td>\n",
       "      <td>...</td>\n",
       "      <td>brain</td>\n",
       "      <td>UBERON:0000955</td>\n",
       "      <td>tissue</td>\n",
       "      <td>brain</td>\n",
       "      <td>UBERON:0000955</td>\n",
       "      <td>4989.0</td>\n",
       "      <td>2761</td>\n",
       "      <td>1.806954</td>\n",
       "      <td>4.679024</td>\n",
       "      <td>20383</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>107372</th>\n",
       "      <td>286425</td>\n",
       "      <td>dc30c3ec-46d6-4cd8-8ec1-b544a3d0f503</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>neuron</td>\n",
       "      <td>CL:0000540</td>\n",
       "      <td>44-year-old human stage</td>\n",
       "      <td>HsapDv:0000138</td>\n",
       "      <td>multiple sclerosis</td>\n",
       "      <td>MONDO:0005301</td>\n",
       "      <td>...</td>\n",
       "      <td>brain</td>\n",
       "      <td>UBERON:0000955</td>\n",
       "      <td>tissue</td>\n",
       "      <td>brain</td>\n",
       "      <td>UBERON:0000955</td>\n",
       "      <td>5201.0</td>\n",
       "      <td>2811</td>\n",
       "      <td>1.850231</td>\n",
       "      <td>4.767241</td>\n",
       "      <td>20383</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>107373</th>\n",
       "      <td>286426</td>\n",
       "      <td>dc30c3ec-46d6-4cd8-8ec1-b544a3d0f503</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>neuron</td>\n",
       "      <td>CL:0000540</td>\n",
       "      <td>44-year-old human stage</td>\n",
       "      <td>HsapDv:0000138</td>\n",
       "      <td>multiple sclerosis</td>\n",
       "      <td>MONDO:0005301</td>\n",
       "      <td>...</td>\n",
       "      <td>brain</td>\n",
       "      <td>UBERON:0000955</td>\n",
       "      <td>tissue</td>\n",
       "      <td>brain</td>\n",
       "      <td>UBERON:0000955</td>\n",
       "      <td>5850.0</td>\n",
       "      <td>3008</td>\n",
       "      <td>1.944814</td>\n",
       "      <td>8.650096</td>\n",
       "      <td>20383</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>107374 rows × 28 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "        soma_joinid                            dataset_id       assay  \\\n",
       "0              4308  a5d95a42-0137-496f-8a60-101e17f263c8  Smart-seq2   \n",
       "1              4309  a5d95a42-0137-496f-8a60-101e17f263c8  Smart-seq2   \n",
       "2              4310  a5d95a42-0137-496f-8a60-101e17f263c8  Smart-seq2   \n",
       "3              4311  a5d95a42-0137-496f-8a60-101e17f263c8  Smart-seq2   \n",
       "4              4312  a5d95a42-0137-496f-8a60-101e17f263c8  Smart-seq2   \n",
       "...             ...                                   ...         ...   \n",
       "107369       286422  dc30c3ec-46d6-4cd8-8ec1-b544a3d0f503   10x 3' v2   \n",
       "107370       286423  dc30c3ec-46d6-4cd8-8ec1-b544a3d0f503   10x 3' v2   \n",
       "107371       286424  dc30c3ec-46d6-4cd8-8ec1-b544a3d0f503   10x 3' v2   \n",
       "107372       286425  dc30c3ec-46d6-4cd8-8ec1-b544a3d0f503   10x 3' v2   \n",
       "107373       286426  dc30c3ec-46d6-4cd8-8ec1-b544a3d0f503   10x 3' v2   \n",
       "\n",
       "       assay_ontology_term_id     cell_type cell_type_ontology_term_id  \\\n",
       "0                 EFO:0008931  naive B cell                 CL:0000788   \n",
       "1                 EFO:0008931  naive B cell                 CL:0000788   \n",
       "2                 EFO:0008931  naive B cell                 CL:0000788   \n",
       "3                 EFO:0008931  naive B cell                 CL:0000788   \n",
       "4                 EFO:0008931  naive B cell                 CL:0000788   \n",
       "...                       ...           ...                        ...   \n",
       "107369            EFO:0009899        neuron                 CL:0000540   \n",
       "107370            EFO:0009899        neuron                 CL:0000540   \n",
       "107371            EFO:0009899        neuron                 CL:0000540   \n",
       "107372            EFO:0009899        neuron                 CL:0000540   \n",
       "107373            EFO:0009899        neuron                 CL:0000540   \n",
       "\n",
       "              development_stage development_stage_ontology_term_id  \\\n",
       "0       26-year-old human stage                     HsapDv:0000120   \n",
       "1       26-year-old human stage                     HsapDv:0000120   \n",
       "2       26-year-old human stage                     HsapDv:0000120   \n",
       "3       26-year-old human stage                     HsapDv:0000120   \n",
       "4       26-year-old human stage                     HsapDv:0000120   \n",
       "...                         ...                                ...   \n",
       "107369  44-year-old human stage                     HsapDv:0000138   \n",
       "107370  44-year-old human stage                     HsapDv:0000138   \n",
       "107371  44-year-old human stage                     HsapDv:0000138   \n",
       "107372  44-year-old human stage                     HsapDv:0000138   \n",
       "107373  44-year-old human stage                     HsapDv:0000138   \n",
       "\n",
       "                   disease disease_ontology_term_id  ... tissue  \\\n",
       "0                   normal             PATO:0000461  ...  blood   \n",
       "1                   normal             PATO:0000461  ...  blood   \n",
       "2                   normal             PATO:0000461  ...  blood   \n",
       "3                   normal             PATO:0000461  ...  blood   \n",
       "4                   normal             PATO:0000461  ...  blood   \n",
       "...                    ...                      ...  ...    ...   \n",
       "107369  multiple sclerosis            MONDO:0005301  ...  brain   \n",
       "107370  multiple sclerosis            MONDO:0005301  ...  brain   \n",
       "107371  multiple sclerosis            MONDO:0005301  ...  brain   \n",
       "107372  multiple sclerosis            MONDO:0005301  ...  brain   \n",
       "107373  multiple sclerosis            MONDO:0005301  ...  brain   \n",
       "\n",
       "        tissue_ontology_term_id tissue_type tissue_general  \\\n",
       "0                UBERON:0000178      tissue          blood   \n",
       "1                UBERON:0000178      tissue          blood   \n",
       "2                UBERON:0000178      tissue          blood   \n",
       "3                UBERON:0000178      tissue          blood   \n",
       "4                UBERON:0000178      tissue          blood   \n",
       "...                         ...         ...            ...   \n",
       "107369           UBERON:0000955      tissue          brain   \n",
       "107370           UBERON:0000955      tissue          brain   \n",
       "107371           UBERON:0000955      tissue          brain   \n",
       "107372           UBERON:0000955      tissue          brain   \n",
       "107373           UBERON:0000955      tissue          brain   \n",
       "\n",
       "       tissue_general_ontology_term_id   raw_sum   nnz raw_mean_nnz  \\\n",
       "0                       UBERON:0000178   17691.0  1199    14.754796   \n",
       "1                       UBERON:0000178   13612.0   841    16.185493   \n",
       "2                       UBERON:0000178  126774.0  1683    75.326203   \n",
       "3                       UBERON:0000178   14370.0   371    38.733154   \n",
       "4                       UBERON:0000178   13738.0   507    27.096647   \n",
       "...                                ...       ...   ...          ...   \n",
       "107369                  UBERON:0000955    2105.0  1357     1.551216   \n",
       "107370                  UBERON:0000955    1791.0  1168     1.533390   \n",
       "107371                  UBERON:0000955    4989.0  2761     1.806954   \n",
       "107372                  UBERON:0000955    5201.0  2811     1.850231   \n",
       "107373                  UBERON:0000955    5850.0  3008     1.944814   \n",
       "\n",
       "       raw_variance_nnz n_measured_vars  \n",
       "0            624.620960           19149  \n",
       "1           1394.944123           19149  \n",
       "2          42215.146798           19149  \n",
       "3           4639.990763           19149  \n",
       "4           3874.079574           19149  \n",
       "...                 ...             ...  \n",
       "107369         4.489447           20383  \n",
       "107370         2.197684           20383  \n",
       "107371         4.679024           20383  \n",
       "107372         4.767241           20383  \n",
       "107373         8.650096           20383  \n",
       "\n",
       "[107374 rows x 28 columns]"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Build iterator with a query filter\n",
    "iterator = census[\"census_data\"][\"homo_sapiens\"].obs.read(value_filter = \"is_primary_data == True\")\n",
    "\n",
    "# Grab first chunk\n",
    "table_chunk=next(iterator)\n",
    "\n",
    "# Convert to pandas\n",
    "table_chunk.to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "e6-UJc_RT7do"
   },
   "source": [
    "The `value_filter` works similalrly to a Pandas `query` interface. It can take a string of which is evaluated as a boolean condition and selects rows that meet the criteria.\n",
    "\n",
    "We can then use other operators to build complex queries, for example all epithelial cells from lung that are primary representations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 423
    },
    "id": "DPnPc5wkT0kL",
    "outputId": "dc29d6c7-9213-4c01-f12b-0c3495ee8a38"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>assay</th>\n",
       "      <th>is_primary_data</th>\n",
       "      <th>cell_type</th>\n",
       "      <th>tissue_general</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Smart-seq2</td>\n",
       "      <td>True</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>lung</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Smart-seq2</td>\n",
       "      <td>True</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>lung</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Smart-seq2</td>\n",
       "      <td>True</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>lung</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Smart-seq2</td>\n",
       "      <td>True</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>lung</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Smart-seq2</td>\n",
       "      <td>True</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>lung</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>59361</th>\n",
       "      <td>10x 5' v2</td>\n",
       "      <td>True</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>lung</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>59362</th>\n",
       "      <td>10x 5' v2</td>\n",
       "      <td>True</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>lung</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>59363</th>\n",
       "      <td>10x 5' v2</td>\n",
       "      <td>True</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>lung</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>59364</th>\n",
       "      <td>10x 5' v2</td>\n",
       "      <td>True</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>lung</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>59365</th>\n",
       "      <td>10x 5' v2</td>\n",
       "      <td>True</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>lung</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>59366 rows × 4 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "            assay  is_primary_data        cell_type tissue_general\n",
       "0      Smart-seq2             True  epithelial cell           lung\n",
       "1      Smart-seq2             True  epithelial cell           lung\n",
       "2      Smart-seq2             True  epithelial cell           lung\n",
       "3      Smart-seq2             True  epithelial cell           lung\n",
       "4      Smart-seq2             True  epithelial cell           lung\n",
       "...           ...              ...              ...            ...\n",
       "59361   10x 5' v2             True  epithelial cell           lung\n",
       "59362   10x 5' v2             True  epithelial cell           lung\n",
       "59363   10x 5' v2             True  epithelial cell           lung\n",
       "59364   10x 5' v2             True  epithelial cell           lung\n",
       "59365   10x 5' v2             True  epithelial cell           lung\n",
       "\n",
       "[59366 rows x 4 columns]"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "filter = \"is_primary_data == True and cell_type == 'epithelial cell' and tissue_general == 'lung'\"\n",
    "columns = [\"assay\"]\n",
    "\n",
    "# Build iterator\n",
    "iterator = census[\"census_data\"][\"homo_sapiens\"].obs.read(\n",
    "    value_filter = filter,\n",
    "    column_names = columns,\n",
    ")\n",
    "\n",
    "# Grab first chunk\n",
    "table_chunk=next(iterator)\n",
    "\n",
    "# Convert to pandas\n",
    "table_chunk.to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "aBo0cnZ1Y2pg"
   },
   "source": [
    "#### Reading a Data Frame with coordinates\n",
    "\n",
    "Finally, you can also read a data frame via coordinates. This is useful when testing code with a small set of data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 599
    },
    "id": "lSW63IWMZXyK",
    "outputId": "38cf90ae-d774-4cd8-fdf0-4fd24bdd48c3"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_joinid</th>\n",
       "      <th>dataset_id</th>\n",
       "      <th>assay</th>\n",
       "      <th>assay_ontology_term_id</th>\n",
       "      <th>cell_type</th>\n",
       "      <th>cell_type_ontology_term_id</th>\n",
       "      <th>development_stage</th>\n",
       "      <th>development_stage_ontology_term_id</th>\n",
       "      <th>disease</th>\n",
       "      <th>disease_ontology_term_id</th>\n",
       "      <th>...</th>\n",
       "      <th>tissue</th>\n",
       "      <th>tissue_ontology_term_id</th>\n",
       "      <th>tissue_type</th>\n",
       "      <th>tissue_general</th>\n",
       "      <th>tissue_general_ontology_term_id</th>\n",
       "      <th>raw_sum</th>\n",
       "      <th>nnz</th>\n",
       "      <th>raw_mean_nnz</th>\n",
       "      <th>raw_variance_nnz</th>\n",
       "      <th>n_measured_vars</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0</td>\n",
       "      <td>0895c838-e550-48a3-a777-dbcd35d30272</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>plasma cell</td>\n",
       "      <td>CL:0000786</td>\n",
       "      <td>human adult stage</td>\n",
       "      <td>HsapDv:0000087</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>caudate lobe of liver</td>\n",
       "      <td>UBERON:0001117</td>\n",
       "      <td>tissue</td>\n",
       "      <td>liver</td>\n",
       "      <td>UBERON:0002107</td>\n",
       "      <td>1742.0</td>\n",
       "      <td>221</td>\n",
       "      <td>7.882353</td>\n",
       "      <td>6661.549733</td>\n",
       "      <td>13696</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1</td>\n",
       "      <td>0895c838-e550-48a3-a777-dbcd35d30272</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>mature B cell</td>\n",
       "      <td>CL:0000785</td>\n",
       "      <td>human adult stage</td>\n",
       "      <td>HsapDv:0000087</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>caudate lobe of liver</td>\n",
       "      <td>UBERON:0001117</td>\n",
       "      <td>tissue</td>\n",
       "      <td>liver</td>\n",
       "      <td>UBERON:0002107</td>\n",
       "      <td>278.0</td>\n",
       "      <td>143</td>\n",
       "      <td>1.944056</td>\n",
       "      <td>3.616567</td>\n",
       "      <td>13696</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>2</td>\n",
       "      <td>0895c838-e550-48a3-a777-dbcd35d30272</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>plasma cell</td>\n",
       "      <td>CL:0000786</td>\n",
       "      <td>human adult stage</td>\n",
       "      <td>HsapDv:0000087</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>caudate lobe of liver</td>\n",
       "      <td>UBERON:0001117</td>\n",
       "      <td>tissue</td>\n",
       "      <td>liver</td>\n",
       "      <td>UBERON:0002107</td>\n",
       "      <td>3723.0</td>\n",
       "      <td>709</td>\n",
       "      <td>5.251058</td>\n",
       "      <td>2959.510327</td>\n",
       "      <td>13696</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>3</td>\n",
       "      <td>0895c838-e550-48a3-a777-dbcd35d30272</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>mature B cell</td>\n",
       "      <td>CL:0000785</td>\n",
       "      <td>human adult stage</td>\n",
       "      <td>HsapDv:0000087</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>caudate lobe of liver</td>\n",
       "      <td>UBERON:0001117</td>\n",
       "      <td>tissue</td>\n",
       "      <td>liver</td>\n",
       "      <td>UBERON:0002107</td>\n",
       "      <td>351.0</td>\n",
       "      <td>179</td>\n",
       "      <td>1.960894</td>\n",
       "      <td>8.487226</td>\n",
       "      <td>13696</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>0895c838-e550-48a3-a777-dbcd35d30272</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>mature B cell</td>\n",
       "      <td>CL:0000785</td>\n",
       "      <td>human adult stage</td>\n",
       "      <td>HsapDv:0000087</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>caudate lobe of liver</td>\n",
       "      <td>UBERON:0001117</td>\n",
       "      <td>tissue</td>\n",
       "      <td>liver</td>\n",
       "      <td>UBERON:0002107</td>\n",
       "      <td>605.0</td>\n",
       "      <td>275</td>\n",
       "      <td>2.200000</td>\n",
       "      <td>18.978102</td>\n",
       "      <td>13696</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>5</td>\n",
       "      <td>0895c838-e550-48a3-a777-dbcd35d30272</td>\n",
       "      <td>10x 3' v2</td>\n",
       "      <td>EFO:0009899</td>\n",
       "      <td>mature B cell</td>\n",
       "      <td>CL:0000785</td>\n",
       "      <td>human adult stage</td>\n",
       "      <td>HsapDv:0000087</td>\n",
       "      <td>normal</td>\n",
       "      <td>PATO:0000461</td>\n",
       "      <td>...</td>\n",
       "      <td>caudate lobe of liver</td>\n",
       "      <td>UBERON:0001117</td>\n",
       "      <td>tissue</td>\n",
       "      <td>liver</td>\n",
       "      <td>UBERON:0002107</td>\n",
       "      <td>338.0</td>\n",
       "      <td>164</td>\n",
       "      <td>2.060976</td>\n",
       "      <td>11.444112</td>\n",
       "      <td>13696</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>6 rows × 28 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "   soma_joinid                            dataset_id      assay  \\\n",
       "0            0  0895c838-e550-48a3-a777-dbcd35d30272  10x 3' v2   \n",
       "1            1  0895c838-e550-48a3-a777-dbcd35d30272  10x 3' v2   \n",
       "2            2  0895c838-e550-48a3-a777-dbcd35d30272  10x 3' v2   \n",
       "3            3  0895c838-e550-48a3-a777-dbcd35d30272  10x 3' v2   \n",
       "4            4  0895c838-e550-48a3-a777-dbcd35d30272  10x 3' v2   \n",
       "5            5  0895c838-e550-48a3-a777-dbcd35d30272  10x 3' v2   \n",
       "\n",
       "  assay_ontology_term_id      cell_type cell_type_ontology_term_id  \\\n",
       "0            EFO:0009899    plasma cell                 CL:0000786   \n",
       "1            EFO:0009899  mature B cell                 CL:0000785   \n",
       "2            EFO:0009899    plasma cell                 CL:0000786   \n",
       "3            EFO:0009899  mature B cell                 CL:0000785   \n",
       "4            EFO:0009899  mature B cell                 CL:0000785   \n",
       "5            EFO:0009899  mature B cell                 CL:0000785   \n",
       "\n",
       "   development_stage development_stage_ontology_term_id disease  \\\n",
       "0  human adult stage                     HsapDv:0000087  normal   \n",
       "1  human adult stage                     HsapDv:0000087  normal   \n",
       "2  human adult stage                     HsapDv:0000087  normal   \n",
       "3  human adult stage                     HsapDv:0000087  normal   \n",
       "4  human adult stage                     HsapDv:0000087  normal   \n",
       "5  human adult stage                     HsapDv:0000087  normal   \n",
       "\n",
       "  disease_ontology_term_id  ...                 tissue  \\\n",
       "0             PATO:0000461  ...  caudate lobe of liver   \n",
       "1             PATO:0000461  ...  caudate lobe of liver   \n",
       "2             PATO:0000461  ...  caudate lobe of liver   \n",
       "3             PATO:0000461  ...  caudate lobe of liver   \n",
       "4             PATO:0000461  ...  caudate lobe of liver   \n",
       "5             PATO:0000461  ...  caudate lobe of liver   \n",
       "\n",
       "   tissue_ontology_term_id tissue_type tissue_general  \\\n",
       "0           UBERON:0001117      tissue          liver   \n",
       "1           UBERON:0001117      tissue          liver   \n",
       "2           UBERON:0001117      tissue          liver   \n",
       "3           UBERON:0001117      tissue          liver   \n",
       "4           UBERON:0001117      tissue          liver   \n",
       "5           UBERON:0001117      tissue          liver   \n",
       "\n",
       "  tissue_general_ontology_term_id raw_sum  nnz raw_mean_nnz raw_variance_nnz  \\\n",
       "0                  UBERON:0002107  1742.0  221     7.882353      6661.549733   \n",
       "1                  UBERON:0002107   278.0  143     1.944056         3.616567   \n",
       "2                  UBERON:0002107  3723.0  709     5.251058      2959.510327   \n",
       "3                  UBERON:0002107   351.0  179     1.960894         8.487226   \n",
       "4                  UBERON:0002107   605.0  275     2.200000        18.978102   \n",
       "5                  UBERON:0002107   338.0  164     2.060976        11.444112   \n",
       "\n",
       "  n_measured_vars  \n",
       "0           13696  \n",
       "1           13696  \n",
       "2           13696  \n",
       "3           13696  \n",
       "4           13696  \n",
       "5           13696  \n",
       "\n",
       "[6 rows x 28 columns]"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    " census[\"census_data\"][\"homo_sapiens\"].obs.read(coords=([0,1,2,3,4,5],)).concat().to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "A3um9EnZa1_N"
   },
   "source": [
    "### Reading expression data\n",
    "\n",
    "The single-cell expression data is stored as a SOMA `SparseNDArray`. This is a sparse representation of the data that enables efficient storage and access for data with a high number of missing values.\n",
    "\n",
    "Currently Census has two expression layers:\n",
    "\n",
    "- Raw counts.\n",
    "- Normalized counts by library size.\n",
    "\n",
    "For human, these are located in the \\\"RNA\\\" measurement at:\n",
    "\n",
    "- `[\"census_data\"][\"homo_sapiens\"].ms[\"RNA\"].X[\"raw\"]`\n",
    "- `[\"census_data\"][\"homo_sapiens\"].ms[\"RNA\"].X[\"normalized\"]`\n",
    "\n",
    "Reading these data works similarly to reading data frames. The main difference is that there are different types of iterators available. In this workshop we'll focus on Arrow table iterators.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 423
    },
    "id": "CgFG-RPwZfJ1",
    "outputId": "ad6e187f-bd68-42fe-c38e-2e3e1d7ab068"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_dim_0</th>\n",
       "      <th>soma_dim_1</th>\n",
       "      <th>soma_data</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0</td>\n",
       "      <td>176</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>0</td>\n",
       "      <td>229</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>0</td>\n",
       "      <td>249</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>0</td>\n",
       "      <td>409</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>0</td>\n",
       "      <td>451</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>134212</th>\n",
       "      <td>1146</td>\n",
       "      <td>91</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>134213</th>\n",
       "      <td>1146</td>\n",
       "      <td>99</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>134214</th>\n",
       "      <td>1146</td>\n",
       "      <td>104</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>134215</th>\n",
       "      <td>1146</td>\n",
       "      <td>106</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>134216</th>\n",
       "      <td>1146</td>\n",
       "      <td>108</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>134217 rows × 3 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "        soma_dim_0  soma_dim_1  soma_data\n",
       "0                0         176        1.0\n",
       "1                0         229        1.0\n",
       "2                0         249        1.0\n",
       "3                0         409        1.0\n",
       "4                0         451        1.0\n",
       "...            ...         ...        ...\n",
       "134212        1146          91        1.0\n",
       "134213        1146          99        1.0\n",
       "134214        1146         104        1.0\n",
       "134215        1146         106        1.0\n",
       "134216        1146         108        1.0\n",
       "\n",
       "[134217 rows x 3 columns]"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Creater a reader\n",
    "reader = census[\"census_data\"][\"homo_sapiens\"].ms[\"RNA\"].X[\"raw\"].read()\n",
    "\n",
    "# Build an iterator of Arrow tables\n",
    "iterator = reader.tables()\n",
    "\n",
    "# Grab first chunk\n",
    "table_chunk=next(iterator)\n",
    "\n",
    "# Convert to pandas\n",
    "table_chunk.to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "kbZM_1ckc-SS"
   },
   "source": [
    "This produces an expression matrix in COO sparse format:\n",
    "\n",
    "- `soma_dim_0` - the ID for the cell.\n",
    "- `soma_dim_1` - the ID for the gene.  \n",
    "- `soma_data` - the expression value.\n",
    "\n",
    "You can then transform this table to other useful representations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "AXLBxsurcYYV",
    "outputId": "1a33acf4-ea37-4a2f-cf23-9448c8f2e595"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<1147x2048 sparse matrix of type '<class 'numpy.float32'>'\n",
       "\twith 134217 stored elements in COOrdinate format>"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# SciPy formats\n",
    "scipy_coo = scipy.sparse.coo_matrix((table_chunk[\"soma_data\"], (table_chunk[\"soma_dim_0\"], table_chunk[\"soma_dim_1\"])))\n",
    "scipy_coo"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "sVzKYxEldu8R",
    "outputId": "d5076122-3084-4cf5-801e-ac05a4b97a81"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[0., 0., 0., ..., 0., 0., 0.],\n",
       "       [0., 0., 0., ..., 0., 0., 0.],\n",
       "       [0., 0., 0., ..., 0., 0., 0.],\n",
       "       ...,\n",
       "       [0., 0., 0., ..., 0., 0., 0.],\n",
       "       [0., 0., 0., ..., 0., 0., 0.],\n",
       "       [0., 0., 0., ..., 0., 0., 0.]], dtype=float32)"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Numpy formats\n",
    "scipy_coo.toarray()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "uRfFYNXpefY_"
   },
   "source": [
    "**🚨 NOTE:** Reading the expression matrix in isolation is usually not very useful without cell and gene metadata. We'll cover that in the next section"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "g50HINMxfJzi"
   },
   "source": [
    "### Atomic reading of expression data AND metadata\n",
    "\n",
    "SOMA provides a convenient interface to query single-cell data in a metadata-aware fashion using `ExperimentAxisQuery`.\n",
    "\n",
    "We covered in a previous section the concept of an SOMA `Experiment`, as a class that represents a single-cell experiment. It always contains two objects:\n",
    "   - `obs`: a `DataFrame` with primary annotations on the observation axis.\n",
    "   - `ms`: a `Collection` of measurements, each composed of `X` matrices and axis annotation matrices or data frames (e.g. `var`, `varm`, `obsm`, etc).\n",
    "\n",
    "**🚨 NOTE:** An `ExperimentAxisQuery` enables users to query and slice an `Experiment` single-cell data and metadata using coordinates or value filters on the axes, similar to how a SOMA `DataFrame` is queried."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "xTq0XxuwLxVy"
   },
   "source": [
    "#### Creating an `ExperimentAxisQuery`\n",
    "\n",
    "To create an `ExperimentAxisQuery` you can call the method `.axis_query()` of a SOMA `Experiment`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "id": "kbca9zAVeaDB"
   },
   "outputs": [],
   "source": [
    "cell_filter = \"tissue_general == 'tongue'\"\n",
    "gene_filter = \"feature_name in ['PECAM1', 'DCN', 'KRT13']\"\n",
    "\n",
    "query = census[\"census_data\"][\"homo_sapiens\"].axis_query(\n",
    "    measurement_name = \"RNA\",\n",
    "    obs_query = tiledbsoma.AxisQuery(value_filter = cell_filter),\n",
    "    var_query = tiledbsoma.AxisQuery(value_filter = gene_filter),\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "g-O_T2-EhkzX",
    "outputId": "9ddc2582-2cff-4867-eb2d-a664066ffeed"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<somacore.query.query.ExperimentAxisQuery at 0x72fbe02fd0d0>"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "spSrAvCriZ3E"
   },
   "source": [
    "#### Inspecting the query results\n",
    "\n",
    "Once the `ExperimentAxisQuery` is created you have access to a variety of convenient methods to fetch data or useful information about your query."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "t6GTjX0Qhn1v",
    "outputId": "36a7277d-672a-4587-e2b3-05333d3f27b5"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(45060, 3)"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Number of (cells, genes) in query\n",
    "query.n_obs, query.n_vars"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 423
    },
    "id": "U57OfzXAis4j",
    "outputId": "1ad149be-e132-4125-c033-6cd5632fe642"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>cell_type</th>\n",
       "      <th>tissue_general</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>45055</th>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>45056</th>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>45057</th>\n",
       "      <td>basal cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>45058</th>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>45059</th>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>45060 rows × 2 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "             cell_type tissue_general\n",
       "0      epithelial cell         tongue\n",
       "1      epithelial cell         tongue\n",
       "2      epithelial cell         tongue\n",
       "3      epithelial cell         tongue\n",
       "4      epithelial cell         tongue\n",
       "...                ...            ...\n",
       "45055     keratinocyte         tongue\n",
       "45056     keratinocyte         tongue\n",
       "45057       basal cell         tongue\n",
       "45058     keratinocyte         tongue\n",
       "45059     keratinocyte         tongue\n",
       "\n",
       "[45060 rows x 2 columns]"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Grabbing cell metadata\n",
    "iterator = query.obs(column_names = [\"cell_type\", \"tissue_general\"])\n",
    "iterator.concat().to_pandas()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 143
    },
    "id": "c-CnS7uRi-5n",
    "outputId": "be5ea7c9-3672-4d1b-f97f-dfa22391c65a"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_joinid</th>\n",
       "      <th>feature_id</th>\n",
       "      <th>feature_name</th>\n",
       "      <th>feature_length</th>\n",
       "      <th>nnz</th>\n",
       "      <th>n_measured_obs</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>299</td>\n",
       "      <td>ENSG00000011465</td>\n",
       "      <td>DCN</td>\n",
       "      <td>12941</td>\n",
       "      <td>7905731</td>\n",
       "      <td>75319655</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>12852</td>\n",
       "      <td>ENSG00000171401</td>\n",
       "      <td>KRT13</td>\n",
       "      <td>2913</td>\n",
       "      <td>712612</td>\n",
       "      <td>62927690</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>28763</td>\n",
       "      <td>ENSG00000261371</td>\n",
       "      <td>PECAM1</td>\n",
       "      <td>7741</td>\n",
       "      <td>7739030</td>\n",
       "      <td>64633082</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   soma_joinid       feature_id feature_name  feature_length      nnz  \\\n",
       "0          299  ENSG00000011465          DCN           12941  7905731   \n",
       "1        12852  ENSG00000171401        KRT13            2913   712612   \n",
       "2        28763  ENSG00000261371       PECAM1            7741  7739030   \n",
       "\n",
       "   n_measured_obs  \n",
       "0        75319655  \n",
       "1        62927690  \n",
       "2        64633082  "
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Grabbing gene metadata\n",
    "iterator = query.var()\n",
    "iterator.concat().to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "EkuPFp8nKyEN"
   },
   "source": [
    "#### Exporting query results to `AnnData`\n",
    "\n",
    "`ExperimentAxisQuery` has the capability to export the query to an `AnnData` object to use for downstream analysis (e.g. with [Scanpy](https://scanpy.readthedocs.io/))."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "keoLddtDjPgG",
    "outputId": "95843be1-5350-4cf4-9bc3-09bb7551d095"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "AnnData object with n_obs × n_vars = 45060 × 3\n",
       "    obs: 'soma_joinid', 'dataset_id', 'assay', 'assay_ontology_term_id', 'cell_type', 'cell_type_ontology_term_id', 'development_stage', 'development_stage_ontology_term_id', 'disease', 'disease_ontology_term_id', 'donor_id', 'is_primary_data', 'observation_joinid', 'self_reported_ethnicity', 'self_reported_ethnicity_ontology_term_id', 'sex', 'sex_ontology_term_id', 'suspension_type', 'tissue', 'tissue_ontology_term_id', 'tissue_type', 'tissue_general', 'tissue_general_ontology_term_id', 'raw_sum', 'nnz', 'raw_mean_nnz', 'raw_variance_nnz', 'n_measured_vars'\n",
       "    var: 'soma_joinid', 'feature_id', 'feature_name', 'feature_length', 'nnz', 'n_measured_obs'"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Convert to AnnData\n",
    "adata = query.to_anndata(X_name=\"normalized\")\n",
    "adata"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 549
    },
    "id": "asa2mjikAlnq",
    "outputId": "5c896be9-bd16-4748-ffaf-3afb4af61f88"
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/ubuntu/.pyenv/versions/scverse-ml-workshop-2024-3.9.19/lib/python3.9/site-packages/scanpy/preprocessing/_simple.py:373: UserWarning: Received a view of an AnnData. Making a copy.\n",
      "  view_to_actual(adata)\n",
      "/home/ubuntu/.pyenv/versions/scverse-ml-workshop-2024-3.9.19/lib/python3.9/site-packages/scanpy/plotting/_dotplot.py:749: UserWarning: No data for colormapping provided via 'c'. Parameters 'cmap', 'norm' will be ignored\n",
      "  dot_ax.scatter(x, y, **kwds)\n"
     ]
    },
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAbYAAAHdCAYAAABxOlzpAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjkuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8hTgPZAAAACXBIWXMAAA9hAAAPYQGoP6dpAAChjklEQVR4nOzdd3gUVdvA4d+mkrbZVEJCCj0BgtINJQkivShNehF45VUBUWzwoiDVghQRAQUEAem9K0ogNBFRlGKoYQMJIaT3sjvfH3ysBFI2BRLCc1/XXro7c545Mwn75Jw5c45KURQFIYQQooIwKesKCCGEEKVJEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICkUSmxBCiApFEpsQQogKRRKbEEKICsWsrCsgxNNOr9cTGRmJnZ0dKpWqrKtT7imKQnJyMu7u7piYyN/m4mGS2IQoY5GRkXh6epZ1NZ44ERERVK1atayrIcohSWxClDE7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",
      "text/plain": [
       "<Figure size 261x520 with 4 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Example: make an expression dot plot\n",
    "adata.var_names = adata.var[\"feature_name\"]\n",
    "adata.X = adata.X * 10000\n",
    "adata = adata[(adata.X.sum(1) > 0), :]  # remove cells that don't express any of the selected genes\n",
    "sc.pp.log1p(adata)\n",
    "sc.pl.dotplot(adata, adata.var[\"feature_name\"], groupby='cell_type');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "tt6n4rLGfiNK"
   },
   "source": [
    "**🚨 NOTE:** The Census package provides a convinient way to get an AnnData object without creating an Experiment Query:\n",
    "\n",
    "```python\n",
    "adata = cellxgene_census.get_anndata(\n",
    "  census = census,\n",
    "  organism = organism,\n",
    "  var_value_filter = gene_filter,\n",
    "  obs_value_filter = cell_filter,\n",
    "  column_names = cell_columns,\n",
    ")\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "rs3tMO9iN7Fj"
   },
   "source": [
    "#### Getting the expression data and metadata\n",
    "\n",
    "An`ExperimentAxisQuery` has all the necessary functionality to obtain the expression matrix along with the corresponding cell and gene metadata.\n",
    "\n",
    "`to_anndata()` (shown in the previous section) uses many of these methods under the hood.\n",
    "\n",
    "Let's take a closer look. First, we can get the cell and gene metadata as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 423
    },
    "id": "iJQdtQ1yJBPe",
    "outputId": "3f2311e1-dc10-4e62-8f8b-1070261371ca"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_joinid</th>\n",
       "      <th>cell_type</th>\n",
       "      <th>tissue_general</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>6763612</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>6763613</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>6763614</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>6763615</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>6763616</td>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>45055</th>\n",
       "      <td>53548544</td>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>45056</th>\n",
       "      <td>53548545</td>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>45057</th>\n",
       "      <td>53548546</td>\n",
       "      <td>basal cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>45058</th>\n",
       "      <td>53548547</td>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>45059</th>\n",
       "      <td>53548548</td>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>45060 rows × 3 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "       soma_joinid        cell_type tissue_general\n",
       "0          6763612  epithelial cell         tongue\n",
       "1          6763613  epithelial cell         tongue\n",
       "2          6763614  epithelial cell         tongue\n",
       "3          6763615  epithelial cell         tongue\n",
       "4          6763616  epithelial cell         tongue\n",
       "...            ...              ...            ...\n",
       "45055     53548544     keratinocyte         tongue\n",
       "45056     53548545     keratinocyte         tongue\n",
       "45057     53548546       basal cell         tongue\n",
       "45058     53548547     keratinocyte         tongue\n",
       "45059     53548548     keratinocyte         tongue\n",
       "\n",
       "[45060 rows x 3 columns]"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get cell metadata, only cell types and SOMA IDs\n",
    "obs = query.obs(column_names = [\"soma_joinid\", \"cell_type\"]).concat().to_pandas()\n",
    "obs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "P3pFkHhuN2LH",
    "outputId": "7aee061f-4198-4507-a9d0-fa5998d5588c"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_joinid</th>\n",
       "      <th>feature_id</th>\n",
       "      <th>feature_name</th>\n",
       "      <th>feature_length</th>\n",
       "      <th>nnz</th>\n",
       "      <th>n_measured_obs</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>299</td>\n",
       "      <td>ENSG00000011465</td>\n",
       "      <td>DCN</td>\n",
       "      <td>12941</td>\n",
       "      <td>7905731</td>\n",
       "      <td>75319655</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>12852</td>\n",
       "      <td>ENSG00000171401</td>\n",
       "      <td>KRT13</td>\n",
       "      <td>2913</td>\n",
       "      <td>712612</td>\n",
       "      <td>62927690</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>28763</td>\n",
       "      <td>ENSG00000261371</td>\n",
       "      <td>PECAM1</td>\n",
       "      <td>7741</td>\n",
       "      <td>7739030</td>\n",
       "      <td>64633082</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   soma_joinid       feature_id feature_name  feature_length      nnz  \\\n",
       "0          299  ENSG00000011465          DCN           12941  7905731   \n",
       "1        12852  ENSG00000171401        KRT13            2913   712612   \n",
       "2        28763  ENSG00000261371       PECAM1            7741  7739030   \n",
       "\n",
       "   n_measured_obs  \n",
       "0        75319655  \n",
       "1        62927690  \n",
       "2        64633082  "
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get gene metadata\n",
    "var = query.var().concat().to_pandas()\n",
    "var"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "P0UpBBhIU_KN"
   },
   "source": [
    "Now let's take a look at expression matrix. There's a method `X()` that works similarly to reading a SOMA `SparseNDArray`, it retunrs a reader that can be then used to create matrix iterators.\n",
    "\n",
    "Importantly `X()` will only return the rows and columns corresponding to cells and genes in the query, respectively."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "88VcwJYAT_fH",
    "outputId": "f83acc99-b3d6-43b5-ee67-8970ec74a74d"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "pyarrow.Table\n",
       "soma_dim_0: int64\n",
       "soma_dim_1: int64\n",
       "soma_data: float\n",
       "----\n",
       "soma_dim_0: [[6763612,6763613,6763614,6763615,6763616,...,53548430,53548466,53548497,53548507,53548548]]\n",
       "soma_dim_1: [[299,299,299,299,299,...,28763,28763,28763,28763,28763]]\n",
       "soma_data: [[8,6,1,6,3,...,16,1,2,1,1]]"
      ]
     },
     "execution_count": 39,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get reader, results, and concatenate them.\n",
    "# We need to specify the layer.\n",
    "X = query.X(layer_name = \"raw\").tables().concat()\n",
    "X"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "_FA7knuIhIeH"
   },
   "source": [
    "Same as before, we can transform this matrix to other formats:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "RGt18fFXhHFB",
    "outputId": "3aca46ef-e519-47c9-8d9a-3d085afa3cc1"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<53548549x28764 sparse matrix of type '<class 'numpy.float32'>'\n",
       "\twith 63579 stored elements in COOrdinate format>"
      ]
     },
     "execution_count": 40,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# SciPy formats\n",
    "scipy_coo = scipy.sparse.coo_matrix((X[\"soma_data\"], (X[\"soma_dim_0\"], X[\"soma_dim_1\"])))\n",
    "scipy_coo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "RmKQusbrhHzo"
   },
   "source": [
    "**🚨 NOTE:** The shape of this matrix is 52,668,282 rows by 27,554 columns.\n",
    "\n",
    "However we know that there are 45K cells and 3 genes in our query. The reason for this discrepancy is that we are using the SOMA IDs as the row and column indices.\n",
    "\n",
    "We can re-index these values to strip away all other cells and genes not included in our query result. Our team is about to release a method that makes this process a one-liner, for now we'll have to do the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {
    "id": "Yxp8MhWTcYF4"
   },
   "outputs": [],
   "source": [
    "# Reset the cell indeces to go from 0 to N (number of cells in the query)\n",
    "obs_index = query.indexer.by_obs(X[\"soma_dim_0\"])\n",
    "\n",
    "# Reset the gene indeces to go from 0 to N (number of genes in the query)\n",
    "var_index = query.indexer.by_var(X[\"soma_dim_1\"])\n",
    "\n",
    "# Get cell and gene soma IDs of the query\n",
    "obs_ids = query.obs_joinids().to_numpy()[:numpy.max(obs_index) + 1]\n",
    "var_ids = query.var_joinids().to_numpy()[:numpy.max(var_index) + 1]\n",
    "\n",
    "# Make scipy.coo matrix\n",
    "x_coo = scipy.sparse.coo_matrix((X[\"soma_data\"].to_numpy(), (obs_index, var_index)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "NwFh1GmBb5AU",
    "outputId": "f5800f79-a164-4fa5-9e82-9d7af05db1c0"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<45060x3 sparse matrix of type '<class 'numpy.float32'>'\n",
       "\twith 63579 stored elements in COOrdinate format>"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x_coo"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {
    "id": "v7UEH4y3dTDt"
   },
   "outputs": [],
   "source": [
    "# Get cell and gene soma IDs of the query\n",
    "obs_ids = query.obs_joinids().to_numpy()[:numpy.max(obs_index) + 1]\n",
    "var_ids = query.var_joinids().to_numpy()[:numpy.max(var_index) + 1]\n",
    "\n",
    "# Set obs/var index as the SOMA IDs\n",
    "obs = obs.set_index(\"soma_joinid\")\n",
    "var = var.set_index(\"soma_joinid\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 455
    },
    "id": "uieYFay4c4TV",
    "outputId": "e4eb9369-740c-439b-cf92-fafc5bc1175d"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>cell_type</th>\n",
       "      <th>tissue_general</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>soma_joinid</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>6763612</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6763613</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6763614</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6763615</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6763616</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>53548544</th>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>53548545</th>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>53548546</th>\n",
       "      <td>basal cell</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>53548547</th>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>53548548</th>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>tongue</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>45060 rows × 2 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "                   cell_type tissue_general\n",
       "soma_joinid                                \n",
       "6763612      epithelial cell         tongue\n",
       "6763613      epithelial cell         tongue\n",
       "6763614      epithelial cell         tongue\n",
       "6763615      epithelial cell         tongue\n",
       "6763616      epithelial cell         tongue\n",
       "...                      ...            ...\n",
       "53548544        keratinocyte         tongue\n",
       "53548545        keratinocyte         tongue\n",
       "53548546          basal cell         tongue\n",
       "53548547        keratinocyte         tongue\n",
       "53548548        keratinocyte         tongue\n",
       "\n",
       "[45060 rows x 2 columns]"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "obs.loc[obs_ids,]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 174
    },
    "id": "PKR2f8qIdfnj",
    "outputId": "9bb4fcd3-6758-4f13-ac74-314a560286b7"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>feature_id</th>\n",
       "      <th>feature_name</th>\n",
       "      <th>feature_length</th>\n",
       "      <th>nnz</th>\n",
       "      <th>n_measured_obs</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>soma_joinid</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>299</th>\n",
       "      <td>ENSG00000011465</td>\n",
       "      <td>DCN</td>\n",
       "      <td>12941</td>\n",
       "      <td>7905731</td>\n",
       "      <td>75319655</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>12852</th>\n",
       "      <td>ENSG00000171401</td>\n",
       "      <td>KRT13</td>\n",
       "      <td>2913</td>\n",
       "      <td>712612</td>\n",
       "      <td>62927690</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>28763</th>\n",
       "      <td>ENSG00000261371</td>\n",
       "      <td>PECAM1</td>\n",
       "      <td>7741</td>\n",
       "      <td>7739030</td>\n",
       "      <td>64633082</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                  feature_id feature_name  feature_length      nnz  \\\n",
       "soma_joinid                                                          \n",
       "299          ENSG00000011465          DCN           12941  7905731   \n",
       "12852        ENSG00000171401        KRT13            2913   712612   \n",
       "28763        ENSG00000261371       PECAM1            7741  7739030   \n",
       "\n",
       "             n_measured_obs  \n",
       "soma_joinid                  \n",
       "299                75319655  \n",
       "12852              62927690  \n",
       "28763              64633082  "
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "var.loc[var_ids,]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "rE2GGC0jeYpT"
   },
   "source": [
    "**🚨 NOTE:** Just like a file, a query should be closed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {
    "id": "KNLsToVAeWsq"
   },
   "outputs": [],
   "source": [
    "query.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "FA-7L5zfeNC4"
   },
   "source": [
    "### Efficient compute capabilities of Census\n",
    "\n",
    "Census has some methods that makes use of SOMA streaming capabilities (iterators) to make it possible to apply  common calculations on million of cells, using a common laptop."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "ValUjof9mBKf"
   },
   "source": [
    "\n",
    "#### Calculating average and variance across genes or cells\n",
    "\n",
    "The Census method `mean_variance` enables calculation of average values across rows (cells) or genes (columns) of the X matrix in the context of an `ExperimentAxisQuery` which we learned how to use in the last section.\n",
    "\n",
    "Let's see how this works. First we create an `ExperimentAxisQuery` [link text](https://)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {
    "id": "cNTDeF0ac7af"
   },
   "outputs": [],
   "source": [
    "# Set filters\n",
    "cell_filter = (\n",
    "  \"is_primary_data == True \"\n",
    "  \"and tissue_general == 'lung' \"\n",
    "  \"and cell_type == 'epithelial cell' \"\n",
    "  \"and disease == 'small cell lung carcinoma'\"\n",
    " )\n",
    "\n",
    "gene_filter = \"feature_name in ['KRAS', 'AQP4']\"\n",
    "\n",
    "# Create query\n",
    "query = census[\"census_data\"][\"homo_sapiens\"].axis_query(\n",
    "  measurement_name=\"RNA\",\n",
    "  obs_query=tiledbsoma.AxisQuery(value_filter=cell_filter),\n",
    "  var_query=tiledbsoma.AxisQuery(value_filter=gene_filter)\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "aveXjqxYiPZx",
    "outputId": "fa16ea60-7900-48ea-d4a2-05b6e45798ea"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(25988, 2)"
      ]
     },
     "execution_count": 48,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query.n_obs, query.n_vars"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "kAMK2ea_icNT"
   },
   "source": [
    "Now we can use the Census `mean_variance()`. In this example we calculate mean and variance across cells.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 143
    },
    "id": "0aIhHUkxiVth",
    "outputId": "8085e2b0-08dc-4559-9fed-eab5c88e707f"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>mean</th>\n",
       "      <th>variance</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>soma_joinid</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>6706</th>\n",
       "      <td>18.114668</td>\n",
       "      <td>829.320056</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>12982</th>\n",
       "      <td>0.018932</td>\n",
       "      <td>0.099153</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                  mean    variance\n",
       "soma_joinid                       \n",
       "6706         18.114668  829.320056\n",
       "12982         0.018932    0.099153"
      ]
     },
     "execution_count": 49,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from cellxgene_census.experimental.pp import mean_variance\n",
    "\n",
    "mean_variance_df = mean_variance(\n",
    "    query,\n",
    "    axis=0,\n",
    "    calculate_mean=True,\n",
    "    calculate_variance=True,\n",
    "    #nnz_only = True,\n",
    ")\n",
    "mean_variance_df"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 112
    },
    "id": "vAhhx0K0ixa4",
    "outputId": "2890b349-d946-4ecd-f713-9c6f6cd444f6"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_joinid</th>\n",
       "      <th>feature_id</th>\n",
       "      <th>feature_name</th>\n",
       "      <th>feature_length</th>\n",
       "      <th>nnz</th>\n",
       "      <th>n_measured_obs</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>6706</td>\n",
       "      <td>ENSG00000133703</td>\n",
       "      <td>KRAS</td>\n",
       "      <td>9230</td>\n",
       "      <td>21891125</td>\n",
       "      <td>76922693</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>12982</td>\n",
       "      <td>ENSG00000171885</td>\n",
       "      <td>AQP4</td>\n",
       "      <td>5943</td>\n",
       "      <td>3274017</td>\n",
       "      <td>70337111</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   soma_joinid       feature_id feature_name  feature_length       nnz  \\\n",
       "0         6706  ENSG00000133703         KRAS            9230  21891125   \n",
       "1        12982  ENSG00000171885         AQP4            5943   3274017   \n",
       "\n",
       "   n_measured_obs  \n",
       "0        76922693  \n",
       "1        70337111  "
      ]
     },
     "execution_count": 50,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query.var().concat().to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "BirKqYyVl3Na"
   },
   "source": [
    "There are a few knobs we can tune in this method:\n",
    "\n",
    "- `layer` the layer from X to use, defaults to `\"raw\"`.\n",
    "- `axis` perform calculations across rows (`0`) or columns (`1`).\n",
    "- `calculate_mean` whether to calculate mean.\n",
    "- `calculate_variance` whether to calculate variance.\n",
    "- `nnz_only` whether to do calculations only on non-zero values.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "atRqFunSnQMf"
   },
   "source": [
    "**🚨 NOTE:** Just like a file, a query should be closed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {
    "id": "iOieSYiNnQMg"
   },
   "outputs": [],
   "source": [
    "query.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "fupyzSA5lsW8"
   },
   "source": [
    "#### Getting highly variable genes\n",
    "\n",
    "Similarly to calculating gene expression mean and variance, we can efficiently find the highest variable genes (memory-efficiently, across millions of cells) using `highly_variable_genes()`.\n",
    "\n",
    "And this method also works with an `ExperimentAxisQuery`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {
    "id": "LRLCEIdFleOE"
   },
   "outputs": [],
   "source": [
    "cell_filter = (\n",
    "  \"is_primary_data == True \"\n",
    "  \"and tissue_general == 'lung' \"\n",
    "  \"and cell_type == 'T cell' \"\n",
    "  \"and disease == 'small cell lung carcinoma'\"\n",
    " )\n",
    "\n",
    "# Create query\n",
    "query = census[\"census_data\"][\"homo_sapiens\"].axis_query(\n",
    "  measurement_name=\"RNA\",\n",
    "  obs_query=tiledbsoma.AxisQuery(value_filter=cell_filter),\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "xEQAPZkOnDT9",
    "outputId": "3a0741fd-d94d-4d96-f97f-abe42224e362"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3898"
      ]
     },
     "execution_count": 53,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query.n_obs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 455
    },
    "id": "MwWytuvvnTpf",
    "outputId": "ad4789e1-9637-4fbb-b98d-b0b7f8896a19",
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>means</th>\n",
       "      <th>variances</th>\n",
       "      <th>highly_variable_rank</th>\n",
       "      <th>variances_norm</th>\n",
       "      <th>highly_variable</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>soma_joinid</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>179</th>\n",
       "      <td>0.015136</td>\n",
       "      <td>0.057508</td>\n",
       "      <td>162.0</td>\n",
       "      <td>2.909841</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>295</th>\n",
       "      <td>0.084146</td>\n",
       "      <td>0.350629</td>\n",
       "      <td>152.0</td>\n",
       "      <td>2.969717</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>391</th>\n",
       "      <td>5.670600</td>\n",
       "      <td>180.631524</td>\n",
       "      <td>192.0</td>\n",
       "      <td>2.758504</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>483</th>\n",
       "      <td>0.184197</td>\n",
       "      <td>0.956055</td>\n",
       "      <td>114.0</td>\n",
       "      <td>3.242163</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>525</th>\n",
       "      <td>0.071832</td>\n",
       "      <td>0.379237</td>\n",
       "      <td>82.0</td>\n",
       "      <td>3.834492</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32040</th>\n",
       "      <td>1.384043</td>\n",
       "      <td>53.327710</td>\n",
       "      <td>8.0</td>\n",
       "      <td>8.311249</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32045</th>\n",
       "      <td>0.133145</td>\n",
       "      <td>1.294303</td>\n",
       "      <td>67.0</td>\n",
       "      <td>4.149883</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32258</th>\n",
       "      <td>0.041816</td>\n",
       "      <td>0.152472</td>\n",
       "      <td>198.0</td>\n",
       "      <td>2.699364</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32293</th>\n",
       "      <td>0.842996</td>\n",
       "      <td>36.706675</td>\n",
       "      <td>3.0</td>\n",
       "      <td>9.840940</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32713</th>\n",
       "      <td>0.319651</td>\n",
       "      <td>1.664284</td>\n",
       "      <td>191.0</td>\n",
       "      <td>2.761724</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>200 rows × 5 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "                means   variances  highly_variable_rank  variances_norm  \\\n",
       "soma_joinid                                                               \n",
       "179          0.015136    0.057508                 162.0        2.909841   \n",
       "295          0.084146    0.350629                 152.0        2.969717   \n",
       "391          5.670600  180.631524                 192.0        2.758504   \n",
       "483          0.184197    0.956055                 114.0        3.242163   \n",
       "525          0.071832    0.379237                  82.0        3.834492   \n",
       "...               ...         ...                   ...             ...   \n",
       "32040        1.384043   53.327710                   8.0        8.311249   \n",
       "32045        0.133145    1.294303                  67.0        4.149883   \n",
       "32258        0.041816    0.152472                 198.0        2.699364   \n",
       "32293        0.842996   36.706675                   3.0        9.840940   \n",
       "32713        0.319651    1.664284                 191.0        2.761724   \n",
       "\n",
       "             highly_variable  \n",
       "soma_joinid                   \n",
       "179                     True  \n",
       "295                     True  \n",
       "391                     True  \n",
       "483                     True  \n",
       "525                     True  \n",
       "...                      ...  \n",
       "32040                   True  \n",
       "32045                   True  \n",
       "32258                   True  \n",
       "32293                   True  \n",
       "32713                   True  \n",
       "\n",
       "[200 rows x 5 columns]"
      ]
     },
     "execution_count": 54,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from cellxgene_census.experimental.pp import highly_variable_genes\n",
    "\n",
    "hvg_df = highly_variable_genes(\n",
    "    query,\n",
    "    n_top_genes = 200,\n",
    "    #batch_key = [\"dataset_id\"]\n",
    ")\n",
    "hvg_df.query(\"highly_variable == True\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 423
    },
    "id": "HBgtxAmUo9zO",
    "outputId": "e90113a5-b190-4a5c-bb0a-1583dd97125e"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>soma_joinid</th>\n",
       "      <th>feature_id</th>\n",
       "      <th>feature_name</th>\n",
       "      <th>feature_length</th>\n",
       "      <th>nnz</th>\n",
       "      <th>n_measured_obs</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0</td>\n",
       "      <td>ENSG00000000003</td>\n",
       "      <td>TSPAN6</td>\n",
       "      <td>4530</td>\n",
       "      <td>4811135</td>\n",
       "      <td>77128603</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1</td>\n",
       "      <td>ENSG00000000005</td>\n",
       "      <td>TNMD</td>\n",
       "      <td>1476</td>\n",
       "      <td>269136</td>\n",
       "      <td>64017621</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>2</td>\n",
       "      <td>ENSG00000000419</td>\n",
       "      <td>DPM1</td>\n",
       "      <td>9276</td>\n",
       "      <td>18420588</td>\n",
       "      <td>77502438</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>3</td>\n",
       "      <td>ENSG00000000457</td>\n",
       "      <td>SCYL3</td>\n",
       "      <td>6883</td>\n",
       "      <td>9268173</td>\n",
       "      <td>76952827</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>4</td>\n",
       "      <td>ENSG00000000460</td>\n",
       "      <td>C1orf112</td>\n",
       "      <td>5970</td>\n",
       "      <td>6484239</td>\n",
       "      <td>76979490</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60532</th>\n",
       "      <td>60532</td>\n",
       "      <td>ENSG00000288718</td>\n",
       "      <td>ENSG00000288718.1</td>\n",
       "      <td>1070</td>\n",
       "      <td>4</td>\n",
       "      <td>1248980</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60533</th>\n",
       "      <td>60533</td>\n",
       "      <td>ENSG00000288719</td>\n",
       "      <td>ENSG00000288719.1</td>\n",
       "      <td>4252</td>\n",
       "      <td>2826</td>\n",
       "      <td>1248980</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60534</th>\n",
       "      <td>60534</td>\n",
       "      <td>ENSG00000288724</td>\n",
       "      <td>ENSG00000288724.1</td>\n",
       "      <td>625</td>\n",
       "      <td>36</td>\n",
       "      <td>1248980</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60535</th>\n",
       "      <td>60535</td>\n",
       "      <td>ENSG00000290735</td>\n",
       "      <td>ENSG00000290735.1</td>\n",
       "      <td>4103</td>\n",
       "      <td>128</td>\n",
       "      <td>49359</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>60536</th>\n",
       "      <td>60536</td>\n",
       "      <td>ENSG00000289810</td>\n",
       "      <td>ENSG00000289810.1</td>\n",
       "      <td>1205</td>\n",
       "      <td>82</td>\n",
       "      <td>48478</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>60537 rows × 6 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "       soma_joinid       feature_id       feature_name  feature_length  \\\n",
       "0                0  ENSG00000000003             TSPAN6            4530   \n",
       "1                1  ENSG00000000005               TNMD            1476   \n",
       "2                2  ENSG00000000419               DPM1            9276   \n",
       "3                3  ENSG00000000457              SCYL3            6883   \n",
       "4                4  ENSG00000000460           C1orf112            5970   \n",
       "...            ...              ...                ...             ...   \n",
       "60532        60532  ENSG00000288718  ENSG00000288718.1            1070   \n",
       "60533        60533  ENSG00000288719  ENSG00000288719.1            4252   \n",
       "60534        60534  ENSG00000288724  ENSG00000288724.1             625   \n",
       "60535        60535  ENSG00000290735  ENSG00000290735.1            4103   \n",
       "60536        60536  ENSG00000289810  ENSG00000289810.1            1205   \n",
       "\n",
       "            nnz  n_measured_obs  \n",
       "0       4811135        77128603  \n",
       "1        269136        64017621  \n",
       "2      18420588        77502438  \n",
       "3       9268173        76952827  \n",
       "4       6484239        76979490  \n",
       "...         ...             ...  \n",
       "60532         4         1248980  \n",
       "60533      2826         1248980  \n",
       "60534        36         1248980  \n",
       "60535       128           49359  \n",
       "60536        82           48478  \n",
       "\n",
       "[60537 rows x 6 columns]"
      ]
     },
     "execution_count": 55,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "query.var().concat().to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "PAbezknrpSec"
   },
   "source": [
    "**🚨 NOTE:** Just like a file, a query should be closed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {
    "id": "U9DUezXLpSed"
   },
   "outputs": [],
   "source": [
    "query.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "kYaZq7xzpW0p"
   },
   "source": [
    "### Scalable modelling with PyTorch and Census\n",
    "\n",
    "Census provides an `ExperimentDataPipe`. It is an implementation of [PyTorch's DataPipe interface](https://pytorch.org/data/main/torchdata.datapipes.iter.html), which defines a common mechanism for wrapping and accessing training data from any underlying source."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "jFNrMOzQscI_"
   },
   "source": [
    "\n",
    "#### Creating an `ExperimentDataPipe`\n",
    "\n",
    "The `ExperimentDataPipe` class encapsulates the details of querying and retrieving Census data from a SOMA `Experiment` and returning it to the caller as PyTorch Tensors.\n",
    "\n",
    "Let's create an `ExperimentDataPipe`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {
    "id": "OzQFgYD8otgM"
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/ubuntu/.pyenv/versions/scverse-ml-workshop-2024-3.9.19/lib/python3.9/site-packages/torchdata/datapipes/__init__.py:18: UserWarning: \n",
      "################################################################################\n",
      "WARNING!\n",
      "The 'datapipes', 'dataloader2' modules are deprecated and will be removed in a\n",
      "future torchdata release! Please see https://github.com/pytorch/data/issues/1196\n",
      "to learn more and leave feedback.\n",
      "################################################################################\n",
      "\n",
      "  deprecation_warning()\n"
     ]
    }
   ],
   "source": [
    "import cellxgene_census.experimental.ml as census_ml\n",
    "\n",
    "experiment = census[\"census_data\"][\"homo_sapiens\"]\n",
    "\n",
    "experiment_datapipe = census_ml.ExperimentDataPipe(\n",
    "    experiment,\n",
    "    measurement_name=\"RNA\",\n",
    "    X_name=\"raw\",\n",
    "    obs_query=tiledbsoma.AxisQuery(value_filter=\"tissue_general == 'tongue' and is_primary_data == True\"),\n",
    "    obs_column_names=[\"cell_type\"],\n",
    "    batch_size=128,\n",
    "    # shuffle=True,\n",
    "    # soma_chunk_size=64,\n",
    "    # shuffle_chunk_count=2000,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "H6yMt-6xqhzP"
   },
   "source": [
    "As you can see this looks very similar to creating an `ExperimentAxisQuery`. There are a few new parameters:\n",
    "\n",
    "- `batch_size` to specify the number of obs rows (cells) in each returned PyTorch tensor.\n",
    "- `shuffle`, `soma_chunk_size`, `shuffle_chunk_count`:\n",
    "  - Randomize the order of the returned rows by fetching `shuffle_chunk_count` chunks of size `soma_chunk_size`, shuffling the result, and iterating through it with stride `batch_size`.\n",
    "  - This improves model-training performance, see [First stable iteration of Census (SOMA) PyTorch loaders](https://chanzuckerberg.github.io/cellxgene-census/articles/2024/20240709-pytorch.html#calibrated-shuffling-of-observations-cells) for more info."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "1DvD_bPir_Lb",
    "outputId": "aeb22c18-6eda-42bc-d1fa-3183b4c553c7"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ExperimentDataPipe"
      ]
     },
     "execution_count": 58,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "experiment_datapipe"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/"
    },
    "id": "U92EfjRxsDfX",
    "outputId": "924c16db-3fa2-4b00-cfa5-18a6579ff192"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(15020, 60537)"
      ]
     },
     "execution_count": 59,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "experiment_datapipe.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "vuFLgipcr-Yu"
   },
   "source": [
    "\n",
    "**🚨 NOTE:** Once you create an `ExperimentDataPipe` you can apply any PyTorch operations and modelling\n",
    "\n",
    "#### Split the dataset\n",
    "\n",
    "You may split the overall dataset into the typical training, validation, and test sets by using the PyTorch [RandomSplitter](https://pytorch.org/data/main/generated/torchdata.datapipes.iter.RandomSplitter.html#torchdata.datapipes.iter.RandomSplitter) `DataPipe`. Using PyTorch's functional form for chaining `DataPipe`s, this is done as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "metadata": {
    "id": "kYhAxNidrne-"
   },
   "outputs": [],
   "source": [
    "train_datapipe, test_datapipe = experiment_datapipe.random_split(weights={\"train\": 0.8, \"test\": 0.2}, seed=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "ra0t22Xmsuy-"
   },
   "source": [
    "#### Create the DataLoader\n",
    "With the full set of DataPipe operations chained together, we can now instantiate a PyTorch [DataLoader](https://pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader) on the training data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "metadata": {
    "id": "Ogh5YuZ5sfAT"
   },
   "outputs": [],
   "source": [
    "experiment_dataloader = census_ml.experiment_dataloader(train_datapipe)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "mxsSBGrNshyb"
   },
   "source": [
    "#### Define the model (Logistic Regression)\n",
    "With the training data retrieval code now in place, we can move on to defining a simple logistic regression model, using PyTorch's `torch.nn.Linear` class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "metadata": {
    "id": "_Xt1lG-HtBEw"
   },
   "outputs": [],
   "source": [
    "import torch\n",
    "\n",
    "class LogisticRegression(torch.nn.Module):\n",
    "    def __init__(self, input_dim, output_dim):\n",
    "        super(LogisticRegression, self).__init__()\n",
    "        self.linear = torch.nn.Linear(input_dim, output_dim)\n",
    "\n",
    "    def forward(self, x):\n",
    "        outputs = torch.sigmoid(self.linear(x))\n",
    "        return outputs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "qoT7kQjUtK0Y"
   },
   "source": [
    "Next, we define a function to train the model for a single epoch:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "metadata": {
    "id": "mYyKC737tIQo"
   },
   "outputs": [],
   "source": [
    "def train_epoch(model, train_dataloader, loss_fn, optimizer, device):\n",
    "    model.train()\n",
    "    train_loss = 0\n",
    "    train_correct = 0\n",
    "    train_total = 0\n",
    "\n",
    "    for batch in train_dataloader:\n",
    "        optimizer.zero_grad()\n",
    "        X_batch, y_batch = batch\n",
    "\n",
    "        X_batch = X_batch.float().to(device)\n",
    "\n",
    "        # Perform prediction\n",
    "        outputs = model(X_batch)\n",
    "\n",
    "        # Determine the predicted label\n",
    "        probabilities = torch.nn.functional.softmax(outputs, 1)\n",
    "        predictions = torch.argmax(probabilities, axis=1)\n",
    "\n",
    "        # Compute the loss and perform back propagation\n",
    "\n",
    "        y_batch = y_batch.flatten()\n",
    "        y_batch = y_batch.to(device)\n",
    "\n",
    "        train_correct += (predictions == y_batch).sum().item()\n",
    "        train_total += len(predictions)\n",
    "\n",
    "        loss = loss_fn(outputs, y_batch.long())\n",
    "        train_loss += loss.item()\n",
    "        loss.backward()\n",
    "        optimizer.step()\n",
    "\n",
    "    train_loss /= train_total\n",
    "    train_accuracy = train_correct / train_total\n",
    "    return train_loss, train_accuracy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "Vdmq5pvWtaAX"
   },
   "source": [
    "#### Train the model\n",
    "\n",
    "Finally, we are ready to train the model. Here we instantiate the model, a loss function, and an optimization method and then iterate through the desired number of training epochs. Note how the `train_dataloader` is passed into `train_epoch`, where for each epoch it will provide a new iterator through the training dataset.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "metadata": {
    "id": "peP_5BiotkBS"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Epoch 1: Train Loss: 0.0160760 Accuracy 0.1902\n",
      "Epoch 2: Train Loss: 0.0148238 Accuracy 0.3603\n",
      "Epoch 3: Train Loss: 0.0142791 Accuracy 0.5729\n",
      "Epoch 4: Train Loss: 0.0139893 Accuracy 0.6436\n",
      "Epoch 5: Train Loss: 0.0138150 Accuracy 0.6891\n"
     ]
    }
   ],
   "source": [
    "device = torch.device(\"cuda\") if torch.cuda.is_available() else torch.device(\"cpu\")\n",
    "\n",
    "# The size of the input dimension is the number of genes\n",
    "input_dim = experiment_datapipe.shape[1]\n",
    "\n",
    "# The size of the output dimension is the number of distinct cell_type values\n",
    "cell_type_encoder = experiment_datapipe.obs_encoders[\"cell_type\"]\n",
    "output_dim = len(cell_type_encoder.classes_)\n",
    "\n",
    "model = LogisticRegression(input_dim, output_dim).to(device)\n",
    "loss_fn = torch.nn.CrossEntropyLoss()\n",
    "optimizer = torch.optim.Adam(model.parameters(), lr=1e-05)\n",
    "\n",
    "n_epochs = 5\n",
    "for epoch in range(n_epochs):\n",
    "    train_loss, train_accuracy = train_epoch(model, experiment_dataloader, loss_fn, optimizer, device)\n",
    "    print(f\"Epoch {epoch + 1}: Train Loss: {train_loss:.7f} Accuracy {train_accuracy:.4f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "-FG0BOxqt4a8"
   },
   "source": [
    "#### Make predictions with the model\n",
    "\n",
    "To make predictions with the model, we first create a new `DataLoader` using the `test_datapipe`, which provides the “test” split of the original dataset. For this example, we will only make predictions on a single batch of data from the test split.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "metadata": {
    "id": "8g19z1KfuDzB"
   },
   "outputs": [],
   "source": [
    "experiment_dataloader = census_ml.experiment_dataloader(test_datapipe)\n",
    "X_batch, y_batch = next(iter(experiment_dataloader))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "vjAlx4jAuGty"
   },
   "source": [
    "Next, we invoke the model on the X_batch input data and extract the predictions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 121
    },
    "id": "Di9cdXQduK7_",
    "outputId": "5cd153b1-43a6-4fb1-f5ae-46bab668c44a"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "tensor([ 1,  1,  1,  1,  7,  1,  1,  1,  7,  7,  7,  7,  1,  5,  7,  6,  1,  7,\n",
       "         1,  7,  1,  1,  1,  1,  1,  7,  1,  1,  7,  2,  1,  1,  1,  1,  1,  1,\n",
       "         1,  8,  7,  8,  1,  8,  7,  1,  8,  7,  1,  1,  1,  7,  8,  1,  7,  1,\n",
       "        11,  8,  1,  1,  7,  1,  1,  1,  1,  7,  1,  7,  1,  1,  1,  1,  1,  8,\n",
       "         7, 11,  8,  1,  7,  8,  1,  1,  1,  1,  1,  1,  8,  1,  8,  1,  1,  1,\n",
       "         1,  7,  1,  1,  1,  7,  1,  1,  6,  1,  7, 11,  1,  1,  1,  1,  5,  1,\n",
       "         8,  1,  5,  7,  1,  1,  1,  1,  7,  1,  1,  1,  1,  8,  7,  1,  1,  7,\n",
       "         1,  1])"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "model.eval()\n",
    "\n",
    "model.to(device)\n",
    "outputs = model(X_batch.to(device))\n",
    "\n",
    "probabilities = torch.nn.functional.softmax(outputs, 1)\n",
    "predictions = torch.argmax(probabilities, axis=1)\n",
    "\n",
    "display(predictions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "DXTD8WoDuN_9"
   },
   "source": [
    "The predictions are returned as the encoded values of `cell_type` label. To recover the original cell type labels as strings, we decode using the encoders from `experiment_datapipe.obs_encoders`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 423
    },
    "id": "dHxjUT-huXls",
    "outputId": "80ecacfa-1863-4df5-a632-d2a5802701e1"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array(['basal cell', 'basal cell', 'basal cell', 'basal cell',\n",
       "       'keratinocyte', 'basal cell', 'basal cell', 'basal cell',\n",
       "       'keratinocyte', 'keratinocyte', 'keratinocyte', 'keratinocyte',\n",
       "       'basal cell', 'epithelial cell', 'keratinocyte', 'fibroblast',\n",
       "       'basal cell', 'keratinocyte', 'basal cell', 'keratinocyte',\n",
       "       'basal cell', 'basal cell', 'basal cell', 'basal cell',\n",
       "       'basal cell', 'keratinocyte', 'basal cell', 'basal cell',\n",
       "       'keratinocyte', 'capillary endothelial cell', 'basal cell',\n",
       "       'basal cell', 'basal cell', 'basal cell', 'basal cell',\n",
       "       'basal cell', 'basal cell', 'leukocyte', 'keratinocyte',\n",
       "       'leukocyte', 'basal cell', 'leukocyte', 'keratinocyte',\n",
       "       'basal cell', 'leukocyte', 'keratinocyte', 'basal cell',\n",
       "       'basal cell', 'basal cell', 'keratinocyte', 'leukocyte',\n",
       "       'basal cell', 'keratinocyte', 'basal cell',\n",
       "       'vein endothelial cell', 'leukocyte', 'basal cell', 'basal cell',\n",
       "       'keratinocyte', 'basal cell', 'basal cell', 'basal cell',\n",
       "       'basal cell', 'keratinocyte', 'basal cell', 'keratinocyte',\n",
       "       'basal cell', 'basal cell', 'basal cell', 'basal cell',\n",
       "       'basal cell', 'leukocyte', 'keratinocyte', 'vein endothelial cell',\n",
       "       'leukocyte', 'basal cell', 'keratinocyte', 'leukocyte',\n",
       "       'basal cell', 'basal cell', 'basal cell', 'basal cell',\n",
       "       'basal cell', 'basal cell', 'leukocyte', 'basal cell', 'leukocyte',\n",
       "       'basal cell', 'basal cell', 'basal cell', 'basal cell',\n",
       "       'keratinocyte', 'basal cell', 'basal cell', 'basal cell',\n",
       "       'keratinocyte', 'basal cell', 'basal cell', 'fibroblast',\n",
       "       'basal cell', 'keratinocyte', 'vein endothelial cell',\n",
       "       'basal cell', 'basal cell', 'basal cell', 'basal cell',\n",
       "       'epithelial cell', 'basal cell', 'leukocyte', 'basal cell',\n",
       "       'epithelial cell', 'keratinocyte', 'basal cell', 'basal cell',\n",
       "       'basal cell', 'basal cell', 'keratinocyte', 'basal cell',\n",
       "       'basal cell', 'basal cell', 'basal cell', 'leukocyte',\n",
       "       'keratinocyte', 'basal cell', 'basal cell', 'keratinocyte',\n",
       "       'basal cell', 'basal cell'], dtype=object)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "cell_type_encoder = experiment_datapipe.obs_encoders[\"cell_type\"]\n",
    "\n",
    "predicted_cell_types = cell_type_encoder.inverse_transform(predictions.cpu())\n",
    "\n",
    "display(predicted_cell_types)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 68,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>actual cell type</th>\n",
       "      <th>predicted cell type</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>basal cell</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>basal cell</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>basal cell</td>\n",
       "      <td>basal cell</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>basal cell</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>keratinocyte</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>123</th>\n",
       "      <td>basal cell</td>\n",
       "      <td>basal cell</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>124</th>\n",
       "      <td>basal cell</td>\n",
       "      <td>basal cell</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>125</th>\n",
       "      <td>keratinocyte</td>\n",
       "      <td>keratinocyte</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>126</th>\n",
       "      <td>epithelial cell</td>\n",
       "      <td>basal cell</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>127</th>\n",
       "      <td>basal cell</td>\n",
       "      <td>basal cell</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>128 rows × 2 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "    actual cell type predicted cell type\n",
       "0    epithelial cell          basal cell\n",
       "1    epithelial cell          basal cell\n",
       "2         basal cell          basal cell\n",
       "3    epithelial cell          basal cell\n",
       "4       keratinocyte        keratinocyte\n",
       "..               ...                 ...\n",
       "123       basal cell          basal cell\n",
       "124       basal cell          basal cell\n",
       "125     keratinocyte        keratinocyte\n",
       "126  epithelial cell          basal cell\n",
       "127       basal cell          basal cell\n",
       "\n",
       "[128 rows x 2 columns]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import pandas as pd\n",
    "\n",
    "display(\n",
    "    pd.DataFrame(\n",
    "        {\n",
    "            \"actual cell type\": cell_type_encoder.inverse_transform(y_batch.ravel().numpy()),\n",
    "            \"predicted cell type\": predicted_cell_types,\n",
    "        }\n",
    "    )\n",
    ")"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "provenance": [],
   "toc_visible": true
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.19"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}