Assigning Files to Samples

Discovery produces a list of files. Assignment turns “this file probably belongs to that sample” into a durable Read record. It is the step that finishes an order — associating the last sample’s R1 is what triggers automatic completion.

Everything here happens on the Associate view of an order’s Sequencing Data page (/orders/[id]/sequencing?view=discover), and requires the FACILITY_ADMIN role, a non-demo session, and an order in SUBMITTED or COMPLETED.

The matching cascade

For each sample, SeqDesk tries three sources in order and stops at the first that yields anything at all.

Statuses and confidence

Every suggestion carries a status and a confidence between 0 and 1.

How the identifier score is computed

Both strings are lower-cased and stripped of every non-alphanumeric character, then compared:

Anything at or below 0.3 is discarded. If two or more distinct pairs score ≥ 0.7, the result is ambiguous and no file is proposed — the alternatives are listed for you to choose from. Otherwise the highest-scoring pair wins, as exact if it reached 0.7 and partial if not.

The length ratio in the second rule is why long generated sample ids match badly. S-1755262041412-K7QX2 normalises to 20 characters; inside a filename like FAX12345_pass_barcode07_a1b2c3d4_0 it appears not at all. This is why the run plan matters — see Sequencing Runs.

Auto-assignment

Auto-assignment is off by default (autoAssign: false), and the Auto-Discover button never turns it on: the interface always sends autoAssign: false together with force: true. Discovery from the interface therefore only ever suggests. You always click to apply.

When a programmatic caller does enable it, a sample is linked automatically only when all three hold:

• the suggestion status is exact, and
• confidence is ≥ 0.9, and
• an R1 file is present.

Note the interaction with the confidence table: a single-end barcode match scores 0.92 and qualifies, while an identifier match scoring 0.85 does not. Everything else — partial, ambiguous, lower confidence — is left for review.

Samples that already have files

Discovery skips samples that already have an active read with a file, unless force is set. Skipped samples are reported with status exact and confidence 1 but no proposed files, which is how the interface shows “already linked, nothing to do”.

Because the Auto-Discover button always sends force: true, pressing it re-evaluates every sample including the linked ones. That is what you want when re-associating after files moved; it also means the suggestion list is longer than you might expect.

Applying matches

The Discovery Results card summarises the run as 12 exact, 3 partial, 1 no match, 2 scan warnings.

Associate reads as

Above the results is an Associate reads as switch with three positions: Cleaned, Raw / protected and Unknown. It sets the dataClass of the reads you are about to link.

Leave it on Cleaned if the files in storage are analysis-ready. Choose Raw / protected for unfiltered sequencer output — the interface warns that raw reads may still contain human contamination and that files should only be marked cleaned once removal has completed. The choice has real consequences, described next.

Raw vs cleaned reads

Every Read carries a dataClass. Its purpose is to stop derived data from silently destroying the original.

A second field, dataClassSource, records how the class was decided: legacy_assumed_cleaned, associate, upload, sequencer_ingest, pipeline or manual.

The protection rule

When you assign or upload a cleaned read over a sample whose current active read is protected and the file paths differ, SeqDesk does not overwrite. In a single transaction it:

1. creates a new Read for the cleaned files and marks it active, and
2. marks the previously active protected read isActive = false and sets its supersededByReadId to the new read.

The protected read is preserved as provenance, never deleted. Replacing a non-protected read in place is allowed and simply updates the existing record.

Choosing the active read

A sample can accumulate several reads. The one everything downstream uses is picked by preferring, in order:

1. an active cleaned read that has a file;
2. any active read that has a file;
3. any read that has a file;
4. the first read of any kind.

Delivery, pipelines and ENA submission all follow this rule.

Manual re-classification

A facility admin can change a read’s class directly — for example marking an associated read as raw after realising it was unfiltered. This sets dataClass, dataClassSource = manual, and records who changed it, when, and an optional note. Re-classification updates the read in place; it never supersedes.

What gets stored

Assigning reads also moves the sample’s facility status from WAITING or PROCESSING to SEQUENCED; clearing them moves SEQUENCED back to WAITING.

Validation before anything is written

Each assignment is checked, and a failure is reported per sample rather than failing the whole batch:

Submitting an assignment with both files null clears the sample’s read link.

Checksums and integrity

Checksums are not computed during assignment — that would make linking a hundred samples unbearably slow. They are computed on demand from the sequencing page, and only for files that do not already have one. The result reports updatedReads, updatedArtifacts, failed and skippedMissingFiles; a missing file is counted separately from a real failure.

The sequencing overview derives an integrity indicator per sample from the combination of linked files and present checksums:

Separately, the page flags Linked read paths need review when a read points at a file that no longer exists on disk.

Uploading files

When the data is not on the server at all, upload it. Uploads are chunked and resumable: a session is created with the expected size, chunks are appended at a byte offset that must match what the server already holds (Upload offset does not match current upload size), and completion moves the temporary file into a generated path under the data base path.

• Read uploads must target R1 or R2 and must use an allowed sequencing extension (Read uploads must use an allowed sequencing file extension), and must name a sample (Read uploads require a target sample).
• Artifact uploads carry a stage and an artifact type instead.
• Completing an upload runs the same protection rules and then the auto-completion check.

Cleaned reads from pipelines

The shipped read-cleaning pipeline does not write to Read records directly. It produces cleaned-read candidates — artifacts flagged sample_read_candidate — which a facility admin reviews under the run’s pending writebacks and promotes explicitly.

Promotion copies the cleaned files into the data directory, creates a new active cleaned read with dataClassSource = pipeline, supersedes the previous active read and preserves any protected raw or unknown reads for provenance. The confirmation text spells it out: existing raw or unknown reads are preserved, existing active cleaned reads are superseded rather than deleted.

Other order-scoped pipelines write back automatically instead:

Requirements for pipelines

Before a pipeline can run over an order or a study:

• every included sample must have at least one read record;
• the read files must exist at the stored paths;
• for paired-end pipelines, both R1 and R2 must be linked.

The launcher validates these before starting a run. See Running a Pipeline.

Troubleshooting

Next

• Sequencing Order Lifecycle — auto-completion and releasing data.
• Running a Pipeline — consuming the reads you just linked.