[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CTZRGFZ4ZP80HZPMWXY0SA":3,"skill-same:01M7CTZRGFZ4ZP80HZPMWXY0SA":59},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":32,"install":33,"resources":46},"01M7CTZRGFZ4ZP80HZPMWXY0SA","bio-crispr-screens-hit-calling",null,"Cross-method decision tree for calling hits in pooled CRISPR screens. Catalogs statistical models (MAGeCK RRA, MAGeCK MLE, BAGEL2, drugZ, JACKS, Chronos, CERES), experimental designs each is built for, failure modes outside design domain, reconciliation when methods disagree, multiple-testing and effect-size thresholds, the order of operations (count -> QC -> CN-correct -> hit-call -> validate), the second-best-sgRNA conservative rule, and consensus-hit strategy. Use when choosing among MAGeCK \u002F BAGEL2 \u002F drugZ \u002F JACKS \u002F Chronos for a given design, reconciling disagreement across two or three methods on the same screen, deciding whether to require consensus, gating downstream validation by hit-confidence tier, or interpreting unstable hit lists across reruns.","mrsonord2240\u002Fopenscience-specialists","mrsonord2240","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F76487430?v=4","01M7CTEM40S43GSJZ9A3YCCXZK","Samuel Nord","01M7CTEM4K69JD1GBYNHVJ9ZP4",2,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Fcrispr-screen-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-crispr-screens-hit-calling\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: bio-crispr-screens-hit-calling\ndescription: Cross-method decision tree for calling hits in pooled CRISPR screens. Catalogs statistical models (MAGeCK RRA, MAGeCK MLE, BAGEL2, drugZ, JACKS, Chronos, CERES), experimental designs each is built for, failure modes outside design domain, reconciliation when methods disagree, multiple-testing and effect-size thresholds, the order of operations (count -> QC -> CN-correct -> hit-call -> validate), the second-best-sgRNA conservative rule, and consensus-hit strategy. Use when choosing among MAGeCK \u002F BAGEL2 \u002F drugZ \u002F JACKS \u002F Chronos for a given design, reconciling disagreement across two or three methods on the same screen, deciding whether to require consensus, gating downstream validation by hit-confidence tier, or interpreting unstable hit lists across reruns.\ntool_type: mixed\nprimary_tool: MAGeCK\n---\n\n## Version Compatibility\n\nReference examples tested with: MAGeCK 0.5.9+, BAGEL2 2.0, drugZ Aug 2019+, JACKS 0.2.0+, Chronos 2.0+ (DepMap), CERES 1.0+, pandas 2.2+, numpy 1.26+, scipy 1.12+, statsmodels 0.14+.\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- CLI: `mageck --version`, `BAGEL.py version`, `python drugz.py --help`\n- Python: `pip show crispr_chronos` (JACKS installs from GitHub, not PyPI)\n\nIf code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.\n\n## Hit Calling Decision Tree\n\n**\"Identify significant hits in my CRISPR screen\"** -> Choose the analysis method that matches the experimental design, statistical assumptions, and quality grade of the screen. Reconcile across methods when high-stakes hits must be validated.\n\nThe primary hit-calling methods cover non-overlapping niches; the decision is not \"which is best\" but \"which matches the design.\"\n\n| Design \u002F question | Primary method | Why | Secondary check |\n|--------------------|----------------|-----|------------------|\n| Two-condition essentiality, one cell line, no CN concerns | MAGeCK RRA | Robust, fast, gold-standard for ranked analysis | BAGEL2 (Bayes factor on same data) |\n| Time course (3+ timepoints) | MAGeCK MLE | RRA cannot model multi-condition | JACKS (efficacy-aware) |\n| Multi-cell-line panel (cancer dependency) | Chronos | Models CN bias + screen quality jointly | MAGeCK MLE per line + meta-analysis |\n| Drug screen (vehicle vs drug) | drugZ | Bidirectional Z; vehicle-anchored | MAGeCK MLE with dose covariate |\n| Multi-screen joint, same library | JACKS | Shared efficacy; enables ~2.5x smaller screens | MAGeCK MLE; results should converge |\n| Essentiality classification with reference sets | BAGEL2 | Bayes factor with CEGv2\u002FNEGv1 calibration | MAGeCK RRA |\n| Combinatorial \u002F paired guide | MAGeCK MLE with GI scoring | Models interaction term; see [[combinatorial-screens]] | Custom GI scoring |\n| Single-cell perturbation (Perturb-seq) | SCEPTRE | NB GLM + permutation; see [[perturb-seq-analysis]] | Mixscape pre-filter |\n| Cancer-line copy-number screen | Chronos (preferred) or CERES | Joint CN-bias + gene-effect modeling; see [[copy-number-correction]] | CRISPRcleanR pre-hoc + MAGeCK |\n\n## Statistical Models Compared\n\n| Method | Year | Statistical model | Tests | Best for | Fails when |\n|--------|------|-------------------|-------|----------|------------|\n| MAGeCK RRA | 2014 | NB per-sgRNA -> alpha-RRA per gene | Two-sided | General two-condition | >40% guides change (median norm breaks); time course; cancer-line CN |\n| MAGeCK MLE | 2015 | NB GLM with design matrix; per-gene beta | Wald per condition | Multi-condition \u002F time course | Cell-line specific essentiality; CN bias |\n| BAGEL2 | 2021 | Bayes factor from log-likelihood ratio | Essential vs non-essential | Essentiality classification | Non-essentiality screens; drug screens |\n| drugZ | 2019 | Bidirectional Z-score on guide-level LFC | Sensitizer vs suppressor | Drug-modifier \u002F chemogenomic | Essentiality (no biological prior); time-course |\n| JACKS | 2019 | Variational Bayes: LFC = gene * efficacy | Per-gene posterior | Multi-screen joint, library calibration | Single screen; cross-chemistry |\n| Chronos | 2021 | Cell-population dynamics ODE + NB | Gene effect adjusted for screen quality | Cancer-line panels, longitudinal | Single screen; non-cancer applications |\n| CERES | 2017 | Nonlinear model decoupling CN-bias from gene effect | Per-gene effect | Cancer-line panel with CN profile | Superseded by Chronos at DepMap |\n\n## RRA vs MLE Within MAGeCK\n\n| Property | RRA (`mageck test`) | MLE (`mageck mle`) |\n|----------|----------------------|---------------------|\n| Conditions supported | 2 | Multiple (design matrix) |\n| Statistical test | Robust rank aggregation | Wald on beta from NB GLM |\n| Output | neg\u002Fpos score, FDR per direction | beta per condition |\n| sgRNA efficiency | Not modeled (optional fixed input) | Modeled via `--sgrna-efficiency` |\n| Outlier robustness | High (rank-based) | Lower (likelihood-based) |\n| Best for | Standard 2-condition screen | Time course, drug screen, multi-cell-line, paired |\n| Speed | Fast | Slow (per-gene optimization) |\n\n## Algorithmic Taxonomy: Why Each Was Built\n\n| Method | Designed to solve |\n|--------|--------------------|\n| MAGeCK RRA | First robust statistical framework for CRISPR-screen ranking; alpha-RRA borrowed from RRA in microarray meta-analysis |\n| MAGeCK MLE | Extend MAGeCK to multi-condition; explicit beta scores allow direct LFC interpretation |\n| BAGEL2 | Reference-set-anchored Bayesian classification; precision-recall calibrated; tumor-suppressor sensitivity (BAGEL1 was uni-directional) |\n| drugZ | Drug-modifier screens have low effect sizes and need bidirectional sensitivity; STARS\u002FMAGeCK miss synthetic-lethal hits |\n| JACKS | Sample-size reduction via library-shared efficacy; library calibration as side product |\n| Chronos | DepMap-scale (1000+ cell lines, billions of cell-divisions) needs population-dynamics model; CN bias + screen quality first-class |\n| CERES | First to formally decouple CN from gene effect at DepMap scale; superseded but historically important |\n\n## Run All Five on the Same Data (Consensus Strategy)\n\n**Goal:** For high-stakes hits (drug-target nomination, paper-level claims), require agreement across 2-3 orthogonal methods.\n\n**Approach:** Run MAGeCK + BAGEL2 + (drugZ or JACKS) on the same count matrix; rank by each; classify hits as called by 1, 2, or 3 methods.\n\n```python\nimport pandas as pd\nfrom scipy.stats import hypergeom\n\ndef _check_comparable(merged, hit_cols):\n    '''Warn if any pair of method hit-sets shows no statistical enrichment for\n    overlap -- the signature of merging results that answer different questions\n    (e.g. a real essentiality MAGeCK+BAGEL2 pair merged against a drugZ table from\n    an unrelated drug-vs-vehicle screen) rather than genuine method disagreement on\n    the same comparison. Verified on real data: matched MAGeCK\u002FBAGEL2 hit sets give\n    p=0 (highly enriched overlap); a mismatched drugZ table against either gives\n    p=1.0 (no enrichment) -- see the Failure Modes entry below.'''\n    n = len(merged)\n    warnings = []\n    for i, col_a in enumerate(hit_cols):\n        for col_b in hit_cols[i + 1:]:\n            a, b = merged[col_a].fillna(False), merged[col_b].fillna(False)\n            k, K, N = int((a & b).sum()), int(a.sum()), int(b.sum())\n            if K == 0 or N == 0:\n                continue\n            p = hypergeom.sf(k - 1, n, K, N)\n            if p > 0.05:\n                warnings.append(f'{col_a} vs {col_b}: overlap not enriched above chance '\n                                 f'(observed={k}, expected~{K * N \u002F n:.1f}, p={p:.3f}) -- '\n                                 'check these came from the SAME experimental comparison '\n                                 'before trusting consensus.')\n    for w in warnings:\n        print(f'WARNING: {w}')\n    return warnings\n\ndef consensus_hits(mageck_path, bagel_path, drugz_path,\n                   mageck_fdr_thresh=0.05, bagel_bf_thresh=6, drugz_fdr_thresh=0.05):\n    '''Build consensus across MAGeCK \u002F BAGEL2 \u002F drugZ on the same screen.\n    Each hit gets a count of supporting methods. Defaults match the Quantitative\n    Thresholds table below -- keep this function and examples\u002Fconsensus_hits.py in\n    sync with that table, not with each other.'''\n    mageck = pd.read_csv(mageck_path, sep='\\t')[['id', 'neg|fdr']].rename(columns={'id': 'gene', 'neg|fdr': 'mageck_neg_fdr'})\n    bagel = pd.read_csv(bagel_path, sep='\\t')[['GENE', 'BF']].rename(columns={'GENE': 'gene', 'BF': 'bagel_bf'})\n    drugz = pd.read_csv(drugz_path, sep='\\t')[['GENE', 'fdr_synth']].rename(columns={'GENE': 'gene', 'fdr_synth': 'drugz_synth_fdr'})\n    merged = mageck.merge(bagel, on='gene', how='outer').merge(drugz, on='gene', how='outer')\n    merged['mageck_hit'] = merged['mageck_neg_fdr'] \u003C mageck_fdr_thresh\n    merged['bagel_hit'] = merged['bagel_bf'] > bagel_bf_thresh\n    merged['drugz_hit'] = merged['drugz_synth_fdr'] \u003C drugz_fdr_thresh\n    _check_comparable(merged, ['mageck_hit', 'bagel_hit', 'drugz_hit'])\n    merged['consensus_count'] = (merged[['mageck_hit', 'bagel_hit', 'drugz_hit']].astype(int)).sum(axis=1)\n    return merged.sort_values('consensus_count', ascending=False)\n```\n\n**Confidence tiers:**\n\n| Tier | Definition | Validation requirement |\n|------|------------|-------------------------|\n| Tier 1 (high) | Called by 3\u002F3 methods | Arrayed validation; orthogonal modality (CRISPRi if originally Cas9) |\n| Tier 2 (medium) | Called by 2\u002F3 methods | Arrayed validation in matched line |\n| Tier 3 (exploratory) | Called by 1\u002F3 methods | Treat as hypothesis; further screens before publication |\n\n## Reconciliation: When Two Methods Disagree\n\n| Pattern | Likely cause | Action |\n|---------|--------------|--------|\n| MAGeCK significant, BAGEL2 not | BAGEL2 trained on CEGv2\u002FNEGv1; gene is essential but not in reference | Trust MAGeCK; flag for follow-up |\n| BAGEL2 significant, MAGeCK not | BAGEL2 has tumor-suppressor sensitivity MAGeCK lacks | Investigate sgrna_summary for one weak guide |\n| MAGeCK significant, JACKS not | JACKS down-weighted one outlier guide | Trust JACKS if guides agree; outlier may be off-target |\n| Chronos and MAGeCK disagree on cancer line | Chronos accounts for CN; MAGeCK does not | Trust Chronos; apply [[copy-number-correction]] |\n| drugZ significant, MAGeCK not on drug screen | drugZ bidirectional Z is more sensitive | Trust drugZ for chemogenomic; MAGeCK may miss small effects |\n| MAGeCK MLE significant, MAGeCK RRA not in 2-condition | Beta-score effect size is significant but rank-based not | Trust MLE if guides consistent; RRA may be over-conservative |\n| All methods disagree | Either no real biology or all methods are mis-applied | Stop. Re-audit QC; check chemistry \u002F library \u002F design matrix |\n| BAGEL2 BF changes between reruns on identical input -- not a real method disagreement, but easy to mistake for one | BAGEL2's `bf` step defaults to a clock-derived random seed; two unseeded runs on the same real HAP1 TKOv3 data differed by up to 26.7 BF and flipped 33\u002F18,053 genes across BF>6 | Always pass a fixed `-s \u003Cint>` seed to `fc`\u002F`bf`\u002F`pr` and verify two reruns are byte-identical before trusting any single BF table or treating a rerun difference as new biology -- see [[bagel-essentiality]]'s \"Reproducibility: Fixing the Random Seed\" section |\n\n## Second-Best sgRNA Conservative Rule\n\n**Goal:** Reduce false positives from single outlier sgRNAs by requiring the second-most-extreme guide per gene to also be a hit.\n\n**Approach:** For each gene, sort sgRNAs by LFC; require the second-best LFC to exceed a threshold. Rejects genes that depend on one extreme guide.\n\n```python\ndef second_best_lfc(sgrna_lfc_df, genes_series, direction='neg'):\n    '''Return per-gene LFC of the second-best sgRNA in the direction of interest,\n    and flag genes with fewer than 2 sgRNAs. For dropout (direction=\"neg\"),\n    second-most-negative LFC. A gene with only one sgRNA has no second guide to\n    check at all -- return NaN and single_guide=True for it rather than silently\n    falling back to the lone guide's own LFC, which would read as \"passing\" the\n    rule with no corroborating guide involved.'''\n    results = []\n    for gene in genes_series.unique():\n        gene_lfc = sgrna_lfc_df[genes_series == gene].sort_values()\n        n = len(gene_lfc)\n        if n >= 2:\n            second = gene_lfc.iloc[1] if direction == 'neg' else gene_lfc.iloc[-2]\n            single = False\n        else:\n            second = float('nan')\n            single = True\n        results.append({'gene': gene, 'second_best_lfc': second, 'single_guide': single})\n    return pd.DataFrame(results)\n```\n\n**Rule:** A high-confidence hit has second-best LFC also passing the threshold. A guide-of-one hit has only one extreme guide and should be flagged for orthogonal validation. This rule predates JACKS and is implicit in MAGeCK RRA but explicit elsewhere. Genes with `single_guide=True` (fewer than 2 sgRNAs in the library) have no second guide to check by construction -- always send these to orthogonal validation rather than treating a NaN second-best LFC as a pass.\n\n## Multiple-Testing Correction Conventions\n\n| Method | Native correction | Cross-method comparison |\n|--------|---------------------|---------------------------|\n| MAGeCK RRA | BH per direction | `neg|fdr`, `pos|fdr` |\n| MAGeCK MLE | BH per condition | `\u003Ccond>|fdr` |\n| BAGEL2 | Bootstrap BF; reports BF threshold | BF > 6 ≈ 90% posterior (Hart 2017); ~5% FDR by convention |\n| drugZ | BH per direction | `fdr_synth`, `fdr_supp` |\n| JACKS | Posterior probability + BH | `fdr_log10` (log10 FDR) |\n| Chronos | DepMap gene-effect probability | `effect_probability` |\n\n**Reconciliation:** BF >6 in BAGEL2 corresponds to ~90% posterior probability (Hart 2017 G3, by overlap with CEGv2) and is commonly used as a stringent cutoff roughly comparable to MAGeCK FDR 0.05. Treat that equivalence as an approximate convention, not an exact calibration. drugZ FDR is per-direction; the `fdr_synth` and `fdr_supp` columns are independent BH corrections.\n\n## Correlating MAGeCK and BAGEL2 Scores (Sign\u002FScale Caution)\n\n`neg|score` (MAGeCK RRA) is p-value-like: smaller = more essential. `BF` (BAGEL2) is a\nlog-likelihood ratio: larger = more essential. The two statistics run in opposite directions on\nthe same biology. Computing Spearman rho directly between the raw columns therefore produces a\nstrongly *negative* number even when the methods agree strongly -- sign-correct one column first\n(use `-neg|score`) before comparing rho to a disagreement threshold.\n\n**Worked example, real HAP1 TKOv3 T0-vs-T18 data (n=18,053 genes with both scores):**\n\n| Comparison | Spearman rho |\n|---|---|\n| `neg|score` vs `BF`, uncorrected | -0.806 |\n| `-neg|score` vs `BF`, sign-corrected | +0.806 |\n\nBoth rows describe the same real agreement between MAGeCK and BAGEL2 on this screen -- only the\nsign flips. Applying a literal \"rho \u003C0.6 means disagreement\" rule to the uncorrected row would\nfalsely flag two methods that in fact concur strongly. Always sign-correct before comparing rho\nto a threshold, and note it in whatever you report (\"rho = 0.81 after sign-correcting `neg|score`\nto make both statistics increase with essentiality\").\n\n## Order of Operations\n\n```\n1. Library design (see library-design)         \u003C- design quality dictates hit calling\n2. Plasmid pool sequencing                     \u003C- baseline; non-negotiable\n3. Run screen at MOI 0.3, 500x coverage\n4. Sequence endpoint\n5. Run mageck count                            \u003C- generates raw + normalized counts\n6. Screen QC (see screen-qc)                   \u003C- gates downstream method choice\n7. Copy-number correction if cancer line       \u003C- CRISPRcleanR or Chronos; see copy-number-correction\n8. Batch correction if multi-batch             \u003C- see batch-correction\n9. Hit calling (this skill)                    \u003C- choose method by design\n10. Consensus across 2-3 methods               \u003C- for high-stakes hits\n11. Orthogonal validation                      \u003C- arrayed; different chemistry\n12. Pathway analysis                           \u003C- see pathway-analysis\u002Fgsea\n```\n\n## Custom z-score Hit Calling (when standard tools don't fit)\n\n**Goal:** Compute gene-level z-scores when neither MAGeCK nor BAGEL2 fits the experimental design.\n\n**Approach:** RPM-normalize, compute per-sgRNA log2 fold-changes, aggregate to gene level, derive z-score from the null distribution of non-targeting controls (cleanest) or all genes (assumes \u003C40% changing), apply BH correction.\n\n```python\nimport pandas as pd\nimport numpy as np\nfrom scipy import stats\nfrom statsmodels.stats.multitest import multipletests\n\ndef custom_zscore_hit_calling(counts_df, ctrl_cols, treat_cols, genes_series, ntc_genes=None):\n    '''Z-score gene-level hit calling. If ntc_genes provided, null derived from NTCs only;\n    otherwise from all genes (assumes \u003C40% changing).'''\n    def rpm(df):\n        return df.div(df.sum(axis=0), axis=1) * 1e6\n    ctrl_rpm = rpm(counts_df[ctrl_cols])\n    treat_rpm = rpm(counts_df[treat_cols])\n    lfc_per_sgrna = np.log2((treat_rpm.mean(axis=1) + 1) \u002F (ctrl_rpm.mean(axis=1) + 1))\n    gene_lfc = pd.DataFrame({'gene': genes_series, 'lfc': lfc_per_sgrna}).groupby('gene')['lfc'].agg(['mean', 'std', 'count'])\n    gene_lfc.columns = ['mean_lfc', 'std_lfc', 'n_sgrnas']\n    if ntc_genes is not None:\n        null = gene_lfc.loc[gene_lfc.index.isin(ntc_genes), 'mean_lfc']\n        null_mean, null_std = null.median(), null.std()\n    else:\n        null_mean = gene_lfc['mean_lfc'].median()\n        null_std = gene_lfc['mean_lfc'].std()\n    gene_lfc['z'] = (gene_lfc['mean_lfc'] - null_mean) \u002F null_std\n    gene_lfc['p'] = 2 * stats.norm.sf(np.abs(gene_lfc['z']))\n    gene_lfc['fdr'] = multipletests(gene_lfc['p'], method='fdr_bh')[1]\n    return gene_lfc.sort_values('z')\n```\n\n## Failure Modes\n\n### MAGeCK and BAGEL2 disagree by 200+ hits at FDR 0.05\n\n**Trigger:** Heavy-selection screen (>40% guides change) or cancer-line CN bias.\n**Mechanism:** MAGeCK median normalization breaks; BAGEL2 is robust due to reference-set anchoring.\n**Symptom:** MAGeCK hit list inflated; BAGEL2 list closer to expected size.\n**Fix:** Run MAGeCK with `--norm-method control`; apply CN correction; trust BAGEL2 for essentiality.\n\n### Chronos and MAGeCK disagree at the top 10 in a cancer line\n\n**Trigger:** Top hits are at amplified loci.\n**Mechanism:** Chronos models CN bias; MAGeCK does not.\n**Symptom:** ERBB2 in HER2+, MYC in MYC-amplified, etc. are top hits in MAGeCK but not Chronos.\n**Fix:** Apply [[copy-number-correction]] before MAGeCK or switch to Chronos.\n\n### drugZ and MAGeCK disagree on small-effect drug-modifier screen\n\n**Trigger:** Effect size is small; MAGeCK rank-based test is less sensitive than drugZ bidirectional Z.\n**Mechanism:** drugZ specifically optimized for small effects in drug screens (Colic et al. 2019); MAGeCK RRA loses sensitivity at small effects.\n**Symptom:** At matched FDR, drugZ calls small-effect chemogenomic interactions (e.g. DDR genes) that MAGeCK RRA misses, with stronger expected-pathway enrichment.\n**Fix:** Use drugZ as primary for chemogenomic; MAGeCK as confirmatory. See [[drugz-chemogenomic]].\n\n### JACKS down-weights efficiency, MAGeCK doesn't, disagreement\n\n**Trigger:** A gene has one or two strong sgRNAs and 2-3 weak ones; MAGeCK averages them, JACKS down-weights the weak.\n**Mechanism:** JACKS variational Bayes correctly identifies low-efficacy guides; MAGeCK aggregates without this prior.\n**Symptom:** Gene is JACKS hit but not MAGeCK.\n**Fix:** Inspect per-sgRNA LFC; if strong guides are consistent, JACKS is correct. Validate gene orthogonally.\n\n### Consensus across 3 methods is empty (no hits)\n\n**Trigger:** Either no real biology, each method hits a different failure mode, or -- easy to\noverlook -- the merged files are not from the same experimental comparison.\n**Mechanism:** Screen quality is low and signal-to-noise across all methods is poor; OR each\ninput file is individually valid but answers a different question (e.g. a real essentiality\nMAGeCK+BAGEL2 pair merged against a drugZ table from an unrelated drug-vs-vehicle screen run on\nthe same library). `consensus_hits()` merges without error either way -- verified on real data:\nmerging matched MAGeCK\u002FBAGEL2 essentiality output with a real but unrelated drugZ drug-screen\ntable produced a 0-gene Tier-1 consensus even though the underlying essentiality screen has\n100% precision against CEGv2\u002FNEGv1 (see Input 1's numbers).\n**Symptom:** Tier 1 consensus list is empty.\n**Fix:** Check each input file's own QC first (screen-qc PR-AUC, precision\u002Frecall against\nCEGv2\u002FNEGv1) -- a high-precision screen with an empty 3-method consensus points to a mismatched\nfile, not a bad screen. `consensus_hits()`'s `_check_comparable()` warning (above) also fires\nwhen a pair's hit-set overlap is no better than chance, the statistical signature of a\nmismatched comparison. Only re-audit QC once a same-comparison mismatch has been ruled out.\n\n## Quantitative Thresholds\n\n| Threshold | Value | Source \u002F Rationale |\n|-----------|-------|--------------------|\n| MAGeCK RRA FDR (gene-level) | \u003C0.05 | Li 2014; standard publication |\n| MAGeCK RRA LFC | abs(LFC) >1 | 2-fold; biological |\n| BAGEL2 Bayes Factor | >6 standard; >12 stricter | Hart 2017; BAGEL convention |\n| drugZ FDR | \u003C0.05 per direction | Colic et al. 2019 |\n| JACKS fdr_log10 | \u003C-1 (FDR \u003C0.1); \u003C-2 (FDR \u003C0.01) | Standard FDR convention |\n| Chronos dependency probability | >0.5 | DepMap convention (dependency-probability cutoff) |\n| Tier 1 consensus (3 methods) | 100% agreement | High confidence; minimal validation needed |\n| Tier 2 consensus (2 of 3) | 67% agreement | Arrayed validation required |\n| Tier 3 (1 method only) | Hypothesis; flag for follow-up | Multiple screens or arrayed required |\n| Second-best sgRNA rule | Second-best LFC also passes threshold | Reduces single-guide outliers |\n\nThis table is the canonical source for MAGeCK-FDR\u002FBAGEL-BF defaults: `consensus_hits()` in this\nfile and `examples\u002Fconsensus_hits.py` must both use FDR\u003C0.05\u002FBF>6 to match it. On real HAP1\nTKOv3 data, FDR\u003C0.05\u002FBF>6 gives 844 Tier-1 consensus genes; the looser FDR\u003C0.1\u002FBF>5 pairing gives\n1131 (+34%) -- pick one number, not whichever default a given script happens to hardcode.\n\n## Common Errors\n\n| Error \u002F symptom | Cause | Solution |\n|-----------------|-------|----------|\n| All genes significant in MAGeCK RRA | Heavy selection breaks median norm | `--norm-method control`; or use BAGEL2 |\n| BAGEL2 returns no hits despite known essentials | Wrong reference gene set | Verify CEGv2\u002FNEGv1 files match library |\n| drugZ output empty | Used Day 0 as control instead of vehicle | Re-run with vehicle as control |\n| Chronos errors out | Missing CN profile for cell line | Use CRISPRcleanR (unsupervised) instead |\n| Methods disagree by orders of magnitude | Quality issue or design mismatch | Re-audit QC; reconcile via tier consensus |\n| Empty tier 1 consensus | No real biology, QC failure, OR merged files are not from the same experimental comparison | Check per-method QC (screen-qc) and `_check_comparable()`'s overlap-enrichment warning first; verify all inputs are the same comparison; only then re-audit QC |\n| Single-guide-driven hits, or genes with only 1 sgRNA in the library | Outlier sgRNA, or library design has no second guide to check | Apply second-best rule; treat `single_guide=True` the same as a failed check; orthogonal validate |\n| BAGEL2 BF differs between two runs on the same input | `bf` step unseeded by default (clock-derived) | Always pass `-s \u003Cfixed-int>`; see [[bagel-essentiality]] Reproducibility section |\n\n## References\n\n- Li W et al. 2014. *Genome Biol* 15:554. MAGeCK alpha-RRA.\n- Li W et al. 2015. *Genome Biol* 16:281. MAGeCK MLE.\n- Kim E & Hart T. 2021. *Genome Med* 13:2. BAGEL2.\n- Colic M et al. 2019. *Genome Med* 11:52. drugZ.\n- Allen F et al. 2019. *Genome Res* 29:464. JACKS.\n- Dempster J et al. 2021. *Genome Biol* 22:343. Chronos.\n- Meyers R et al. 2017. *Nat Genet* 49:1779. CERES.\n- Hart T & Moffat J. 2016. *BMC Bioinformatics* 17:164. BAGEL Bayes factor framework.\n- Hart T et al. 2017. *G3* 7:2719. CEGv2\u002FNEGv1 calibration.\n\n## Related Skills\n\n- crispr-screens\u002Fmageck-analysis - Full MAGeCK RRA + MLE detail\n- crispr-screens\u002Fbagel-essentiality - Full BAGEL2 detail\n- crispr-screens\u002Fdrugz-chemogenomic - Full drugZ detail for drug screens\n- crispr-screens\u002Fjacks-analysis - Full JACKS detail and library calibration\n- crispr-screens\u002Fcopy-number-correction - Chronos, CERES, CRISPRcleanR\n- crispr-screens\u002Fscreen-qc - Quality gates that drive method choice\n- crispr-screens\u002Flibrary-design - Library type dictates analysis method\n- crispr-screens\u002Fcombinatorial-screens - GI scoring (synthetic lethality)\n- crispr-screens\u002Fperturb-seq-analysis - SCEPTRE for single-cell screens\n- crispr-screens\u002Fbatch-correction - Multi-batch normalization upstream of hit calling\n- pathway-analysis\u002Fgsea - Downstream pathway enrichment\n- pathway-analysis\u002Fgo-enrichment - GO enrichment of hit lists\n","## Version Compatibility\n\nReference examples tested with: MAGeCK 0.5.9+, BAGEL2 2.0, drugZ Aug 2019+, JACKS 0.2.0+, Chronos 2.0+ (DepMap), CERES 1.0+, pandas 2.2+, numpy 1.26+, scipy 1.12+, statsmodels 0.14+.\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- CLI: `mageck --version`, `BAGEL.py version`, `python drugz.py --help`\n- Python: `pip show crispr_chronos` (JACKS installs from GitHub, not PyPI)\n\nIf code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.\n\n## Hit Calling Decision Tree\n\n**\"Identify significant hits in my CRISPR screen\"** -> Choose the analysis method that matches the experimental design, statistical assumptions, and quality grade of the screen. Reconcile across methods when high-stakes hits must be validated.\n\nThe primary hit-calling methods cover non-overlapping niches; the decision is not \"which is best\" but \"which matches the design.\"\n\n| Design \u002F question | Primary method | Why | Secondary check |\n|--------------------|----------------|-----|------------------|\n| Two-condition essentiality, one cell line, no CN concerns | MAGeCK RRA | Robust, fast, gold-standard for ranked analysis | BAGEL2 (Bayes factor on same data) |\n| Time course (3+ timepoints) | MAGeCK MLE | RRA cannot model multi-condition | JACKS (efficacy-aware) |\n| Multi-cell-line panel (cancer dependency) | Chronos | Models CN bias + screen quality jointly | MAGeCK MLE per line + meta-analysis |\n| Drug screen (vehicle vs drug) | drugZ | Bidirectional Z; vehicle-anchored | MAGeCK MLE with dose covariate |\n| Multi-screen joint, same library | JACKS | Shared efficacy; enables ~2.5x smaller screens | MAGeCK MLE; results should converge |\n| Essentiality classification with reference sets | BAGEL2 | Bayes factor with CEGv2\u002FNEGv1 calibration | MAGeCK RRA |\n| Combinatorial \u002F paired guide | MAGeCK MLE with GI scoring | Models interaction term; see [[combinatorial-screens]] | Custom GI scoring |\n| Single-cell perturbation (Perturb-seq) | SCEPTRE | NB GLM + permutation; see [[perturb-seq-analysis]] | Mixscape pre-filter |\n| Cancer-line copy-number screen | Chronos (preferred) or CERES | Joint CN-bias + gene-effect modeling; see [[copy-number-correction]] | CRISPRcleanR pre-hoc + MAGeCK |\n\n## Statistical Models Compared\n\n| Method | Year | Statistical model | Tests | Best for | Fails when |\n|--------|------|-------------------|-------|----------|------------|\n| MAGeCK RRA | 2014 | NB per-sgRNA -> alpha-RRA per gene | Two-sided | General two-condition | >40% guides change (median norm breaks); time course; cancer-line CN |\n| MAGeCK MLE | 2015 | NB GLM with design matrix; per-gene beta | Wald per condition | Multi-condition \u002F time course | Cell-line specific essentiality; CN bias |\n| BAGEL2 | 2021 | Bayes factor from log-likelihood ratio | Essential vs non-essential | Essentiality classification | Non-essentiality screens; drug screens |\n| drugZ | 2019 | Bidirectional Z-score on guide-level LFC | Sensitizer vs suppressor | Drug-modifier \u002F chemogenomic | Essentiality (no biological prior); time-course |\n| JACKS | 2019 | Variational Bayes: LFC = gene * efficacy | Per-gene posterior | Multi-screen joint, library calibration | Single screen; cross-chemistry |\n| Chronos | 2021 | Cell-population dynamics ODE + NB | Gene effect adjusted for screen quality | Cancer-line panels, longitudinal | Single screen; non-cancer applications |\n| CERES | 2017 | Nonlinear model decoupling CN-bias from gene effect | Per-gene effect | Cancer-line panel with CN profile | Superseded by Chronos at DepMap |\n\n## RRA vs MLE Within MAGeCK\n\n| Property | RRA (`mageck test`) | MLE (`mageck mle`) |\n|----------|----------------------|---------------------|\n| Conditions supported | 2 | Multiple (design matrix) |\n| Statistical test | Robust rank aggregation | Wald on beta from NB GLM |\n| Output | neg\u002Fpos score, FDR per direction | beta per condition |\n| sgRNA efficiency | Not modeled (optional fixed input) | Modeled via `--sgrna-efficiency` |\n| Outlier robustness | High (rank-based) | Lower (likelihood-based) |\n| Best for | Standard 2-condition screen | Time course, drug screen, multi-cell-line, paired |\n| Speed | Fast | Slow (per-gene optimization) |\n\n## Algorithmic Taxonomy: Why Each Was Built\n\n| Method | Designed to solve |\n|--------|--------------------|\n| MAGeCK RRA | First robust statistical framework for CRISPR-screen ranking; alpha-RRA borrowed from RRA in microarray meta-analysis |\n| MAGeCK MLE | Extend MAGeCK to multi-condition; explicit beta scores allow direct LFC interpretation |\n| BAGEL2 | Reference-set-anchored Bayesian classification; precision-recall calibrated; tumor-suppressor sensitivity (BAGEL1 was uni-directional) |\n| drugZ | Drug-modifier screens have low effect sizes and need bidirectional sensitivity; STARS\u002FMAGeCK miss synthetic-lethal hits |\n| JACKS | Sample-size reduction via library-shared efficacy; library calibration as side product |\n| Chronos | DepMap-scale (1000+ cell lines, billions of cell-divisions) needs population-dynamics model; CN bias + screen quality first-class |\n| CERES | First to formally decouple CN from gene effect at DepMap scale; superseded but historically important |\n\n## Run All Five on the Same Data (Consensus Strategy)\n\n**Goal:** For high-stakes hits (drug-target nomination, paper-level claims), require agreement across 2-3 orthogonal methods.\n\n**Approach:** Run MAGeCK + BAGEL2 + (drugZ or JACKS) on the same count matrix; rank by each; classify hits as called by 1, 2, or 3 methods.\n\n```python\nimport pandas as pd\nfrom scipy.stats import hypergeom\n\ndef _check_comparable(merged, hit_cols):\n    '''Warn if any pair of method hit-sets shows no statistical enrichment for\n    overlap -- the signature of merging results that answer different questions\n    (e.g. a real essentiality MAGeCK+BAGEL2 pair merged against a drugZ table from\n    an unrelated drug-vs-vehicle screen) rather than genuine method disagreement on\n    the same comparison. Verified on real data: matched MAGeCK\u002FBAGEL2 hit sets give\n    p=0 (highly enriched overlap); a mismatched drugZ table against either gives\n    p=1.0 (no enrichment) -- see the Failure Modes entry below.'''\n    n = len(merged)\n    warnings = []\n    for i, col_a in enumerate(hit_cols):\n        for col_b in hit_cols[i + 1:]:\n            a, b = merged[col_a].fillna(False), merged[col_b].fillna(False)\n            k, K, N = int((a & b).sum()), int(a.sum()), int(b.sum())\n            if K == 0 or N == 0:\n                continue\n            p = hypergeom.sf(k - 1, n, K, N)\n            if p > 0.05:\n                warnings.append(f'{col_a} vs {col_b}: overlap not enriched above chance '\n                                 f'(observed={k}, expected~{K * N \u002F n:.1f}, p={p:.3f}) -- '\n                                 'check these came from the SAME experimental comparison '\n                                 'before trusting consensus.')\n    for w in warnings:\n        print(f'WARNING: {w}')\n    return warnings\n\ndef consensus_hits(mageck_path, bagel_path, drugz_path,\n                   mageck_fdr_thresh=0.05, bagel_bf_thresh=6, drugz_fdr_thresh=0.05):\n    '''Build consensus across MAGeCK \u002F BAGEL2 \u002F drugZ on the same screen.\n    Each hit gets a count of supporting methods. Defaults match the Quantitative\n    Thresholds table below -- keep this function and examples\u002Fconsensus_hits.py in\n    sync with that table, not with each other.'''\n    mageck = pd.read_csv(mageck_path, sep='\\t')[['id', 'neg|fdr']].rename(columns={'id': 'gene', 'neg|fdr': 'mageck_neg_fdr'})\n    bagel = pd.read_csv(bagel_path, sep='\\t')[['GENE', 'BF']].rename(columns={'GENE': 'gene', 'BF': 'bagel_bf'})\n    drugz = pd.read_csv(drugz_path, sep='\\t')[['GENE', 'fdr_synth']].rename(columns={'GENE': 'gene', 'fdr_synth': 'drugz_synth_fdr'})\n    merged = mageck.merge(bagel, on='gene', how='outer').merge(drugz, on='gene', how='outer')\n    merged['mageck_hit'] = merged['mageck_neg_fdr'] \u003C mageck_fdr_thresh\n    merged['bagel_hit'] = merged['bagel_bf'] > bagel_bf_thresh\n    merged['drugz_hit'] = merged['drugz_synth_fdr'] \u003C drugz_fdr_thresh\n    _check_comparable(merged, ['mageck_hit', 'bagel_hit', 'drugz_hit'])\n    merged['consensus_count'] = (merged[['mageck_hit', 'bagel_hit', 'drugz_hit']].astype(int)).sum(axis=1)\n    return merged.sort_values('consensus_count', ascending=False)\n```\n\n**Confidence tiers:**\n\n| Tier | Definition | Validation requirement |\n|------|------------|-------------------------|\n| Tier 1 (high) | Called by 3\u002F3 methods | Arrayed validation; orthogonal modality (CRISPRi if originally Cas9) |\n| Tier 2 (medium) | Called by 2\u002F3 methods | Arrayed validation in matched line |\n| Tier 3 (exploratory) | Called by 1\u002F3 methods | Treat as hypothesis; further screens before publication |\n\n## Reconciliation: When Two Methods Disagree\n\n| Pattern | Likely cause | Action |\n|---------|--------------|--------|\n| MAGeCK significant, BAGEL2 not | BAGEL2 trained on CEGv2\u002FNEGv1; gene is essential but not in reference | Trust MAGeCK; flag for follow-up |\n| BAGEL2 significant, MAGeCK not | BAGEL2 has tumor-suppressor sensitivity MAGeCK lacks | Investigate sgrna_summary for one weak guide |\n| MAGeCK significant, JACKS not | JACKS down-weighted one outlier guide | Trust JACKS if guides agree; outlier may be off-target |\n| Chronos and MAGeCK disagree on cancer line | Chronos accounts for CN; MAGeCK does not | Trust Chronos; apply [[copy-number-correction]] |\n| drugZ significant, MAGeCK not on drug screen | drugZ bidirectional Z is more sensitive | Trust drugZ for chemogenomic; MAGeCK may miss small effects |\n| MAGeCK MLE significant, MAGeCK RRA not in 2-condition | Beta-score effect size is significant but rank-based not | Trust MLE if guides consistent; RRA may be over-conservative |\n| All methods disagree | Either no real biology or all methods are mis-applied | Stop. Re-audit QC; check chemistry \u002F library \u002F design matrix |\n| BAGEL2 BF changes between reruns on identical input -- not a real method disagreement, but easy to mistake for one | BAGEL2's `bf` step defaults to a clock-derived random seed; two unseeded runs on the same real HAP1 TKOv3 data differed by up to 26.7 BF and flipped 33\u002F18,053 genes across BF>6 | Always pass a fixed `-s \u003Cint>` seed to `fc`\u002F`bf`\u002F`pr` and verify two reruns are byte-identical before trusting any single BF table or treating a rerun difference as new biology -- see [[bagel-essentiality]]'s \"Reproducibility: Fixing the Random Seed\" section |\n\n## Second-Best sgRNA Conservative Rule\n\n**Goal:** Reduce false positives from single outlier sgRNAs by requiring the second-most-extreme guide per gene to also be a hit.\n\n**Approach:** For each gene, sort sgRNAs by LFC; require the second-best LFC to exceed a threshold. Rejects genes that depend on one extreme guide.\n\n```python\ndef second_best_lfc(sgrna_lfc_df, genes_series, direction='neg'):\n    '''Return per-gene LFC of the second-best sgRNA in the direction of interest,\n    and flag genes with fewer than 2 sgRNAs. For dropout (direction=\"neg\"),\n    second-most-negative LFC. A gene with only one sgRNA has no second guide to\n    check at all -- return NaN and single_guide=True for it rather than silently\n    falling back to the lone guide's own LFC, which would read as \"passing\" the\n    rule with no corroborating guide involved.'''\n    results = []\n    for gene in genes_series.unique():\n        gene_lfc = sgrna_lfc_df[genes_series == gene].sort_values()\n        n = len(gene_lfc)\n        if n >= 2:\n            second = gene_lfc.iloc[1] if direction == 'neg' else gene_lfc.iloc[-2]\n            single = False\n        else:\n            second = float('nan')\n            single = True\n        results.append({'gene': gene, 'second_best_lfc': second, 'single_guide': single})\n    return pd.DataFrame(results)\n```\n\n**Rule:** A high-confidence hit has second-best LFC also passing the threshold. A guide-of-one hit has only one extreme guide and should be flagged for orthogonal validation. This rule predates JACKS and is implicit in MAGeCK RRA but explicit elsewhere. Genes with `single_guide=True` (fewer than 2 sgRNAs in the library) have no second guide to check by construction -- always send these to orthogonal validation rather than treating a NaN second-best LFC as a pass.\n\n## Multiple-Testing Correction Conventions\n\n| Method | Native correction | Cross-method comparison |\n|--------|---------------------|---------------------------|\n| MAGeCK RRA | BH per direction | `neg|fdr`, `pos|fdr` |\n| MAGeCK MLE | BH per condition | `\u003Ccond>|fdr` |\n| BAGEL2 | Bootstrap BF; reports BF threshold | BF > 6 ≈ 90% posterior (Hart 2017); ~5% FDR by convention |\n| drugZ | BH per direction | `fdr_synth`, `fdr_supp` |\n| JACKS | Posterior probability + BH | `fdr_log10` (log10 FDR) |\n| Chronos | DepMap gene-effect probability | `effect_probability` |\n\n**Reconciliation:** BF >6 in BAGEL2 corresponds to ~90% posterior probability (Hart 2017 G3, by overlap with CEGv2) and is commonly used as a stringent cutoff roughly comparable to MAGeCK FDR 0.05. Treat that equivalence as an approximate convention, not an exact calibration. drugZ FDR is per-direction; the `fdr_synth` and `fdr_supp` columns are independent BH corrections.\n\n## Correlating MAGeCK and BAGEL2 Scores (Sign\u002FScale Caution)\n\n`neg|score` (MAGeCK RRA) is p-value-like: smaller = more essential. `BF` (BAGEL2) is a\nlog-likelihood ratio: larger = more essential. The two statistics run in opposite directions on\nthe same biology. Computing Spearman rho directly between the raw columns therefore produces a\nstrongly *negative* number even when the methods agree strongly -- sign-correct one column first\n(use `-neg|score`) before comparing rho to a disagreement threshold.\n\n**Worked example, real HAP1 TKOv3 T0-vs-T18 data (n=18,053 genes with both scores):**\n\n| Comparison | Spearman rho |\n|---|---|\n| `neg|score` vs `BF`, uncorrected | -0.806 |\n| `-neg|score` vs `BF`, sign-corrected | +0.806 |\n\nBoth rows describe the same real agreement between MAGeCK and BAGEL2 on this screen -- only the\nsign flips. Applying a literal \"rho \u003C0.6 means disagreement\" rule to the uncorrected row would\nfalsely flag two methods that in fact concur strongly. Always sign-correct before comparing rho\nto a threshold, and note it in whatever you report (\"rho = 0.81 after sign-correcting `neg|score`\nto make both statistics increase with essentiality\").\n\n## Order of Operations\n\n```\n1. Library design (see library-design)         \u003C- design quality dictates hit calling\n2. Plasmid pool sequencing                     \u003C- baseline; non-negotiable\n3. Run screen at MOI 0.3, 500x coverage\n4. Sequence endpoint\n5. Run mageck count                            \u003C- generates raw + normalized counts\n6. Screen QC (see screen-qc)                   \u003C- gates downstream method choice\n7. Copy-number correction if cancer line       \u003C- CRISPRcleanR or Chronos; see copy-number-correction\n8. Batch correction if multi-batch             \u003C- see batch-correction\n9. Hit calling (this skill)                    \u003C- choose method by design\n10. Consensus across 2-3 methods               \u003C- for high-stakes hits\n11. Orthogonal validation                      \u003C- arrayed; different chemistry\n12. Pathway analysis                           \u003C- see pathway-analysis\u002Fgsea\n```\n\n## Custom z-score Hit Calling (when standard tools don't fit)\n\n**Goal:** Compute gene-level z-scores when neither MAGeCK nor BAGEL2 fits the experimental design.\n\n**Approach:** RPM-normalize, compute per-sgRNA log2 fold-changes, aggregate to gene level, derive z-score from the null distribution of non-targeting controls (cleanest) or all genes (assumes \u003C40% changing), apply BH correction.\n\n```python\nimport pandas as pd\nimport numpy as np\nfrom scipy import stats\nfrom statsmodels.stats.multitest import multipletests\n\ndef custom_zscore_hit_calling(counts_df, ctrl_cols, treat_cols, genes_series, ntc_genes=None):\n    '''Z-score gene-level hit calling. If ntc_genes provided, null derived from NTCs only;\n    otherwise from all genes (assumes \u003C40% changing).'''\n    def rpm(df):\n        return df.div(df.sum(axis=0), axis=1) * 1e6\n    ctrl_rpm = rpm(counts_df[ctrl_cols])\n    treat_rpm = rpm(counts_df[treat_cols])\n    lfc_per_sgrna = np.log2((treat_rpm.mean(axis=1) + 1) \u002F (ctrl_rpm.mean(axis=1) + 1))\n    gene_lfc = pd.DataFrame({'gene': genes_series, 'lfc': lfc_per_sgrna}).groupby('gene')['lfc'].agg(['mean', 'std', 'count'])\n    gene_lfc.columns = ['mean_lfc', 'std_lfc', 'n_sgrnas']\n    if ntc_genes is not None:\n        null = gene_lfc.loc[gene_lfc.index.isin(ntc_genes), 'mean_lfc']\n        null_mean, null_std = null.median(), null.std()\n    else:\n        null_mean = gene_lfc['mean_lfc'].median()\n        null_std = gene_lfc['mean_lfc'].std()\n    gene_lfc['z'] = (gene_lfc['mean_lfc'] - null_mean) \u002F null_std\n    gene_lfc['p'] = 2 * stats.norm.sf(np.abs(gene_lfc['z']))\n    gene_lfc['fdr'] = multipletests(gene_lfc['p'], method='fdr_bh')[1]\n    return gene_lfc.sort_values('z')\n```\n\n## Failure Modes\n\n### MAGeCK and BAGEL2 disagree by 200+ hits at FDR 0.05\n\n**Trigger:** Heavy-selection screen (>40% guides change) or cancer-line CN bias.\n**Mechanism:** MAGeCK median normalization breaks; BAGEL2 is robust due to reference-set anchoring.\n**Symptom:** MAGeCK hit list inflated; BAGEL2 list closer to expected size.\n**Fix:** Run MAGeCK with `--norm-method control`; apply CN correction; trust BAGEL2 for essentiality.\n\n### Chronos and MAGeCK disagree at the top 10 in a cancer line\n\n**Trigger:** Top hits are at amplified loci.\n**Mechanism:** Chronos models CN bias; MAGeCK does not.\n**Symptom:** ERBB2 in HER2+, MYC in MYC-amplified, etc. are top hits in MAGeCK but not Chronos.\n**Fix:** Apply [[copy-number-correction]] before MAGeCK or switch to Chronos.\n\n### drugZ and MAGeCK disagree on small-effect drug-modifier screen\n\n**Trigger:** Effect size is small; MAGeCK rank-based test is less sensitive than drugZ bidirectional Z.\n**Mechanism:** drugZ specifically optimized for small effects in drug screens (Colic et al. 2019); MAGeCK RRA loses sensitivity at small effects.\n**Symptom:** At matched FDR, drugZ calls small-effect chemogenomic interactions (e.g. DDR genes) that MAGeCK RRA misses, with stronger expected-pathway enrichment.\n**Fix:** Use drugZ as primary for chemogenomic; MAGeCK as confirmatory. See [[drugz-chemogenomic]].\n\n### JACKS down-weights efficiency, MAGeCK doesn't, disagreement\n\n**Trigger:** A gene has one or two strong sgRNAs and 2-3 weak ones; MAGeCK averages them, JACKS down-weights the weak.\n**Mechanism:** JACKS variational Bayes correctly identifies low-efficacy guides; MAGeCK aggregates without this prior.\n**Symptom:** Gene is JACKS hit but not MAGeCK.\n**Fix:** Inspect per-sgRNA LFC; if strong guides are consistent, JACKS is correct. Validate gene orthogonally.\n\n### Consensus across 3 methods is empty (no hits)\n\n**Trigger:** Either no real biology, each method hits a different failure mode, or -- easy to\noverlook -- the merged files are not from the same experimental comparison.\n**Mechanism:** Screen quality is low and signal-to-noise across all methods is poor; OR each\ninput file is individually valid but answers a different question (e.g. a real essentiality\nMAGeCK+BAGEL2 pair merged against a drugZ table from an unrelated drug-vs-vehicle screen run on\nthe same library). `consensus_hits()` merges without error either way -- verified on real data:\nmerging matched MAGeCK\u002FBAGEL2 essentiality output with a real but unrelated drugZ drug-screen\ntable produced a 0-gene Tier-1 consensus even though the underlying essentiality screen has\n100% precision against CEGv2\u002FNEGv1 (see Input 1's numbers).\n**Symptom:** Tier 1 consensus list is empty.\n**Fix:** Check each input file's own QC first (screen-qc PR-AUC, precision\u002Frecall against\nCEGv2\u002FNEGv1) -- a high-precision screen with an empty 3-method consensus points to a mismatched\nfile, not a bad screen. `consensus_hits()`'s `_check_comparable()` warning (above) also fires\nwhen a pair's hit-set overlap is no better than chance, the statistical signature of a\nmismatched comparison. Only re-audit QC once a same-comparison mismatch has been ruled out.\n\n## Quantitative Thresholds\n\n| Threshold | Value | Source \u002F Rationale |\n|-----------|-------|--------------------|\n| MAGeCK RRA FDR (gene-level) | \u003C0.05 | Li 2014; standard publication |\n| MAGeCK RRA LFC | abs(LFC) >1 | 2-fold; biological |\n| BAGEL2 Bayes Factor | >6 standard; >12 stricter | Hart 2017; BAGEL convention |\n| drugZ FDR | \u003C0.05 per direction | Colic et al. 2019 |\n| JACKS fdr_log10 | \u003C-1 (FDR \u003C0.1); \u003C-2 (FDR \u003C0.01) | Standard FDR convention |\n| Chronos dependency probability | >0.5 | DepMap convention (dependency-probability cutoff) |\n| Tier 1 consensus (3 methods) | 100% agreement | High confidence; minimal validation needed |\n| Tier 2 consensus (2 of 3) | 67% agreement | Arrayed validation required |\n| Tier 3 (1 method only) | Hypothesis; flag for follow-up | Multiple screens or arrayed required |\n| Second-best sgRNA rule | Second-best LFC also passes threshold | Reduces single-guide outliers |\n\nThis table is the canonical source for MAGeCK-FDR\u002FBAGEL-BF defaults: `consensus_hits()` in this\nfile and `examples\u002Fconsensus_hits.py` must both use FDR\u003C0.05\u002FBF>6 to match it. On real HAP1\nTKOv3 data, FDR\u003C0.05\u002FBF>6 gives 844 Tier-1 consensus genes; the looser FDR\u003C0.1\u002FBF>5 pairing gives\n1131 (+34%) -- pick one number, not whichever default a given script happens to hardcode.\n\n## Common Errors\n\n| Error \u002F symptom | Cause | Solution |\n|-----------------|-------|----------|\n| All genes significant in MAGeCK RRA | Heavy selection breaks median norm | `--norm-method control`; or use BAGEL2 |\n| BAGEL2 returns no hits despite known essentials | Wrong reference gene set | Verify CEGv2\u002FNEGv1 files match library |\n| drugZ output empty | Used Day 0 as control instead of vehicle | Re-run with vehicle as control |\n| Chronos errors out | Missing CN profile for cell line | Use CRISPRcleanR (unsupervised) instead |\n| Methods disagree by orders of magnitude | Quality issue or design mismatch | Re-audit QC; reconcile via tier consensus |\n| Empty tier 1 consensus | No real biology, QC failure, OR merged files are not from the same experimental comparison | Check per-method QC (screen-qc) and `_check_comparable()`'s overlap-enrichment warning first; verify all inputs are the same comparison; only then re-audit QC |\n| Single-guide-driven hits, or genes with only 1 sgRNA in the library | Outlier sgRNA, or library design has no second guide to check | Apply second-best rule; treat `single_guide=True` the same as a failed check; orthogonal validate |\n| BAGEL2 BF differs between two runs on the same input | `bf` step unseeded by default (clock-derived) | Always pass `-s \u003Cfixed-int>`; see [[bagel-essentiality]] Reproducibility section |\n\n## References\n\n- Li W et al. 2014. *Genome Biol* 15:554. MAGeCK alpha-RRA.\n- Li W et al. 2015. *Genome Biol* 16:281. MAGeCK MLE.\n- Kim E & Hart T. 2021. *Genome Med* 13:2. BAGEL2.\n- Colic M et al. 2019. *Genome Med* 11:52. drugZ.\n- Allen F et al. 2019. *Genome Res* 29:464. JACKS.\n- Dempster J et al. 2021. *Genome Biol* 22:343. Chronos.\n- Meyers R et al. 2017. *Nat Genet* 49:1779. CERES.\n- Hart T & Moffat J. 2016. *BMC Bioinformatics* 17:164. BAGEL Bayes factor framework.\n- Hart T et al. 2017. *G3* 7:2719. CEGv2\u002FNEGv1 calibration.\n\n## Related Skills\n\n- crispr-screens\u002Fmageck-analysis - Full MAGeCK RRA + MLE detail\n- crispr-screens\u002Fbagel-essentiality - Full BAGEL2 detail\n- crispr-screens\u002Fdrugz-chemogenomic - Full drugZ detail for drug screens\n- crispr-screens\u002Fjacks-analysis - Full JACKS detail and library calibration\n- crispr-screens\u002Fcopy-number-correction - Chronos, CERES, CRISPRcleanR\n- crispr-screens\u002Fscreen-qc - Quality gates that drive method choice\n- crispr-screens\u002Flibrary-design - Library type dictates analysis method\n- crispr-screens\u002Fcombinatorial-screens - GI scoring (synthetic lethality)\n- crispr-screens\u002Fperturb-seq-analysis - SCEPTRE for single-cell screens\n- crispr-screens\u002Fbatch-correction - Multi-batch normalization upstream of hit calling\n- pathway-analysis\u002Fgsea - Downstream pathway enrichment\n- pathway-analysis\u002Fgo-enrichment - GO enrichment of hit lists\n",{"name":5,"tool_type":24,"description":7,"primary_tool":25},"mixed","MAGeCK","main","e0956dc9606356ab78468936b502e55a365282e2","specialists\u002Fcrispr-screen-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-crispr-screens-hit-calling",0,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists","https:\u002F\u002Fgithub.com\u002Fmrsonord2240","2026-10-12 03:19:04",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add mrsonord2240\u002Fopenscience-specialists --skill bio-crispr-screens-hit-calling",{"tool":39,"command":40},"bunx","bunx skills add mrsonord2240\u002Fopenscience-specialists --skill bio-crispr-screens-hit-calling",{"tool":42,"command":43},"pnpm","pnpm dlx skills add mrsonord2240\u002Fopenscience-specialists --skill bio-crispr-screens-hit-calling","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Fcrispr-screen-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-crispr-screens-hit-calling\u002FSKILL.md",true,[47,53],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"examples\u002Fconsensus_hits.py","SCRIPT","脚本",2380,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Fcrispr-screen-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-crispr-screens-hit-calling\u002Fexamples\u002Fconsensus_hits.py",{"path":54,"resourceType":55,"resourceTypeDesc":56,"sizeBytes":57,"sourceHtmlUrl":58},"usage-guide.md","REFERENCE","参考文档",9104,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Fcrispr-screen-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-crispr-screens-hit-calling\u002Fusage-guide.md",[60,67,74,81,88,95],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M7CW36A6QAGWFE2C008M1XPG","bio-workflows-metabolomics-pipeline","Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC\u002Fdrift\u002Fnormalization, confidence-stratified annotation, permutation-validated statistics, background-aware pathway mapping), naming what each stage decides and where it silently fails. Use when running a full LC-MS metabolomics study from raw mzML to enriched pathways and needing the honest handoffs between stages. Each stage defers to its component skill for parameters and traps; for stable-isotope flux (a separate branch, not this untargeted flow) see metabolomics\u002Fisotope-tracing.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-workflows-metabolomics-pipeline\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M7CW2Y18623NA2S1Y30FRQW1","bio-metabolomics-xcms-preprocessing","Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment\u002FXcmsExperiment API, taking raw mzML to a feature table via CentWave peak detection, retention-time alignment, peak-density correspondence, gap-filling, CAMERA redundancy collapse, and built-in QC feature filtering. Use when converting centroided LC-MS runs into a features-by-samples matrix and deciding centWave\u002Fgrouping\u002Falignment parameters. For drift correction and QC\u002FCV filtering execution see metabolomics\u002Fnormalization-qc; for metabolite identification see metabolomics\u002Fmetabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics\u002Fmsdial-preprocessing; for downstream statistics see metabolomics\u002Fstatistical-analysis.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-xcms-preprocessing\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7CW2M364HVWPNQEKE2WP4PP","bio-metabolomics-statistical-analysis","Decision-grade statistical analysis for metabolomics intensity tables. Covers transformation and scaling (Pareto vs unit-variance as a hidden hypothesis), unsupervised structure (PCA\u002FHCA for QC), permutation-validated PLS-DA\u002FOPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch\u002FMann-Whitney\u002FANOVA\u002FLMM with covariate adjustment), and dependence-aware multiple testing. Use when testing which metabolites differ, building or validating a discriminant model, choosing a scaling, or correcting many correlated tests. For sample-wise normalization\u002Fdrift correction see metabolomics\u002Fnormalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning\u002Fbiomarker-discovery and machine-learning\u002Fmodel-validation; for pathway interpretation see metabolomics\u002Fpathway-mapping; for design\u002Fpower\u002Fmultiplicity regime see experimental-design\u002Fmultiple-testing.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-statistical-analysis\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M7CW2BCBF851WYE03Z8XPEDQ","bio-metabolomics-pathway-mapping","Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA\u002FQEA), mummichog\u002FPSEA on raw m\u002Fz peaks, and network-diffusion enrichment (FELLA), with correct background-set construction and honest interpretive ceilings. Use when interpreting differential metabolites or an untargeted LC-MS feature table in pathway context, choosing ORA vs MSEA vs mummichog vs topology, or setting the reference\u002Fbackground set. For annotation confidence levels feeding ORA see metabolomics\u002Fmetabolite-annotation; for gene-set concepts see pathway-analysis\u002Fgo-enrichment and pathway-analysis\u002Fgsea; for joint gene+metabolite pathways see multi-omics-integration\u002Fmofa-integration.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-pathway-mapping\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M7CW21NSZMCPMF7D9CHJM718","bio-metabolomics-normalization-qc","Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS\u002FGC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak\u002Ffeature table before statistical analysis, choosing a drift-correction or sample-normalization method, deciding QC RSD vs D-ratio filtering, or handling left-censored missing values. The feature table is produced by metabolomics\u002Fxcms-preprocessing or metabolomics\u002Fmsdial-preprocessing; transformation\u002Fscaling for modeling defers to metabolomics\u002Fstatistical-analysis; cross-study design issues link to experimental-design\u002Fbatch-design.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-normalization-qc\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":19},"01M7CW1SWVM0NYHVE6Q7MA3G7R","bio-metabolomics-msdial-preprocessing","Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA\u002FDIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics\u002Fxcms-preprocessing; for lipid annotation mode see metabolomics\u002Flipidomics; for MSI-level confidence honesty see metabolomics\u002Fmetabolite-annotation; for drift correction and QC see metabolomics\u002Fnormalization-qc.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-msdial-preprocessing\u002FSKILL.md",[],[]]