Add construct-aware paired-guide decoding to the screening workflow

Description of feature

Following discussion in the #crisprseq community, I would like to contribute a bounded construct-aware decoding path to the screening workflow.

The current screening path works well when one sequenced spacer identifies one sgRNA. Complex pooled libraries can encode a biological construct using more than one sequenced element. In a paired-guide library, forcing each read through a single-spacer counting model can lose construct identity or hide ambiguous assignments.

The proposed first contribution is intentionally narrow. It adds native decoding for one paired-guide library architecture upstream of the shared count-table channel. The existing CRISPRcleanR, MAGeCK, BAGEL2, DrugZ and HitSelection steps remain unchanged.

paired-end FASTQ
    -> CRISPRDECODE_PAIRED_GUIDE
    -> MAGeCK-compatible count table -> existing ch_counts
    -> assignment and library-recovery QC -> MultiQC inputs

Proposed MVP

Included:

• Paired-guide libraries without UMI/iBAR handling.
• One target label per construct for compatibility with the existing gene-level downstream methods.
• Explicit extraction of the two informative guide elements from paired-end reads.
• Exact, conservative construct assignment.
• Separate counts for uniquely assigned, ambiguous, unassigned and extraction-failed reads.
• A MAGeCK-compatible count table with the canonical first columns followed by one column per sample.
• A small deterministic synthetic test fixture with a known truth set.
• nf-test coverage, parameter/schema validation, output documentation and MultiQC-ready QC files.
• No change to the default standard-sgRNA behaviour.

Not included in the first PR:

• UMI/iBAR counting, IRA, LDA or URA.
• Pooled pegRNA/prime-editing libraries.
• New downstream statistical tests.
• The CasprFlow GUI or the complete CasprFlow workflow.
• Combinatorial constructs that require a two-target statistical model downstream.

Proposed interface

The existing screening samplesheet would be reused:

sample,fastq_1,fastq_2,condition

The paired-guide construct library would use an explicit headered TSV:

construct_id  target_id  spacer_r1  spacer_r2

The exact parameter names are open to maintainer preference. A possible design is:

• --screening_count_method crisprdecode, with the current behaviour remaining the default;
• a dedicated construct-library parameter or a schema-discriminated use of --library;
• explicit anchor/read-orientation parameters for the supported paired-guide architecture.

The output count table would re-enter the existing workflow at ch_counts. Proposed QC outputs are:

• assignment_summary.tsv: total, extracted, uniquely assigned, ambiguous, unassigned and failed reads per sample;
• library_recovery.tsv: assignability class, observed counts and zero-count status per construct;
• MultiQC-ready summary data.

Constructs with identical observable decode signatures would not be assigned arbitrarily. They would be reported as non-uniquely identifiable and their reads would remain in the ambiguous category.

Validation and acceptance criteria

The synthetic fixture will include:

• uniquely assignable constructs with exact expected counts;
• duplicate observable construct signatures;
• ambiguous and unassigned reads;
• reads failing anchor extraction;
• zero-count constructs;
• mismatched paired FASTQ record counts.

The tests should verify:

1. Exact equality to the truth count matrix.
2. unique + ambiguous + unassigned + extraction_failed = total for every sample.
3. Deterministic output order and assignment classes.
4. Actionable failure for malformed libraries and desynchronised paired FASTQs.
5. Compatibility of the generated table with the existing --count_table downstream path.
6. No output change for the existing standard screening test profile.
7. Passing nf-test and nf-core lint checks on the supported minimum and current Nextflow versions.

The CI fixture will be synthetic and distributable. Collaborator data will not be uploaded as public test data without explicit permission and provenance.

Proposed implementation structure

The user-facing feature can be one option while remaining modular internally. The initial implementation would likely be a local subworkflow composed of per-sample processes for:

1. construct-library validation and decode-reference creation;
2. guide-element extraction;
3. construct assignment and per-sample counting;
4. count-matrix and QC aggregation.

Stable generic processes can be considered for nf-core/modules later if the maintainers find them broadly reusable.

Related work

• #243 proposes 2FAST2Q as another alternative count-matrix provider for reads containing multiple features. This proposal is complementary but focuses on library-defined construct identity, conservative ambiguity handling and explicit library-recovery QC.
• #267 adapts the pipeline to strict syntax.
• #276 is the current nf-core template update.

Decisions requested from maintainers

Before implementation is hardened, could the maintainers please confirm:

1. Whether the current dev head or one of #267/#276 should be used as the implementation base.
2. Whether ch_counts is the correct re-entry boundary.
3. The preferred feature/parameter naming and whether the new library should use a separate parameter.
4. Whether a local CRISPRDECODE_PAIRED_GUIDE subworkflow is the preferred first structure.
5. The exact canonical count-table headers expected by all existing downstream branches.
6. Whether MultiQC integration is required in the first code PR or may follow immediately after the core path.
7. The preferred reviewer/maintainer for the screening count-generation code.

I am happy to implement the feature, add the deterministic fixture and tests, and support review and validation after the design is confirmed.

Start by reviewing the screening workflow entry point, the existing standard screening test profile, and the ch_counts handoff. Before implementation, confirm the base branch, parameter and library-interface decisions, and the required count-table headers with maintainers. Done means a deterministic synthetic fixture, nf-test and schema/lint coverage, unchanged standard behavior, and the specified count and QC outputs.