Best Practices

Most SeqDesk rework comes from a handful of avoidable decisions: submitting an order before the sample table is right, splitting samples across studies the wrong way, or turning researchers loose before the departments and the form exist. This page collects the habits that prevent that.

Before you invite anyone

Set up departments first

Researchers pick a department during registration, and the list they see is the list you have configured. Register users into an empty department list and you will be reassigning them by hand afterwards. Create departments at Users → Departments (/admin/departments) before you share the URL.

Departments matter beyond tidiness: Settings → Accounts → Access & Sharing has a department sharing toggle that lets researchers in the same department see each other’s sequencing orders. That is the only mechanism SeqDesk has for widening visibility beyond a single owner, and it keys off the department you assigned at registration.

Shape the order form before real orders exist

The default order form works out of the box, but every field you remove later leaves orphaned data in Order.customFields and Sample.customFields on orders that already used it. Do the surgery at Settings → Sequencing Order Form (/admin/form-builder) while the instance is empty:

• Delete fields your facility never fills in.
• Add the ones you actually need — cost centres, grant numbers, sample volumes.
• Mark facility-only fields admin-only so they appear in a separate Facility Fields step that researchers never see.
• Decide which modules you want on (Settings → Modules) before configuring the form, since modules add and remove whole field groups.

Set the data storage path before the first sequencing run

The sidebar’s Infrastructure entry carries a warning badge until two things are configured: the Data storage path and the Pipeline run directory. The data path is what the file browser scans, so nothing can be attached to a sample until it is set. Pick a stable, predictable layout — for example /data/sequencing/<year>/<run-folder>/ — because the scanner walks a limited number of directory levels (scanDepth, default 2) and only matches configured extensions (default .fastq.gz, .fq.gz, .fastq, .fq).

For researchers

Finish the sample table before you submit

While the order is DRAFT you can add, edit, delete and bulk-import samples. After you submit, the API rejects structural changes with Cannot modify samples after order submission, and you cannot delete the order either (Cannot delete order after submission). Treat Review as the point of no return, and use the Excel round trip if the table is large: download Excel Template, fill it in offline, then Upload Excel.

Give the order a name that means something in six months

The number is generated (ORD-20260415-0007) and tells you nothing. The Sequencing Order Name field is what appears in every list, including your facility admin’s. “Soil metagenome — Field Trial B, spring 2026” beats “Batch 3”. It is optional out of the box, so make a habit of filling it in — or mark it required in the order form builder so nobody has to remember.

Fill in taxonomy at the same time as the sample

Every sample needs a valid NCBI taxonomy ID for ENA submission, and chasing it later means editing samples you can no longer edit. Use the Organism autocomplete; searching by common or scientific name both work. For environmental samples use metagenome terms — “soil metagenome”, “gut metagenome”, “wastewater metagenome” — rather than the host species.

Understand what “Sample Alias” is and is not

Sample Alias is a free-text label for your own bookkeeping. SeqDesk does not enforce uniqueness on it, does not generate one if you leave it blank, and — the part that surprises people — does not send it to ENA. The alias SeqDesk submits is the internal sampleId, generated as S-<timestamp>-<random>. So use the alias for a scheme that helps you (TRIALB-SITE3-001), and do not plan an ENA naming convention around it.

Mark samples as sent, then wait

After submitting, the order page shows a three-step Sequencing Order Process panel. Step 2 has a Mark sent button — press it once the physical samples are shipped. It writes a SAMPLES_SENT note that the facility can see, and it only works after submission. Your facility’s shipping instructions appear in the same panel once the order is submitted.

Expect your data to appear only when the facility publishes it

Sequencing files do not become visible or downloadable the moment they are attached. A facility admin has to press Make downloadable to user on the order. Likewise, a pipeline run only becomes visible to you once an admin marks it Final. If you can see that an order is COMPLETED but no files, the facility has attached them and not yet published them — ask, do not assume it is broken.

For facility admins

Enable ENA test mode first, and keep it on until it works

SiteSettings.enaTestMode defaults to true, which points submissions at wwwdev.ebi.ac.uk. The test server accepts the same XML and issues throwaway accessions. Get one whole study through the test server — registration, samples, reads — before flipping to production, because a production registration cannot be taken back.

Classify reads honestly

Every read carries a dataClass: cleaned, raw or unknown. Only cleaned and isActive reads are ever delivered to the requesting researcher. If you ingest raw reads that still contain host sequence, mark them raw — the delivery gate will then refuse to hand them over, and the read-cleaning pipeline can produce a cleaned successor that supersedes them. A read left unknown is treated as protected, so a delivery that shows “nothing to publish” is usually an unclassified-reads problem, not a missing-files problem.

Publish deliberately, and use “Use as final” to curate

Two separate publish decisions exist and they are independent:

• Make downloadable to user on the order publishes sequencing files.
• Use as final on a completed pipeline run publishes that analysis.

Only one run can be final per pipeline per target, so marking a re-run as final quietly replaces the previous one in the researcher’s view. That is the intended way to correct a bad run — mark the good one final rather than deleting the bad one.

Watch a pipeline run for its first two minutes

Most pipeline failures are pre-flight: a missing input, an unset conda path, a process asking for more CPUs than the allocation has. Those surface within seconds in the run’s event feed and DAG view. Waiting for a wall-clock timeout to tell you the same thing costs hours. See Monitoring.

Keep the pipeline run directory off the same volume as your reads

Nextflow work directories grow fast and are disposable; sequencing reads are precious and are not. Configuring pipelineRunDir on separate storage means you can prune one without risking the other.

Metadata quality

Choose the MIxS checklist when you create the study, not later

The checklist determines which metadata fields exist, and SeqDesk pins the MIxS registry version onto the study at creation (Study.mixsVersion) so a later registry update never rewrites an existing study’s fields. Changing the checklist afterwards means re-entering metadata against a different field set.

Be consistent with units

MIxS fields carry a value and a unit, stored separately (Sample.checklistData and Sample.checklistUnits). Depth in metres in one sample and centimetres in another will pass SeqDesk and fail at ENA, or worse, pass ENA and be wrong in the public record. Agree a unit per field across the study.

Write a study description someone else could use

SeqDesk does not enforce a minimum length, but the study title and description go straight into the ENA PROJECT XML as <TITLE> and <DESCRIPTION> and become the permanent public-facing metadata for your data. Write them as if a stranger will read them, because one will.

Studies and analysis

One study per analysis context

A sample belongs to at most one study, so studies are a partition, not a tagging system. If you run MAG on soil samples and a separate analysis on water samples, that is two studies. Trying to make one study serve both means the samplesheet carries samples the workflow cannot handle, and the ENA submission mixes environments under one project.

Check read assignment before launching

Pipelines that declare requires.reads need every selected sample to have a linked FASTQ file. The launch UI reports how many of the required inputs are available; a run started with gaps either skips samples silently or fails at input preparation and never launches. Verify first — it is a ten-second check.

Review bin quality before you submit anything

After a MAG run, SeqDesk records CheckM completeness and contamination per bin and lets you nominate a preferred assembly per sample. It does not enforce a quality cutoff. The MIMAG “high-quality draft” convention is at least 90% completeness with under 5% contamination; use that as the guideline for what is worth putting in a public archive.