Foundry
Home Pattern

Collection: unbox singleton

Use __EXTRACT_DATASET__ with which: first when a one-element collection must become a dataset.

draft pattern
Revised
2026-05-03
Rev
2
Molds
Related

Pattern health

warn
  • IWC exemplar anchors

    3 abstract workflow anchors declared.

  • Foundry verification fixture

    No structural verification fixture yet.

  • Pattern map coverage

    No pattern map links to this leaf yet.

  • Metadata contract

    Pattern frontmatter matches the site contract.

Collection: unbox singleton

Tool

Use Galaxy built-in __EXTRACT_DATASET__ with which: first.

This page covers the corpus-dominant shape: an upstream step emits a known one-element collection, but the downstream step or workflow output expects a dataset.

When to reach for it

Use this when the collection has exactly one meaningful element by construction.

Common IWC context: QC/reporting tools emit images, stats, or HTML outputs as singleton collections after map-over or conditional branching. The workflow immediately extracts the first element so ordinary dataset-consuming steps can use it.

Do not use this to reshape a real multi-element collection. If N > 1 is meaningful, preserve collection semantics or use a collection-aware operation.

Parameters

  • input: connected collection.
  • which: first: singleton unboxing.

The same tool supports by-index and by-identifier extraction, but the survey signal is overwhelmingly the singleton case. Prefer by-identifier over by-index if you genuinely need arbitrary element extraction.

Idiomatic shape

tool_id: __EXTRACT_DATASET__
tool_state:
  input: { __class__: ConnectedValue }
  which: first

Read this as an assertion: this collection has exactly one useful element here.

Pitfalls

  • which: first hides bugs if the collection unexpectedly has multiple elements.
  • Do not use it as collection filtering; selecting a named element is a different operation.
  • Check conditional branches. Singleton extraction often follows single-sample vs multi-sample routing.
  • Once unboxed, collection element identifiers are no longer available as collection metadata.

See also

IWC exemplars3 anchors

IWC Exemplars

VGP-assembly-v2/Scaffolding-HiC-VGP8/Scaffolding-HiC-VGP8high

Repeatedly unboxes singleton QC/report outputs such as alignment scores, alignment stats, and snapshots.

VGP-assembly-v2/Assembly-Hifi-HiC-phasing-VGP4/Assembly-Hifi-HiC-phasing-VGP4high

Shows repeated singleton extraction for Merqury and PNG outputs.

VGP-assembly-v2/Purge-duplicates-one-haplotype-VGP6b/Purging-duplicates-one-haplotype-VGP6bhigh

Uses the same VGP reporting and QC singleton extraction shape.

Incoming References (6)

  • Manifest to mapped collection lifecyclerelated pattern— Use a manifest or table to build a collection, map a tool per row, then relabel or reshape outputs.
  • Galaxy Apply Rules DSLrelated note— Reference for Galaxy's Apply Rules DSL: rule operations, mapping operations, composition patterns, pitfalls.
  • Iwc Map Over Lifecycle Surveyrelated pattern— Survey of IWC map-over lifecycle recipes, with a Nextflow-to-Galaxy crosswalk for collection construction, cleanup, reshape, reduce, and publish phases.
  • Iwc Transformations Surveyrelated note— Corpus survey of collection-shape transformations across IWC: built-in collection ops, toolshed transformers, and the multi-step recipes that bracket map-over.
  • Nextflow: grouped channel to regrouped Galaxy collectionimplemented_by_patterns— Route Nextflow groupTuple, transpose, and grouped tuple payloads to Galaxy collection reshape patterns when the key is a real axis.
  • Nextflow: mapped output cleanup and publishingimplemented_by_patterns— Route Nextflow mapped-output cleanup and publishDir-style intent to Galaxy filtering, relabeling, gating, bundling, and reports.