Study vs Sequencing Order Pipelines

Every pipeline package declares which targets it supports. There are exactly two, and they are not interchangeable:

{ "targets": { "supported": ["study"] } }
{ "targets": { "supported": ["order"] } }
{ "targets": { "supported": ["study", "order"] } }

A run is created against one of them — PipelineRun.targetType is study or order, and exactly one of studyId / orderId is set. Asking for both, or neither, is rejected before a run row is created:

Exactly one of studyId or orderId is required            → 400
Pipeline <id> does not support <study|order> targets     → 400

At a glance

Taxonomic Profiling (Kraken2 + Bracken) is the only shipped package that declares both targets ("supported": ["study", "order"]), so it appears in both catalogs.

Study pipelines

A study is an analysis grouping: samples pulled together across sequencing orders because they belong to one scientific question, with a shared MIxS checklist and — for published work — a shared ENA project. A study pipeline treats that whole group as one unit of work.

What that buys you. The generated samplesheet can carry study-level context that an order simply does not have. The MAG samplesheet, for example, emits a group column sourced from study.id, which nf-core/mag uses for co-assembly grouping. A study_report output is attached to the study, not to a single order, so it survives the fact that its inputs came from four different orders.

What it costs you. Study pipelines are all-or-nothing per run: you select samples once, press Start Pipeline once, and one PipelineRun covers them all. If one sample’s reads are broken, that run fails as a whole.

Study pipelines write into study-linked models:

Use a study pipeline when the answer you want is about the dataset — assembly, binning, taxonomy, an aggregate report, or a public submission.

Sequencing Order pipelines

A sequencing order is an operational record: the tubes a customer sent, the run plan, and the FASTQ files that came off the instrument. Order pipelines are the facility’s tooling for that stage — validate, measure, clean, and only then hand the data on.

What that buys you. The order surface is per-sample. Each sample row shows its readiness and its own Run button, and Run All Ready starts the pipeline for every sample that currently qualifies. A single broken sample does not block the other twenty. The readiness check is explicit, and its reasons are the ones you will see in the UI:

What it costs you. An order pipeline can never reach across orders, and it cannot consume study-level inputs. If a package declares a required input whose scope is study (or whose source starts with study.), running it against an order is refused with:

<PIPELINE> requires study-scoped input <source> and cannot run on an order target

Order pipelines write into the canonical Read record and into run artifacts — never into Assembly or Bin.

What a package may write back

This is the sharpest practical difference between the two scopes, and it is enforced centrally rather than trusted to the workflow.

An output that wants to change a read declares a writeback block. Only ten Read fields are addressable at all:

file1  file2  checksum1  checksum2  readCount1  readCount2
avgQuality1  avgQuality2  fastqcReport1  fastqcReport2

Anything else in a fields map fails manifest validation. An output that declares writeback.target: "Read" must also use destination: "sample_reads", or the package linter rejects it.

SeqDesk then classifies the write into a result kind and a writeback policy, which is what actually decides whether a value lands immediately or waits for a human:

The classification is derived from the manifest: an output writing file1/file2 is a replace, an output writing only scalars is metadata, and an output that explicitly declares result.kind: "sample_read_candidate" is staged. See Results & Outputs for what promotion does on disk.

Worked example: what each shipped order pipeline writes

Study pipelines write back too, just to different tables — and one of them, Quality Overview, also updates readCount1/2 and avgQuality1/2 on the Read rows of the samples it measured, even though it is study-scoped. Scope governs which target a run belongs to, not whether reads may be touched.

A common order-side sequence

On a fresh install or a demo dataset, the order pipelines chain naturally:

1. Simulate Reads — generates FASTQ files and links them to the samples, so the rest of the chain has something to work on. This is the only order pipeline that does not require existing reads.
2. FASTQ Checksum — writes checksum1 / checksum2. ENA submission later refuses to proceed without these, so doing it early avoids a late surprise.
3. FastQC — publishes per-read HTML reports and writes read counts and mean quality onto the same Read rows.
4. Read Cleaning — only if host or contaminant removal is needed. It stages candidates; nothing changes until an admin reviews and promotes.

Each step is a separate run, each is independently repeatable, and each writes to the same canonical Read rows the rest of SeqDesk reads from.

How scope is derived

If a manifest declares targets.supported, that declaration wins outright. Only when it is absent does SeqDesk fall back to the registry’s input.supportedScopes, mapping study / sample / samples to the study catalog and order to the order catalog.

That fallback matters when reading a package: Taxonomic Profiling has supportedScopes: ["study", "samples"] in registry.json but targets.supported: ["study", "order"] in manifest.json — and the manifest is authoritative, so it is offered on sequencing orders too.

A package also declares sequencingCompatibility (readLengthClass, readLayouts, platformFamilies). Today this is descriptive metadata: it is validated by the manifest schema and carried through the loader, but the catalog is not filtered by it. The only compatibility gate currently enforced at launch time is MAG’s, which is implemented directly in metadata validation and refuses long-read or single-end-only technologies:

Sequencing technology "…" incompatible with MAG.
MAG requires short-read technologies that support paired reads.

Choosing, in one paragraph

If the work is about files — do they exist, do they match their checksums, are they clean enough to hand over — it is an order pipeline, and you run it from the sequencing order while the data is still being processed. If the work is about biology — assemble, bin, classify, report, publish — it is a study pipeline, and you run it from the study after the samples have been grouped. When both would technically work, prefer the order pipeline for anything that should happen once per delivery, and the study pipeline for anything that should be reproducible as a dataset-level result.

Related pages

• Running a Pipeline — the launch flow for both scopes.
• Available Pipelines — every shipped package with its declared target.
• Results & Outputs — what happens to produced files.
• Adding Custom Pipelines — declaring targets, inputs and writeback in your own package.
• Sequencing Runs — the physical run record, which is not a pipeline target.