Creating Studies
Create a study when you know which samples belong together scientifically — that is, when you are ready to run pipelines across them or publish them as one ENA project. There is no benefit to creating one earlier: an empty study cannot be marked ready and does nothing.
The wizard lives at /studies/new. Unusually, it opens on sample selection
rather than on a details form, because the samples determine which metadata the
rest of the wizard needs to collect.
Before you start
- The samples must already exist, which means their sequencing orders must have been created. The order does not need to be submitted or completed.
- The samples must be unassigned, or you will be moving them out of another study.
- Know which MIxS environment package fits your samples. Changing it later invalidates the metadata you have already entered — see Study Metadata & MIxS.
The wizard
Steps are built from the enabled modules, so the exact list depends on your installation’s configuration.
Select Samples
Shown when the sample-association module is enabled.
The picker lists every sample you can see — your own, or all of them if you are a facility admin — with its order number, order status and current study. It is split into unassigned and already-assigned groups, and a select all unassigned shortcut takes the whole unassigned set at once.
At least one sample is required: submitting with none fails with
Please select at least one sample.
Already-assigned samples are shown, not hidden. Selecting one moves it out of
its current study — the assignment endpoint simply overwrites studyId. Check
the study column before selecting.
Study Details
| Field | Required | Notes |
|---|---|---|
| Study Title | Yes | Appears in ENA. Rejected empty with Study title is required |
| Description | No | Free text context |
Plus any study-level fields your admin configured. On a default install these are normalised into two fixed sections, Study Information and Metadata, plus an Additional Details bucket for ungrouped fields.
The study alias is not asked for here. POST /api/studies accepts only
title, description, checklistType and studyMetadata — it ignores
anything else. Set the alias afterwards from the study’s edit page. The alias
becomes the ENA project alias, and it also works as a URL identifier:
/studies/<alias> resolves.
Environment Type
Shown when the MIxS module is enabled, and required — submitting without a
selection fails with Please select a MIxS checklist type.
The picker is driven by the live checklist registry
(GET /api/mixs-checklists),
not by a hardcoded list, so it shows whatever your installation has available.
A stock install offers all seventeen shipped checklists, including
GSC MIMAGS and ENA binned metagenome as well as the thirteen environment
packages.
Underneath, a Metadata Fields panel appears. Mandatory fields are listed and always included; optional fields are searchable checkboxes. Enable only what you will actually fill in — each one becomes a column in the next step.
Sample Metadata
Shown when sample association is on and there are per-sample fields to fill.
- One row per selected sample, one column per enabled MIxS or custom field.
- Missing required values are collected as warnings, not errors. A dialog
lists them (
S-1755262041412-K7QX2: collection date is required) and lets you create the study anyway. - The Excel Template / Upload Excel toolbar works here exactly as it does in the order wizard: download a template, fill it in, upload it back.
- Values are written to each sample’s
checklistDataas JSON.
Review
A summary of the study details, the selected samples and their metadata. Creating
the study leaves readyForSubmission at false.
What actually happens on submit
Two requests, in order:
POST /api/studiescreates the study with your title, description,checklistTypeandstudyMetadata. If a checklist was chosen, SeqDesk also stampsmixsVersionwith the currently active registry version, pinning the study to the field definitions it was authored against.POST /api/studies/[id]/samplessetsstudyIdon every selected sample and writes the per-sample metadata.
If step 2 fails, the study still exists but has no samples. Open it and add them from the study page rather than starting over.
Empty values are dropped before sending, so a field you left blank is simply
absent from checklistData rather than stored as "".
Study properties
| Field | Set where | Notes |
|---|---|---|
title | Wizard, edit page | Required |
alias | Edit page only | ENA project alias; also resolves as a URL segment |
description | Wizard, edit page | Free text |
checklistType | Wizard, edit page | The canonical slug (soil, human-gut, …) when the checklist is one of the thirteen environment packages; the raw ENA accession (ERC000047) otherwise |
mixsVersion | Stamped at creation | Pins the checklist definition version |
studyMetadata | Wizard, edit page | Study-level custom fields, JSON |
notes | Notes panel | Internal notes with notesEditedAt / notesEditedById tracking |
readyForSubmission / readyAt | Mark as Ready on the overview | See Study Workflow |
studyAccessionId, submitted, submittedAt, testRegisteredAt | ENA submission | Never set by hand |
Managing samples afterwards
From the study workspace you can:
- Add samples — assign further unassigned samples from any of your orders.
- Remove samples — sets
studyIdback tonull. The sample stays in its order with all its metadata intact. - Edit metadata — the Table Overview gives one row per sample with inline
editing of every metadata column, plus CSV and XLSX export
(
<alias>-table-view.csv; the XLSX adds a Study Metadata sheet for the study-level fields). - View linked files — Sequencing Data shows which reads each sample has.
How metadata edits merge depends on who you are. A facility admin writing
per-sample metadata replaces checklistData wholesale. A researcher’s
write is merged field-by-field against the fields the questionnaire currently
exposes, so a partial post or a shrunk questionnaire never wipes previously
captured answers. Clearing a value means submitting it empty, not omitting it.
A sample belongs to at most one study. To move one, remove it from its current study first — or simply select it in another study’s picker, which reassigns it.
Per-study questionnaires
With the dynamic-studies module enabled, each study gets its own
questionnaire stored in a StudyFormConfig row rather than sharing the global
study form. A new study is seeded with a minimal default (Sample Association,
Principal Investigator, Study Abstract, …) or cloned from an existing study.
This changes two things elsewhere:
- The order wizard gains a first Study step so samples can be associated with a study up front and their metadata collected against that study’s form.
- Deleting a study with samples still attached is refused — see Study Workflow.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Study title is required | Blank title | Enter a title |
Please select a MIxS checklist type | Environment step skipped | Choose an environment package |
Please select at least one sample | No samples selected | Select at least one |
| Warning dialog on submit | Required per-sample values are missing | Fill them, or continue and complete the metadata later |
| Alias field missing in the wizard | It is not part of study creation | Set it on the study’s edit page |
| A sample you wanted is not listed | It belongs to another user’s order | Facility admins see all samples; researchers see only their own |
No checklists available. | The registry returned nothing | Check the MIxS registry configuration in admin settings |
Next
- Study Metadata & MIxS — what the checklist choice commits you to.
- Study Workflow — marking ready, pipelines, submission and deletion.
SeqDesk and this documentation were developed with assistance from generative AI tools (Claude Code, Codex), and reviewed and tested by the maintainers. Generative AI disclosure