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.