Samples & Metadata

Samples are the core data unit in SeqDesk. Each sample belongs to an order and can optionally be assigned to a study for analysis and ENA submission.

Default Sample Fields

Every sample has these system-level fields that are always present:

These fields are managed by SeqDesk and stored directly on the Sample record in the database.

Default Per-Sample Form Fields

The order wizard includes these per-sample columns by default:

Two additional per-sample fields ship by default but are admin-only — they are visible and editable only by facility admins, not researchers:

Unlike regular sample data, these admin-only fields can be edited by facility admins even after the order leaves DRAFT.

Per-Sample Facility Status

Each sample also carries a facility-managed processing status, independent of the order’s own lifecycle. It defaults to Waiting and moves through the sequencing workflow:

This status is set by the facility and is tracked per sample with a last-updated timestamp.

MIxS Metadata

MIxS (Minimum Information about any Sequence) is a standard for describing sequencing samples. When a MIxS checklist is selected for an order or study, additional metadata columns appear in the sample table.

MIxS fields are stored as JSON in the checklistData field. Units for numeric fields are stored separately in checklistUnits.

SeqDesk ships the GSC and ENA MIxS catalogs in data/field-templates/mixs-full/. Commonly used checklists include:

• ENA default sample checklist
• GSC MIMAGS (Metagenome-Assembled Genomes)
• GSC MIxS soil / water / wastewater & sludge / sediment
• GSC MIxS host associated / plant associated
• GSC MIxS human gut / human skin / human oral / human vaginal / human associated
• GSC MIxS air / microbial mat biofilm / miscellaneous environment
• ENA binned metagenome

The full catalog is exposed by the /api/mixs-checklists endpoint.

The required fields vary by checklist type and are important for ENA submission.

Editing Samples

Table Editing

The sample table supports:

• Keyboard navigation — arrow keys, Tab, Enter to move between cells
• Inline editing — click a cell to edit it directly
• Organism autocomplete — type a name to search NCBI taxonomy
• Add rows — add blank rows at the bottom
• Delete rows — remove rows (DRAFT orders only)
• Undo — revert unsaved changes

Bulk Editing and Export

The sample table toolbar offers two distinct download paths:

• Excel template (round-trip import/export) — generates an .xlsx spreadsheet with a column for every per-sample field. This is the path used for bulk editing: download the template, fill in rows in your spreadsheet application, then upload it back. On import, columns are matched by header name and rows are added or updated accordingly. Importing is only available while the order is editable (DRAFT).
• Export CSV — a one-way, read-only export of the current sample table (samples_<order>.csv) including system fields, MIxS checklist fields, and custom fields. It is for download only and cannot be re-imported.

The Excel round-trip is the fastest way to add many samples with metadata.

Custom Fields

If the admin has configured per-sample custom fields in the Form Builder, they appear as additional columns in the sample table. Custom field data is stored as JSON in the customFields field.

Sample Lifecycle

Created in Order (DRAFT)
  → Order submitted
  → Assigned to Study (optional)
  → Files assigned (Reads linked)
  → Pipeline run (Assemblies, Bins created)
  → ENA submission (Accession numbers assigned)

Key Relationships

• Order — every sample belongs to exactly one order (required)
• Study — a sample can be assigned to one study (optional)
• Reads — sequencing files linked to the sample
• Assemblies — pipeline output assemblies
• Bins — genome bins from binning pipelines