Add construct-aware paired-guide decoding to screening

[Yifan1835]

Summary

• add an opt-in --screening_count_method crisprdecode counting path to the screening workflow while retaining MAGeCK as the default
• validate a headered paired-guide construct library and perform conservative exact assignment from synchronized R1/R2 reads
• report unique, ambiguous, unassigned and extraction-failed reads without arbitrary assignment of duplicate observable signatures
• aggregate a MAGeCK-compatible count matrix and per-sample/library-recovery QC, with assignment metrics included in MultiQC
• add schema validation, usage/output documentation, an immutable Python container reference and a deterministic synthetic truth fixture

Motivation

The existing screening path assumes that one sequenced spacer identifies one sgRNA. Paired-guide libraries encode construct identity using two observed guide elements, so treating each read as a conventional single guide can lose construct identity and conceal ambiguous signatures. This contribution adds a bounded construct-aware count-generation path that rejoins the existing workflow at ch_counts; downstream CRISPRcleanR, MAGeCK, BAGEL2, DrugZ and HitSelection behavior is unchanged.

User impact

Users can select paired-guide counting with:

--screening_count_method crisprdecode

The construct library is a headered TSV with construct_id, target_id, spacer_r1 and spacer_r2. Optional per-read anchor, offset and reverse-complement parameters describe the supported read geometry. The default value remains mageck, and a regression nf-test verifies the existing MAGeCK route.

Validation

Fixed test release: crisprdecode-test-20260910, commit 7d258b5f9624bee74b6e5235f15c92234306cab8.

The dedicated CRISPRDecode collaborator tests run passed all three jobs on that commit:

• Python validation and assignment: 8 unit tests passed, including rejection of duplicated required TSV headers and acceptance of a unique metadata column.
• Nextflow decoding: 2 nf-tests passed (one stub and one real synthetic decode).
• Nextflow screening routing: 2 stub nf-tests passed, covering CRISPRDecode and the default MAGeCK route.

The synthetic fixture contains 5 read pairs: 2 unique, 1 ambiguous, 1 unassigned and 1 extraction failure. Counts are 1 each for construct_a and construct_b, and 0 for the duplicate-signature and zero-count constructs. The tests verify read-pair conservation and do not allocate ambiguous signatures arbitrarily.

The workflow uses GitHub-hosted Ubuntu 24.04, Python 3.12.8 for unit tests, Java 17, Nextflow 25.04.0, nf-test 0.9.3 and Docker. Decoding processes use explicitly qualified, digest-pinned Docker Hub Python 3.11.4 images with ps available for Nextflow metrics. Software-version snapshots compare sorted parsed maps while checking workflow metadata separately.

These results validate the listed synthetic and routing cases. They do not establish full real-data or downstream statistical validation, and the fork CI run does not replace upstream PR checks. Earlier local parsing, lint and pre-commit results apply to the original implementation commit; they are not presented as fresh checks of this release.

Collaborator testing

Testing instructions and feedback template include local commands, expected outputs and environment requirements.

The dedicated workflow triggers on pushes to test/crisprdecode-* branches. A collaborator can enable Actions in their fork and push a new matching branch at the fixed tag to run the tests without repository secrets or custom runners. Updating this PR's feat/crisprdecode-paired-guide branch does not itself trigger that dedicated push workflow. Manual dispatch requires the workflow to exist on the default branch.

Feedback should include the exact commit SHA, run URL, counts/QC discrepancies, failing logs and setup/test/review time. Independent collaborator feedback is pending; this PR remains a draft.

Scope

This MVP supports paired-end paired-guide libraries with exact matching and one downstream target label per construct. UMI/iBAR processing, pooled pegRNA libraries and combinatorial two-target statistical models remain out of scope.

Closes #278