perturbguard 1.0.0__tar.gz

perturbguard-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -q
+      - name: Build package
+        run: python -m build
+      - name: Install wheel smoke
+        shell: bash
+        run: |
+          python -m venv /tmp/pg-wheel
+          source /tmp/pg-wheel/bin/activate
+          python -m pip install --upgrade pip
+          python -m pip install dist/*.whl
+          perturbguard --help

perturbguard-1.0.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.0.0
+
+- First stable PerturbGuard release.
+- Adds the full guardrail loop for perturbation benchmarking: config inference, AnnData repair, validation, audit, split generation, claim checking, adversarial leakage checks, model prediction evaluation, benchmark manifest validation, large-file profiling, and dataset-card generation.
+- Adds interactive HTML reports with status summary cards, searchable tables, status filters, plot links, and clearer PASS/WARNING/FAIL/SUPPORTED/UNSUPPORTED styling.
+- Adds target mapping audits for gene, drug class, pathway/class, missing, and unmapped targets, with optional user-supplied perturbation-to-target maps.
+- Adds power/design planning checks for planned cells, controls, replicate support, and batch support.
+- Expands CLI smoke testing across synthetic scenarios, real public datasets, split strategies, claim types, design checks, benchmark manifests, and the advanced guardrail commands.
+- Packages configs, docs, and Snakemake workflow assets in release artifacts.
+
+## 0.1.0
+
+- Initial production-hardening line for PerturbGuard.
+- Adds CLI commands for validation, audit, split generation, claim checking, dataset comparison, design checks, and synthetic simulation.
+- Adds schema mapping, synthetic and real-data smoke workflows, split leakage checks, QC tables, recommendations, HTML reports, and plot artifacts.

perturbguard-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PerturbGuard contributors
+
+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.

perturbguard-1.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include CHANGELOG.md
+recursive-include configs *.yaml
+recursive-include docs *.md
+recursive-include scripts *.py
+recursive-include workflows *
+recursive-include .github *.yml

perturbguard-1.0.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: perturbguard
+Version: 1.0.0
+Summary: QC, leakage detection, split design, and claim validation for single-cell perturbation studies.
+Author: PerturbGuard contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/perturbguard/perturbguard
+Project-URL: Documentation, https://github.com/perturbguard/perturbguard#readme
+Project-URL: Issues, https://github.com/perturbguard/perturbguard/issues
+Keywords: single-cell,perturb-seq,quality-control,leakage,anndata
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anndata>=0.10
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: statsmodels
+Requires-Dist: networkx
+Requires-Dist: typer
+Requires-Dist: rich
+Requires-Dist: pyyaml
+Requires-Dist: jinja2
+Requires-Dist: plotly
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# PerturbGuard
+
+[![CI](https://github.com/prithvirajanR/perturbguard/actions/workflows/ci.yml/badge.svg)](https://github.com/prithvirajanR/perturbguard/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![Release](https://img.shields.io/badge/release-1.0.0-green)](https://github.com/prithvirajanR/perturbguard/releases/tag/v1.0.0)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)
+
+**FastQC-style guardrails for single-cell perturbation datasets, splits, claims, and model benchmarks.**
+
+PerturbGuard helps you answer the uncomfortable but necessary question:
+
+> Is this perturbation benchmark actually valid, or did leakage, controls, confounding, weak target effects, or split design make it look better than it is?
+
+It works with AnnData `.h5ad` files and produces interactive HTML reports, machine-readable CSV tables, JSON summaries, and Markdown dataset cards.
+
+## Why Use It
+
+Perturbation models are easy to overclaim. A model can appear to generalize because the split leaked perturbations, a batch variable predicts the label, controls are missing, target effects failed, or a drug target was treated as a single gene when it is really a pathway/class.
+
+PerturbGuard audits those failure modes before you trust a dataset, split, claim, or benchmark.
+
+## Install
+
+From GitHub:
+
+```bash
+pip install "perturbguard @ git+https://github.com/prithvirajanR/perturbguard.git@v1.0.0"
+```
+
+For local development:
+
+```bash
+git clone https://github.com/prithvirajanR/perturbguard.git
+cd perturbguard
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Quickstart
+
+```bash
+perturbguard simulate --scenario batch_confounded --out data/demo/batch_confounded.h5ad
+perturbguard audit --data data/demo/batch_confounded.h5ad --out results/demo_audit
+```
+
+Open:
+
+```text
+results/demo_audit/report.html
+```
+
+You get a searchable report with status filters, summary cards, linked plots, recommendations, and CSV tables under `results/demo_audit/tables/`.
+
+## Common Workflows
+
+### Audit a raw public dataset
+
+```bash
+perturbguard infer-config --data data/raw.h5ad --out configs/inferred.yaml
+perturbguard repair --data data/raw.h5ad --config configs/inferred.yaml --out data/repaired.h5ad
+perturbguard audit --data data/repaired.h5ad --config configs/inferred.yaml --out results/audit
+```
+
+### Generate and validate a split
+
+```bash
+perturbguard split \
+  --data data/repaired.h5ad \
+  --strategy leave-perturbation-out \
+  --out results/split
+
+perturbguard claim \
+  --data data/repaired.h5ad \
+  --split results/split/split.csv \
+  --claim unseen_perturbation \
+  --out results/claim
+```
+
+### Evaluate model predictions
+
+```bash
+perturbguard evaluate \
+  --data data/repaired.h5ad \
+  --predictions predictions.csv \
+  --out results/evaluation
+```
+
+## Feature Map
+
+| Area | What PerturbGuard Does |
+| --- | --- |
+| AnnData validation | Checks loadability, matrix presence, cell/gene counts, controls, perturbation metadata, duplicate obs/var names, and malformed files. |
+| Config inference | Suggests YAML schema mappings from common metadata aliases in messy public datasets. |
+| Repair | Writes normalized `.h5ad` files with canonical metadata, unique indices, inferred controls, and repair action logs. |
+| QC audit | Audits perturbation support, controls, cell counts, confounding, metadata shortcuts, target effects, guide consistency, and target mapping. |
+| Split generation | Creates random, leave-target-gene-out, leave-perturbation-out, metadata holdout, strict combination, and seen-component combination splits. |
+| Claim checking | Verifies whether a split supports claims like unseen perturbation, unseen target gene, or unseen combinations. |
+| Leakage detection | Detects train/val/test leakage, combination leakage, unsupported claims, split imbalance, and invalid split labels. |
+| Model evaluation | Audits prediction CSVs for overall metrics, per-group performance, and confidence calibration. |
+| Adversarial checks | Tests whether metadata-only shortcuts can predict perturbation identity. |
+| Target mapping | Classifies targets as measured genes, drug target classes, pathway/class annotations, missing, or unmapped. |
+| Design planning | Checks planned cells, controls, replicate support, and batch support before running an experiment. |
+| Benchmark manifests | Validates dataset/split/claim/model/metrics manifests and runs claim-support checks. |
+| Large files | Profiles `.h5ad` files in backed mode before expensive audits. |
+| Dataset cards | Generates Markdown dataset cards with audit counts, uses, and limitations. |
+| Reports | Writes interactive HTML reports, plot links, CSV tables, `summary.json`, and recommendations. |
+
+## CLI Commands
+
+```text
+perturbguard simulate
+perturbguard validate
+perturbguard audit
+perturbguard split
+perturbguard claim
+perturbguard evaluate
+perturbguard repair
+perturbguard infer-config
+perturbguard target-map
+perturbguard compare-datasets
+perturbguard design-check
+perturbguard power-check
+perturbguard benchmark-check
+perturbguard profile-large
+perturbguard adversarial-check
+perturbguard dataset-card
+```
+
+## Input Formats
+
+### AnnData
+
+Required for full audits:
+
+- `perturbation`
+- `is_control`, or enough configured control labels to infer controls
+
+Recommended:
+
+- `target_gene`
+- `guide_id`
+- `perturbation_type`
+- `batch`
+- `replicate`
+- `cell_type`
+- `donor`
+- `plate`
+- `timepoint`
+- `dose`
+
+### Prediction CSV
+
+Required for `perturbguard evaluate`:
+
+- `cell_id`
+- `y_true`
+- `y_pred`
+
+Optional:
+
+- `confidence`
+
+### Target Mapping CSV
+
+Recommended for `perturbguard target-map`:
+
+- `perturbation`
+- `target`
+- optional `target_type`
+- optional `source`
+
+### Benchmark Manifest
+
+```yaml
+dataset: data/repaired.h5ad
+split: results/split/split.csv
+claim: unseen_perturbation
+model:
+  name: my-model
+metrics:
+  - accuracy
+  - macro_f1
+```
+
+## Real Data Smoke Test
+
+PerturbGuard has been smoke-tested locally on public example AnnData files for SciPlex, Jorge, and LINCS-style perturbation datasets.
+
+Example SciPlex run:
+
+```powershell
+Invoke-WebRequest `
+  -Uri "https://huggingface.co/cyclopeta/PerturbNet_reproduce/resolve/main/example_data/sciplex_example.h5ad" `
+  -OutFile data/real/sciplex_example.h5ad
+
+perturbguard audit `
+  --data data/real/sciplex_example.h5ad `
+  --config configs/sciplex_example.yaml `
+  --out results/real/sciplex_audit
+```
+
+Full smoke matrix:
+
+```bash
+python scripts/run_smoke_matrix.py --include-real
+```
+
+## What It Is Not
+
+PerturbGuard is not a perturbation prediction model and does not claim biological truth for unmeasured perturbations. It is a guardrail system: it tells you when your dataset, split, controls, metadata, or benchmark claim may not support the conclusion you want to draw.
+
+## Release
+
+Current stable release: `1.0.0`
+
+Built and verified with:
+
+- Python 3.11+
+- AnnData
+- pandas / NumPy / SciPy
+- scikit-learn
+- Plotly
+- Typer
+

perturbguard-1.0.0/README.md

@@ -0,0 +1,224 @@
+# PerturbGuard
+
+[![CI](https://github.com/prithvirajanR/perturbguard/actions/workflows/ci.yml/badge.svg)](https://github.com/prithvirajanR/perturbguard/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![Release](https://img.shields.io/badge/release-1.0.0-green)](https://github.com/prithvirajanR/perturbguard/releases/tag/v1.0.0)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)
+
+**FastQC-style guardrails for single-cell perturbation datasets, splits, claims, and model benchmarks.**
+
+PerturbGuard helps you answer the uncomfortable but necessary question:
+
+> Is this perturbation benchmark actually valid, or did leakage, controls, confounding, weak target effects, or split design make it look better than it is?
+
+It works with AnnData `.h5ad` files and produces interactive HTML reports, machine-readable CSV tables, JSON summaries, and Markdown dataset cards.
+
+## Why Use It
+
+Perturbation models are easy to overclaim. A model can appear to generalize because the split leaked perturbations, a batch variable predicts the label, controls are missing, target effects failed, or a drug target was treated as a single gene when it is really a pathway/class.
+
+PerturbGuard audits those failure modes before you trust a dataset, split, claim, or benchmark.
+
+## Install
+
+From GitHub:
+
+```bash
+pip install "perturbguard @ git+https://github.com/prithvirajanR/perturbguard.git@v1.0.0"
+```
+
+For local development:
+
+```bash
+git clone https://github.com/prithvirajanR/perturbguard.git
+cd perturbguard
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Quickstart
+
+```bash
+perturbguard simulate --scenario batch_confounded --out data/demo/batch_confounded.h5ad
+perturbguard audit --data data/demo/batch_confounded.h5ad --out results/demo_audit
+```
+
+Open:
+
+```text
+results/demo_audit/report.html
+```
+
+You get a searchable report with status filters, summary cards, linked plots, recommendations, and CSV tables under `results/demo_audit/tables/`.
+
+## Common Workflows
+
+### Audit a raw public dataset
+
+```bash
+perturbguard infer-config --data data/raw.h5ad --out configs/inferred.yaml
+perturbguard repair --data data/raw.h5ad --config configs/inferred.yaml --out data/repaired.h5ad
+perturbguard audit --data data/repaired.h5ad --config configs/inferred.yaml --out results/audit
+```
+
+### Generate and validate a split
+
+```bash
+perturbguard split \
+  --data data/repaired.h5ad \
+  --strategy leave-perturbation-out \
+  --out results/split
+
+perturbguard claim \
+  --data data/repaired.h5ad \
+  --split results/split/split.csv \
+  --claim unseen_perturbation \
+  --out results/claim
+```
+
+### Evaluate model predictions
+
+```bash
+perturbguard evaluate \
+  --data data/repaired.h5ad \
+  --predictions predictions.csv \
+  --out results/evaluation
+```
+
+## Feature Map
+
+| Area | What PerturbGuard Does |
+| --- | --- |
+| AnnData validation | Checks loadability, matrix presence, cell/gene counts, controls, perturbation metadata, duplicate obs/var names, and malformed files. |
+| Config inference | Suggests YAML schema mappings from common metadata aliases in messy public datasets. |
+| Repair | Writes normalized `.h5ad` files with canonical metadata, unique indices, inferred controls, and repair action logs. |
+| QC audit | Audits perturbation support, controls, cell counts, confounding, metadata shortcuts, target effects, guide consistency, and target mapping. |
+| Split generation | Creates random, leave-target-gene-out, leave-perturbation-out, metadata holdout, strict combination, and seen-component combination splits. |
+| Claim checking | Verifies whether a split supports claims like unseen perturbation, unseen target gene, or unseen combinations. |
+| Leakage detection | Detects train/val/test leakage, combination leakage, unsupported claims, split imbalance, and invalid split labels. |
+| Model evaluation | Audits prediction CSVs for overall metrics, per-group performance, and confidence calibration. |
+| Adversarial checks | Tests whether metadata-only shortcuts can predict perturbation identity. |
+| Target mapping | Classifies targets as measured genes, drug target classes, pathway/class annotations, missing, or unmapped. |
+| Design planning | Checks planned cells, controls, replicate support, and batch support before running an experiment. |
+| Benchmark manifests | Validates dataset/split/claim/model/metrics manifests and runs claim-support checks. |
+| Large files | Profiles `.h5ad` files in backed mode before expensive audits. |
+| Dataset cards | Generates Markdown dataset cards with audit counts, uses, and limitations. |
+| Reports | Writes interactive HTML reports, plot links, CSV tables, `summary.json`, and recommendations. |
+
+## CLI Commands
+
+```text
+perturbguard simulate
+perturbguard validate
+perturbguard audit
+perturbguard split
+perturbguard claim
+perturbguard evaluate
+perturbguard repair
+perturbguard infer-config
+perturbguard target-map
+perturbguard compare-datasets
+perturbguard design-check
+perturbguard power-check
+perturbguard benchmark-check
+perturbguard profile-large
+perturbguard adversarial-check
+perturbguard dataset-card
+```
+
+## Input Formats
+
+### AnnData
+
+Required for full audits:
+
+- `perturbation`
+- `is_control`, or enough configured control labels to infer controls
+
+Recommended:
+
+- `target_gene`
+- `guide_id`
+- `perturbation_type`
+- `batch`
+- `replicate`
+- `cell_type`
+- `donor`
+- `plate`
+- `timepoint`
+- `dose`
+
+### Prediction CSV
+
+Required for `perturbguard evaluate`:
+
+- `cell_id`
+- `y_true`
+- `y_pred`
+
+Optional:
+
+- `confidence`
+
+### Target Mapping CSV
+
+Recommended for `perturbguard target-map`:
+
+- `perturbation`
+- `target`
+- optional `target_type`
+- optional `source`
+
+### Benchmark Manifest
+
+```yaml
+dataset: data/repaired.h5ad
+split: results/split/split.csv
+claim: unseen_perturbation
+model:
+  name: my-model
+metrics:
+  - accuracy
+  - macro_f1
+```
+
+## Real Data Smoke Test
+
+PerturbGuard has been smoke-tested locally on public example AnnData files for SciPlex, Jorge, and LINCS-style perturbation datasets.
+
+Example SciPlex run:
+
+```powershell
+Invoke-WebRequest `
+  -Uri "https://huggingface.co/cyclopeta/PerturbNet_reproduce/resolve/main/example_data/sciplex_example.h5ad" `
+  -OutFile data/real/sciplex_example.h5ad
+
+perturbguard audit `
+  --data data/real/sciplex_example.h5ad `
+  --config configs/sciplex_example.yaml `
+  --out results/real/sciplex_audit
+```
+
+Full smoke matrix:
+
+```bash
+python scripts/run_smoke_matrix.py --include-real
+```
+
+## What It Is Not
+
+PerturbGuard is not a perturbation prediction model and does not claim biological truth for unmeasured perturbations. It is a guardrail system: it tells you when your dataset, split, controls, metadata, or benchmark claim may not support the conclusion you want to draw.
+
+## Release
+
+Current stable release: `1.0.0`
+
+Built and verified with:
+
+- Python 3.11+
+- AnnData
+- pandas / NumPy / SciPy
+- scikit-learn
+- Plotly
+- Typer
+

perturbguard-1.0.0/configs/default.yaml

@@ -0,0 +1,19 @@
+schema:
+  perturbation: perturbation
+  is_control: is_control
+  target_gene: target_gene
+  guide_id: guide_id
+  perturbation_type: perturbation_type
+  cell_type: cell_type
+  batch: batch
+  replicate: replicate
+controls:
+  labels: ["control", "ctrl", "NTC", "non-targeting", "DMSO", "vehicle"]
+  min_controls_per_group: 30
+cell_count:
+  min_cells_warning: 50
+  min_cells_fail: 20
+confounding:
+  metadata_columns: ["batch", "replicate", "donor", "plate", "timepoint"]
+  cramers_v_warning: 0.3
+  cramers_v_fail: 0.5

perturbguard-1.0.0/configs/jorge_example.yaml

@@ -0,0 +1,10 @@
+schema:
+  perturbation: mutation_name
+  is_control: UTR_cond
+  target_gene: mutation_name
+  guide_id: mutation_poi
+  perturbation_type: UTR_cond
+  batch: mutation_poi
+
+controls:
+  labels: ["WT", "not mutated"]

perturbguard-1.0.0/configs/lincs_example.yaml

@@ -0,0 +1,11 @@
+schema:
+  perturbation: pert_iname
+  target_gene: pert_id
+  perturbation_type: pert_type
+  cell_type: cell_id
+  batch: batch_ident
+  timepoint: pert_time
+  dose: fake_dose
+
+controls:
+  labels: ["DMSO", "vehicle", "control", "ctrl"]

perturbguard-1.0.0/configs/sciplex_example.yaml

@@ -0,0 +1,15 @@
+schema:
+  perturbation: product_name_clean
+  is_control: vehicle
+  target_gene: target
+  perturbation_type: perturb_string_processed
+  cell_type: cell_type
+  batch: culture_plate
+  replicate: replicate
+  timepoint: time_point
+  dose: dose
+  n_counts: n_counts
+  pct_mito: percent_mito
+
+controls:
+  labels: ["DMSO", "vehicle", "control", "ctrl"]

perturbguard-1.0.0/docs/advanced_features.md

@@ -0,0 +1,16 @@
+# Advanced Features
+
+PerturbGuard now includes ten higher-level guardrails beyond the original audit core.
+
+1. `evaluate`: audits model predictions overall, by metadata group, and by optional confidence calibration.
+2. `repair`: writes a normalized AnnData file with canonical metadata, unique indices, and inferred controls where possible.
+3. Interactive HTML reports: reports include search, status filters, summary cards, and plot links.
+4. `target-map`: classifies target annotations as measured genes, drug classes, pathways/classes, missing, or unmapped.
+5. `power-check`: checks planned cells, controls, replicate support, and batch support before an experiment.
+6. `benchmark-check`: validates a benchmark manifest and checks whether the declared claim is supported by the split.
+7. `profile-large`: opens `.h5ad` files in backed mode and reports shape/storage metadata before expensive audits.
+8. `adversarial-check`: asks whether technical metadata can predict perturbation identity.
+9. `infer-config`: suggests a YAML schema mapping from common metadata aliases.
+10. `dataset-card`: writes a Markdown summary of dataset size, controls, audit statuses, supported uses, and limitations.
+
+These checks are guardrails. They help prevent invalid benchmark claims and brittle analyses, but they do not replace biological validation or model-specific evaluation.

perturbguard-1.0.0/docs/assumptions.md

@@ -0,0 +1,14 @@
+# Statistical Assumptions And Thresholds
+
+PerturbGuard reports measurable audit risks. It does not prove biological truth.
+
+Default thresholds are intentionally conservative:
+
+- Low perturbation support: warning below 50 cells, fail below 20 cells.
+- Batch or metadata confounding: warning at Cramer's V >= 0.3, fail at >= 0.5.
+- Dominant metadata concentration: warning at 70%, fail at 90%.
+- Metadata-only shortcut baseline: warning at balanced accuracy >= 0.4, fail at >= 0.6.
+- Guide consistency: warning at median correlation <= 0.2, fail at <= 0.0.
+
+These are screening thresholds, not universal biological cutoffs. Users should tune them for
+experiment size, modality, cell type diversity, dose design, and intended claim.

perturbguard-1.0.0/docs/beta_test_report.md

@@ -0,0 +1,15 @@
+# Beta Test Report
+
+PerturbGuard has been smoke-tested on synthetic perturbation scenarios and public example
+AnnData files from the PerturbNet reproduction repository.
+
+Real-data cases:
+
+| Dataset | File | Purpose |
+|---|---|---|
+| SciPlex | `data/real/sciplex_example.h5ad` | Drug perturbation metadata, dose/time/cell-type fields |
+| Jorge | `data/real/Jorge_example.h5ad` | Variant perturbation labels and dataset-specific controls |
+| LINCS | `data/real/lincs_example.h5ad` | Drug perturbations, many batches/cell IDs, provided holdouts |
+
+The real-data tests verify that schema mapping, missing-control handling, target classification,
+audit table writing, HTML reports, plots, and provided split claim checks complete without crashes.