API Reference

The nf-bids API reference is generated directly from the GroovyDoc docstrings in src/main/groovy, so it always reflects the actual public surface of the plugin.

The full generated reference is available here:

Public API Overview

The tables below summarise every public class by package. Follow the links or browse the generated GroovyDoc for full method signatures and parameter descriptions.

nfneuro.plugin — Plugin core

Class One-line purpose

BidsPlugin

PF4J plugin entry point; discovered and loaded by the Nextflow plugin manager.

BidsExtension

DSL extension point; provides Channel.fromBIDS(), groupTupleBy, joinBy, and combineBy.

BidsFactory

TraceObserverFactory that registers BidsObserver with each pipeline run.

BidsObserver

TraceObserver that emits startup and completion lifecycle messages.

nfneuro.plugin.channel — Channel construction

Class One-line purpose

BidsChannelFactory

Orchestrates the complete Channel.fromBIDS() workflow: validation → parsing → grouping → emission.

BidsHandler

Fluent builder that sequences config loading, parsing, set-handler routing, cross-modal broadcasting, and channel emission.

nfneuro.plugin.channel.operations — Channel operators

Class One-line purpose

GroupTupleByOp

Groups channel items by a closure-extracted key; emits [key, [items]] tuples.

JoinByOp

Inner-joins two channels by closure-extracted keys; emits fused items (no key in payload).

CombineByOp

Produces the cartesian product of left × right items within each matching key group.

nfneuro.plugin.channel.operations.keys — Key infrastructure

Class One-line purpose

KeyExtractor

Validates key-extractor closures and invokes them with consistent error handling; wraps list keys in CompositeKey.

CompositeKey

Immutable wrapper for multi-part (list) grouping keys that provides correct equals / hashCode semantics.

nfneuro.plugin.parser — BIDS parsing

Class One-line purpose

BidsParser

Drives dataset parsing: calls LibBidsShWrapper, parses the resulting TSV, and returns a BidsDataset.

LibBidsShWrapper

Locates and executes the libBIDS.sh bash library; validates paths against a shell-injection deny-list.

BidsValidator

Stub bids-validator integration (deferred to v1.1); provides pre-flight directory / config checks.

nfneuro.plugin.config — Configuration

Class One-line purpose

BidsConfigLoader

Reads and parses bids2nf.yaml via SnakeYAML; delegates to BidsConfigValidator.

BidsConfigValidator

Validates the parsed YAML structure (set types, required groups, loop_over); returns a ValidationResult.

BidsConfigAnalyzer

Scans the config map and returns boolean flags that drive set-handler selection in BidsHandler.

nfneuro.plugin.grouping — Set handlers

Class One-line purpose

BaseSetHandler

Abstract base that groups files by loop-over entities, matches them against config entries, and delegates emission to sub-classes.

PlainSetHandler

Handles plain_set: — emits one {ext: path, …} map per file.

NamedSetHandler

Handles named_set: — assigns files to named groups (e.g. T1w, MTw, PDw) via entity-pattern matching.

SequentialSetHandler

Handles sequential_set: — orders files along one or more sequence entities into flat or nested arrays.

MixedSetHandler

Handles mixed_set: — combines named and sequential dimensions into {groupName: [orderedFiles]}.

nfneuro.plugin.model — Domain model

Class One-line purpose

BidsDataset

Root container: path, name, description, file list, and participant table.

BidsFile

Single BIDS file entry: path, suffix, entity list, sidecar references, and file-system metadata.

BidsEntity

A single BIDS key–value entity (sub-01, ses-BL, …); normalises long/short names and sanitises values.

BidsChannelData

In-flight accumulator used by set handlers; serialises to the [groupingKey, enrichedData] tuple consumed by BidsHandler.

nfneuro.plugin.util — Utilities

Class One-line purpose

BidsLogger

Structured SLF4J logging with context-prefixed messages and an optional withTiming wrapper.

SuffixMapper

Resolves suffix_maps_to aliases so that virtual config keys (e.g. dwi_fullreverse) map to real BIDS suffixes.

BidsEntityUtils

Entity filtering and groupByEntities helper called by BaseSetHandler.

BidsErrorHandler

Context-aware error wrapping (tryWithContext, safeExecute, validateWithContext) and typed BIDS exception sub-classes.

BidsCsvParser

Parses the TSV produced by libBIDSsh_parse_bids_to_table into BidsFile objects.

Key entry points

The table below shows the exact signatures of the four user-facing DSL entry points, cross-verified against the source in BidsExtension.groovy.

Entry point Signature (as called from a Nextflow workflow)

Channel.fromBIDS

 
Channel.fromBIDS(
    String bidsDir,
    String configPath = null,
    Map    options    = [:]   // libbids_sh, flatten_output, unpack_json_sidecar, bids_validation
)

Returns a DataflowWriteChannel. Each emitted item is a flat map [meta: [subject: …, session: …, …], T1w: [nii: Path, json: Path], …] (default in 0.1.0-beta.9+) or a [groupingKey, enrichedData] tuple when options.flatten_output = false. With options.unpack_json_sidecar = true, .json sidecar fields are emitted as parsed maps.

groupTupleBy

 
channel.groupTupleBy(
    Closure keyExtractor,
    Map     opts = [:]        // size, sort, remainder
)

Emits [key, [items]] tuples. Items with a null key are silently dropped. When opts.remainder is true (default) all partial groups are flushed on channel completion.

joinBy

 
channel.joinBy(
    DataflowReadChannel right,
    Closure             keyExtractor,
    Map                 opts           // remainder (outer join)
)

channel.joinBy(
    DataflowReadChannel right,
    Closure             leftKeyExtractor,
    Closure             rightKeyExtractor = null,  // defaults to leftKeyExtractor
    Map                 opts              = [:]    // remainder (outer join)
)

Inner join by default; set opts.remainder = true for an outer join that emits unmatched items with null partner. The extractor closures are invoked with one item from each side independently and must return the association key. Emits fused items (key omitted).

combineBy

 
channel.combineBy(rightChannel, { it.id })

channel.combineBy(
    DataflowReadChannel rightChannel,
    Closure             leftKeyExtractor,
    Closure             rightKeyExtractor,
    Map                 opts = [:]
)

Produces the full cartesian product of left × right items within each matched key group. The key-extractor closures are invoked with one item at a time from their respective channels. Unmatched keys are silently dropped (inner semantics). Emits fused items (key omitted).

See Channel Operators for worked examples and Source model for the data structures flowing through these operators.

Contributing to the API reference

Any change to the public API in src/main/groovy must add or update the Groovydoc comment so that the generated reference does not drift from the implementation. Specifically:

  • New public classes must have a class-level /** … */ block summarising their responsibility.

  • New public methods must document all parameters (@param), the return value (@return), and any thrown exceptions (@throws) where applicable.

  • Parameter names in @param tags must match the actual parameter names in the source; mismatches break the GroovyDoc generation.

  • Methods or classes that are intentionally excluded from the public surface (e.g. internal helpers) must be private or protected so GroovyDoc omits them automatically.

  • The ./gradlew groovydoc task is run at the review gate; the build must complete without warnings before a PR is merged.