Sequencing Runs

A Sequencing Run (SequencingRun) is one run on one instrument. It exists for a single purpose that pays for itself immediately: it records which sample was loaded under which barcode. That mapping is what lets SeqDesk find the right FASTQ files later, when the sequencer has written a directory tree full of barcode07/ folders that mention no sample names at all.

Prerequisites

Run plans are managed from the Run Plan card on the order’s Sequencing Data page (/orders/[id]/sequencing). You need all three of:

• the FACILITY_ADMIN role — anything else gets Only facility admins can manage sequencing data;
• an order in SUBMITTED or COMPLETED status — a DRAFT order gets Sequencing run plans can only be managed on submitted or completed sequencing orders;
• a non-demo session — the public demo returns Sequencing data management is disabled in the public demo.

Creating a run

What a run stores

Populating the run plan

There are three ways to get barcodes onto samples, and they are checked in that order when files are matched later.

1. Automatic prefill from the order

If your order form collects a per-sample Barcode field (_barcode — added by the Oxford Nanopore run-plan preset, or by hand in the Form Builder), creating a run copies those values straight into the run plan. Samples whose barcode is unique within the order are assigned; duplicated barcodes are listed and skipped.

This is the path to design for. Collecting the barcode at order time means the run plan builds itself.

2. Manual editing

Facility admins can set or change a sample’s barcode and its run-specific preparation fields directly in the run plan table. On a default install the run-assignment form has two groups:

All of these are admin-only. A single save request is limited to 500 assignment rows.

3. Excel import

The Import Excel button on the Run Plan card uploads a spreadsheet and bulk-assigns samples. The import runs in two phases: the first upload returns a preview and changes nothing; only a second call with apply=true writes.

Limits, all enforced server-side:

SeqDesk looks for a worksheet named Run Samples, then Samples, then Tabelle2, and finally the first sheet with more than one row. Row 1 is the header.

Headers are normalised (lower-cased, non-alphanumerics collapsed to _, µ rewritten to u, * stripped) and matched against a fixed alias table:

Unrecognised columns are reported in the preview as unmappedColumns and are otherwise ignored.

Every row must have both a Run and a Sample value, otherwise it is reported as Rows must include both Run and Sample/Patient columns. Sample codes are matched against Sample.sampleId within this order; unknown ones produce Sample not found on this order: <code>. A barcode used twice within one run produces Barcode barcode07 appears 2 times in run 20260415.

The import can create runs. If a row names a run id that does not exist on the order, SeqDesk creates it (with runName set to the same id) and prefills it from the order barcodes before applying the imported rows.

Imported values are split by destination: fields that belong to the sample (internal_sample_code, material_body_site, sampling_date, storage_box, storage_position, storage_buffer) are merged into Sample.customFields; everything else is stored on the run assignment.

Barcode normalisation

Barcodes are normalised on the way in and on every comparison, so you can be sloppy about format and still get a match.

The rule: trim, lower-case; if what remains matches an optional barcode/bc prefix followed by 1–3 digits (leading zeros allowed), rewrite it as barcode plus the digits zero-padded to two places. Otherwise keep the lower-cased string as-is.

Uniqueness rules

Three database constraints define what a run plan may contain:

A sample may appear in several runs — that is how a re-run is represented — and it may carry a different barcode in each.

When two samples claim one barcode

SeqDesk resolves this differently depending on where the conflict comes from:

• Within one save request, the request is rejected outright: Barcode barcode07 is assigned more than once in this request. Nothing is written.
• Against a barcode already held by another sample in the same run, and that other sample is also part of this request: the previous owner’s barcode is cleared first and the new assignment applied. This is what makes “shift every sample down one barcode” work in a single save.
• Against a barcode held by a sample that is not in this request: Barcode barcode07 is already assigned in this run. Clear the other sample’s barcode first.
• During automatic prefill from the order, duplicated _barcode values are never assigned. They are returned as duplicateBarcodes for you to fix by hand.

Why the run plan makes file matching work

When file discovery runs, it tries the run-plan barcode first, before falling back to a sample barcode and finally to fuzzy filename matching. A barcode match is checked against every path segment of a discovered file — directory names as well as the filename — and, when the run has a runId, the path must also contain that run id. A unique hit is treated as an exact match with confidence 0.99 (paired) or 0.92 (single-end).

That is why a run plan pays for itself: with barcodes in place, a Nanopore output tree of 20260415/barcode01/… matches deterministically, while filename-similarity matching against S-1755262041412-K7QX2 would find nothing at all.

See Assigning Files to Samples for the full matching cascade.

Reads and their run

When reads are assigned, the assignment can carry a sequencingRunId, linking the Read record back to the run it came off. The sequencing overview then shows the run id and name alongside each sample’s files.

QC artifacts, not run columns

Run-level and sample-level outputs are stored as SequencingArtifact records rather than on the run itself. Each artifact has a stage and a type:

Each artifact also carries a visibility of facility (the default) or customer. Only customer artifacts with a viewable extension are ever released to the researcher, and only after the order’s delivery is published — see Releasing data to the researcher.

Artifacts can be uploaded through the sequencing page or linked to a file that already exists under the data base path.

Pipeline writeback to reads

Sequencing-order pipelines operate on the linked reads and write selected results back onto the canonical Read record, so QC, validation and submission all read the same numbers:

Read Cleaning is the exception: it does not write to Read directly but produces candidates for review. See Cleaned reads from pipelines.

Troubleshooting

Next

• File Discovery & Auto-Detect — how the scan finds the files a run plan will be matched against.
• Assigning Files to Samples — the matching cascade and what auto-assignment will and will not do.