BioMetaHarmonizer Documentation

BioMetaHarmonizer is a universal Python library and command-line tool for fetching, harmonizing, and standardizing NCBI BioSample metadata at scale. It resolves both BioSample accessions (SAMN/SAME/SAMD) and assembly accessions (GCF_/GCA_) to a fixed 51-column output schema, parses collection dates to ISO 8601 format, resolves geographic locations to ISO 3166-1 country codes, classifies isolation sources into One Health categories (Human, Animal, Food, Environmental, etc.), and extracts antibiogram drug-susceptibility tables from NCBI Pathogen records. The tool is aimed at computational biologists and epidemiologists working with large-scale genomic metadata from public repositories.

Getting Started

• Installation
  • Requirements
  • PyPI Installation
  • Development Install from Source
  • NCBI API Key
  • Cache Directory
• Quickstart
  • Example 1 — Minimal: Three BioSample Accessions
  • Example 2 — Large-Scale Run with API Key and Custom Cache
  • Example 3 — Assembly Accession Input
  • Output Columns

User Guide

• Ingestion
  • Overview
  • ID Classification
  • Assembly Accession Resolution
  • esearch + efetch Pipeline for BioSample Accessions
  • Batch Size Constants
  • Rate Limits and Inter-Batch Sleep
  • Retry Logic
  • Null Normalization
  • Suppressed and Invalid Accessions
  • Ingest Summary Log
  • BioProject and Assembly Back-Fill
  • _extra_attributes
• Harmonization
  • Date Engine
  • Geo Engine
  • One Health Classifier
  • Synonym Resolution
  • Null Normalization in Harmonization Engines
• Antibiogram
  • XML Structure
  • Parsed Columns
  • Empty Cell Handling
  • Storage in _extra_attributes
  • Working with Antibiogram Data
  • Commonly Empty Columns
• Output
  • Supported Formats
  • write() Signature
  • write_summary() Signature
  • Expanding _extra_attributes
  • Unnesting the Antibiogram
  • Parquet Output and Downstream Pipelines

Reference

• API Reference
  • biometaharmonizer.ingestion
  • biometaharmonizer.output
  • biometaharmonizer.date_engine
  • biometaharmonizer.geo_engine
  • biometaharmonizer.one_health
  • biometaharmonizer.key_mapper
  • biometaharmonizer.synonyms
• CLI Reference
  • run subcommand
  • Flags
  • CLI Flag ↔ Python API Mapping
  • Complete Invocation Examples
  • Log Output Format
• Schema Reference
  • Output Columns
  • _extra_attributes

Developer Guide

• Developer Scripts
  • build_dictionaries.py
  • build_ncbi_attribute_cache.py
  • generate_summary_report.py
• FAQ
• Changelog
  • v0.6.0 — 2025