Metadata-Version: 2.5
Name: pepkio-matched-null-gene-set-generator
Version: 0.1.0
Summary: Python client for Pepkio matched-null-gene-set-generator tool
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# Pepkio Matched Null Gene Set Generator

Empirical confounder-matched negative control gene set generator for statistical calibration of pathway enrichment and transcriptomic analyses.

# What It Does

The `pepkio-matched-null-gene-set-generator` Python package generates empirical negative control gene sets tailored to the exact length, expression level, GC content, and biotype characteristics of your input gene signature. It provides robust null distributions for Gene Set Enrichment Analysis (GSEA), fgsea, and clusterProfiler to eliminate false-positive pathway discoveries driven by technical sequencing confounders.

# Features

- **Multi-Feature Matching**: Matches query gene signatures on baseline expression, transcript length, GC content, and biotype.
- **Stratified Binning**: Configurable tercile, quintile, and decile feature partitioning for balanced surrogate sampling.
- **Statistical Balance Metrics**: Calculates Standardized Mean Difference (SMD) and Kolmogorov-Smirnov (KS) metrics for quality control.
- **Built-in Reference Organisms**: Pre-compiled background databases for human, mouse, rat, zebrafish, fruit fly, *C. elegans*, and yeast.
- **Custom Background Support**: Allows upload of user-defined reference gene matrices and expression TPM datasets.
- **Enrichment Exports**: Outputs Gene Matrix Transposed (GMT) files, tabular CSVs, and R/Python downstream evaluation snippets.
- **CLI & Python API**: Usable as a scriptable Python library or a direct command-line tool.

# Installation

```bash
pip install pepkio-matched-null-gene-set-generator
```

Or using `uv`:

```bash
uv add pepkio-matched-null-gene-set-generator
```

# Quick Example

```python
from pepkio_matched_null_gene_set_generator import PepkioClient

with PepkioClient() as client:
    result = client.run({
        "gene_list": "TP53\nBRCA1\nEGFR\nMYC\nKRAS",
        "organism": "human",
        "null_set_count": 3,
        "seed": 42,
        "match_expression": True,
        "match_length": True,
        "match_gc": True
    })

    print("Status:", result.status)
    print("Generated GMT:\n", result.result["gmt_export"])
```

# Typical Use Cases

- **Empirical FDR Calibration in GSEA/fgsea**: Generate 10–50 matched null sets to benchmark experimental enrichment scores against confound-matched null distributions.
- **Transcript Length Bias Correction**: Form negative control sets for differentially expressed gene lists with extreme transcript length distributions.
- **Expression-Matched Background Controls**: Control for baseline abundance in cell-type marker gene signatures in single-cell or bulk RNA-seq.
- **CRISPR & RNAi Screen Validation**: Test whether top candidate genes from functional genomic screens remain statistically enriched when comparing against size-matched control sets.

# Scientific Background

In functional genomics and transcriptomics, gene length, GC content, and baseline expression levels systematically skew detection probabilities. Drawing naive uniformly random gene sets from the genome produces null distributions that do not account for these systematic biases. By stratifying background genomes into multi-dimensional covariate bins and validating balance with Standardized Mean Difference ($\text{SMD} < 0.1$), this package yields accurate empirical significance thresholds.

# Web Application

For researchers who prefer an interactive graphical interface, a hosted web version is available with real-time balance histograms, ECDF visualizations, and one-click GMT downloads.

Web Application: https://www.pepkio.com/tools/matched-null-gene-set-generator

# Documentation and Resources

- GitHub Repository: https://github.com/pepkio/pepkio-matched-null-gene-set-generator
- Web Application: https://www.pepkio.com/tools/matched-null-gene-set-generator
- PyPI Package: https://pypi.org/project/pepkio-matched-null-gene-set-generator/

# About Pepkio

Pepkio (https://www.pepkio.com/) develops software tools and bioinformatics solutions for life science researchers, including laboratory calculators and analysis services (https://www.pepkio.com/cro).

# Keywords

matched null gene set, GSEA negative controls, fgsea empirical null, gene set enrichment analysis, confounder matching, gene length bias, RNA-seq expression matching, GMT file export, clusterProfiler negative control, empirical FDR, biological negative control, transcript length confounder, GC content bias, stratified gene sampling, bioinformatics null model, human gene set matcher, mouse pathway control, zebrafish matched gene sets, yeast pathway null control, custom background gene enrichment, differential expression bias correction, camera pathway test calibration, topGO length bias, gseapy matched control, single-cell marker gene null set, CRISPR hit validation controls, multi-dimensional covariate binning, transcriptomics empirical FDR, bioinformatic negative control, reproducible gene set analysis
