mageck

Files (4)

• SKILL.md
• design.md · references/
• runtime.md · references/
• screen_analysis.py · scripts/

SKILL.md (first lines)

# 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](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](https://sourceforge.net/projects/mageck/files/0.5/) still lists
0.5.9.5 as its latest MAGeCK release. Upstream now links the separate
[MAGeCK2 project](https://github.com/davidliwei/mageck2); 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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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](references/design.md); do not collapse
   batches or time courses into an unjustified two-group test.
7. 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.

```bash
# 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

- [MAGeCK usage and command semantics](https://sourceforge.net/p/mageck/wiki/usage/)
- [Official installation guidance](https://sourceforge.net/p/mageck/wiki/install/)
- [Input formats](https://sourceforge.net/p/mageck/wiki/input/)
- [Output field meanings](https://sourceforge.net/p/mageck/wiki/output/)

From K-Dense-AI/scientific-agent-skills, MIT.

More from K-Dense-AI/scientific-agent-skills