Samplesheet Dependencies & Channel Naming

This document outlines the critical dependencies between the input samplesheet, the Nextflow pipeline logic, and the Python scripts that generate load_data.csv files for CellProfiler. Correctly formatting your samplesheet and naming your files is essential for the pipeline to function correctly.

Samplesheet Requirements¶

The samplesheet is the single source of truth for experimental metadata. The pipeline expects specific columns to be present.

Required Columns¶

Metadata Flow¶

1. Ingestion: The samplesheet is read by main.nf.

2. Channel Creation: Nextflow creates channels carrying [meta, image] tuples. meta contains all the columns above.

3. Metadata JSON construction (Groovy): Each CellProfiler module’s Nextflow subworkflow builds a canonical metadata JSON object (one entry per image/channel, see Python Scripts) and passes it to generate_load_data_csv.py via --metadata-json. generate_load_data_csv.py itself does no filename parsing - every field (well, site, channel, cycle, column_prefix, etc.) is stated explicitly in that JSON.

   • Illumination Calculation/Application: channel comes directly from the samplesheet’s channels column for both arms (via expandImageChannels in Groovy). cycle is carried through for barcoding, but explicitly nulled out for painting (expandImageChannels(..., record_cycle: false)) - phenotyping rounds use distinct channel names instead of Cycle{NN}_-prefixed columns, so real per-round cycle values never reach these CSVs.

   • Segmentation Check, Preprocessing & Combined Analysis: these steps consume images generated by an earlier pipeline stage, so their Groovy code derives channel/cycle by parsing the standardized filenames those earlier stages produced (see regexes below) before building the metadata JSON entry.

Channel Naming Constraints¶

The Nextflow workflow code (not the Python script - see above) uses regular expressions to parse filenames and extract Channel and Cycle information when building the metadata JSON for segcheck, preprocess, and combined analysis. This is where most user errors occur.

Cell Painting Arm¶

Input Images (Raw)

• Requirement: Must contain the channel names specified in your samplesheet channels column, comma-separated in a Channel... token in the filename.

• Example: ..._ChannelDNA,Phalloidin,Mito_... - expandImageChannels (Groovy) pairs these positionally with the samplesheet’s channels list, not by re-parsing this token.

Corrected Images (Intermediate)

• Requirement: The pipeline generates these. If you provide pre-corrected images, they must match the pattern.

• Regex (in workflows/stitch-align-crop.nf, subworkflows/local/cellpainting*/main.nf, workflows/nf-pooled-cellpainting.nf, workflows/no-stitch.nf): .*_Corr(.+?)\.tiff?$

• Example: Plate_P1_Well_A01_Site_1_CorrDNA.tiff

  • Here, DNA is extracted as the channel name.

  • Constraint: This extracted name MUST match one of the entries in your samplesheet channels column (e.g., DNA).

Barcoding Arm¶

Input Images (Raw)

• Requirement: Must contain cycle information if it’s a multi-cycle experiment.

Preprocessing & Alignment

• Constraint: The barcoding arm is stricter. It expects specific channel names for the barcode bases.

• Allowed Channels: A, C, G, T (for bases), DNA, DAPI (for reference).

• Regex (in subworkflows/local/barcoding*/main.nf, workflows/stitch-align-crop.nf): .*_Cycle(\d+)_(.+?)\.tiff?$

• Example: Plate_P1_Well_A01_Site_1_Cycle01_A.tiff

  • Cycle01 -> Cycle 1

  • A -> Channel A

Combined Analysis Dependencies¶

The Combined Analysis step merges data from both arms. This is the most fragile step regarding naming.

The “Plate Name” Trap¶

The Python script groups files by (Plate, Well, Site).

• Source: It takes Plate, Well, Site from the samplesheet metadata.

• Matching: It looks for files in the input directory.

The Constraint: The input files for combined analysis are generated by previous steps (IllumApply). These files are named using the metadata from those previous steps.

• If your samplesheet says Plate is Plate_1 (underscore), but your raw filenames said Plate1 (no underscore) and you relied on filename parsing earlier, you might have a mismatch.

• Best Practice: Ensure the plate column in your samplesheet EXACTLY matches the plate identifier used in your filenames if you are relying on any filename-based grouping logic.

Channel Matching¶

Before invoking generate_load_data_csv.py, the combined-analysis Groovy code (workflows/{nf-pooled-cellpainting,no-stitch,stitch-align-crop}.nf) uses regex to identify if a file is “Cell Painting” or “Barcoding” based on its filename pattern, so it can set the right arm/column_prefix/channel/cycle in the metadata JSON entry:

1. Barcoding Pattern: Looks for Cycle(\d+).

   • Matches: ..._Cycle01_A.tiff

2. Cell Painting Pattern: Looks for Corr(.+).

   • Matches: ..._CorrDNA.tiff

Impact: If you name a Cell Painting channel Cycle1 (e.g., CorrCycle1.tiff), the script might mistakenly try to parse it as a barcoding image because of the Cycle keyword.

• Rule: Avoid using the word Cycle in your Cell Painting channel names.

Summary Checklist¶

Before running the pipeline:

• Samplesheet Columns: Ensure batch, plate, well, site, channels, arm are present.

• Channel Names:

  • Cell Painting: Names in channels column match the names in your raw image filenames (e.g., DNA, Mito).

  • Barcoding: Names in channels column are A, C, G, T, DNA, or DAPI.

• Avoid Keywords: Do not use Cycle or Corr as part of your raw channel names to avoid regex confusion.

• Consistency: Ensure plate names are consistent across all rows for the same physical plate.