obitools4/autodoc/docmd/pkg/obilua/obitaxon.md

Lua Bindings for Taxonomic Operations in obilua

This Go package provides a set of Lua-accessible functions for manipulating taxonomic data through the obitax library. It exposes a custom Lua type, "Taxon", enabling users to create and query hierarchical taxonomic entities directly from Lua scripts.

Core Features

• Taxon Type Registration:
  A new userdata type Taxon is registered in the Lua state, with methods exposed via a metatable and "__index" delegation.

• Taxon Creation:
  The Taxon.new(taxid, parent, sname, rank[, isroot]) constructor creates a new taxon node in the taxonomy. It supports optional root flag and raises errors on failure.

• Scientific Name Management:
  taxon:scientific_name([newname]) gets or sets the scientific name of a taxon.

• Taxonomic Navigation:
  Methods allow upward/downward traversal:

  • taxon:parent() → returns the parent taxon (or nil if root).
  • taxon:species(), .genus(), .family() → return the nearest taxon at that rank.
  • taxon:taxon_at_rank(rank) → returns the ancestor taxon at a given rank (e.g., "order", "class").

• String Representation:
  taxon:string() returns a human-readable string (typically the scientific name).

• Integration with Taxonomy Context:
  All operations assume an active taxonomy context (enforced via checkTaxonomy), and taxon instances are wrapped as Lua userdata with proper type checking.

Use Case

Ideal for scripting biodiversity pipelines (e.g., in OBITools), where users need to dynamically inspect or build taxonomies during sequence annotation, filtering, or reporting.