bidshandler.BIDSTree

class bidshandler.BIDSTree(fpath, initialize=True)[source]

Bases: bidshandler.querymixin.QueryMixin

Highest BIDS archive level containing all the various projects

Parameters:
  • fpath (str or path-like object) – File path containing all the project folders organised using the BIDS specification.
  • initialize (bool, optional) – Whether to parse the folder and load any child structures.
__init__(fpath, initialize=True)[source]

Initialize self. See help(type(self)) for accurate signature.

Methods

__init__(fpath[, initialize]) Initialize self.
add(other[, copier]) Add another Scan, Session, Subject, Project or BIDSTree to this object.
generate_map([output_file]) Generate a map of the BIDS folder.
project(id_) Return the Project corresponding to the provided id.
query(obj, token, condition, value) Query the BIDS object and return the appropriate data.

Attributes

projects List of all Projects contained in the BIDS folder.
scans List of all Scans contained in the BIDS folder.
sessions List of all Sessions contained in the BIDS folder.
subjects List of all Subjects contained in the BIDS folder.
__contains__(other)[source]

Determine if the Subject contains a certain Scan, Session, Subject or Project.

Parameters:other (Instance of bidshandler.Scan, bidshandler.Session, bidshandler.Subject or bidshandler.Project) – Object to check whether it is contained in this BIDS folder.
__getitem__(item)[source]

Return the child project with the corresponding name (if it exists).

__iter__()[source]

Iterable of the contained Project objects.

add(other, copier=<function _copyfiles>)[source]

Add another Scan, Session, Subject, Project or BIDSTree to this object.

Parameters:
  • other (Instance of bidshandler.Scan, bidshandler.Session, bidshandler.Subject, bidshandler.Project or bidshandler.BIDSTree) – Object to be added to this BIDSTree. The added object must already exist in the same context as this object (except BIDSTree objects).
  • copier (function) – A function to facilitate the copying of any applicable data. This function must have the call signature function(src_files: list, dst_files: list) Where src_files is the list of files to be moved and dst_files is the list of corresponding destinations. This will default to using utils._copyfiles which simply implements shutil.copy() and creates any directories that do not already exist.
generate_map(output_file=None)[source]

Generate a map of the BIDS folder.

Parameters:output_file (str) – Path to write the file to. If not provided this will return the string representation.
Returns:String representation of xml structure.
Return type:str
project(id_)[source]

Return the Project corresponding to the provided id.

projects

List of all Projects contained in the BIDS folder.

query(obj, token, condition, value)

Query the BIDS object and return the appropriate data.

Parameters:
  • obj (str) – The object type that should be returned. This can be one of (‘project’, ‘subject’, ‘session’, ‘scan’)
  • token (str) –

    The key to query for. This can be a value from the following list:

    • task: Corresponds to the task key in the BIDS filename.
    • acquisition or acq: Corresponds to the acq key in the BIDS filename.
    • run: Corresponds to the run key in the BIDS filename.
    • proc: Corresponds to the proc key in the BIDS filename.
    • age: Corresponds to the age of the participant. [Only available for obj=’subject’]
    • sex: Corresponds to the gender of the participant. [Only available for obj=’subject’]
    • group: Corresponds to the group of the participant. [Only available for obj=’subject’]
    • rec_date: Corresponds to the time and date of the recording. The value can either be formatted like “%Y-%m-%d” (ie. YYYY-MM-DD) to specify a single day, or it can be specified to the second by formatting it using the format string “%Y-%m-%dT%H:%M:%S” (ie. YYYY-MM-DDTHH:mm:ss).
    • subjects: Corresponds to the number of subjects contained. [Only available for obj=’project’]
    • sessions: Corresponds to the number of sessions contained. [Only available for obj=’project’ or ‘subject’]
    • scans: Corresponds to the number of scans contained. [Only available for obj=’project’, ‘subject’ or ‘session’]
    • Any other token will be considered to be a key in the sidecar.json file.
  • condition (str) – One of (‘<’, ‘<=’, ‘=’, ‘!=’, ‘!!=’ (none equal), ‘=>’, ‘>’). Used to perform comaprisons between the value provided and the values the data have. The ‘!!=’ operator here is used to distinguish between the case of when you want to determine if something contains something that isn’t the value you specify, and whether something doesn’t contain the value specified. This operator is currently only supported for the tokens ‘task’, ‘acquisition’/’acq’, `’run’ and ‘proc’.
  • value (str | int | float) – The value the token has (or the value to compare using the condition argument). The value provided must match exactly if the equality operator is used, and must have a type appropriate for comparison if an inequality operator is used. Currently regex is not supported, but this may come in the future.
Returns:

return_data – List of objects that satisfy the provided query conditions.
Return type:

bidshandler.querylist.QueryList
scans

List of all Scans contained in the BIDS folder.

sessions

List of all Sessions contained in the BIDS folder.

subjects

List of all Subjects contained in the BIDS folder.