bids.layout.BIDSLayout

class BIDSLayout(root=None, validate=True, absolute_paths=True, derivatives=False, config=None, sources=None, regex_search=False, database_path=None, reset_database=False, indexer=None, **indexer_kwargs)[source]

Layout class representing an entire BIDS dataset.

Parameters
  • root (str) – The root directory of the BIDS dataset.

  • validate (bool, optional) – If True, all files are checked for BIDS compliance when first indexed, and non-compliant files are ignored. This provides a convenient way to restrict file indexing to only those files defined in the “core” BIDS spec, as setting validate=True will lead files in supplementary folders like derivatives/, code/, etc. to be ignored.

  • absolute_paths (bool, optional) – If True, queries always return absolute paths. If False, queries return relative paths (for files and directories).

  • derivatives (bool or str or list, optional) – Specifies whether and/or which derivatives to index. If True, all pipelines found in the derivatives/ subdirectory will be indexed. If a str or list, gives the paths to one or more derivatives directories to index. If False or None, the derivatives/ directory is ignored during indexing, and derivatives will have to be added manually via add_derivatives(). Note: derivatives datasets MUST contain a dataset_description.json file in order to be indexed.

  • config (str or list or None, optional) – Optional name(s) of configuration file(s) to use. By default (None), uses ‘bids’.

  • sources (bids.layout.BIDSLayout or list or None, optional) – Optional BIDSLayout(s) from which the current BIDSLayout is derived.

  • config_filename (str) – Optional name of filename within directories that contains configuration information.

  • regex_search (bool) – Whether to require exact matching (True) or regex search (False, default) when comparing the query string to each entity in .get() calls. This sets a default for the instance, but can be overridden in individual .get() requests.

  • database_path (str) – Optional path to directory containing SQLite database file index for this BIDS dataset. If a value is passed and the folder already exists, indexing is skipped. By default (i.e., if None), an in-memory SQLite database is used, and the index will not persist unless .save() is explicitly called.

  • reset_database (bool) – If True, any existing directory specified in the database_path argument is deleted, and the BIDS dataset provided in the root argument is reindexed. If False, indexing will be skipped and the existing database file will be used. Ignored if database_path is not provided.

  • indexer (BIDSLayoutIndexer or callable) – An optional BIDSLayoutIndexer instance to use for indexing, or any callable that takes a BIDSLayout instance as its only argument. If None, a new indexer with default parameters will be implicitly created.

  • indexer_kwargs (dict) – Optional keyword arguments to pass onto the newly created BIDSLayoutIndexer. Valid keywords are ‘ignore’, ‘force_index’, ‘index_metadata’, and ‘config_filename’. Ignored if indexer is not None.

Attributes
config
entities

Get the entities.

files

Get the files.

root
session

Methods

add_derivatives(path[, parent_database_path])

Add BIDS-Derivatives datasets to tracking.

build_path(source[, path_patterns, strict, ...])

Construct a target filename for a file or dictionary of entities.

clone()

Return a deep copy of the current BIDSLayout.

copy_files([files, path_patterns, ...])

Copy BIDSFile(s) to new locations.

get([return_type, target, scope, ...])

Retrieve files and/or metadata from the current Layout.

get_bval(path, **kwargs)

Get bval file for passed path.

get_bvec(path, **kwargs)

Get bvec file for passed path.

get_collections(level[, types, variables, ...])

Return one or more variable Collections in the BIDS project.

get_dataset_description([scope, all_])

Return contents of dataset_description.json.

get_entities([scope, metadata])

Get entities for all layouts in the specified scope.

get_fieldmap(path[, return_list])

Get fieldmap(s) for specified path.

get_file(filename[, scope])

Return the BIDSFile object with the specified path.

get_files([scope])

Get BIDSFiles for all layouts in the specified scope.

get_metadata(path[, include_entities, scope])

Return metadata found in JSON sidecars for the specified file.

get_nearest(path[, return_type, strict, ...])

Walk up file tree from specified path and return nearest matching file(s).

get_tr([derivatives])

Return the scanning repetition time (TR) for one or more runs.

load(database_path)

Load index from database path.

parse_file_entities(filename[, scope, ...])

Parse the passed filename for entity/value pairs.

save(database_path[, replace_connection])

Save the current index as a SQLite3 DB at the specified location.

to_df([metadata])

Return information for BIDSFiles tracked in Layout as pd.DataFrame.

write_to_file(entities[, path_patterns, ...])

Write data to a file defined by the passed entities and patterns.

__init__(root=None, validate=True, absolute_paths=True, derivatives=False, config=None, sources=None, regex_search=False, database_path=None, reset_database=False, indexer=None, **indexer_kwargs)[source]

Methods

__init__([root, validate, absolute_paths, ...])

add_derivatives(path[, parent_database_path])

Add BIDS-Derivatives datasets to tracking.

build_path(source[, path_patterns, strict, ...])

Construct a target filename for a file or dictionary of entities.

clone()

Return a deep copy of the current BIDSLayout.

copy_files([files, path_patterns, ...])

Copy BIDSFile(s) to new locations.

get([return_type, target, scope, ...])

Retrieve files and/or metadata from the current Layout.

get_bval(path, **kwargs)

Get bval file for passed path.

get_bvec(path, **kwargs)

Get bvec file for passed path.

get_collections(level[, types, variables, ...])

Return one or more variable Collections in the BIDS project.

get_dataset_description([scope, all_])

Return contents of dataset_description.json.

get_entities([scope, metadata])

Get entities for all layouts in the specified scope.

get_fieldmap(path[, return_list])

Get fieldmap(s) for specified path.

get_file(filename[, scope])

Return the BIDSFile object with the specified path.

get_files([scope])

Get BIDSFiles for all layouts in the specified scope.

get_metadata(path[, include_entities, scope])

Return metadata found in JSON sidecars for the specified file.

get_nearest(path[, return_type, strict, ...])

Walk up file tree from specified path and return nearest matching file(s).

get_tr([derivatives])

Return the scanning repetition time (TR) for one or more runs.

load(database_path)

Load index from database path.

parse_file_entities(filename[, scope, ...])

Parse the passed filename for entity/value pairs.

save(database_path[, replace_connection])

Save the current index as a SQLite3 DB at the specified location.

to_df([metadata])

Return information for BIDSFiles tracked in Layout as pd.DataFrame.

write_to_file(entities[, path_patterns, ...])

Write data to a file defined by the passed entities and patterns.

Attributes

config

entities

Get the entities.

files

Get the files.

root

session