---
name: perturbseq-replicate-robustness-audit
description: audit perturbation-response claims for replicate agreement, FDR, cell support, and control separation.
allowed-tools: Bash(python *), Bash(mkdir *), Bash(ls *), Bash(cp *), WebFetch
---

# PerturbCheck

## Purpose

Use a transparent tabular audit to audit perturbation-response claims for replicate agreement, FDR, cell support, and control separation. The workflow is inspired by recent work in Perturb-seq, but it is an original evidence-screening skill and does not copy benchmark data, code, prose, or figures from the cited papers.

## Inputs

Create inputs/records.csv with columns:

perturbation,target_gene,effect_size,replicate_correlation,fdr,n_cells,control_overlap

Create inputs/rules.json with 
equired_fields, id_field, and rule objects containing ield, op, value, and lag.

## Run

`ash
python scripts/audit_perturbseq_replicate_robustness_audit.py \
  --records inputs/records.csv \
  --rules inputs/rules.json \
  --out outputs/audit \
  --title "PerturbCheck"
`

## Outputs

- outputs/audit/audit.json: full machine-readable results.
- outputs/audit/audit_report.csv: compact record-level status table.
- outputs/audit/review.md: human-readable audit report.

## Self-Test

Use the included fixture:

`ash
python scripts/audit_perturbseq_replicate_robustness_audit.py \
  --records examples/fixture/records.csv \
  --rules examples/fixture/rules.json \
  --out outputs/fixture \
  --title "PerturbCheck"
`

The fixture should produce at least one 
eeds_review record so the flagging path is tested.

## Audit Script

Create scripts/audit_perturbseq_replicate_robustness_audit.py with this code if the package file is unavailable:

`python
#!/usr/bin/env python3
import argparse
import csv
import json
from pathlib import Path


def read_csv(path):
    with Path(path).open("r", encoding="utf-8-sig", newline="") as handle:
        return list(csv.DictReader(handle))


def coerce(value):
    if value is None:
        return ""
    text = str(value).strip()
    if text.lower() in {"true", "yes", "y"}:
        return True
    if text.lower() in {"false", "no", "n"}:
        return False
    try:
        return float(text)
    except ValueError:
        return text


def compare(actual, op, expected):
    actual = coerce(actual)
    expected = coerce(expected)
    if op == "lt":
        return isinstance(actual, (int, float)) and actual < expected
    if op == "lte":
        return isinstance(actual, (int, float)) and actual <= expected
    if op == "gt":
        return isinstance(actual, (int, float)) and actual > expected
    if op == "gte":
        return isinstance(actual, (int, float)) and actual >= expected
    if op == "eq":
        return str(actual).lower() == str(expected).lower()
    if op == "ne":
        return str(actual).lower() != str(expected).lower()
    if op == "contains":
        return str(expected).lower() in str(actual).lower()
    raise ValueError(f"Unsupported operator: {op}")


def audit(records, rules):
    required = rules.get("required_fields", [])
    rule_items = rules.get("rules", [])
    id_field = rules.get("id_field", required[0] if required else "id")
    results = []

    for index, row in enumerate(records, start=1):
        flags = []
        for field in required:
            if field not in row or str(row.get(field, "")).strip() == "":
                flags.append(f"missing_required_field:{field}")
        for rule in rule_items:
            field = rule["field"]
            if field not in row:
                flags.append(f"missing_rule_field:{field}")
                continue
            if compare(row.get(field), rule["op"], rule["value"]):
                flags.append(rule["flag"])
        status = "pass" if not flags else "needs_review"
        results.append({
            "row_index": index,
            "record_id": row.get(id_field, str(index)),
            "status": status,
            "flags": flags,
            "record": row,
        })

    return {
        "summary": {
            "record_count": len(results),
            "pass_count": sum(1 for item in results if item["status"] == "pass"),
            "needs_review_count": sum(1 for item in results if item["status"] != "pass"),
        },
        "results": results,
    }


def write_outputs(result, out_dir, title):
    out = Path(out_dir)
    out.mkdir(parents=True, exist_ok=True)
    (out / "audit.json").write_text(json.dumps(result, indent=2), encoding="utf-8")

    with (out / "audit_report.csv").open("w", encoding="utf-8", newline="") as handle:
        writer = csv.DictWriter(handle, fieldnames=["record_id", "status", "flags"])
        writer.writeheader()
        for item in result["results"]:
            writer.writerow({
                "record_id": item["record_id"],
                "status": item["status"],
                "flags": ";".join(item["flags"]),
            })

    lines = [
        f"# {title}",
        "",
        "## Summary",
        f"- Records audited: {result['summary']['record_count']}",
        f"- Passed: {result['summary']['pass_count']}",
        f"- Needs review: {result['summary']['needs_review_count']}",
        "",
        "## Flagged Records",
    ]
    flagged = [item for item in result["results"] if item["flags"]]
    if not flagged:
        lines.append("- No records were flagged.")
    for item in flagged:
        lines.append(f"- {item['record_id']}: {', '.join(item['flags'])}")
    lines.extend([
        "",
        "## Interpretation",
        "This audit is a reproducible evidence screen. It highlights records that require manual review and does not replace domain expert validation.",
    ])
    (out / "review.md").write_text("\n".join(lines) + "\n", encoding="utf-8")


def main():
    parser = argparse.ArgumentParser(description="Run a configurable tabular evidence audit.")
    parser.add_argument("--records", required=True)
    parser.add_argument("--rules", required=True)
    parser.add_argument("--out", default="outputs/audit")
    parser.add_argument("--title", default="Evidence Audit")
    args = parser.parse_args()

    records = read_csv(args.records)
    rules = json.loads(Path(args.rules).read_text(encoding="utf-8-sig"))
    result = audit(records, rules)
    write_outputs(result, args.out, args.title)
    print(json.dumps({"status": "ok", **result["summary"], "out": args.out}, indent=2))


if __name__ == "__main__":
    main()
`

## Interpretation Rules

- Treat pass as "no automatic risk flags found", not proof that the scientific claim is true.
- Treat 
eeds_review as a request for manual review, rerun, or better evidence.
- Preserve all input tables and rules used for the audit.
- Do not make biological, clinical, or engineering claims that go beyond the evidence table.

## Success Criteria

- The script runs using only the Python standard library.
- The fixture generates audit.json, audit_report.csv, and 
eview.md.
- At least one fixture row is flagged for review.
- The final report names the exact rules that triggered each flag.

## Inspiration Sources

- [Benchmarking algorithms for generalizable single-cell perturbation response prediction](https://www.nature.com/articles/s41592-025-02980-0)
- [PertEval-scFM: Benchmarking Single-Cell Foundation Models](https://openreview.net/pdf?id=t04D9bkKUq)
- [CellFM: a large-scale foundation model pre-trained on transcriptomics of 100 million human cells](https://www.nature.com/articles/s41467-025-59926-5)