Metadata-Version: 2.4
Name: cellsweep
Version: 1.0.0
Summary: Denoising scRNA-seq in a smart and efficient way.
Author-email: Maya Caskey <mcaskey@caltech.edu>, Joseph Rich <jmrich@caltech.edu>
Maintainer-email: Maya Caskey <mcaskey@caltech.edu>, Joseph Rich <jmrich@caltech.edu>
License: BSD 2-Clause License
        
        Copyright (c) 2024, Pachter Lab
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Project-URL: Homepage, https://github.com/pachterlab/cellsweep
Project-URL: Documentation, https://cellsweep.readthedocs.io
Keywords: bioinformatics,machine learning,single-cell,scRNA-seq,denoising,data-analysis
Classifier: Environment :: Console
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: numba>=0.56.2
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: anndata
Requires-Dist: pydantic<3.0,>=2.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black[jupyter]>=22.0.0; extra == "dev"
Requires-Dist: isort>=6.0.0; extra == "dev"
Requires-Dist: pympler>=1.1; extra == "dev"
Provides-Extra: analysis
Requires-Dist: nbval>=0.10.0; extra == "analysis"
Requires-Dist: nbdime>=4.0.2; extra == "analysis"
Requires-Dist: ipython>=8.0.0; extra == "analysis"
Requires-Dist: upsetplot; extra == "analysis"
Requires-Dist: PyYAML; extra == "analysis"
Requires-Dist: scanpy; extra == "analysis"
Requires-Dist: seaborn; extra == "analysis"
Requires-Dist: matplotlib; extra == "analysis"
Requires-Dist: celltypist; extra == "analysis"
Requires-Dist: mpl-scatter-density; extra == "analysis"
Requires-Dist: astropy; extra == "analysis"
Requires-Dist: scikit-learn; extra == "analysis"
Requires-Dist: ipywidgets; extra == "analysis"
Requires-Dist: torch; extra == "analysis"
Requires-Dist: scikit-misc; extra == "analysis"
Requires-Dist: leidenalg; extra == "analysis"
Requires-Dist: adjustText; extra == "analysis"
Requires-Dist: squidpy; extra == "analysis"
Requires-Dist: tqdm; extra == "analysis"
Requires-Dist: requests; extra == "analysis"
Dynamic: license-file

# cellsweep

Sweep out noisy counts from single-cell RNA-seq data with CellSweep!

Documentation: https://cellsweep.readthedocs.io

![alt text](https://github.com/pachterlab/cellsweep/blob/main/figures/logo.png?raw=true)

## Install
### Basic use
```
pip install cellsweep
```

### To run notebooks:
```
pip install cellsweep[analysis]
```

### To remake figures from the paper:
```
git clone https://github.com/pachterlab/cellsweep.git
cd cellsweep
conda env create -f environment.yml
pip install cellsweep[analysis]==0.1.1
```

## Quickstart
CellSweep has a single function denoise that takes a raw count matrix in an AnnData object and produces a denoised count matrix in another AnnData object. See a simple, fully worked example in the `notebooks/intro.ipynb` Jupyter Notebook.

### Python API
```python
import cellsweep
adata_cellsweep = cellsweep.denoise(adata_raw_path, adata_out=adata_cellsweep_path)  # see below for expected structure

# for help
help(cellsweep.denoise)
```

### Command line interface
```
cellsweep denoise -o adata_cellsweep.h5ad adata_raw.h5ad  # see below for expected structure

# for help
cellsweep denoise --help
```

There are many utility functions in the `cellsweep.utils` module for data processing, plotting, and analysis. See examples in our Jupyter Notebooks.

## Anndata object
The input Anndata object/h5ad file should have the following structure:
- `adata.X` : cell count matrix (cells x genes)
- `adata.obs`:
    - `adata.obs[celltype_key]`: a column indicating the cell type of each cell.
    - `adata.obs[is_empty_key]` (optional): a boolean column indicating whether each cell is an empty droplet. If not provided, CellSweep will infer empty droplets using the `empty_droplet_method` argument.

Additional column inputs can be provided in advanced use cases. See the documentation for details.

CellSweep returns a denoised Anndata object (and writes it to `adata_out`, if provided) with an updated `adata.X` and the following added fields. By default the empty droplets are removed from the output so it only contains the real cells; pass `keep_empties=True` (CLI: `--keep-empties`) to keep every input barcode.
- `adata.layers["raw"]` : raw count matrix
- `adata.obs`:
    - `adata.obs["alpha_hat"]` : final optimized alpha values
    - `adata.obs["contamination_fraction"]` : total contamination fraction per cell, `(1 - beta_hat) * alpha_hat + beta_hat`
    - `adata.obs["z_hat"]` : final cell-type assignments
- `adata.var`:
    - `adata.var["ambient_hat"]` : final optimized ambient distribution
    - `adata.var["bulk_hat"]` : global noise distribution
- `adata.uns`:
    - `adata.uns["p_hat"]` : final optimized matrix of cell-type profiles (K x G)
    - `adata.uns["beta_hat"]` : final optimized beta
    - `adata.uns["loglike"]` : final log-likelihood (this is the relative log-likelihood, not the complete log-likelihood)


### Multiple samples
CellSweep fits a single ambient profile, global contamination profile and global contamination fraction per run. Ambient contamination is specific to each sample, so run CellSweep separately on each sequencing sample (e.g. each 10x channel or plate), with that sample's own non-cellular barcodes, rather than on a matrix that combines several samples, batches or plates.

## Tutorials
We have several Jupyter Notebooks demonstrating the use of CellSweep for denoising count matrices and analyzing the results. See the `notebooks` folder in the repository.
