Results & Outputs

A Nextflow workflow writes files. SeqDesk’s job is to turn a subset of those files into database records that the rest of the application can use: an assembly you can submit to ENA, a checksum a submission check can verify, a report a researcher can open. That translation is called output resolution, and it is entirely driven by the package’s declared outputs.

How resolution works

When a run reaches completion, SeqDesk scans the run folder’s output/ directory and matches files against each declared output’s discovery pattern — a glob, plus a rule for associating a file with a sample (by filename, or by parent directory). Each matched file is then routed by its destination:

Three properties follow from this and explain most surprises:

• Resolution is idempotent. Artifacts are unique per (run, path), assemblies and bins per (run, sample, file). Re-running resolution — which happens whenever a weblog completion and the monitor race each other — skips what already exists instead of duplicating it.
• A pattern that matches nothing is not an error. The run still completes; the artifact is simply absent. If a completed run shows no results, the first thing to check is whether the produced filenames match the package’s declared patterns.
• The workflow never writes to the database. It writes files. SeqDesk reads them and performs every write itself, after validating the declared contract.

A summary of each pass is stored on the run as JSON: assembliesCreated, binsCreated, artifactsCreated, pendingWritebacks, plus errors and warnings when there were any. Errors here mean ingestion problems, not pipeline failures — a run can be completed and still report output errors, and the Pipeline Runs table flags that.

Where files live

Nothing is moved by default. Discovered outputs are recorded with their absolute path inside the run folder:

/data/pipeline_runs/MAG-20260415-003/output/…

The two exceptions are the writes that have to become permanent data:

• Promoted read candidates are copied into the data base path under a deterministic layout, so deleting the run folder cannot orphan an active read:

  <dataBasePath>/_pipeline/orders/<orderId>/<pipelineId>/<runNumber>/<sampleCode>/<outputId>/R1-<filename>

• Assemblies and bins keep their run-folder paths but are referenced from Assembly.assemblyFile / Bin.binFile, which is why deleting a run also deletes those rows.

Artifacts

A PipelineArtifact records one produced file: its path, size, the manifest outputId it satisfied, the step that produced it, the sample it belongs to (when sample-scoped), and any parsed metadata as JSON.

The stored type is one of three values, derived from how the package classified the file: report, qc, or data. Artifacts are the generic container — anything that is not an assembly, a bin, or a read write ends up here.

The results list on a run

The run row in Pipeline Runs, and the run detail page, show a curated list rather than every file:

• Sample-scoped artifacts are excluded from the top-level list and counted separately, so a 200-sample run does not bury its one summary report.
• The list is capped at 12 files; anything beyond that is reported as an omitted count and remains reachable through the file browser.
• Files are ranked, not alphabetised. An output whose package marks it as the primary preview ranks highest, followed by study_report/order_report destinations, then reports, then HTML, then PDF, then tabular formats. Logs are pushed down.
• Nextflow’s own report.html is added as Nextflow report if it exists, and is deliberately ranked below real results.
• A file is previewable inline only if its extension is one of .html, .htm, .pdf, .txt, .tsv, .csv, .log, .json and it lives inside the run folder.

The Pipeline Output tab is the uncurated view: a browser over everything under output/, walking up to 10 directory levels and 1000 files, with dotfiles skipped.

Assemblies

An Assembly is a set of contigs for one sample.

The MAG package discovers assemblies with the pattern Assembly/*/*.contigs.fa.gz, matching the sample by filename — the wildcard directory means MEGAHIT and SPAdes output both resolve, so one sample can end up with several assemblies.

Preferred assembly

Because a sample can have more than one assembly, one must be chosen for downstream use — in practice, for ENA submission. Sample.preferredAssemblyId records an explicit choice; when it is unset, SeqDesk falls back to the newest assembly, ordered by the creating run’s timestamp.

That produces four selection states, shown as a badge in the Selection column:

Missing Preferred is not cosmetic. Submission validation resolves the preferred assembly strictly, so a dangling choice blocks the run rather than silently falling back:

Sample S-… has an invalid preferred assembly selection (update it in Study Analysis)

Genome bins

A Bin is one genome extracted from a metagenomic assembly.

MAG discovers bins at GenomeBinning/DASTool/bins/**/*.fa, matching the sample by parent directory, and falls back to GenomeBinning/{MetaBAT2,MaxBin2}/**/*.fa when DAS Tool produced nothing. DAS Tool bins are refined — they combine and de-replicate the output of the individual binners — which is why they are preferred.

Completeness and contamination are not read from the FASTA. They come from a declarative parser that reads GenomeBinning/QC/checkm_summary.tsv and joins on the bin name. If that file is missing, bins are still created; their quality columns are simply empty.

The conventional interpretation of those numbers (MIMAG-style):

SeqDesk stores the values and displays them; it does not enforce a threshold or filter bins by quality.

Taxonomy is handled the same way: a parser reads Taxonomy/GTDB-Tk/*.summary.tsv, joins on bin name, and attaches the classification as sample metadata.

Read writeback and candidate review

Order pipelines write to the canonical Read record. Which of the three behaviours applies is decided by the package’s declared result kind — see Pipeline Scopes for the full mapping.

Reviewing candidates

Read Cleaning is the pipeline that uses the review path. Its cleaned FASTQ files are staged, not applied, and the run’s page shows Review pending read outputs with one row per sample: the candidate files, the sample’s current active reads, and a Candidate or Promoted badge. Selecting rows and pressing Set as active reads promotes them, behind an explicit confirmation checkbox.

Promotion is deliberate about what it does to existing data:

1. The candidate file is copied out of the run folder into the data base path (the _pipeline/orders/… layout above). Its source path is checked to be inside the run folder first — a candidate pointing anywhere else is rejected.
2. MD5 and read count are computed for the copy.
3. A new Read row is created with dataClassSource: "pipeline" and a classification note naming the run.
4. Every currently-active read on that sample is deactivated and linked to the new read via supersededByReadId, then the new read is activated.

Guards worth knowing: promotion requires a completed, order-scoped run (Only completed pipeline runs can be promoted, Pending read promotion requires an order-scoped run), a configured data base path, and at least one un-promoted candidate (No pending read candidates selected for promotion). A double submit cannot create two active reads — the transaction re-checks for an existing read promoted from the same run and sample.

API

All four require FACILITY_ADMIN, and promotion is disabled in the public demo.

Publishing a run to the researcher

By default, a pipeline run is invisible to everyone except facility admins — including the researcher who owns the study or the sequencing order. Read access requires both ownership and publication; without publication the run’s API routes answer 403 Forbidden.

Publication is the Use as final action in a run’s row menu. It records a PipelineResultSelection keyed by (pipelineId, target), so one run per pipeline per study or order is the final one. Selecting a different run moves the marker; Clear final removes it and makes the run private again.

Constraints:

• FACILITY_ADMIN only, and disabled in the public demo.
• Only completed runs qualify: Only completed pipeline runs can be selected as final.
• The run must have a target: Pipeline run does not have a study or order target.

The selected run carries a Final badge in the Pipeline Runs table.

Assemblies Viewer

The Assemblies page (/assemblies) is the cross-study view of every sample that has an assembly and belongs to a study.

Visibility rules:

• Facility admins see every sample with an assembly.
• Researchers see only samples in their own studies, in orders whose status is COMPLETED — and only when the allowUserAssemblyDownload setting is on. With it off, the page answers Assembly downloads are disabled by the facility administrator.
• The page is disabled entirely in the public demo.

Deleting a run

Deleting a run is a FACILITY_ADMIN-only action available from the run’s row menu (Delete run) or in bulk via Select → Delete. It is irreversible, and it removes more than the run row.

What happens, in order:

1. A running run is refused: Cannot delete a running run. Cancel it first.
2. A pending or queued run that already has a scheduler job is cancelled first, so the job is not orphaned against a deleted folder.
3. For a terminal run, output cleanup runs — but only for packages that declare a sample_reads destination. For those, the read files this run materialised are deleted, and read rows or metadata fields it wrote are cleaned up. Cleanup is scoped to the run’s own samples, and a metadata-only pipeline clears the fields it wrote rather than deleting the read.
4. Assembly and Bin rows created by the run are deleted.
5. Steps, events and artifacts are deleted (they also cascade).
6. The run row is deleted.
7. The run folder is removed from disk, best-effort.

Re-resolving outputs without re-running

If a run completed but its outputs were not picked up — a late file, a fixed discovery pattern, a transient storage error — an admin can re-run resolution alone:

POST /api/pipelines/runs/{id}/resolve-outputs

It accepts only completed or failed runs (Can only resolve outputs for completed or failed runs), needs a run folder (Run folder not set) and samples (No samples found for this run). Because resolution is idempotent, running it repeatedly is safe.

Where to find results

Related pages

• Monitoring a Run — how a run gets to the point where outputs are ingested.
• Study vs Sequencing Order Pipelines — which writes each scope may make.
• Available Pipelines — the declared outputs of every shipped package.
• Adding Custom Pipelines — writing discovery patterns and result contracts.
• ENA Submission — what happens to assemblies and bins afterwards.