.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "python/gallery/beginner_guide.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_python_gallery_beginner_guide.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_python_gallery_beginner_guide.py:


.. _beginner-guide:

Beginner guide
==============

The `atlasapprox-disease <https://github.com/fabilab/cell_atlas_approximations_disease_API>`_ Python API provides access to over 600 disease-related single-cell datasets.
Currently, it includes datasets from the CELLxGENE Census as its initial source, covering diseases such as COVID-19, diabetes, acute kidney failure, and gastritis, along with metadata like cell type, developmental stage, and sex.
This API enables users to quickly explore cellular and gene expression patterns in disease contexts.

Follow this tutorial to get started with the basics of using the API.


.. GENERATED FROM PYTHON SOURCE LINES 19-34

Installation
------------

(Optional) To ensure consistent dependencies, we recommend setting up a virtual environment:

.. code-block:: bash

    python -m venv ./venv
    source ./venv/bin/activate

Then, install the ``atlasapprox-disease`` package using ``pip``:

.. code-block:: bash

    pip install atlasapprox-disease

.. GENERATED FROM PYTHON SOURCE LINES 36-40

Python quick start
------------------

Below are 2 examples of common operations you can do with the atlasapprox_disease Python API:

.. GENERATED FROM PYTHON SOURCE LINES 40-46

.. code-block:: Python


    # Import the package and initialise the API
    import atlasapprox_disease

    api = atlasapprox_disease.API()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Loading atlasapprox_disease from: /home/docs/checkouts/readthedocs.org/user_builds/cell-atlas-approximations-disease-api/checkouts/latest/Python/atlasapprox_disease/__init__.py




.. GENERATED FROM PYTHON SOURCE LINES 47-53

Querying cell metadata
^^^^^^^^^^^^^^^^^^^^^^

The ``metadata`` function lets you explore cell metadata across datasets by applying filters
on attributes like tissue, disease, or developmental stage.
For example, the following filters cells from lung tissue at the adult stage:

.. GENERATED FROM PYTHON SOURCE LINES 53-59

.. code-block:: Python


    api.metadata(
        tissue="lung",
        development_stage="adult"
    )






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>unique_id</th>
          <th>dataset_id</th>
          <th>cell_type</th>
          <th>tissue_general</th>
          <th>disease</th>
          <th>development_stage_general</th>
          <th>sex</th>
          <th>cell_count</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>98ac1a55676e61a854d68c3f3e5f791a</td>
          <td>01209dce-3575-4bed-b1df-129f57fbc031</td>
          <td>CD4-positive, alpha-beta T cell</td>
          <td>lung</td>
          <td>normal</td>
          <td>adult</td>
          <td>male</td>
          <td>1993</td>
        </tr>
        <tr>
          <th>1</th>
          <td>01b9218f253b6c07a021b1b4f3954871</td>
          <td>01209dce-3575-4bed-b1df-129f57fbc031</td>
          <td>CD4-positive, alpha-beta thymocyte</td>
          <td>lung</td>
          <td>normal</td>
          <td>adult</td>
          <td>male</td>
          <td>3056</td>
        </tr>
        <tr>
          <th>2</th>
          <td>bbff9e63b378470377555ed3f97bedb2</td>
          <td>01209dce-3575-4bed-b1df-129f57fbc031</td>
          <td>CD8-positive, alpha-beta T cell</td>
          <td>lung</td>
          <td>normal</td>
          <td>adult</td>
          <td>male</td>
          <td>2391</td>
        </tr>
        <tr>
          <th>3</th>
          <td>2540425305dd88c7aedd91fcebea46d0</td>
          <td>01209dce-3575-4bed-b1df-129f57fbc031</td>
          <td>CD8-positive, alpha-beta thymocyte</td>
          <td>lung</td>
          <td>normal</td>
          <td>adult</td>
          <td>male</td>
          <td>3350</td>
        </tr>
        <tr>
          <th>4</th>
          <td>b387d4572395da54759d1b9fdd9b4a66</td>
          <td>01209dce-3575-4bed-b1df-129f57fbc031</td>
          <td>immature alpha-beta T cell</td>
          <td>lung</td>
          <td>normal</td>
          <td>adult</td>
          <td>male</td>
          <td>171</td>
        </tr>
        <tr>
          <th>...</th>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
        </tr>
        <tr>
          <th>1413</th>
          <td>2430bd747f2aad4f2ead5a33ff9ef3b8</td>
          <td>f72958f5-7f42-4ebb-98da-445b0c6de516</td>
          <td>type II pneumocyte</td>
          <td>lung</td>
          <td>normal</td>
          <td>adult</td>
          <td>male</td>
          <td>30969</td>
        </tr>
        <tr>
          <th>1414</th>
          <td>548cac77e1039631066deb4d65bdaa39</td>
          <td>f72958f5-7f42-4ebb-98da-445b0c6de516</td>
          <td>unknown</td>
          <td>lung</td>
          <td>normal</td>
          <td>adult</td>
          <td>female</td>
          <td>866</td>
        </tr>
        <tr>
          <th>1415</th>
          <td>bb0f087ae00b96f2552bd1e84e8fa105</td>
          <td>f72958f5-7f42-4ebb-98da-445b0c6de516</td>
          <td>unknown</td>
          <td>lung</td>
          <td>normal</td>
          <td>adult</td>
          <td>male</td>
          <td>1358</td>
        </tr>
        <tr>
          <th>1416</th>
          <td>1c4e1440f60ee38746e5200b635337c7</td>
          <td>f72958f5-7f42-4ebb-98da-445b0c6de516</td>
          <td>vein endothelial cell</td>
          <td>lung</td>
          <td>normal</td>
          <td>adult</td>
          <td>female</td>
          <td>2028</td>
        </tr>
        <tr>
          <th>1417</th>
          <td>077eee6802a2c541daf0fd33c379f677</td>
          <td>f72958f5-7f42-4ebb-98da-445b0c6de516</td>
          <td>vein endothelial cell</td>
          <td>lung</td>
          <td>normal</td>
          <td>adult</td>
          <td>male</td>
          <td>5882</td>
        </tr>
      </tbody>
    </table>
    <p>1418 rows × 8 columns</p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 60-64

The output is a ``pandas.DataFrame`` with over 1400 unique combinations of cell types, diseases,
and other columns such as ``sex``, ``cell_count`` and the ``dataset`` it comes from.
You can get a quick overview of what cell types and conditions are available
and use this information later for querying other API functions.

.. GENERATED FROM PYTHON SOURCE LINES 66-71

Querying average gene expression
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The ``average`` function retrieves average gene expression across cell types, tissues, and diseases.
For example, to query immune-related genes in COVID-19:

.. GENERATED FROM PYTHON SOURCE LINES 71-77

.. code-block:: Python


    api.average(
        features="ACE2,TLR4,NLRP3,MBL2,IL6",
        disease="COVID-19"
    )






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>cell_count</th>
          <th>cell_type</th>
          <th>tissue_general</th>
          <th>disease</th>
          <th>dataset_id</th>
          <th>ACE2</th>
          <th>TLR4</th>
          <th>NLRP3</th>
          <th>MBL2</th>
          <th>IL6</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>42850</td>
          <td>B cell</td>
          <td>blood</td>
          <td>COVID-19</td>
          <td>01ad3cd7-3929-4654-84c0-6db05bd5fd59</td>
          <td>0.000000</td>
          <td>0.020387</td>
          <td>0.014871</td>
          <td>0.0</td>
          <td>0.246985</td>
        </tr>
        <tr>
          <th>1</th>
          <td>111297</td>
          <td>CD4-positive, alpha-beta T cell</td>
          <td>blood</td>
          <td>COVID-19</td>
          <td>01ad3cd7-3929-4654-84c0-6db05bd5fd59</td>
          <td>0.000000</td>
          <td>0.011792</td>
          <td>0.016089</td>
          <td>0.0</td>
          <td>0.000325</td>
        </tr>
        <tr>
          <th>2</th>
          <td>64766</td>
          <td>CD8-positive, alpha-beta T cell</td>
          <td>blood</td>
          <td>COVID-19</td>
          <td>01ad3cd7-3929-4654-84c0-6db05bd5fd59</td>
          <td>0.000000</td>
          <td>0.016499</td>
          <td>0.018025</td>
          <td>0.0</td>
          <td>0.000705</td>
        </tr>
        <tr>
          <th>3</th>
          <td>113753</td>
          <td>classical monocyte</td>
          <td>blood</td>
          <td>COVID-19</td>
          <td>01ad3cd7-3929-4654-84c0-6db05bd5fd59</td>
          <td>0.000000</td>
          <td>0.636274</td>
          <td>0.534583</td>
          <td>0.0</td>
          <td>0.006524</td>
        </tr>
        <tr>
          <th>4</th>
          <td>4776</td>
          <td>conventional dendritic cell</td>
          <td>blood</td>
          <td>COVID-19</td>
          <td>01ad3cd7-3929-4654-84c0-6db05bd5fd59</td>
          <td>0.000000</td>
          <td>0.123744</td>
          <td>0.248952</td>
          <td>0.0</td>
          <td>0.002513</td>
        </tr>
        <tr>
          <th>...</th>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
        </tr>
        <tr>
          <th>565</th>
          <td>118</td>
          <td>mast cell</td>
          <td>respiratory system</td>
          <td>COVID-19</td>
          <td>f156606a-dd9a-49fd-bc40-0e069b6cf07c</td>
          <td>0.000000</td>
          <td>0.090158</td>
          <td>0.000000</td>
          <td>0.0</td>
          <td>0.000000</td>
        </tr>
        <tr>
          <th>566</th>
          <td>1108</td>
          <td>mature NK T cell</td>
          <td>respiratory system</td>
          <td>COVID-19</td>
          <td>f156606a-dd9a-49fd-bc40-0e069b6cf07c</td>
          <td>0.000000</td>
          <td>0.042362</td>
          <td>0.104304</td>
          <td>0.0</td>
          <td>0.013103</td>
        </tr>
        <tr>
          <th>567</th>
          <td>7438</td>
          <td>myeloid cell</td>
          <td>respiratory system</td>
          <td>COVID-19</td>
          <td>f156606a-dd9a-49fd-bc40-0e069b6cf07c</td>
          <td>0.000000</td>
          <td>0.736049</td>
          <td>0.948961</td>
          <td>0.0</td>
          <td>0.164485</td>
        </tr>
        <tr>
          <th>568</th>
          <td>4</td>
          <td>neutrophil</td>
          <td>respiratory system</td>
          <td>COVID-19</td>
          <td>f156606a-dd9a-49fd-bc40-0e069b6cf07c</td>
          <td>0.000000</td>
          <td>0.000000</td>
          <td>4.633920</td>
          <td>0.0</td>
          <td>0.000000</td>
        </tr>
        <tr>
          <th>569</th>
          <td>241</td>
          <td>unknown</td>
          <td>respiratory system</td>
          <td>COVID-19</td>
          <td>f156606a-dd9a-49fd-bc40-0e069b6cf07c</td>
          <td>0.001793</td>
          <td>0.250800</td>
          <td>0.319913</td>
          <td>0.0</td>
          <td>0.081020</td>
        </tr>
      </tbody>
    </table>
    <p>570 rows × 10 columns</p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 78-82

The output is a ``pandas.DataFrame`` with columns such as ``cell_type``, ``tissue_general``,
``disease``, ``dataset_id``, and the expression levels of the queried genes (in counts per 10k).
This helps you explore gene activity in specific conditions and identify key genes
for further analysis.

.. GENERATED FROM PYTHON SOURCE LINES 84-92

Next steps
----------

This tutorial introduced the basics of the ``atlasapprox-disease`` API.
To learn more, explore additional functions like ``dotplot`` for visualizing gene expression,
or query ``differential gene expression`` data.

Visit the `official documentation <https://cell-atlas-approximations-disease-api.readthedocs.io/en/latest/python/index.html>`_
for further details.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 27.095 seconds)


.. _sphx_glr_download_python_gallery_beginner_guide.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: beginner_guide.ipynb <beginner_guide.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: beginner_guide.py <beginner_guide.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: beginner_guide.zip <beginner_guide.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_