bids.layout.BIDSDataFile

class BIDSDataFile(filename)[source]

Represents a single data file in a BIDS dataset.

Derived from BIDSFile and provides additional functionality such as obtaining pandas DataFrame data representation (via get_df).

Attributes
class_
dirname
filename
is_dir
path
relpath

Return path relative to layout root

tags

Methods

copy(self, path_patterns[, symbolic_link, …])

Copy the contents of a file to a new location.

get_associations(self[, kind, include_parents])

Get associated files, optionally limiting by association kind.

get_df(self[, include_timing, adjust_onset, …])

Return the contents of a tsv file as a pandas DataFrame.

get_entities(self[, metadata, values])

Return entity information for the current file.

get_metadata(self)

Return all metadata associated with the current file.

__init__(self, filename)

Methods

__init__(self, filename)

copy(self, path_patterns[, symbolic_link, …])

Copy the contents of a file to a new location.

get_associations(self[, kind, include_parents])

Get associated files, optionally limiting by association kind.

get_df(self[, include_timing, adjust_onset, …])

Return the contents of a tsv file as a pandas DataFrame.

get_entities(self[, metadata, values])

Return entity information for the current file.

get_metadata(self)

Return all metadata associated with the current file.

Attributes

class_

dirname

entities

filename

is_dir

metadata

path

relpath

Return path relative to layout root

tags

copy(self, path_patterns, symbolic_link=False, root=None, conflicts='fail')

Copy the contents of a file to a new location.

Parameters
  • path_patterns (list) – List of patterns used to construct the new filename. See build_path documentation for details.

  • symbolic_link (bool) – If True, use a symbolic link to point to the existing file. If False, creates a new file.

  • root (str) – Optional path to prepend to the constructed filename.

  • 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

get_associations(self, kind=None, include_parents=False)

Get associated files, optionally limiting by association kind.

Parameters
  • kind (str) – The kind of association to return (e.g., “Child”). By default, all associations are returned.

  • include_parents (bool) – If True, files related through inheritance are included in the returned list. If False, only directly associated files are returned. For example, a file’s JSON sidecar will always be returned, but other JSON files from which the sidecar inherits will only be returned if include_parents=True.

Returns

A list of BIDSFile instances.

Return type

list

get_df(self, include_timing=True, adjust_onset=False, enforce_dtypes=True, **pd_args)[source]

Return the contents of a tsv file as a pandas DataFrame.

Parameters
  • include_timing (bool) – If True, adds an “onset” column to dense timeseries files (e.g., *_physio.tsv.gz).

  • adjust_onset (bool) – If True, the onset of each sample in a dense timeseries file is shifted to reflect the “StartTime” value in the JSON sidecar. If False, the first sample starts at 0 secs. Ignored if include_timing=False.

  • enforce_dtypes (bool) – If True, enforces the data types defined in the BIDS spec on core columns (e.g., subject_id and session_id must be represented as strings).

  • pd_args (dict) – Optional keyword arguments to pass onto pd.read_csv().

Returns

A pandas DataFrame.

Return type

pandas.DataFrame

get_entities(self, metadata=False, values='tags')

Return entity information for the current file.

Parameters
  • metadata (bool or None) – If False (default), only entities defined for filenames (and not those found in the JSON sidecar) are returned. If True, only entities found in metadata files (and not defined for filenames) are returned. If None, all available entities are returned.

  • values (str) –

    The kind of object to return in the dict’s values. Must be one of:

    • ’tags’: Returns only the tagged value–e.g., if the key

    is “subject”, the value might be “01”. * ‘objects’: Returns the corresponding Entity instance.

Returns

A dict, where keys are entity names and values are Entity instances.

Return type

dict

get_metadata(self)

Return all metadata associated with the current file.

property relpath

Return path relative to layout root