Preparing a Submission

ENA rejects a submission for reasons that are cheap to fix before you send it and expensive to diagnose afterwards. This page covers what SeqDesk itself validates, what it silently passes through, and what a well-prepared study looks like.

The two ENA paths have different requirements. Registration is deliberately permissive — it only needs enough to build valid PROJECT and SAMPLE XML. The submg pipeline is strict, because it has to stage real files and drive webin-cli. Prepare for registration first; prepare for submg only when you actually intend to publish data files.

What XML registration requires

These are hard checks in POST /api/admin/submissions. Each one returns HTTP 400 and no XML is generated or sent.

Notice what is not checked: there is no minimum length on the title or description, no uniqueness check on the alias, no requirement that the study is marked ready, and no validation of MIxS completeness. A study with a one-character description and no environmental metadata will register successfully — and produce a nearly useless public record. The quality bar is yours to set.

The check panel in the UI

The Register at ENA screen shows the same requirements as a live checklist before you can click anything. In Test mode the panel is titled Submission Requirements and lists five rows, each with a pencil icon that jumps straight to the relevant edit screen:

The Metadata row is the only one with no server-side counterpart — the registration API will happily proceed without it. It exists because sample attributes are the part of the record that makes the data reusable, and the easiest moment to fill them is before the record is public.

Switching the toggle to Production replaces the panel with Production Requirements, which is a different, stricter set. See the test-first gate.

What the submg pipeline requires

submg validation runs twice: once when the run is created (in validatePipelineMetadata) and again when the run is prepared (in the submg runner). Both refuse to start the run rather than sending a partial submission, so a failed check costs you nothing but time.

Per study:

• The study must already have a PRJ… accession. Register first.
• If the global ENA target is Test, the study must additionally have a test registration that is less than 24 hours old. An expired or missing test registration is a hard error, not a warning.
• submg only runs on study targets. There is no sequencing-order-scoped variant.

Per sample:

Bins are optional. A sample with no bins produces a warning, not an error, and is submitted without a BINS: block.

Assembly coverage

submg’s assembly manifest needs a COVERAGE_VALUE. SeqDesk looks for one in the sample’s custom fields first and then the sequencing order’s custom fields, trying these keys in order:

assembly_coverage_value, coverage_value, coverage_depth, target_coverage_depth, target_coverage, coverage

If none is found and no assemblyCoverageValue was set in the pipeline configuration, it falls back to 1 and emits a warning naming the sample. A coverage of 1 is almost never true. Set coverage_depth on the sample or sequencing order, or override assemblyCoverageValue when you launch the run, if the number matters for your submission.

How sample attributes are built

This is the part that surprises people. The SAMPLE_ATTRIBUTE entries in the XML are not a copy of one field — they are a merge of four sources, applied in this order, where later sources overwrite earlier ones on key collision:

Only non-empty string values are carried through at each stage; blanks are dropped rather than overwriting a good value with an empty one. The study’s checklistType is emitted separately as an ENA-CHECKLIST attribute so ENA validates the sample against the right checklist.

The practical consequence: if a value looks wrong in the generated XML, check all four sources, not just the checklist. The Submissions Dashboard shows the exact XML that was sent, which is the fastest way to see the merged result.

The field-name mapping

ENA expects specific attribute names, several of which contain spaces and parentheses. SeqDesk rewrites a fixed list of internal keys onto them. Anything not in this list is sent verbatim under whatever key your form used.

So a form field named broad_scale_environmental_context — a perfectly reasonable name, and one the built-in demo data uses — is not rewritten, because the map keys that field as env_broad_scale. It reaches ENA as a custom attribute called broad_scale_environmental_context. It will not fail validation, but it will not satisfy the checklist’s mandatory broad-scale environmental context field either.

If a checklist field is being reported as missing by ENA even though you filled it in, this mapping is the first place to look.

A worked example

A twelve-sample human gut metagenome study, prepared for both paths:

Study
  title        Human Gut Shotgun Metagenomes (PRJEB54724)
  alias        human-gut-shotgun-prjeb54724
  description  Twelve paired-end Illumina shotgun metagenomes from adult
               faecal samples collected in the Netherlands, 2016.
  checklist    host-associated

Sample HGM-01
  sampleId       HGM-01                     -> SAMPLE alias
  sampleTitle    Human faecal shotgun metagenome Subject-01
  taxId          408170                     -> TAXON_ID
  scientificName human gut metagenome       -> SCIENTIFIC_NAME
  checklistData
    collection_date                        2016-05-12
    geographic_location_country_and_or_sea  Netherlands
    env_broad_scale                        host-associated habitat [ENVO:00009003]
    env_local_scale                        gastrointestinal tract environment [ENVO:2100002]
    env_medium                             feces [ENVO:00002003]
    host_scientific_name                   Homo sapiens
  customFields
    coverage_depth                         28

That yields a sample element carrying ENA-CHECKLIST, a mapped collection date, a mapped geographic location (country and/or sea), three mapped environmental context attributes, host scientific name, and a coverage_depth attribute that also serves as the submg coverage source.

Pre-flight checklist

Where to go next

• Submitting to ENA — the workflow itself.
• Troubleshooting ENA — when a check fails or ENA rejects the XML.
• Study Metadata & MIxS — where checklist fields come from.