Metadata-Version: 2.2
Name: atlasapprox_disease
Version: 0.1.4
Summary: Cell atlas approximations for diseases, Python API
Author-email: Ying Xu <ying.xu3@unsw.edu.au>
License: Copyright 2025 Fabio Zanini
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Project-URL: Repository, https://github.com/fabilab/cell_atlas_approximations_disease_API
Project-URL: Bug Tracker, https://github.com/fabilab/cell_atlas_approximations_disease_API/issues
Keywords: single cell,cell atlas,omics,biology,disease,bioinformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.TXT
Requires-Dist: requests
Requires-Dist: numpy
Requires-Dist: pandas

Python interface to disease-related cell atlas approximations
=============================================

`atlasapprox_disease` is a Python interface designed to provide easy access to disease-related cell atlas data. Built using the [cellxgene census](https://github.com/chanzuckerberg/cellxgene-census) as the initial data source and powered by the [scquill approximation algorithm](https://github.com/fabilab/scquill/), this package enables researchers to explore thousands of datasets efficiently. 

The package enables researchers to address complex biological questions across multiple organs, cell types, and disease conditions such as:

- *What is the expression of a specific gene in a specific disease across all datasets?*
- *In COVID-19, what is the differential cell abundance of each cell type between normal and disease states?*
- *What are the top 20 most differentially expressed genes in kidney disease?*

---

## Features

- **Differential analysis**:
    - Compare differential gene expression across diseases, tissues, sexes, or conditions.
    - Retrieve differential cell type abundance between disease states.
- **Expression & Abundance Queries:**:
    - Retrieve average gene expression levels across multiple datasets
    - Compute the fraction of cells expressing specific genes.
    - Identify the highest-expressing cell types for a given gene across diseases and datasets.
- **Metadata Access**:
    - Retrieve dataset metadata, including cell types, tissues, diseases, sex, development stage.
- **Visualization:**:
    - Generate dot plots to visualize gene expression and detection frequencies.

## Installation

**To install the package, run:**
```bash
pip install atlasapprox-disease
```

## Quick start
**Initialise the API**
```python
import atlasapprox_disease as aad
api = aad.API()
```

**Retrieve Metadata**
```python
metadata = api.metadata()
print(metadata.head())
```

**Query differential gene expression**
```python
diff_exp = api.differential_gene_expression(
    differential_axis="disease",
    disease="Diabetes",
    top_n=10,  # Get top 10 upregulated & downregulated genes
    method="delta_fraction"
)
print(diff_exp)
```

**Generate average gene expression**
```python
average_exp = api.average(
    features="INS,GCK,MAFA,PECAM1",
    disease="Diabetes",
    include_normal=True
)
print(average_exp)
```

For more detailed tutorials and examples, please visit the [API github repo](https://github.com/fabilab/cell_atlas_approximations_disease_API).
