Should this repo get 2nd life as bids-cmdline or smth like that?

[yarikoptic]

For a while I felt the need, and at some point expressed it (but forgot where), to get a command line (or may be eventually some GUI) utility to manipulate a BIDS dataset. Quite often due to inherent redundancy, some trivial operations are not that trivial. E.g.

note: the list has being edited (last in March 2026) to reflect discovered needs

List of commands/needs with priorities

• migrate (need: high): establish migration path(s) to address deprecations and potential breaking changes for BIDS 2.0
  • prototype: based on BIDS-2.0 bids-specification#1775, copilot extracted into [SCHEMA] Add migrate command to adopt standardized BIDS conventions bids-specification#2282 within bst
• renaming a subject (need: medium): (codename subject-rename for now) requires
  • renaming sub- directory
    • possibly also under sourcedata/ (and who knows -- may be .heudiconv/)
  • renaming every file under that directory since they all carry sub- prefix
    • possibly also under sourcedata/
  • fixing up _scans file as well since that is where those files are listed as well
• remove a subject[/session] (need: low)
• remove a run (need: low) while shifting all subsequent run indexes
• rename or fix a filename (need: high) (just rename) - could be used by subject-rename -- since a file might have a side car file, and then listed in _scans, might come handy
  • some non-BIDS compliant file, e.g. having spurious suffix like a _test
  • prototypes:
    • spacetop dataset (openneuro ds005256, rename_file)
• renaming a session (need: medium) (session-rename)
• moving into a session (need: medium) (session-rename '' session) -- whenever dataset (or a specific subject?) was collected without any session'ing, and then multiple sessions decided to be taken
• merge datasets (need: low) - implementation might relate to Moving into a session. Take two datasets (possibly without sessions) and then merge them either by
  • just combining subjects (and failing if conflicting)
  • placing each one into a (specified) session
  • using subjects (re)mapping file
• bubble-up/condense/organize metadata (need: medium) - move common (meta)data up in the hierarchy to make BIDS dataset easier for users to find at higher level, and not duplicated underneath (
  • inheritance principle, bids, 1.10.2 (IIRC), 2: summarization)
  • "prototype": @Lestropie initiated https://github.com/Lestropie/IP-freely (TODO: review)
  • could have modes to
    • aggregate -- propagate up common metadata
    • segregate -- propagate down into the leafs
    • one-copy -- combined with either of the above to remove either at the leafs or at the roots

Various related ideas

Testing

• we have outstanding and well maintained https://github.com/bids-standard/bids-examples/ of valid datasets of different kinds. We must make as much use of it as possible, e.g.
  • for each command sweep through datasets, perform basic operation(s) they implement while verifying that valid (before) datasets remain valid after the operation!

Extra features

• git/git-annex awareness (need: medium):
  • Ideally the tool should be aware of git and/or git-annex, i.e. that files might be under VCS and then should use corresponding VCS functions.
  • If for the function we need content of the files it could either be obtained (datalad get) or accessed transparently remotely (through fsspec + info from annex. See https://github.com/datalad/datalad-fuse/ providing support interfaces

Originally I thought to propose this development within pybids, but per-se such utility (bids) does not have to (although likely will) be implemented using pybids. Some functionalities, which operate on BIDS-compliant datasets, could be achieved via re-layouting using pybids, but then it should also become capable to capture those under .heudiconv and sourcedata/ which is not strongly "prescribed" in BIDS (there is only a recommendation to follow BIDS naming there as well)

[chrisgorgo]

That would be a great tool. Happy to contribute!

[tyarkoni]

I think this kind of functionality could quite comfortably live inside of pybids. Note that per discussion in bids-standard/pybids#63, it's now possible to re-map entire file structures (both within BIDS and to/from other structures) in a pretty elegant way via grabbids/grabbit. The only thing we're missing is a set of output patterns that define all the valid BIDS paths.

This doesn't preclude a utility of the kind you're proposing, of course. From a UI standpoint, users don't want to have to muck around with project-wide remapping, they just want to call session_rename or something. But implementation-wise, I think it would be very nice from an abstraction and maintainability standpoint to implement these kinds of tools as wrappers around the existing grabbids/grabbit functionality.

[yarikoptic]

YES, definitely pybids/grabbids/grabbit should be used as much as possible!
Although it sounds only logical, and makes many things easier, and precedents exist (nibabel providing nib-* utilites), I didn't dare to suggest it to live inside pybids, to not mud the purity of it:

• pybids might have its own dev/release cycle
• some utils might come from different languages (bash?)
• ideally it should be just a "bids" utility, but then "who is pybids to provide bin/bids"? ;)

but yeah, for a quick start could also be done within pybids -- so "to be decided" I guess ;)

[yarikoptic]

A note for a bash "born as one liner" monster for renaming a file I came up with: https://github.com/spatialtopology/ds005256/blob/master/code/rename_file which could give ideas on what to not forget about while renaming a file within a subject (not even across subjects etc)

[yarikoptic]

I will consider this superseded by

• Initial design + implementation done via spec-kit + claude code #4