Samples & Metadata

A Sample is one physical tube and everything SeqDesk knows about it. It is the unit that reads attach to, that pipelines run on, and that ENA registers as a BioSample. Every sample belongs to exactly one sequencing order, and optionally to one study.

What is stored where

The Sample record mixes four kinds of data, and knowing which is which explains most editing rules.

Real database columns

Form-builder fields map onto these columns when their name matches — sample_alias, sample_title, sample_description, scientific_name, tax_id and the camelCase equivalents all resolve to the column of the same meaning, and an organism field writes both taxId and scientificName. Anything else is stored as JSON.

JSON blobs

Default per-sample columns

On a fresh installation the sample table has three researcher-visible columns:

and two facility-only columns that researchers never see:

The admin-only pair is special in one important way: facility admins can edit them after the order leaves DRAFT, through the facility-fields mode of the sample endpoint. Everything else in the table is frozen the moment the order is submitted.

Your admin can add further per-sample columns — volume, concentration, barcodes, body site, storage location — through the Form Builder. The Oxford Nanopore run-plan preset, for example, adds _barcode, internal_sample_code, material_body_site, sampling_date and three admin-only storage fields.

Facility processing status

Each sample carries a facilityStatus, tracked with a facilityStatusUpdatedAt timestamp. It is independent of the order’s own lifecycle: it describes where the tube is in the lab, not where the paperwork is.

Facility admins set these from the Sequencing Data page, but two transitions happen on their own:

• Assigning reads to a sample moves it from WAITING or PROCESSING to SEQUENCED. A sample already in QC_REVIEW, READY or ISSUE is left alone.
• Clearing a sample’s reads moves it from SEQUENCED back to WAITING. No other status is reverted.

Any other value is rejected with Invalid status, and an unknown sample identifier with Sample not found.

MIxS metadata

MIxS — Minimum Information about any Sequence — is the Genomic Standards Consortium’s family of checklists describing what contextual metadata a sequence needs to be interpretable. ENA implements them as numbered checklists (ERC0000nn), and SeqDesk ships the ENA catalog offline so a fresh install works without network access.

Answers are stored per sample in checklistData. The checklist itself is chosen once — on the order (stored as _mixsChecklist in the order’s customFields) or on the study (stored as Study.checklistType).

The shipped catalog

Seventeen checklists live in data/field-templates/mixs-full/. They are exposed by GET /api/mixs-checklists.

Note the shape of the problem: GSC MIxS water asks for 130 fields, nine of them mandatory. You are not expected to fill all 130. The order wizard’s MIxS step and the study wizard’s Metadata Fields panel both let you pick which optional fields to collect on top of the mandatory ones — do that deliberately, because every field you enable becomes a column in the sample table.

The catalog can be refreshed from a remote registry; the active version is recorded so that studies authored against an older definition keep resolving their original fields. See Study Metadata & MIxS.

Editing samples

In the table

The sample table is a spreadsheet-style grid:

• Keyboard navigation — arrow keys, Tab and Enter move between cells.
• Inline editing — click a cell and type.
• Organism autocomplete — type two or more characters to search.
• Add rows at the bottom; delete rows while the order is DRAFT.
• Undo reverts unsaved changes.

Deleting a row deletes the Sample record and everything cascading from it (reads, run-plan assignments, artifacts). It is only possible in DRAFT.

Quick Actions

Excel round-trip

The toolbar’s Excel Template button downloads sample_template_<order name>.xlsx with one column per per-sample field, pre-filled with the current rows. Upload Excel parses your edited file and opens the Import Excel Data dialog, which shows the parsed row count, any unmapped columns, and per-row errors and warnings before applying anything.

A separate Export CSV button produces samples_<order name>.csv containing system fields, checklist fields and custom fields. It is a one-way snapshot and cannot be re-imported.

Worked example

A wastewater surveillance order with 24 samples:

1. In the wizard, set Number of Samples to 24; the table pre-fills with 24 blank rows.
2. On the MIxS step choose GSC MIxS wastewater sludge (ERC000023) and enable geographic location (country and/or sea), collection date and environmental medium on top of the eight mandatory fields.
3. Set the organism on row 1 to wastewater metagenome (527639), then use Copy organism to all samples.
4. Download the Excel Template, paste in your sampling dates, plant names and barcodes, and Upload Excel.
5. Review the import dialog. If a row reports an error, fix it in the spreadsheet and upload again rather than importing partially.
6. Submit. From here the sample table is read-only and the facility takes over.

What a sample connects to

Troubleshooting

Next

• Organism & Taxonomy — getting taxId right.
• Studies — regrouping samples for analysis and publication.
• Preparing a Submission — what ENA checks before it accepts these records.