菜单
BIDS neuroimaging dataset structure and the bundled libBIDS.sh parser: entities, long/short names, TSV table contract, bidsignore behavior, JSON sidecars. Use when working on parsing, entity handling, or writing BIDS test data or configs.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | bids-domain-libbids |
| description | BIDS neuroimaging dataset structure and the bundled libBIDS.sh parser: entities, long/short names, TSV table contract, bidsignore behavior, JSON sidecars. Use when working on parsing, entity handling, or writing BIDS test data or configs. |
BIDS filenames are entity-value chains followed by suffix + extension:
sub-01_ses-02_acq-highres_dir-AP_dwi.nii.gz
└─ entities ────────────────┘ └─suffix┘└ext┘
Files live under <root>/<subject>/<session>/<datatype>/ (e.g. anat/, dwi/, fmap/, eeg/).
JSON sidecars (same basename, .json extension) carry acquisition metadata.
The plugin and bids2nf YAML configs always use the long (name) form. The short key form appears only in filenames.
| filename token (key) | table column / config name |
|---|---|
sub | subject |
ses | session |
acq | acquisition |
rec | reconstruction |
dir | direction |
inv | inversion |
mt | mtransfer |
part | part |
task, run, echo, flip, chunk, split | same |
tpl | template |
cohort, atlas, scale | same (verify in libBIDS.sh/AGENTS.md) |
Passing a short key (e.g. sub) where a long name is expected silently fails to match.
libBIDS.sh/ is a git submodule — never modify files inside it.
The library is a single sourced Bash file; no build step required.
Core entry point: libBIDSsh_parse_bids_to_table — BIDS directory → TSV table.
derivatives | datatype | entity names (long form) | suffix | extension | path | (optional) json_path
| Function | Purpose |
|---|---|
libBIDSsh_parse_bids_to_table | Parse BIDS dir → TSV; honors .bidsignore by default |
libBIDSsh_table_filter | AWK-based filter: columns, rows, drop-NA, invert |
libBIDSsh_drop_na_columns | Remove all-NA columns |
libBIDSsh_apply_bidsignore | Drop rows excluded by .bidsignore |
libBIDSsh_extension_json_rows_to_column_json_path | Fold JSON sidecar rows → json_path column |
libBIDSsh_table_column_to_array | TSV column → Bash array |
libBIDSsh_table_iterator | Iterate rows into associative array, with sorting |
libBIDSsh_json_to_associative_array | Parse JSON file → Bash associative array |
libBIDSsh_parse_bids_to_table.--no-bidsignore, --no-default-ignores.use_bidsignore and use_default_ignores options (passed to BidsParser.parseToDataset).Exact filename only — no BIDS inheritance resolution.
LibBidsShWrapper searches a priority list: plugin lib/, submodule path, system install. Override explicitly via the libbids_sh option on Channel.fromBIDS.
Extend supported entities via libBIDS.sh/custom/custom_entities.json.tpl (requires jq). See libBIDS.sh/AGENTS.md.
See libBIDS.sh/AGENTS.md and libBIDS.sh/README.md for the authoritative API reference.
See documentation/modules/ROOT/pages/concepts/bids-parsing.adoc for how the plugin wraps the library.
LibBidsShWrapper searches in this order (first found wins):
lib/libBIDS.sh inside the plugin JAR (standard plugin distribution)./lib/libBIDS.sh (relative to working directory)libBIDS.sh/libBIDS.sh (git submodule in current directory)../libBIDS.sh/libBIDS.sh (one level up)../../libBIDS.sh/libBIDS.sh (two levels up)../../../libBIDS.sh/libBIDS.sh (three levels up — for test/validation/ subdirectory)/usr/local/bin/libBIDS.sh (system-wide install)~/.local/bin/libBIDS.sh (user-local install)Override all steps: set libbids_sh option in Channel.fromBIDS(..., [libbids_sh: '/path/to/libBIDS.sh']).
Before calling the subprocess, bidsDir and all user-supplied paths are validated against a shell-metacharacter blocklist.
Blocked characters: ;, &, |, $, `, (, ), <, >, ", ', \, and newlines.
Validation failure throws IllegalArgumentException before any shell command runs.
The parsing pipeline populates these objects (used by all set handlers):
BidsFile — relative path, suffix, extension, List<BidsEntity> entitiesBidsEntity — name+value pair (e.g. subject=sub-01); normalizeName() maps short↔longBidsDataset — root path, dataset name, List<BidsFile> files, List<Map> participants (from participants.tsv)BidsChannelData — internal carrier from set handlers; wraps grouped file refs + bidsParentDir; toChannelTuple() serializes to [groupingKey, enrichedData]nf-bids closure-based channel operators groupTupleBy, joinBy, combineBy: signatures, return formats, KeyExtractor/CompositeKey internals, design rationale. Use when using, modifying, or extending these operators.
Debugging playbook for nf-bids: known gotcha catalogue, root-cause methodology for grouping and matching bugs, logging, multi-candidate matching diagnosis. Use when channel output is wrong, groups are missing, files match the wrong config, or changes seem to have no effect.
Nextflow plugin development mechanics for nf-bids. Use when adding operators or factory methods, registering extension points, debugging plugin loading, or when code changes seem to have no effect at runtime.
nf-bids plugin architecture: runtime flow of Channel.fromBIDS, set handler routing, suffix mapping design, flat output shaping, cross-modal broadcasting. Use when navigating the codebase, tracing data flow, or modifying handlers/output structure.