mirror of
https://github.com/metabarcoding/obitools4.git
synced 2026-04-30 12:00:39 +00:00
Eric Coissac
8c7017a99d
- Update obioptions.Version from "Release 4.4.29" to "/v/ Release v5" - Update version.txt from 4.29 → .30 (automated by Makefile)
31 lines
1.6 KiB
Markdown
31 lines
1.6 KiB
Markdown
# 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.
|