bids.layout.BIDSLayout

class BIDSLayout(root, validate=True, index_associated=True, include=None, absolute_paths=True, derivatives=False, config=None, sources=None, **kwargs)[source]

Layout class representing an entire BIDS dataset.

Parameters:
  • root (str) – The root directory of the BIDS dataset.
  • validate (bool) – 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.
  • index_associated (bool) – Argument passed onto the BIDSValidator; ignored if validate = False.
  • include (str, list) – String or list of strings specifying which of the directories that are by default excluded from indexing should be included. The default exclusion list is [‘code’, ‘stimuli’, ‘sourcedata’, ‘models’].
  • absolute_paths (bool) – If True, queries always return absolute paths. If False, queries return relative paths, unless the root argument was left empty (in which case the root defaults to the file system root).
  • derivatives (bool, str, list) – Specificies 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().
  • config (str, list) – Optional name(s) of configuration file(s) to use. By default (None), uses ‘bids’.
  • sources (BIDLayout, list) – Optional BIDSLayout(s) from which the current BIDSLayout is derived.
  • kwargs – Optional keyword arguments to pass onto the Layout initializer in grabbit.

Methods

add_derivatives(path, **kwargs) Add BIDS-Derivatives datasets to tracking.
add_entity(domain, **kwargs) Add a new Entity to tracking.
as_data_frame(**kwargs) Return information for all Files tracked in the Layout as a pandas DataFrame.
build_path(source[, path_patterns, strict, …]) Constructs a target filename for a file or dictionary of entities.
copy_files([files, path_patterns, …]) Copies one or more Files to new locations defined by each File’s entities and the specified path_patterns.
count(entity[, files]) Return the count of unique values or files for the named entity.
get([return_type, target, extensions, …]) 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_fieldmap(path[, return_list]) Get fieldmap(s) for specified path.
get_file(filename[, derivatives]) Returns the BIDSFile object with the specified path.
get_metadata(path[, include_entities]) Return metadata found in JSON sidecars for the specified file.
get_nearest(path[, return_type, strict, …]) Walk up the file tree from the specified path and return the nearest matching file(s).
load_index(filename[, reindex]) Load the Layout’s index from a plaintext file.
save_index(filename) Save the current Layout’s index to a .json file.
to_df(**kwargs) Return information for all Files tracked in the Layout as a pandas DataFrame.
unique(entity) Return a list of unique values for the named entity.
write_contents_to_file(entities[, …]) Write arbitrary data to a file defined by the passed entities and path patterns.
clone  
get_domain_entities  
index  
parse_file_entities  
add_derivatives(path, **kwargs)[source]

Add BIDS-Derivatives datasets to tracking.

Parameters:
  • path (str, 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).
  • kwargs (dict) – Optional keyword arguments to pass on to BIDSLayout() when initializing each of the derivative datasets.
add_entity(domain, **kwargs)

Add a new Entity to tracking.

as_data_frame(**kwargs)

Return information for all Files tracked in the Layout as a pandas DataFrame.

Parameters:kwargs – Optional keyword arguments passed on to get(). This allows one to easily select only a subset of files for export.
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.
build_path(source, path_patterns=None, strict=False, domains=None)

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

Parameters:
  • source (str, File, dict) –

    The source data to use to construct the new file path. Must be one of: - A File object - A string giving the path of a File 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.
  • 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.
  • domains (str, list) – Optional name(s) of domain(s) to scan for path patterns. If None, all domains are scanned. If two or more domains are provided, the order determines the precedence of path patterns (i.e., earlier domains will have higher precedence).
copy_files(files=None, path_patterns=None, symbolic_links=True, root=None, conflicts='fail', **get_selectors)

Copies one or more Files to new locations defined by each File’s entities and the specified path_patterns.

Parameters:
  • files (list) – Optional list of File objects to write out. If none provided, use files from running a get() query using remaining **kwargs.
  • path_patterns (str, 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) – One of ‘fail’, ‘skip’, ‘overwrite’, or ‘append’ that defines the desired action when a output path already exists. ‘fail’ raises an exception; ‘skip’ does nothing; ‘overwrite’ overwrites the existing file; ‘append’ adds a suffix to each file copy, starting with 0. Default is ‘fail’.
  • **get_selectors (kwargs) – Optional key word arguments to pass into a get() query.
count(entity, files=False)

Return the count of unique values or files for the named entity.

Parameters:
  • entity (str) – The name of the entity.
  • files (bool) – If True, counts the number of filenames that contain at least one value of the entity, rather than the number of unique values of the entity.
get(return_type='tuple', target=None, extensions=None, derivatives=True, regex_search=None, defined_fields=None, domains=None, **kwargs)[source]

Retrieve files and/or metadata from the current Layout.

Parameters:
  • return_type (str) –

    Type of result to return. Valid values: ‘tuple’: returns a list of namedtuples containing file name as

    well as attribute/value pairs for all named entities.

    ’file’: returns a list of matching filenames. ‘dir’: returns a list of directories. ‘id’: returns a list of unique IDs. Must be used together with

    a valid target.

    ’obj’: returns a list of matching File objects.

  • target (str) – Optional name of the target entity to get results for (only used if return_type is ‘dir’ or ‘id’).
  • extensions (str, list) – One or more file extensions to filter on. Files with any other extensions will be excluded.
  • derivatives (bool, str, list) – Whether/how to search associated BIDS-Derivatives datasets. If True (default), all available derivatives are searched. If a str or list, must be the name(s) of the derivatives to search (as defined in the PipelineDescription.Name field in dataset_description.json).
  • regex_search (bool or None) – Whether to require exact matching (False) or regex search (True) when comparing the query string to each entity. If None (default), uses the value found in self.
  • defined_fields (list) – Optional list of names of metadata fields that must be defined in JSON sidecars in order to consider the file a match, but which don’t need to match any particular value.
  • domains (str, list) – Domain(s) to search in. Valid values are ‘bids’ and ‘derivatives’.
  • kwargs (dict) – Any optional key/values to filter the entities on. Keys are entity names, values are regexes to filter on. For example, passing filter={ ‘subject’: ‘sub-[12]’} would return only files that match the first two subjects.
Returns:

A named tuple (default) or a list (see return_type for details).

get_bval(path, **kwargs)[source]

Get bval file for passed path.

get_bvec(path, **kwargs)[source]

Get bvec file for passed path.

get_collections(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 (str) – The level of analysis to return variables for. Must be one of ‘run’, ‘session’, ‘subject’, or ‘dataset’.
  • types (str, list) – Types of variables to retrieve. All valid values
  • the filename stipulated in the BIDS spec for each kind of (reflect) –
  • Valid values include (variable.) – ‘events’, ‘physio’, ‘stim’,
  • 'participants', 'sessions', and 'confounds'. ('scans',) –
  • 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, str) – If level=’run’, the sampling rate to pass onto the returned 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 load_variables.
get_fieldmap(path, return_list=False)[source]

Get fieldmap(s) for specified path.

get_file(filename, derivatives=True)[source]

Returns the BIDSFile object with the specified path.

Parameters:
  • filename (str) – The path of the file to retrieve.
  • (bool (derivatives) – If True, checks all associated derivative datasets as well.

Returns: A BIDSFile.

get_metadata(path, include_entities=False, **kwargs)[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) – If True, all available entities extracted from the filename (rather than JSON sidecars) are included in the returned metadata dictionary.
  • kwargs (dict) – Optional keyword arguments to pass onto get_nearest().
Returns: A dictionary of key/value pairs extracted from all of the
target file’s associated JSON sidecars.

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(path, return_type='file', strict=True, all_=False, ignore_strict_entities=None, full_search=False, **kwargs)

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

Parameters:
  • path (str) – The file to search from.
  • return_type (str) – What to return; must be one of ‘file’ (default) or ‘tuple’.
  • strict (bool) – When True, all entities present in both the input 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.
  • all (bool) – When True, returns all matching files. When False (default), only returns the first match.
  • ignore_strict_entities (list) – Optional list of entities to 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’].
  • full_search (bool) – If True, searches all indexed files, even if they don’t share a common root with the provided path. If False, only files that share a common root will be scanned.
  • kwargs – Optional keywords to pass on to .get().
load_index(filename, reindex=False)

Load the Layout’s index from a plaintext file.

Parameters:
  • filename (str) – Path to the plaintext index file.
  • reindex (bool) – If True, discards entity values provided in the loaded index and instead re-indexes every file in the loaded index against the entities defined in the config. Default is False, in which case it is assumed that all entity definitions in the loaded index are correct and do not need any further validation.

Note: At the moment, directory-specific config files aren’t serialized. This means reconstructed indexes will only work properly in cases where there aren’t multiple layout specs within a project.

save_index(filename)

Save the current Layout’s index to a .json file.

Parameters:filename (str) – Filename to write to.

Note: At the moment, this won’t serialize directory-specific config files. This means reconstructed indexes will only work properly in cases where there aren’t multiple layout specs within a project.

to_df(**kwargs)[source]

Return information for all Files tracked in the Layout as a pandas DataFrame.

Parameters:kwargs – Optional keyword arguments passed on to get(). This allows one to easily select only a subset of files for export.
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.
unique(entity)

Return a list of unique values for the named entity.

Parameters:entity (str) – The name of the entity to retrieve unique values of.
write_contents_to_file(entities, path_patterns=None, contents=None, link_to=None, content_mode='text', conflicts='fail', strict=False, domains=None, index=False, index_domains=None)

Write arbitrary data to a file defined by the passed entities and path 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).
  • conflicts (str) – One of ‘fail’, ‘skip’, ‘overwrite’, or ‘append’
  • defines the desired action when the output path already (that) –
  • 'fail' raises an exception; 'skip' does nothing; (exists.) –
  • overwrites the existing file; 'append' adds a suffix ('overwrite') –
  • each file copy, starting with 1. Default is 'fail'. (to) –
  • 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.
  • domains (list) – List of Domains to scan for path_patterns. Order determines precedence (i.e., earlier Domains will be scanned first). If None, all available domains are included.
  • index (bool) – If True, adds the generated file to the current index using the domains specified in index_domains.
  • index_domains (list) – List of domain names to attach the generated file to when indexing. Ignored if index == False. If None, All available domains are used.