The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.
Brain Imaging Data Structure (BIDS) is a standard for
organizing neuroimaging and behavioral data (see https://bids.neuroimaging.io/index.html).
The goal of package bidsr is to provide comprehensive
tools to query and manipulate ‘BIDS’ data files.
This vignette aims to demonstrate high-level tools to query a ‘BIDS’ project. The code requires executing a built-in command to download ‘BIDS’ example data-sets. Please copy-paste-run the following R commands:
BIDS projectLet’s inspect the project ds000117 from the official
BIDS example repository:
project_path <- file.path(example_root, "ds000117")
project <- bids_project(path = project_path)
print(project)
#> <ds000117>[BIDSProject] at:
#> /Users/dipterix/Library/Caches/org.R-project.R/R/bidsr/bids-examples/bids-examples-master/ds000117
#> - raw-data path: .
#> - source-data path: sourcedata
#> - derivative path: derivatives
#> +- Descriptions: ---------------------------------------------------------------
#> | This dataset was obtained from the OpenNeuro project
#> | (https://www.openneuro.org). Accession #: ds000117
#> |
#> | The same dataset is also available here:
#> | ftp://ftp.mrc-cbu.cam.ac.uk/personal/rik.henson/wakemandg_hensonrn/, but in
#> | a non-BIDS format (which may be easier to download by subject rather than
#> | by modality)
#> |
#> | Note that it is a subset of the data available on OpenfMRI
#> | (http://www.openfmri.org; Accession #: ds000117).
#> |
#> | Description: Multi-subject, multi-modal (sMRI+fMRI+MEG+EEG) neuroimaging
#> | dataset on face processing
#> |
#> | Please cite the following reference if you use these data:
#> |
#> | Wakeman, D.G. & Henson, R.N. (2015). A multi-subject, multi-modal human
#> | neuroimaging dataset. Sci. Data 2:150001 doi: 10.1038/sdata.2015.1
#> |
#> | The data have been used in several publications including, for example:
#> |
#> | Henson, R.N., Abdulrahman, H., Flandin, G. & Litvak, V. (2019). Multimodal
#> | integration of M/EEG and f/MRI data in SPM12. Frontiers in Neuroscience,
#> | Methods, 13, 300.
#> |
#> | Henson, R.N., Wakeman, D.G., Litvak, V. & Friston, K.J. (2011). A
#> | Parametric Empirical Bayesian framework for the EEG/MEG inverse problem:
#> | generative models for multisubject and multimodal integration. Frontiers in
#> | Human Neuroscience, 5, 76, 1-16.
#> |
#> | Chapter 42 of the SPM12 manual
#> | (http://www.fil.ion.ucl.ac.uk/spm/doc/manual.pdf)
#> |
#> | (see
#> | ftp://ftp.mrc-cbu.cam.ac.uk/personal/rik.henson/wakemandg_hensonrn/Publications
#> | for full list), as well as the BioMag2010 data competition and the Kaggle
#> | competition: https://www.kaggle.com/c/decoding-the-human-brain)
#> |
#> | ==================================================================================
#> |
#> | func/ ----- Unlike in v1-v3 of this dataset, the first two (dummy) volumes
#> | have now been removed (as stated in *.json), so event onset times correctly
#> | refer to t=0 at start of third volume
#> |
#> | Note that, owing to scanner error, Subject 10 only has 170 volumes in last
#> | run (Run 9) (hence the BIDS warning of some onsets in events.tsv file being
#> | later than the data)
#> |
#> | meg/ ---- Three anatomical fiducials were digitized for aligning the MEG
#> | with the MRI: the nasion (lowest depression between the eyes) and the left
#> | and right ears (lowest depression between the tragus and the helix, above
#> | the tragus). This procedure is illustrated here:
#> | http://neuroimage.usc.edu/brainstorm/CoordinateSystems#Subject_Coordinate_System_.28SCS_.2F_CTF.29
#> | and in task-facerecognition_fidinfo.pdf
#> |
#> | The following triggers are included in the .fif files and are also used in
#> | the “trigger” column of the meg and bold events files:
#> |
#> | Trigger Label Simplified Label
#> |
#> | 5 Initial Famous Face FAMOUS 6 Immediate Repeat Famous Face FAMOUS 7
#> | Delayed Repeat Famous Face FAMOUS 13 Initial Unfamiliar Face UNFAMILIAR 14
#> | Immediate Repeat Unfamiliar Face UNFAMILIAR 15 Delayed Repeat Unfamiliar
#> | Face UNFAMILIAR 17 Initial Scrambled Face SCRAMBLED 18 Immediate Repeat
#> | Scrambled Face SCRAMBLED 19 Delayed Repeat Scrambled Face SCRAMBLED
#> |
#> | stimuli/meg/ ------------ The .bmp files correspond to those described in
#> | the text. There are 6 additional images in this directory, which were used
#> | in the practice experiment to familiarize participants with the task (hence
#> | some more BIDS validator warnings)
#> |
#> | stimuli/mri/ ------------ The .bmp files correspond to those described in
#> | the text.
#> |
#> | Defacing -------- Defacing of MPRAGE T1 images was performed by the
#> | submitter. A subset of subjects have given consent for non-defaced versions
#> | to be shared - in which case, please contact rik.henson@mrc-cbu.cam.ac.uk.
#> |
#> | Quality Control --------------- Mriqc was run on the dataset. Results are
#> | located in derivatives/mriqc. Learn more about it here:
#> | https://mriqc.readthedocs.io/en/latest/
#> |
#> | Known Issues ------------ N/A
#> |
#> | Relationship of Subject Numbering relative to other versions of Dataset
#> | ------------
#> |
#> | There are multiple versions of the dataset available on the web (see notes
#> | above), and these entailed a renumbering of the subjects for various
#> | reasons. Here are all the versions and how to match subjects between them
#> | (plus some rationale and history for different versions):
#> |
#> | 1. Original Paper (N=19): Wakeman & Henson (2015): doi:10.1038/sdata.2015.1
#> | Number refers to order that tested (and some, eg 4, 7, 13 etc were excluded
#> | for not completing both MRI and MEG sessions)
#> |
#> | 2. openfMRI, renumbered from paper:
#> | http://openfmri.org/s3-browser/?prefix=ds000117/ds000117_R0.1.1/uncompressed/
#> | Numbers 1-19 just made contiguous
#> |
#> | 3. FTP subset of N=16: ftp:
#> | ftp://ftp.mrc-cbu.cam.ac.uk/personal/rik.henson/wakemandg_hensonrn/ This
#> | set was used for SPM Courses Designed to illustrate multimodal integration,
#> | so wanted good MRI+MEG+EEG data for all subjects Removed original
#> | subject_01 and subject_06 because bad EEG data; subject_19 because poor EEG
#> | and fMRI data (And renumbered subject_14 for some reason).
#> |
#> | 4. Current OpenNeuro subset N=16 used for (BIDS):
#> | https://openneuro.org/datasets/ds000117 OpenNeuro was rebranding of
#> | openfMRI, and enforced BIDS format Since this version designed to
#> | illustrate multi-modal BIDS, kept same numbering as FTP
#> |
#> | W&H2015 openfMRI FTP openNeuro ======== ====== === ======= subject_01
#> | sub001 subject_02 sub002 Sub01 sub-01 subject_03 sub003 Sub02 sub-02
#> | subject_05 sub004 Sub03 sub-03 subject_06 sub005 subject_08 sub006 Sub05
#> | sub-05 subject_09 sub007 Sub06 sub-06 subject_10 sub008 Sub07 sub-07
#> | subject_11 sub009 Sub08 sub-08 subject_12 sub010 Sub09 sub-09 subject_14
#> | sub011 Sub04 sub-04 subject_15 sub012 Sub10 sub-10 subject_16 sub013 Sub11
#> | sub-11 subject_17 sub014 Sub12 sub-12 subject_18 sub015 Sub13 sub-13
#> | subject_19 sub016 subject_23 sub017 Sub14 sub-14 subject_24 sub018 Sub15
#> | sub-15 subject_25 sub019 Sub16 sub-16dataset_description.jsonThe top-level data description can be parsed via
To obtain the values, use $ or @ operator
(same as . in Python):
participants.tsvFile participants.tsv is a top-level tabular that lists
all the subjects. This file can be queried via method
get_participants:
Alternatively, we can read any tsv file with
as_bids_tabular
participant_path <- file.path(project, "participants.tsv")
as_bids_tabular(participant_path, cls = BIDSTabularParticipants)
#> <BIDS Tabular>[BIDSTabular]
#> $meta:
#> {
#> "age": {
#> "LongName": "age",
#> "Units": "year",
#> "TermURL": "http://purl.obolibrary.org/obo/PATO_0000011"
#> },
#> "sex": {
#> "LongName": "sex",
#> "Description": "String value indicating phenotypical sex.",
#> "Levels": {
#> "F": {
#> "Description": "Female",
#> "TermURL": "http://purl.obolibrary.org/obo/PATO_0000383"
#> },
#> "M": {
#> "Description": "Male",
#> "TermURL": "http://purl.obolibrary.org/obo/PATO_0000384"
#> }
#> },
#> "TermURL": "http://purl.obolibrary.org/obo/PATO_0001894"
#> },
#> "first_ses": {
#> "LongName": "first session",
#> "Description": "Indicates which session was the first session for this subject.",
#> "Levels": {
#> "meg": {
#> "Description": "meg was the first session"
#> },
#> "mri": {
#> "Description": "mri was the first session"
#> }
#> }
#> }
#> }
#>
#> $content:
#> participant_id age sex first_ses
#> <char> <int> <char> <char>
#> 1: sub-01 31 M meg
#> 2: sub-02 25 M meg
#> 3: sub-03 30 M meg
#> 4: sub-04 26 F meg
#> 5: sub-05 23 F meg
#> ---
#> 13: sub-13 25 F meg
#> 14: sub-14 24 F mri
#> 15: sub-15 30 M mri
#> 16: sub-16 25 M mri
#> 17: sub-emptyroom NA <NA> <NA>BIDS subjectGiven a project path or instance, a BIDS subject can be
instantiated via
subject <- bids_subject(
project = project,
subject_code = "sub-06"
)
print(subject)
#> <BIDSSubject> `sub-06` (project `ds000117`)All BIDS subjects have entity key sub- that
marks the subject code, for example, sub-06 means subject
06, hence the entity key sub- can be omitted,
and bidsr accepts input such as
subject_code = "06".
If project is not instantiated, its path is also
acceptable, check this alternative:
BIDS mainly focuses on regulating the raw data, however,
it also supports formatting source data and derivatives. The
corresponding paths can be queried via resolve_bids_path
method. To resolve the root path for raw/source data,
# resolve subject path (raw data by default)
resolve_bids_path(subject)
#> /Users/dipterix/Library/Caches/org.R-project.R/R/bidsr/bids-examples/bids-examples-master/ds000117/./sub-06
resolve_bids_path(subject, storage = "source")
#> /Users/dipterix/Library/Caches/org.R-project.R/R/bidsr/bids-examples/bids-examples-master/ds000117/sourcedata/sub-06For derivatives, please specify the derivative names, for example:
The official BIDS and its extensions support various of
data types, such as anat, func,
meg, eeg, ieeg, etc.
To query the data files by type, use query_bids method.
The following example shows all the anat data path, and its
potential meta files
query_bids(subject, "anat")
#> parsed data_type suffix extension sub ses acq run echo
#> <AsIs> <char> <char> <char> <char> <char> <char> <int> <int>
#> 1: sub-06/s.... anat T1w nii.gz 06 mri mprage NA NA
#> 2: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 1
#> 3: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 2
#> 4: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 3
#> 5: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 4
#> 6: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 5
#> 7: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 6
#> 8: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 7
#> 9: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 1
#> 10: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 2
#> 11: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 3
#> 12: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 4
#> 13: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 5
#> 14: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 6
#> 15: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 7To use fine-grained search parameters, replace 'anat'
with a list of search parameters.
query_bids(subject, list(
# dataset to filter, choices are raw, source, or derivative
storage = "raw",
# include JSON sidecars; default is `FALSE`
sidecars = FALSE,
# set to `NULL` to include all data types
data_types = "anat",
# filter all suffixes
suffixes = NULL
))
#> parsed data_type suffix extension sub ses acq run echo
#> <AsIs> <char> <char> <char> <char> <char> <char> <int> <int>
#> 1: sub-06/s.... anat T1w nii.gz 06 mri mprage NA NA
#> 2: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 1
#> 3: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 2
#> 4: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 3
#> 5: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 4
#> 6: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 5
#> 7: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 6
#> 8: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 1 7
#> 9: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 1
#> 10: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 2
#> 11: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 3
#> 12: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 4
#> 13: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 5
#> 14: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 6
#> 15: sub-06/s.... anat FLASH nii.gz 06 mri <NA> 2 7Here is another example that filters derivative files that are
BIDS compliant.
query_bids(subject, list(
# filter derivatives
storage = "derivative",
# filter `derivatives/meg_derivatives` folder
prefix = "meg_derivatives",
# include JSON sidecars
sidecars = TRUE,
# set to `NULL` to include all data types
data_types = NULL,
# only keep files with *_meg/log.* suffixes
suffixes = c("meg", "log")
))
#> parsed data_type suffix extension sub ses task
#> <AsIs> <char> <char> <char> <char> <char> <char>
#> 1: derivati.... _root meg json 06 meg facerecognition
#> 2: derivati.... meg meg json 06 meg facerecognition
#> 3: derivati.... meg log txt 06 meg facerecognition
#> 4: derivati.... meg meg fif 06 meg facerecognition
#> 5: derivati.... meg log txt 06 meg facerecognition
#> 6: derivati.... meg meg fif 06 meg facerecognition
#> 7: derivati.... meg log txt 06 meg facerecognition
#> 8: derivati.... meg meg fif 06 meg facerecognition
#> 9: derivati.... meg log txt 06 meg facerecognition
#> 10: derivati.... meg meg fif 06 meg facerecognition
#> 11: derivati.... meg log txt 06 meg facerecognition
#> 12: derivati.... meg meg fif 06 meg facerecognition
#> 13: derivati.... meg log txt 06 meg facerecognition
#> 14: derivati.... meg meg fif 06 meg facerecognition
#> proc run
#> <char> <int>
#> 1: sss NA
#> 2: sss NA
#> 3: sss 1
#> 4: sss 1
#> 5: sss 2
#> 6: sss 2
#> 7: sss 3
#> 8: sss 3
#> 9: sss 4
#> 10: sss 4
#> 11: sss 5
#> 12: sss 5
#> 13: sss 6
#> 14: sss 6BIDS entityHere is an example of filtering func event files with
BIDS entity run=02 The first column contains a
list of file instances. Here’s an example to read the ACPC
electrode coordinates:
filter_result <- query_bids(subject, list(
storage = "raw",
sidecars = FALSE,
data_types = "func",
suffixes = "events",
# use R "formula" to filter entities
entity_filters = list(
# entity_key ~ expression returning TRUE/FALSE
# When filtering the entities, `entity_key` will be
# replaced with its value
run ~ as.integer(run) == 2
)
))
filter_result
#> parsed data_type suffix extension sub ses task run
#> <AsIs> <char> <char> <char> <char> <char> <char> <int>
#> 1: sub-06/s.... func events tsv 06 mri facerecognition 2The first column "filter_result" is the parsed file
object with entity information:
event_file <- filter_result$parsed[[1]]
event_file
#> sub-06/ses-mri/func/sub-06_ses-mri_task-facerecognition_run-02_events.tsvTo get entity values, use get_bids_entity:
If supported by schema, the BIDS entity rules for the
file can be queried via get_bids_entity_rules(event_file)
method
Object event_file is relative to the project root, hence
can be read by joining the project root path
event_path <- file.path(project, event_file)
# or
event_path <- resolve_bids_path(project, format(event_file))
as_bids_tabular(event_path)
#> <BIDS Tabular>[BIDSTabular]
#> $meta:
#> {}
#>
#> $content:
#> onset duration circle_duration stim_type trigger button_pushed
#> <num> <num> <num> <char> <int> <int>
#> 1: 0.000 0.897 0.596 UNFAMILIAR 13 4
#> 2: 3.207 0.895 0.549 UNFAMILIAR 14 4
#> 3: 6.514 0.959 0.547 SCRAMBLED 17 7
#> 4: 9.738 0.850 0.495 SCRAMBLED 18 7
#> 5: 12.895 0.988 0.548 FAMOUS 5 4
#> ---
#> 96: 385.073 0.935 0.439 UNFAMILIAR 13 4
#> 97: 388.331 0.944 0.551 UNFAMILIAR 13 4
#> 98: 391.455 0.988 0.417 FAMOUS 5 7
#> 99: 394.711 0.912 0.498 FAMOUS 6 7
#> 100: 397.401 0.012 0.000 <NA> 999 0
#> response_time stim_file
#> <num> <char>
#> 1: 0.849 func/u020.bmp
#> 2: 0.729 func/u020.bmp
#> 3: 1.197 func/s030.bmp
#> 4: 0.695 func/s030.bmp
#> 5: 1.075 func/f027.bmp
#> ---
#> 96: 0.884 func/u031.bmp
#> 97: 1.183 func/u029.bmp
#> 98: 0.869 func/f021.bmp
#> 99: 1.200 func/f021.bmp
#> 100: 0.000 func/Circle.bmpThese binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.