Metadata-Version: 2.4
Name: perturbio
Version: 0.1.0
Summary: Comprehensive Python package for Crop-Seq (CRISPR + single-cell RNA-seq) analysis
Author: Siavash Ghaffari
License-Expression: MIT
Project-URL: Homepage, https://github.com/Siavashghaffari/Perturbio
Project-URL: Documentation, https://github.com/Siavashghaffari/Perturbio#readme
Project-URL: Repository, https://github.com/Siavashghaffari/Perturbio
Project-URL: Bug Tracker, https://github.com/Siavashghaffari/Perturbio/issues
Keywords: crispr,crop-seq,perturb-seq,single-cell,scrna-seq,perturbation,genomics,bioinformatics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anndata>=0.8
Requires-Dist: scanpy>=1.9
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: matplotlib>=3.6
Requires-Dist: seaborn>=0.12
Requires-Dist: click>=8.0
Requires-Dist: tqdm>=4.65
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: bam
Requires-Dist: pysam>=0.20; extra == "bam"
Provides-Extra: all
Requires-Dist: pysam>=0.20; extra == "all"
Requires-Dist: jupyter>=1.0; extra == "all"
Requires-Dist: plotly>=5.0; extra == "all"
Dynamic: license-file

# Perturbio

```
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  ██████╗ ███████╗██████╗ ████████╗██╗   ██╗██████╗ ██████╗ ██╗ │
│  ██╔══██╗██╔════╝██╔══██╗╚══██╔══╝██║   ██║██╔══██╗██╔══██╗██║ │
│  ██████╔╝█████╗  ██████╔╝   ██║   ██║   ██║██████╔╝██████╔╝██║ │
│  ██╔═══╝ ██╔══╝  ██╔══██╗   ██║   ██║   ██║██╔══██╗██╔══██╗██║ │
│  ██║     ███████╗██║  ██║   ██║   ╚██████╔╝██║  ██║██████╔╝██║ │
│  ╚═╝     ╚══════╝╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚═════╝ ╚═╝ │
│                                                                 │
│         Crop-Seq Analysis Made Simple                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

**Perturbio** is a comprehensive Python package for end-to-end analysis of Crop-Seq experiments (CRISPR pooled screens + single-cell RNA sequencing). From raw data to biological insights in under 5 minutes.

## Features

- **Guide Extraction**: Automatically identify CRISPR guide RNAs in single cells
- **Differential Expression**: Discover genes affected by perturbations
- **Beautiful Visualizations**: Publication-ready plots with minimal code
- **Scanpy Integration**: Works seamlessly with the scanpy ecosystem
- **Simple CLI**: One command to run complete analysis
- **Fast**: Analyze thousands of cells in minutes

## Installation

Install from source:

```bash
git clone https://github.com/Siavashghaffari/Perturbio.git
cd Perturbio
pip install -e .
```

Once released on PyPI:

```bash
pip install perturbio
```

## Quick Start

### Command Line

```bash
# Run complete analysis
perturbio analyze cropseq_data.h5ad --guides guides.csv

# Results saved to perturbio_results_YYYYMMDD_HHMMSS/
```

### Python API

```python
from perturbio import CropSeqAnalyzer

# One-liner magic
analyzer = CropSeqAnalyzer("cropseq_data.h5ad")
results = analyzer.run()

# Access results
print(results.top_hits("BRCA1_guide1", n=20))
results.plot_volcano("MYC_guide1")
```

### Scanpy Integration

```python
import scanpy as sc
import perturbio as pt

# Standard scanpy workflow
adata = sc.read_h5ad("cropseq_data.h5ad")
sc.pp.normalize_total(adata)
sc.pp.log1p(adata)

# Extract guides
pt.guides.extract(adata, guide_file="guides.csv")

# Differential expression
pt.tl.differential_expression(adata, groupby='perturbation', control='non-targeting')

# Visualize
pt.pl.volcano(adata, perturbation='BRCA1_guide1')
```

## Guide Library Format

Create a CSV file with your guide library:

```csv
guide_id,target_gene,guide_sequence
BRCA1_guide1,BRCA1,GCACTCAGGAAACAGCTATG
BRCA1_guide2,BRCA1,CTGAAGACTGCTCAGTGTAG
MYC_guide1,MYC,GTACTTGGTGAGGCCAGCGC
non-targeting_1,control,GTAGCGAACGTGTCCGGCGT
```

## Documentation

- [Installation](#installation)
- [Quick Start Tutorial](examples/01_quickstart.ipynb)
- [Complete Workflow](examples/02_complete_workflow.ipynb)
- [Scanpy Integration Guide](examples/03_advanced_scanpy_integration.md)
- [CLI Examples](examples/04_cli_examples.md)
- [All Examples](examples/)

## Requirements

- Python 3.9+
- AnnData/Scanpy for single-cell analysis
- Works on macOS, Linux, and Windows

## Authors

This work was developed by **Siavash Ghaffari**. For any questions, feedback, or additional information, please feel free to reach out. Your input is highly valued and will help improve and refine this pipeline further.



