mirror of
https://github.com/metabarcoding/obitools4.git
synced 2026-04-30 12:00:39 +00:00
34 lines
1.9 KiB
Markdown
34 lines
1.9 KiB
Markdown
|
# Obilua: Lua-Based Sequence Processing Framework
|
|||
|
|
|
|||
|
|
The `obilua` package provides a bridge between Go and the Lua scripting language for high-performance, parallelizable biological sequence processing. It enables users to write custom analysis logic in Lua while leveraging Go’s concurrency and I/O capabilities.
|
|||
|
|
|
|||
|
|
## Core Features
|
|||
|
|
|
|||
|
|
- **Lua Interpreter Initialization**: `NewInterpreter()` creates an isolated Lua state preloaded with Obi-specific types (`BioSequence`, etc.).
|
|||
|
|
- **Compilation Support**: `Compile()` and `CompileScript()` parse and compile Lua code into efficient function prototypes.
|
|||
|
|
- **Worker Conversion**: `LuaWorker(proto)` wraps a compiled Lua script as a Go-compatible `SeqWorker`, allowing seamless integration into sequence pipelines.
|
|||
|
|
- **Pipeline Integration**:
|
|||
|
|
- `LuaProcessor()` executes a Lua script over an iterator of sequences using configurable parallelism.
|
|||
|
|
- It supports optional `begin()` and `finish()` hook functions in Lua for initialization/cleanup.
|
|||
|
|
- Errors can be handled either by halting (`breakOnError=true`) or logging warnings.
|
|||
|
|
|
|||
|
|
- **Pipeable Interface**:
|
|||
|
|
- `LuaPipe()` and `LuaScriptPipe()` expose Lua scripts as reusable, chainable pipeline stages (`obiiter.Pipeable`), supporting both inline programs and external `.lua` files.
|
|||
|
|
|
|||
|
|
## Lua API Contract
|
|||
|
|
|
|||
|
|
Scripts must define a global `worker(sequence)` function returning either:
|
|||
|
|
- A single `BioSequence`
|
|||
|
|
- A list (`BioSequenceSlice`)
|
|||
|
|
Or return nothing (interpreted as filtered out).
|
|||
|
|
|
|||
|
|
Optionally, `begin()` and `finish()` functions may be defined for lifecycle management.
|
|||
|
|
|
|||
|
|
## Parallel Execution
|
|||
|
|
|
|||
|
|
Uses Go routines to run multiple workers concurrently, with batched input and output management. Default worker count falls back to system-wide parallelism settings if `nworkers ≤ 0`.
|
|||
|
|
|
|||
|
|
## Logging & Error Handling
|
|||
|
|
|
|||
|
|
Uses Logrus for structured logging; fatal errors are logged during setup, while runtime issues respect the `breakOnError` flag.
|