BIDSMAPPER(1)

✨ BIDSMAPPER ✨

okay bestie, sit down, hydrate, because this one is literally the glow-up your messy raw data folder has been waiting for 💅 (it's a page from the Generated Python Manual, and the command is just bidsmapper — yes, all lowercase, we're chill here)

---

🌸 SYNOPSIS 🌸

bidsmapper [-h] [-b NAME] [-t NAME] [-p NAME [NAME ...]] [-n PREFIX] [-m PREFIX] [-u PATTERN] [-s] [-a] [-f] [--no-update] sourcefolder
       bidsfolder

---

🦋 DESCRIPTION 🦋

so here's the tea ☕ — the bidsmapper scans your source data repository to figure out what different data types you've got, by matching them against the run-items in the template bidsmap. the moment it finds a match, it makes a mapping over to BIDS output data types and drops that run-item into the study bidsmap. then you get to peek at and edit those generated bids-mappings however you like with the bidseditor (which launches automatically, she's self-inviting like that 🙈).

re-run the bidsmapper every time something changes in your data acquisition protocol, and then edit the new data type to your needs — your existing bidsmap gets reused, no cap 🫶

also, the bidsmapper uses plugins, which live in the 'Options' section of the bidsmap, to do its thing and handle all the different data modalities and formats. it's giving "delegation queen" 👑

sourcefolder

The study root folder containing the raw source data folders

bidsfolder

The destination folder with the (future) bids data and the bidsfolder/code/bidscoin/bidsmap.yaml output file

---

💖 OPTIONS 💖

• -b NAME, --bidsmap NAME — the study bidsmap file holding the mapping heuristics. if the bidsmap filename is just the base name (so, no / anywhere in it), it's assumed to be chillin' in the current directory or in bidsfolder/code/bidscoin. Default: bidsmap.yaml
• -t NAME, --template NAME — the bidsmap template file with the default heuristics (your institute might have hooked you up with this one 🎀). if the bidsmap filename is just the base name (again, no / in the name), it's assumed to live in the bidscoin config folder. Default: bidsmap_dccn
• -p NAME [NAME ...], --plugins NAME [NAME ...] — the list of plugins to use. Default: the plugin list of the study/template bidsmap
• -n PREFIX, --subprefix PREFIX — the prefix that's common to all your source subject-folders (like, 'Pt' is the subprefix if your subject folders are named 'Pt018', 'Pt019', ...). use '*' when your subject folders don't have a prefix at all. Default: the value of the study/template bidsmap, e.g. 'sub-'
• -m PREFIX, --sesprefix PREFIX — the prefix common to all your source session-folders (so 'M_' is the subprefix if your session folders are named 'M_pre', 'M_post', ...). use '*' when your session folders have no prefix. Default: the value of the study/template bidsmap, e.g. 'ses-'
• -u PATTERN, --unzip PATTERN — a wildcard pattern to unpack tarball/zip-files in the sub/ses sourcefolder that need to be unzipped (into a tempdir, bestie) so the data is actually readable. Default: the value of the study/template bidsmap
• -s, --store — store newly discovered data samples in the bidsfolder/code/provenance folder (super useful for editing stuff like zipped or DICOMDIR datasets 🍓)
• -a, --automated — save the automatically generated bidsmap to disk, and skip the whole interactive tweaking-with-the-bidseditor moment. zero chatting, all business 💀
• -f, --force — throw out the previously saved bidsmap and log file instead of reusing them. reach for this one when you want a fresh start ✨
• --no-update — do not update any sub-/ses-prefixes in, or prepend the sourcefolder name to, the <<filepath:regex>> expression that extracts the subject/session labels. this is normally done to make the extraction more robust, but it could cause problems for certain use cases 👀

---

🌈 COMMENTS 🌈

examples, because seeing it hits different:

bidsmapper myproject/raw myproject/bids
bidsmapper myproject/raw myproject/bids -t bidsmap_custom  # Uses a template bidsmap of choice
bidsmapper myproject/raw myproject/bids -p nibabel2bids    # Uses a plugin of choice
bidsmapper myproject/raw myproject/bids -n patient- -m '*' # Handles DICOMDIR datasets
bidsmapper myproject/raw myproject/bids -u '*.tar.gz'      # Unzip tarball source files

---

👑 AUTHOR 👑

Marcel Zwiers <m.zwiers@donders.ru.nl>

---

and that's the whole page, bestie 🧚 this was bidscoin version 4.6.2, dated 2025-11-06, and honestly? iconic. go map some bids, you absolute main character 💜⭐