bids.layout.BIDSLayout¶
-
class
BIDSLayout
(root, validate=True, absolute_paths=True, derivatives=False, config=None, sources=None, ignore=None, force_index=None, config_filename='layout_config.json', regex_search=False, database_path=None, database_file=None, reset_database=False, index_metadata=True)[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 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.ignore (str or SRE_Pattern or list) – Path(s) to exclude from indexing. Each path is either a string or a SRE_Pattern object (i.e., compiled regular expression). If a string is passed, it must be either an absolute path, or be relative to the BIDS project root. If an SRE_Pattern is passed, the contained regular expression will be matched against the full (absolute) path of all files and directories. By default, indexing ignores all files in ‘code/’, ‘stimuli/’, ‘sourcedata/’, ‘models/’, and any hidden files/dirs beginning with ‘.’ at root level.
force_index (str or SRE_Pattern or list) – Path(s) to forcibly index in the BIDSLayout, even if they would otherwise fail validation. See the documentation for the ignore argument for input format details. Note that paths in force_index takes precedence over those in ignore (i.e., if a file matches both ignore and force_index, it will be indexed). Note: NEVER include ‘derivatives’ here; use the derivatives argument (or
bids.layout.BIDSLayout.add_derivatives
) for that.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.
index_metadata (bool) – If True, all metadata files are indexed at initialization. If False, metadata will not be available (but indexing will be faster).
- Attributes
Methods
add_derivatives
(self, path[, …])Add BIDS-Derivatives datasets to tracking.
build_path
(self, source[, path_patterns, …])Construct a target filename for a file or dictionary of entities.
clone
(self)Return a deep copy of the current BIDSLayout.
copy_files
(self[, files, path_patterns, …])Copy BIDSFile(s) to new locations.
get
(self[, return_type, target, scope, …])Retrieve files and/or metadata from the current Layout.
get_bval
(self, path, \*\*kwargs)Get bval file for passed path.
get_bvec
(self, path, \*\*kwargs)Get bvec file for passed path.
get_collections
(self, level[, types, …])Return one or more variable Collections in the BIDS project.
get_dataset_description
(self[, scope, all_])Return contents of dataset_description.json.
get_entities
(self[, scope, metadata])Get entities for all layouts in the specified scope.
get_fieldmap
(self, path[, return_list])Get fieldmap(s) for specified path.
get_file
(self, filename[, scope])Return the BIDSFile object with the specified path.
get_files
(self[, scope])Get BIDSFiles for all layouts in the specified scope.
get_metadata
(self, path[, include_entities, …])Return metadata found in JSON sidecars for the specified file.
get_nearest
(self, path[, return_type, …])Walk up file tree from specified path and return nearest matching file(s).
get_tr
(self[, derivatives])Return the scanning repetition time (TR) for one or more runs.
load
(database_path)Load index from database path.
parse_file_entities
(self, filename[, scope, …])Parse the passed filename for entity/value pairs.
save
(self, database_path[, replace_connection])Save the current index as a SQLite3 DB at the specified location.
to_df
(self[, metadata])Return information for BIDSFiles tracked in Layout as pd.DataFrame.
write_to_file
(self, entities[, …])Write data to a file defined by the passed entities and patterns.
-
__init__
(self, root, validate=True, absolute_paths=True, derivatives=False, config=None, sources=None, ignore=None, force_index=None, config_filename='layout_config.json', regex_search=False, database_path=None, database_file=None, reset_database=False, index_metadata=True)[source]¶ Initialize BIDSLayout.
Methods
__init__
(self, root[, validate, …])Initialize BIDSLayout.
add_derivatives
(self, path[, …])Add BIDS-Derivatives datasets to tracking.
build_path
(self, source[, path_patterns, …])Construct a target filename for a file or dictionary of entities.
clone
(self)Return a deep copy of the current BIDSLayout.
copy_files
(self[, files, path_patterns, …])Copy BIDSFile(s) to new locations.
get
(self[, return_type, target, scope, …])Retrieve files and/or metadata from the current Layout.
get_bval
(self, path, \*\*kwargs)Get bval file for passed path.
get_bvec
(self, path, \*\*kwargs)Get bvec file for passed path.
get_collections
(self, level[, types, …])Return one or more variable Collections in the BIDS project.
get_dataset_description
(self[, scope, all_])Return contents of dataset_description.json.
get_entities
(self[, scope, metadata])Get entities for all layouts in the specified scope.
get_fieldmap
(self, path[, return_list])Get fieldmap(s) for specified path.
get_file
(self, filename[, scope])Return the BIDSFile object with the specified path.
get_files
(self[, scope])Get BIDSFiles for all layouts in the specified scope.
get_metadata
(self, path[, include_entities, …])Return metadata found in JSON sidecars for the specified file.
get_nearest
(self, path[, return_type, …])Walk up file tree from specified path and return nearest matching file(s).
get_tr
(self[, derivatives])Return the scanning repetition time (TR) for one or more runs.
load
(database_path)Load index from database path.
parse_file_entities
(self, filename[, scope, …])Parse the passed filename for entity/value pairs.
save
(self, database_path[, replace_connection])Save the current index as a SQLite3 DB at the specified location.
to_df
(self[, metadata])Return information for BIDSFiles tracked in Layout as pd.DataFrame.
write_to_file
(self, entities[, …])Write data to a file defined by the passed entities and patterns.
Attributes
Get the entities.
Get the files.
-
add_derivatives
(self, path, parent_database_path=None, **kwargs)[source]¶ Add BIDS-Derivatives datasets to tracking.
- Parameters
path (str or list) – One or more paths to BIDS-Derivatives datasets. Each path can point to either a derivatives/ directory containing one more more pipeline directories, or to a single pipeline directory (e.g., derivatives/fmriprep).
parent_database_path (str) – If not None, use the pipeline name from the dataset_description.json file as the database folder name to nest within the parent database folder name to write out derivative index to.
kwargs (dict) – Optional keyword arguments to pass on to BIDSLayout() when initializing each of the derivative datasets.
Notes
Every derivatives directory intended for indexing MUST contain a valid dataset_description.json file. See the BIDS-Derivatives specification for details.
-
build_path
(self, source, path_patterns=None, strict=False, scope='all', validate=True, absolute_paths=None)[source]¶ Construct a target filename for a file or dictionary of entities.
- Parameters
source (str or
bids.layout.BIDSFile
or dict) –The source data to use to construct the new file path. Must be one of: - A BIDSFile object - A string giving the path of a BIDSFile contained within the
current Layout.
A dict of entities, with entity names in keys and values in values
path_patterns (list) –
Optional path patterns to use to construct the new file path. If None, the Layout-defined patterns will be used. Entities should be represented by the name surrounded by curly braces. Optional portions of the patterns should be denoted by square brackets. Entities that require a specific value for the pattern to match can pass them inside angle brackets. Default values can be assigned by specifying a string after the pipe operator. E.g., (e.g., {type<image>|bold} would only match the pattern if the entity ‘type’ was passed and its value is “image”, otherwise the default value “bold” will be used).
Example: ‘sub-{subject}/[var-{name}/]{id}.csv’ Result: ‘sub-01/var-SES/1045.csv’
strict (bool, optional) – If True, all entities must be matched inside a pattern in order to be a valid match. If False, extra entities will be ignored so long as all mandatory entities are found.
scope (str or list, optional) – The scope of the search space. Indicates which BIDSLayouts’ path patterns to use. See BIDSLayout docstring for valid values. By default, uses all available layouts. If two or more values are provided, the order determines the precedence of path patterns (i.e., earlier layouts will have higher precedence).
validate (bool, optional) – If True, built path must pass BIDS validator. If False, no validation is attempted, and an invalid path may be returned (e.g., if an entity value contains a hyphen).
absolute_paths (bool, optional) – Optionally override the instance-wide option to report either absolute or relative (to the top of the dataset) paths. If None, will fall back on the value specified at BIDSLayout initialization.
-
copy_files
(self, files=None, path_patterns=None, symbolic_links=True, root=None, conflicts='fail', **kwargs)[source]¶ Copy BIDSFile(s) to new locations.
The new locations are defined by each BIDSFile’s entities and the specified path_patterns.
- Parameters
files (list) – Optional list of BIDSFile objects to write out. If none provided, use files from running a get() query using remaining **kwargs.
path_patterns (str or list) – Write patterns to pass to each file’s write_file method.
symbolic_links (bool) – Whether to copy each file as a symbolic link or a deep copy.
root (str) – Optional root directory that all patterns are relative to. Defaults to current working directory.
conflicts (str) –
Defines the desired action when the output path already exists. Must be one of:
’fail’: raises an exception ‘skip’ does nothing ‘overwrite’: overwrites the existing file ‘append’: adds a suffix to each file copy, starting with 1
kwargs (dict) – Optional key word arguments to pass into a get() query.
-
property
entities
¶ Get the entities.
-
property
files
¶ Get the files.
-
get
(self, return_type='object', target=None, scope='all', regex_search=False, absolute_paths=None, invalid_filters='error', **filters)[source]¶ Retrieve files and/or metadata from the current Layout.
- Parameters
return_type (str, optional) –
Type of result to return. Valid values: ‘object’ (default): return a list of matching BIDSFile objects. ‘file’ or ‘filename’: return a list of matching filenames. ‘dir’: return a list of directories. ‘id’: return a list of unique IDs. Must be used together
with a valid target.
target (str, optional) – Optional name of the target entity to get results for (only used if return_type is ‘dir’ or ‘id’).
scope (str or list, optional) – Scope of the search space. If passed, only nodes/directories that match the specified scope will be searched. Possible values include: ‘all’ (default): search all available directories. ‘derivatives’: search all derivatives directories. ‘raw’: search only BIDS-Raw directories. ‘self’: search only the directly called BIDSLayout. <PipelineName>: the name of a BIDS-Derivatives pipeline.
regex_search (bool or None, optional) – Whether to require exact matching (False) or regex search (True) when comparing the query string to each entity.
absolute_paths (bool, optional) – Optionally override the instance-wide option to report either absolute or relative (to the top of the dataset) paths. If None, will fall back on the value specified at BIDSLayout initialization.
(str) (invalid_filters) –
encountered that don’t exist in the database (e.g., in the case of a typo like subbject=’0.1’). Valid values:
’error’ (default): Raise an explicit error. ‘drop’: Silently drop invalid filters (equivalent to not having
passed them as arguments in the first place).
- ’allow’: Include the invalid filters in the query, resulting
in no results being returned.
filters (dict) –
Any optional key/values to filter the entities on. Keys are entity names, values are regexes to filter on. For example, passing filters={‘subject’: ‘sub-[12]’} would return only files that match the first two subjects. In addition to ordinary data types, the following enums are defined (in the Query class):
Query.NONE: The named entity must not be defined.
- Query.ANY: the named entity must be defined, but can have any
value.
- Returns
A list of BIDSFiles (default) or strings (see return_type).
- Return type
list of
bids.layout.BIDSFile
or str
-
get_collections
(self, level, types=None, variables=None, merge=False, sampling_rate=None, skip_empty=False, **kwargs)[source]¶ Return one or more variable Collections in the BIDS project.
- Parameters
level ({'run', 'session', 'subject', 'dataset'}) – The level of analysis to return variables for. Must be one of ‘run’, ‘session’,’subject’, or ‘dataset’.
types (str or list) – Types of variables to retrieve. All valid values reflect the filename stipulated in the BIDS spec for each kind of variable. Valid values include: ‘events’, ‘physio’, ‘stim’, ‘scans’, ‘participants’, ‘sessions’, and ‘regressors’. Default is None.
variables (list) – Optional list of variables names to return. If None, all available variables are returned.
merge (bool) – If True, variables are merged across all observations of the current level. E.g., if level=’subject’, variables from all subjects will be merged into a single collection. If False, each observation is handled separately, and the result is returned as a list.
sampling_rate (int or str) – If level=’run’, the sampling rate to pass onto the returned
bids.variables.collections.BIDSRunVariableCollection
.skip_empty (bool) – Whether or not to skip empty Variables (i.e., where there are no rows/records in a file after applying any filtering operations like dropping NaNs).
kwargs – Optional additional arguments to pass onto
bids.variables.io.load_variables
.
- Returns
or
bids.variables.collections.BIDSVariableCollection
A list if merge=False; a singlebids.variables.collections.BIDSVariableCollection
if merge=True.- Return type
-
get_dataset_description
(self, scope='self', all_=False)[source]¶ Return contents of dataset_description.json.
- Parameters
scope (str) – The scope of the search space. Only descriptions of BIDSLayouts that match the specified scope will be returned. See
bids.layout.BIDSLayout.get
docstring for valid values. Defaults to ‘self’ –i.e., returns the dataset_description.json file for only the directly-called BIDSLayout.all_ (bool) – If True, returns a list containing descriptions for all matching layouts. If False (default), returns for only the first matching layout.
- Returns
a dictionary or list of dictionaries (depending on all_).
- Return type
dict or list of dict
-
get_entities
(self, scope='all', metadata=None)[source]¶ Get entities for all layouts in the specified scope.
- Parameters
scope (str) – The scope of the search space. Indicates which BIDSLayouts’ entities to extract. See
bids.layout.BIDSLayout.get
docstring for valid values.metadata (bool or None) – By default (None), all available entities are returned. If True, only entities found in metadata files (and not defined for filenames) are returned. If False, only entities defined for filenames (and not those found in JSON sidecars) are returned.
- Returns
Dictionary where keys are entity names and values are Entity instances.
- Return type
-
get_file
(self, filename, scope='all')[source]¶ Return the BIDSFile object with the specified path.
- Parameters
filename (str) – The path of the file to retrieve. Must be either an absolute path, or relative to the root of this BIDSLayout.
scope (str or list, optional) – Scope of the search space. If passed, only BIDSLayouts that match the specified scope will be searched. See
BIDSLayout.get
docstring for valid values. Default is ‘all’.
- Returns
File found, or None if no match was found.
- Return type
bids.layout.BIDSFile
or None
-
get_files
(self, scope='all')[source]¶ Get BIDSFiles for all layouts in the specified scope.
- Parameters
scope (str) – The scope of the search space. Indicates which BIDSLayouts’ entities to extract. See
bids.layout.BIDSLayout.get
docstring for valid values.- Returns
A dict, where keys are file paths and values are
bids.layout.BIDSFile
instances.
-
get_metadata
(self, path, include_entities=False, scope='all')[source]¶ Return metadata found in JSON sidecars for the specified file.
- Parameters
path (str) – Path to the file to get metadata for.
include_entities (bool, optional) – If True, all available entities extracted from the filename (rather than JSON sidecars) are included in the returned metadata dictionary.
scope (str or list, optional) – The scope of the search space. Each element must be one of ‘all’, ‘raw’, ‘self’, ‘derivatives’, or a BIDS-Derivatives pipeline name. Defaults to searching all available datasets.
- Returns
A dictionary of key/value pairs extracted from all of the target file’s associated JSON sidecars.
- Return type
Notes
A dictionary containing metadata extracted from all matching .json files is returned. In cases where the same key is found in multiple files, the values in files closer to the input filename will take precedence, per the inheritance rules in the BIDS specification.
-
get_nearest
(self, path, return_type='filename', strict=True, all_=False, ignore_strict_entities='extension', full_search=False, **filters)[source]¶ Walk up file tree from specified path and return nearest matching file(s).
- Parameters
(str) (return_type) –
(str) – (default) or ‘tuple’.
(bool) (full_search) – path and the target file(s) must match perfectly. When False, files will be ordered by the number of matching entities, and partial matches will be allowed.
(bool) – (default), only returns the first match.
(str, list) (ignore_strict_entities) – exclude from strict matching when strict is True. This allows one to search, e.g., for files of a different type while matching all other entities perfectly by passing ignore_strict_entities=[‘type’]. Ignores extension by default.
(bool) – they don’t share a common root with the provided path. If False, only files that share a common root will be scanned.
filters (dict) – Optional keywords to pass on to
bids.layout.BIDSLayout.get
.
-
get_tr
(self, derivatives=False, **filters)[source]¶ Return the scanning repetition time (TR) for one or more runs.
- Parameters
- Returns
A single float.
- Return type
Notes
Raises an exception if more than one unique TR is found.
-
classmethod
load
(database_path)[source]¶ Load index from database path. Initalization parameters are set to those found in database_path JSON sidecar.
- Parameters
database_path (str) – The path to the desired database folder. By default, uses .db_cache. If a relative path is passed, it is assumed to be relative to the BIDSLayout root directory.
-
parse_file_entities
(self, filename, scope='all', entities=None, config=None, include_unmatched=False)[source]¶ Parse the passed filename for entity/value pairs.
- Parameters
filename (str) – The filename to parse for entity values
scope (str or list, optional) – The scope of the search space. Indicates which BIDSLayouts’ entities to extract. See
bids.layout.BIDSLayout.get
docstring for valid values. By default, extracts all entities.entities (list or None, optional) – An optional list of Entity instances to use in extraction. If passed, the scope and config arguments are ignored, and only the Entities in this list are used.
config (str or
bids.layout.models.Config
or list or None, optional) – One or morebids.layout.models.Config
objects, or paths to JSON config files on disk, containing the Entity definitions to use in extraction. If passed, scope is ignored.include_unmatched (bool, optional) – If True, unmatched entities are included in the returned dict, with values set to None. If False (default), unmatched entities are ignored.
- Returns
Dictionary where keys are Entity names and values are the values extracted from the filename.
- Return type
-
save
(self, database_path, replace_connection=True)[source]¶ Save the current index as a SQLite3 DB at the specified location.
Note: This is only necessary if a database_path was not specified at initialization, and the user now wants to save the index. If a database_path was specified originally, there is no need to re-save using this method.
- Parameters
database_path (str) – The path to the desired database folder. By default, uses .db_cache. If a relative path is passed, it is assumed to be relative to the BIDSLayout root directory.
replace_connection (bool, optional) – If True, the newly created database will be used for all subsequent connections. This means that any changes to the index made after the .save() call will be reflected in the database file. If False, the previous database will continue to be used, and any subsequent changes will not be reflected in the new file unless save() is explicitly called again.
-
to_df
(self, metadata=False, **filters)[source]¶ Return information for BIDSFiles tracked in Layout as pd.DataFrame.
- Parameters
- Returns
A pandas DataFrame, where each row is a file, and each column is a tracked entity. NaNs are injected whenever a file has no value for a given attribute.
- Return type
-
write_to_file
(self, entities, path_patterns=None, contents=None, link_to=None, copy_from=None, content_mode='text', conflicts='fail', strict=False, validate=True)[source]¶ Write data to a file defined by the passed entities and patterns.
- Parameters
entities (dict) – A dictionary of entities, with Entity names in keys and values for the desired file in values.
path_patterns (list) – Optional path patterns to use when building the filename. If None, the Layout-defined patterns will be used.
contents (object) – Contents to write to the generate file path. Can be any object serializable as text or binary data (as defined in the content_mode argument).
link_to (str) – Optional path with which to create a symbolic link to. Used as an alternative to and takes priority over the contents argument.
conflicts (str) –
Defines the desired action when the output path already exists. Must be one of:
’fail’: raises an exception ‘skip’ does nothing ‘overwrite’: overwrites the existing file ‘append’: adds a suffix to each file copy, starting with 1
strict (bool) – If True, all entities must be matched inside a pattern in order to be a valid match. If False, extra entities will be ignored so long as all mandatory entities are found.
validate (bool) – If True, built path must pass BIDS validator. If False, no validation is attempted, and an invalid path may be returned (e.g., if an entity value contains a hyphen).