Metadata-Version: 2.5
Name: pepkio-power-and-effect-navigator
Version: 0.1.0
Summary: Python client for Pepkio power-and-effect-navigator tool
Author-email: Pepkio Team <tools@pepkio.com>
Requires-Python: >=3.11
Requires-Dist: click>=8.4.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.4
Description-Content-Type: text/markdown

# Pepkio Power & Effect Navigator

Execute biostatistical power analysis, sample size determination, minimum detectable effect sizing, and IACUC protocol text generation for t-tests, ANOVA, proportions, and RNA-seq assays via Python or REST API.

# What It Does

Determining appropriate sample sizes and statistical power ($1 - \beta \ge 0.80$) is vital for biomedical experiments, including cell culture knockouts, animal treatment trials, quantitative PCR (qPCR), ELISA, and high-throughput RNA-sequencing (RNA-seq). Planning sample sizes ensures studies possess sufficient statistical sensitivity to detect biological differences while avoiding excessive sample usage that wastes reagents or animal lives.

The `pepkio-power-and-effect-navigator` package connects Python data pipelines directly to the Pepkio Power & Effect Navigator engine. It calculates required sample sizes, achieved statistical power, or minimum detectable effect (MDE) across standard univariate designs and negative binomial RNA-seq models. Calculations automatically account for real-world experimental factors including sample dropout rates, unequal group allocation ratios ($n_2 / n_1$), pilot variance uncertainty corrections, and False Discovery Rate (FDR) control.

# Features

- **Multi-Test Statistical Suite**: Supports independent two-sample t-tests, paired t-tests, one-sample t-tests, One-Way ANOVA, two-sample proportion tests, and bulk RNA-seq differential expression analysis.
- **Flexible Optimization Targets**: Computes required sample size per group ($n$), achieved statistical power ($1 - \beta$), or minimum detectable effect size (Cohen's $d$, Cohen's $f$, proportion delta, or RNA-seq log-fold change).
- **Experimental Dropout & Allocation Adjustment**: Calculates both analyzable sample count ($n_{\text{analyzable}}$) and total enrolled subjects ($n_{\text{enrolled}}$) based on expected sample loss and unequal group allocation ratios ($n_2 / n_1$).
- **Pilot Variance Uncertainty Correction**: Applies non-central distribution confidence bounds to variance estimates derived from small pilot studies ($n_{\text{pilot}} \ge 4$), preventing sample size underestimation in pivotal trials.
- **RNA-Seq Negative Binomial Power Model**: Incorporates average read depth ($\mu$), biological coefficient of variation ($\text{BCV} = \sqrt{\phi}$), total gene counts ($m$), expected differentially expressed fraction ($\pi_1$), and target False Discovery Rate ($q$).
- **Protocol Justification Generator**: Produces formatted sample size justification text tailored for IACUC protocol submissions, grant applications (NIH, ERC), and manuscript methods sections.
- **Python API & CLI**: Provides both a programmatic Python client (`PepkioClient`, `PowerInput`) and a command-line interface (`pepkio-power-and-effect-navigator`) for batch processing.

# Installation

Install the package via `pip`:

```bash
pip install pepkio-power-and-effect-navigator
```

Set your Pepkio API key as an environment variable before running calculations:

```bash
export PEPKIO_API_KEY="your-api-key"
```

# Quick Example

Python API usage:

```python
from pepkio_power_and_effect_navigator import PepkioClient, PowerInput

with PepkioClient() as client:
    ttest_input = PowerInput(
        test_type="ttest",
        solve_for="n",
        alpha=0.05,
        power=0.80,
        effect_size=0.8,
        allocation_ratio=1.0,
        dropout_rate=0.10,
        ttest_design="two_sample",
        justification_template="iacuc",
    )

    result = client.run(ttest_input)
    output = result.parsed_output

    if output:
        print("Analyzable Sample Size per Group:", output.n_per_group_1)
        print("Total Enrolled Sample Size:", output.n_total_enrolled)
        print(f"Achieved Power: {output.achieved_power:.3f}")
        print("\nIACUC Protocol Justification:\n", output.justification_text)
```

Command-line interface usage:

```bash
pepkio-power-and-effect-navigator manifest
pepkio-power-and-effect-navigator run --example ttest_two_sample_n
```

# Typical Use Cases

- **Pre-clinical Animal Trials**: Calculate group sample sizes for a multi-arm mouse study evaluated by One-Way ANOVA, adjusting for a 15% animal loss rate and generating ready-to-paste IACUC protocol justification text.
- **Cell Line Knockout Validation**: Determine the minimum detectable effect size (Cohen's $d$) when comparing target protein expression between wild-type and knockout lines with a fixed sample size ($n = 4$ per group).
- **Bulk RNA-Seq Assay Design**: Estimate biological replicate counts required to detect a 1.5-fold expression change at FDR $q = 0.05$, given mean gene read depth of 20 counts and biological coefficient of variation ($\text{BCV}$) of 0.4.
- **Paired Microplate Screening**: Evaluate statistical power for paired t-test designs comparing organoid responses before and after compound exposure ($n = 10$ paired samples).
- **Flow Cytometry Population Analysis**: Calculate sample size requirements for comparing marker-positive cell fractions ($p_1 = 5\%$ vs $p_2 = 15\%$) using two-sample proportion tests with an unequal $2:1$ treatment-to-control ratio.

# Scientific Background

Statistical power ($1 - \beta$) measures the probability of correctly rejecting a false null hypothesis. Univariate power calculations rely on non-central $t$ or $F$ distributions, where non-centrality parameters depend on standardized effect size (Cohen's $d$ or $f$), sample size ($n$), and significance level ($\alpha$). Bulk RNA-seq data exhibit overdispersion and are modeled using negative binomial distributions where variance is a function of mean read count $\mu$ and biological coefficient of variation ($\text{BCV} = \sqrt{\phi}$), with significance thresholds adjusted for genome-wide multiple testing via False Discovery Rate (FDR) control. Standard deviation estimates from small pilot studies ($n < 10$) carry high uncertainty; applying non-central chi-squared confidence corrections ensures full-scale studies are not underpowered due to pilot sampling error.

# Web Application

For researchers who prefer a graphical interface, an interactive web version is available.

Web Application: https://www.pepkio.com/tools/power-and-effect-navigator

The web interface features interactive power-versus-sample-size curves, minimum detectable effect sensitivity contour plots, downloadable CSV worksheets, shareable calculation permalinks, and interactive protocol text editors.

# Documentation and Resources

GitHub Repository: https://github.com/pepkio/pepkio-power-and-effect-navigator

Web Application: https://www.pepkio.com/tools/power-and-effect-navigator

# 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

statistical power calculator, sample size calculator, minimum detectable effect size, Cohen's d calculator, Cohen's f calculator, t-test power analysis, ANOVA power calculator, proportion test sample size, RNA-seq sample size estimation, negative binomial power model, biological coefficient of variation, BCV dispersion calculator, False Discovery Rate power, FDR sample size adjustment, IACUC sample size justification, pilot study variance correction, experimental dropout rate adjustment, allocation ratio sample size, power curve generator, pepkio-power-and-effect-navigator, Python biostatistics package, REST API statistical power engine, paired t-test power, one-sample t-test sample size, biological replicate calculator, calculate sample size for mouse experiment IACUC protocol, estimate biological replicate number for RNA-seq differential expression, determine sample size per group with expected animal dropout rate, calculate minimum detectable effect size Cohen's d for small sample size, RNA-seq power calculation negative binomial read depth BCV, pilot study uncertainty adjustment sample size calculation Python, generate sample size justification text for grant proposal, two-sample t-test sample size with unequal allocation ratio, One-Way ANOVA statistical power calculation Python client, calculate power for paired organoid drug response assay, estimate proportion test sample size for flow cytometry screening, automate statistical power analysis in Python data pipeline, convert raw pilot variance to sample size with confidence bounds, REST API sample size calculator with IACUC protocol text generation, batch statistical power navigation via Python client and CLI
