---

name: io-metadata description: "Use scikit-bio IO registry formats and metadata objects for reading, writing, validation, and serialization." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

scikit-bio IO and Metadata

Use this sub-skill when a task involves skbio.io.read, skbio.io.write, skbio.io.sniff, object-oriented .read() / .write(), supported file formats, QIIME-style sample metadata, metadata column validation, missing-value schemes, or interval metadata serialization.

Route Here For

• Reading or writing FASTA, FASTQ, Newick, GFF3, GenBank, EMBL, CLUSTAL, PHYLIP, BIOM, ordination, distance-matrix, BLAST, taxonomy dump, embedding, Stockholm, QSeq, LSMat, or sample metadata files.
• Choosing between procedural I/O (skbio.io.read(file, format=..., into=...)) and object-oriented I/O (SomeClass.read(file, format=...), obj.write(file, format=...)).
• Streaming sequence records from large files or writing generators without loading a full object into memory.
• Diagnosing format sniffing, UnrecognizedFormatError, FileFormatError, format-specific parse errors, compression/filehandle caveats, and reader/writer route mismatches.
• Constructing, loading, saving, filtering, merging, and converting SampleMetadata, MetadataColumn, NumericMetadataColumn, and CategoricalMetadataColumn objects.
• Validating sample/feature metadata ID headers, directives, duplicate IDs/columns, column types, and missing-data schemes.
• Creating or attaching Interval and IntervalMetadata objects, especially for GFF3, GenBank, and EMBL feature annotations.

Start With

• references/format-reference.md for supported formats, registry patterns, read/write routes, streaming, sniffing, and custom-format extension guidance.
• references/metadata-reference.md for SampleMetadata, metadata columns, missing schemes, dataframe conversion, filtering, merging, ID-header rules, and interval metadata.
• references/troubleshooting.md for compact diagnosis and repair patterns covering the common IO and metadata failures.
• scripts/io_metadata_smoke.py for a deterministic public-API smoke check that reads/writes a Newick tree, streams FASTA records, builds sample metadata, and prints JSON.

Boundaries

• For sequence construction, sequence validation, TabularMSA manipulation, alignment, translation, or per-sequence metadata after records are read, use ../sequences-alignment/SKILL.md.
• For TreeNode editing, rooting, comparison, or phylogenetic algorithms after Newick parsing, use ../trees-phylogeny/SKILL.md.
• For diversity metrics, BIOM-like count table analysis, distance-matrix statistics, or ordination interpretation after files are read, use ../diversity-tables/SKILL.md and ../statistics-ordination/SKILL.md when present.
• Keep this sub-skill focused on serialization, registry route selection, metadata validation, metadata object transformations, and interval annotation attachment.
• Do not depend on source repository examples, fixtures, or docs at runtime; the references and smoke script here are self-contained.

Quick Sanity Check

From any working directory with scikit-bio and its runtime dependencies installed, run:

python /path/to/skills/scikit-bio/sub-skills/io-metadata/scripts/io_metadata_smoke.py

The script also supports --help and --indent. It imports only public scikit-bio APIs, uses StringIO inputs, catches common import/format/metadata exceptions, and prints compact JSON on success.