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)
51 lines
2.8 KiB
Markdown
51 lines
2.8 KiB
Markdown
# `obiscript` Package: CLI Scriptable Processing Pipeline
|
||
|
||
The `obiscript` package provides a high-level, modular interface for embedding custom Lua scripts into OBITools4’s sequence processing pipelines. It enables users to define bioinformatics workflows using a lightweight, embeddable scripting language—without sacrificing performance or composability.
|
||
|
||
## Public API Overview
|
||
|
||
### `CLIScriptPipeline() Pipeable`
|
||
Returns a reusable, parallelized pipeline stage that executes user-provided Lua scripts on sequence data. Internally uses `obilua.LuaScriptPipe()` with parallelism enabled (default worker count from `obidefault.ParallelWorkers`). Accepts a script path via the pipeline configuration (typically set through `CLIScriptFilename()` in CLI usage). Designed to integrate seamlessly with other pipeable stages from the `obiiter` framework.
|
||
|
||
### Script Lifecycle Hooks (Exposed via Lua API)
|
||
The embedded ObiLua runtime expects the user script to define three optional functions:
|
||
|
||
- **`begin()`**
|
||
Called once before processing any sequences. Used for initialization (e.g., counters, file handles). Optional.
|
||
|
||
- **`worker(sequence)`**
|
||
Invoked for each input sequence. Provides full access to metadata via `sequence:attribute(name, value?)`, supports in-place modification of tags/IDs, and allows interaction with global context (`obicontext`) for cross-sequence state management.
|
||
|
||
- **`finish()`**
|
||
Called after all sequences have been processed. Typically used to output summary statistics or cleanup resources.
|
||
|
||
### CLI Integration
|
||
|
||
- **`--script FILE`, `-S FILE`**
|
||
Specifies the Lua script to execute. The file must exist and be syntactically valid.
|
||
|
||
- **`--template`**
|
||
Outputs a minimal, self-contained Lua script template to stdout. Includes stubs for `begin()`, `worker(...)`, and `finish()` with inline documentation.
|
||
|
||
- **Shared Options**
|
||
Reuses configuration sets from core OBITools4 modules:
|
||
- `obiconvert.DataIOOptionSet`: input/output format, file paths.
|
||
- `obigrep.SequenceSelectionOptionSet`: filtering/sorting logic.
|
||
|
||
## Semantic Role
|
||
|
||
`obiscript` abstracts the complexity of embedding and orchestrating Lua scripts in a streaming, parallelizable context. It decouples *workflow logic* (Lua) from *pipeline orchestration* (Go), enabling:
|
||
- Rapid prototyping of NGS processing steps.
|
||
- Custom annotation, filtering, assembly, or reporting without recompilation.
|
||
- Consistent CLI behavior across OBITools4 tools.
|
||
|
||
## Use Cases
|
||
|
||
| Scenario | Example |
|
||
|---------|---------|
|
||
| Read filtering + renaming | Filter low-quality reads and prepend sample ID to sequence names |
|
||
| Annotation injection | Add UMI or barcode info from external metadata file per read |
|
||
| Summary reporting | Count reads passing filters, write stats to log at end |
|
||
|
||
> *Designed for extensibility: users extend functionality by writing Lua, not Go.*
|