MAGeCK pooled-screen analysis
When to use
Use this skill to count existing sequencing reads against a supplied guide library or compare
already-counted pooled screens. Deliver the count matrix, QC, guide and gene results, contrast
provenance, and a short interpretation of enrichment/depletion. This workflow analyzes screens;
it does not design guides or infer gene function from a hit alone.
Runtime
The tested source installation and external-runtime caveat are in
references/runtime.md. Verify both mageck --version and
mageck test --help before an analysis. The bundled Python helper is standard-library only.
MAGeCK itself also needs NumPy, SciPy, and the RRA binary. PDF/R reporting is optional and not
needed by the helper.
The official release directory still lists
0.5.9.5 as its latest MAGeCK release. Upstream now links the separate
MAGeCK2 project; these commands and the helper target
MAGeCK 0.5.9.5, not an interchangeable MAGeCK2 installation. This is a local CLI workflow with
no service API or authentication.
Workflow
- Establish the library version, perturbation modality, sample names, selection direction,
biological replicates, baseline material, time point, and batch. Separate sequencing lanes
from independent biological replicates. A plasmid baseline and a cell day-zero baseline
answer different questions. Require an explicit treatment/control contrast; the helper
never silently assigns all unused samples to the control group.
- Validate a headerless TSV library containing guide ID, DNA sequence, gene. IDs and
sequences must be unique. The helper requires a count-table header beginning
sgRNA, Gene,
followed by unique nonnumeric sample names such as c1. MAGeCK can interpret numeric names
as column indices or count values; rename them before analysis. Guide/gene IDs must have no
whitespace. The helper rejects ambiguous sequences and any count/library ID or gene mismatch;
resolve intentional multi-target guides explicitly upstream. These are deliberate helper
restrictions; native MAGeCK also accepts other input variants.
- For FASTQ, inspect read structure and known guide sequences to establish trimming and
orientation. Use MAGeCK
count, with one space-separated argument per biological sample;
comma-join lanes only when they are technical replicates of that same sample. Preserve
unmapped-read and count-summary evidence when mapping is poor. A zero-count guide remains
in the library; do not drop it to improve QC.
- Run QC before statistical testing. Review library representation, median reads per guide,
zero fractions, Gini coefficients, and within-condition replicate correlations. The
helper's 10% zero and 0.8 correlation flags are review prompts, not universal acceptance
thresholds. High correlation can coexist with systematic artifacts. Read depth is not
experimental cell coverage. The helper uses a raw-count population Gini; MAGeCK's native
count-summary Gini uses log(count + 1) with a finite-sample correction. Do not compare their
values or thresholds as the same statistic.
- Choose normalization based on the screen. Median normalization assumes most guides are
stable. For a strong global shift, supplied validated negative-control guides may support
--normalization control. These must be guide IDs, one per line; a gene list is not
interchangeable. Biological control samples and negative-control guides serve different
roles. At least two controls must be present, and every guide assigned to a control gene
must be designated a control. Supplying --control-guides also changes the RRA null distribution,
even with median normalization. Record their origin and check their count distribution.
MAGeCK 0.5.9.5 switches median normalization to total-count scaling for a zero median or
more than 45% zero guides in any selected sample; for control normalization it evaluates
the control-guide subset. Check the report's applied method, size factors, and warnings.
- Use
test for a two-group comparison. --paired requires both lists in corresponding
biological order and equal length; matching lengths alone do not establish pairing.
The helper reports genes at the requested FDR in both directions and retains full rankings.
For a multi-factor design, see references/design.md; do not collapse
batches or time courses into an unjustified two-group test.
- Inspect guide concordance for leading genes, essential-gene recovery where appropriate,
negative controls, replicate consistency, and copy-number artifacts in nuclease knockout
screens. Report effect sizes alongside FDR. An enriched guide can indicate resistance,
growth advantage, or a sampling artifact depending on the selection; depletion need not
imply universal essentiality. Lack of replication or low-count guides weakens inference.
Commands
Run paths relative to the installed skill directory. Input and output paths refer to the user's
analysis directory. The helper refuses to reuse an existing results directory.
# Single-end guide reads; trim and orientation must match the user's library preparation.
mageck count -l library.tsv --fastq c1.fastq.gz c2.fastq.gz t1.fastq.gz t2.fastq.gz \
--sample-label c1,c2,t1,t2 --trim-5 0 --norm-method none -n counts
python scripts/screen_analysis.py qc --counts counts.count.txt --library library.tsv \
--control c1 c2 --treatment t1 t2 --output qc.json
python scripts/screen_analysis.py test --counts counts.count.txt --library library.tsv \
--control c1 c2 --treatment t1 t2 --normalization median --fdr 0.05 --output result
The FASTQ command structure was exercised with a synthetic two-guide library: counts of 30 and
12 were recovered exactly. A separate trimmed, reverse-complemented, two-lane fixture recovered
15, 7, and 0 reads. The two-group helper was exercised with 500 guides and two replicates per
condition in unpaired and paired modes; known depleted and enriched genes ranked first in their
respective directions and passed FDR 0.05. Sparse fixtures verified the total-normalization fallback.
These tests establish execution and signal direction, not real-screen statistical calibration.
Real-file paths above are illustrative.
result/report.json records count/library/control-guide SHA-256, control-guide IDs, MAGeCK version,
actual arguments, QC, applied normalization, warnings, hit direction, FDR, log2 fold change and rank.
The helper explicitly selects median guide LFC aggregation and --remove-zero both: all-zero
guides remain in the input/QC but are excluded from ranking. Native MAGeCK also skips NA/na
gene labels by default. The helper's --fdr filters completed gene results; it does not set MAGeCK's
--gene-test-fdr-threshold, which controls the RRA guide-selection cutoff. Negative and positive
FDRs are separate families; their union does not establish joint FDR control across directions or
across multiple contrasts. screen.gene_summary.txt, screen.sgrna_summary.txt, normalized
counts and the execution log retain the complete evidence. Include the original library, sample
sheet and negative-control list in the analysis handoff; the count checksum cannot reconstruct them.
Primary references
1---2name: mageck3description: Analyzes pooled CRISPR screen FASTQ reads and guide-count matrices with MAGeCK, validates guide libraries and contrasts, measures replicate and library QC, and produces gene hit rankings with effect sizes and FDR. Use for new knockout, CRISPRi, or CRISPRa screen analysis, enrichment or depletion contrasts, and MAGeCK count/test workflows; existing public dependency-score lookup belongs to DepMap.4license: MIT5compatibility: Requires Python 3.10+ for the helper and MAGeCK 0.5.9.5 with its compiled RRA executable for analysis. Tested runtime uses Python 3.11, NumPy 1.26.4 and SciPy 1.13.1. Source installation needs a C++ compiler; network is needed only for installation. No credentials.6metadata:7 source: https://skillmd.com/skills/k-dense-ai/mageck8 version: "1.1"9 skill-author: K-Dense Inc.10 upstream-version: "0.5.9.5"11 last-reviewed: "2026-10-01"12---1314# MAGeCK pooled-screen analysis1516## When to use1718Use this skill to count existing sequencing reads against a supplied guide library or compare19already-counted pooled screens. Deliver the count matrix, QC, guide and gene results, contrast20provenance, and a short interpretation of enrichment/depletion. This workflow analyzes screens;21it does not design guides or infer gene function from a hit alone.2223## Runtime2425The tested source installation and external-runtime caveat are in26[references/runtime.md](references/runtime.md). Verify both `mageck --version` and27`mageck test --help` before an analysis. The bundled Python helper is standard-library only.28MAGeCK itself also needs NumPy, SciPy, and the `RRA` binary. PDF/R reporting is optional and not29needed by the helper.3031The [official release directory](https://sourceforge.net/projects/mageck/files/0.5/) still lists320.5.9.5 as its latest MAGeCK release. Upstream now links the separate33[MAGeCK2 project](https://github.com/davidliwei/mageck2); these commands and the helper target34MAGeCK 0.5.9.5, not an interchangeable MAGeCK2 installation. This is a local CLI workflow with35no service API or authentication.3637## Workflow38391. Establish the library version, perturbation modality, sample names, selection direction,40 biological replicates, baseline material, time point, and batch. Separate sequencing lanes41 from independent biological replicates. A plasmid baseline and a cell day-zero baseline42 answer different questions. Require an explicit treatment/control contrast; the helper43 never silently assigns all unused samples to the control group.442. Validate a **headerless TSV library** containing guide ID, DNA sequence, gene. IDs and45 sequences must be unique. The helper requires a count-table header beginning `sgRNA`, `Gene`,46 followed by unique nonnumeric sample names such as `c1`. MAGeCK can interpret numeric names47 as column indices or count values; rename them before analysis. Guide/gene IDs must have no48 whitespace. The helper rejects ambiguous sequences and any count/library ID or gene mismatch;49 resolve intentional multi-target guides explicitly upstream. These are deliberate helper50 restrictions; native MAGeCK also accepts other input variants.513. For FASTQ, inspect read structure and known guide sequences to establish trimming and52 orientation. Use MAGeCK `count`, with one space-separated argument per biological sample;53 comma-join lanes only when they are technical replicates of that same sample. Preserve54 unmapped-read and count-summary evidence when mapping is poor. A zero-count guide remains55 in the library; do not drop it to improve QC.564. Run QC before statistical testing. Review library representation, median reads per guide,57 zero fractions, Gini coefficients, and within-condition replicate correlations. The58 helper's 10% zero and 0.8 correlation flags are review prompts, not universal acceptance59 thresholds. High correlation can coexist with systematic artifacts. Read depth is not60 experimental cell coverage. The helper uses a raw-count population Gini; MAGeCK's native61 count-summary Gini uses log(count + 1) with a finite-sample correction. Do not compare their62 values or thresholds as the same statistic.635. Choose normalization based on the screen. Median normalization assumes most guides are64 stable. For a strong global shift, supplied validated negative-control guides may support65 `--normalization control`. These must be **guide IDs**, one per line; a gene list is not66 interchangeable. Biological control samples and negative-control guides serve different67 roles. At least two controls must be present, and every guide assigned to a control gene68 must be designated a control. Supplying `--control-guides` also changes the RRA null distribution,69 even with median normalization. Record their origin and check their count distribution.70 MAGeCK 0.5.9.5 switches median normalization to total-count scaling for a zero median or71 more than 45% zero guides in any selected sample; for control normalization it evaluates72 the control-guide subset. Check the report's applied method, size factors, and warnings.736. Use `test` for a two-group comparison. `--paired` requires both lists in corresponding74 biological order and equal length; matching lengths alone do not establish pairing.75 The helper reports genes at the requested FDR in both directions and retains full rankings.76 For a multi-factor design, see [references/design.md](references/design.md); do not collapse77 batches or time courses into an unjustified two-group test.787. Inspect guide concordance for leading genes, essential-gene recovery where appropriate,79 negative controls, replicate consistency, and copy-number artifacts in nuclease knockout80 screens. Report effect sizes alongside FDR. An enriched guide can indicate resistance,81 growth advantage, or a sampling artifact depending on the selection; depletion need not82 imply universal essentiality. Lack of replication or low-count guides weakens inference.8384## Commands8586Run paths relative to the installed skill directory. Input and output paths refer to the user's87analysis directory. The helper refuses to reuse an existing results directory.8889```bash90# Single-end guide reads; trim and orientation must match the user's library preparation.91mageck count -l library.tsv --fastq c1.fastq.gz c2.fastq.gz t1.fastq.gz t2.fastq.gz \92 --sample-label c1,c2,t1,t2 --trim-5 0 --norm-method none -n counts9394python scripts/screen_analysis.py qc --counts counts.count.txt --library library.tsv \95 --control c1 c2 --treatment t1 t2 --output qc.json9697python scripts/screen_analysis.py test --counts counts.count.txt --library library.tsv \98 --control c1 c2 --treatment t1 t2 --normalization median --fdr 0.05 --output result99```100101The FASTQ command structure was exercised with a synthetic two-guide library: counts of 30 and10212 were recovered exactly. A separate trimmed, reverse-complemented, two-lane fixture recovered10315, 7, and 0 reads. The two-group helper was exercised with 500 guides and two replicates per104condition in unpaired and paired modes; known depleted and enriched genes ranked first in their105respective directions and passed FDR 0.05. Sparse fixtures verified the total-normalization fallback.106These tests establish execution and signal direction, not real-screen statistical calibration.107Real-file paths above are illustrative.108109`result/report.json` records count/library/control-guide SHA-256, control-guide IDs, MAGeCK version,110actual arguments, QC, applied normalization, warnings, hit direction, FDR, log2 fold change and rank.111The helper explicitly selects median guide LFC aggregation and `--remove-zero both`: all-zero112guides remain in the input/QC but are excluded from ranking. Native MAGeCK also skips `NA`/`na`113gene labels by default. The helper's `--fdr` filters completed gene results; it does not set MAGeCK's114`--gene-test-fdr-threshold`, which controls the RRA guide-selection cutoff. Negative and positive115FDRs are separate families; their union does not establish joint FDR control across directions or116across multiple contrasts. `screen.gene_summary.txt`, `screen.sgrna_summary.txt`, normalized117counts and the execution log retain the complete evidence. Include the original library, sample118sheet and negative-control list in the analysis handoff; the count checksum cannot reconstruct them.119120## Primary references121122- [MAGeCK usage and command semantics](https://sourceforge.net/p/mageck/wiki/usage/)123- [Official installation guidance](https://sourceforge.net/p/mageck/wiki/install/)124- [Input formats](https://sourceforge.net/p/mageck/wiki/input/)125- [Output field meanings](https://sourceforge.net/p/mageck/wiki/output/)