Module

File has following public fields:

• path - path to the file
• metadata - dictionary parsed from JSON-sidecar
• entities - dictionary parsed from key-value filename

The File can be initialized by specifying only path. Other behavior can also be tweaked accordingly with the optional parameters:

• load_metadata::Bool - defaults to true. If true, this expects a JSON-sidecar to be present alongside with every BIDS files.
• require_modality::Bool - defaults to true. If true this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gz
• strict::Bool - defaults to true. If true, BIDSTools will throw an error on invalid BIDS filename, this can be turned to false to not parse those file names and display a warning instead. This will result in empty dictionary in entities.
• extract_from_full_path::Bool - defaults to true. If true, will try to extract sub and ses from full path and append to entities if they can't be found in the parsed filename.

Example

julia> file = File("/path/to/bids/root/sub-Subtest/ses-1/anat/sub-Subtest-1_run-001_T1w.nii.gz")
File:
    path = /path/to/bids/root/sub-Subtest/ses-1/anat/sub-Amelll_ses-1_run-001_T1w.nii.gz
    metadata_exist = true

Layout has following public fields:

• root - the root folder of the data
• subjects - a vector of Subject
• longitudinal - true if a longitudinal study, i.e. multi-session/multi-visit per subject.
• description - dictionary parsed from dataset_description.json.
• subjects_details - DataFrame from subjects.tsv

The BIDS directory must follow the specification, i.e. root/sub-<subject_id>/[ses-<session_id>]

The Layout can be initialized by specifying only root. Other behavior can also be tweaked accordingly with the optional parameters:

• search::Bool - defaults to true. If true this will search over root to find Subject, Session and Files.
• load_metadata::Bool - defaults to true. If true, this expects a JSON-sidecar to be present alongside with every BIDS files.
• require_modality::Bool - defaults to true. If true this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gz
• longitudinal::Bool - defaults to true. If true this expects a session directory ses- exists under subject directory.
• strict::Bool - defaults to true. If true, BIDSTools will throw errors on invalid BIDS filenames, this can be turned to false to not parse those file names and display a warning instead.
• extract_from_full_path::Bool - defaults to true. If true, will try to extract sub and ses from full path and append to entities if they can't be found in the parsed filename.

Example

julia> layout = Layout("/path/to/bids/root/")
Layout:
    root = "/path/to/bids/root/"
    total subject = 49
    total session = 74
    total files = 1161

Session has following public fields:

• path - path to the session directory
• identifier - identifier of session, extracted from directory name ses-<session_id>. In non-longitudinal study, this will always be "1".
• files - a vector of File
• scans_details - DataFrame parsed from *_scans.tsv. If the tsv is not exist, this will be an empty DataFrame

The Subject can be initialized by specifying only path. Other behavior can also be tweaked accordingly with the optional parameters:

• search::Bool - defaults to true. If true this will search over root to find Subject, Session and Files.
• load_metadata::Bool - defaults to true. If true, this expects a JSON-sidecar to be present alongside with every BIDS files.
• require_modality::Bool - defaults to true. If true this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gz
• longitudinal::Bool - defaults to true. If true this expects a session directory ses- exists under subject directory.
• strict::Bool - defaults to true. If true, BIDSTools will throw errors on invalid BIDS filenames, this can be turned to false to not parse those file names and display a warning instead.
• extract_from_full_path::Bool - defaults to true. If true, will try to extract sub and ses from full path and append to entities if they can't be found in the parsed filename.

Example

julia> ses = Session("/path/to/bids/root/sub-Subtest/ses-1/")
Session:
    identifier = 1
    total files = 8

Subject has following public fields:

• path - path to the subject directory
• identifier - identifier of subject, extracted from directory name sub-<subject_id>
• sessions - a vector of Session

The Subject can be initialized by specifying only path. Other behavior can also be tweaked accordingly with the optional parameters:

• search::Bool - defaults to true. If true this will search over root to find Subject, Session and Files.
• load_metadata::Bool - defaults to true. If true, this expects a JSON-sidecar to be present alongside with every BIDS files.
• require_modality::Bool - defaults to true. If true this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gz
• longitudinal::Bool - defaults to true. If true this expects a session directory ses- exists under subject directory.
• strict::Bool - defaults to true. If true, BIDSTools will throw errors on invalid BIDS filenames, this can be turned to false to not parse those file names and display a warning instead.
• extract_from_full_path::Bool - defaults to true. If true, will try to extract sub and ses from full path and append to entities if they can't be found in the parsed filename.

Example

julia> sub = Subject("/path/to/bids/root/sub-Subtest/")
Subject:
    identifier = Subtest
    total session = 1
    total files = 8

function construct_fname(entities::AbstractDict; ext::Union{String,Nothing}=nothing)

Function to construct BIDS filename from entities. It is recommended to use OrderedDict for this purpose to retain the order of the elements. To supply modality, e.g. _T1w, use modality key, i.e. "modality"=>"T1w".

function get_files(
    files::Vector{File}; path::Union{String, Regex, Nothing}=nothing, kws...
)

Function to query files based on their path, entities, and metadata. path is optional and can be passed as either String or Regex, while entities and metadata can be passed as keyword args, i.e. key="value".

In addition to querying vector of File, this can also be used to obtain desired files in a Layout, Subject, or Session by simply replacing Vector{File} into desired object.

Example

filtered_files = get_files(files, path="anat", run="002", modality="T1w")

# Filter from layout only from entities and metadata
filtered_files = get_files(layout, run="002", modality="T1w")

function get_metadata_path(path)

Get file path of metadata file (json sidecar) for a BIDS path which can be a string or File.

function get_ses(
    path;
    from_fname::Bool=true,
    require_modality::Bool=true,
    strict::Bool=true
)

Function to get session_id from path or File object.

The following keyword arguments can be passed:

• from_fname::Bool - defaults to true. If true, only looks the session_id from filename, otherwise, looks into full path if session_id can't be found in filename
• require_modality::Bool - defaults to true. If true this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gz
• strict::Bool - defaults to true. If true, BIDSTools will throw an error on invalid BIDS filename, this can be turned to false to not parse those file names and display a warning instead. This will result in empty dictionary in entities.

Returns nothing if no session ID found.

function get_sub(
    path;
    from_fname::Bool=true,
    require_modality::Bool=true,
    strict::Bool=true
)

Function to get subject_id from path or File object.

The following keyword arguments can be passed:

• from_fname::Bool - detauls to true. If true, only looks the subject_id from filename, otherwise, looks into full path if subject_id can't be found in filename
• require_modality::Bool - defaults to true. If true this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gz
• strict::Bool - defaults to true. If true, BIDSTools will throw an error on invalid BIDS filename, this can be turned to false to not parse those file names and display a warning instead. This will result in empty dictionary in entities.

Returns nothing if no subject ID found.

function list_scans_detail(session::Session)

Function to pretty print scans detail spreadsheet (_scans.tsv) using PrettyTables

function list_subject_detail(layout::Layout)

Function to pretty print subject spreadsheet (subjects.tsv) using PrettyTables

function parse_fname(
    fname::AbstractString; require_modality::Bool=true, strict::Bool=true
)

Function to parse filename keys and values with this following structure <k1>-<v1>_<k2>-<v2>_..._<kn>-<vn>

The following keyword arguments can be passed:

• require_modality::Bool - defaults to true. If true this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gz
• strict::Bool - defaults to true. If true, BIDSTools will throw an error on invalid BIDS filename, this can be turned to false to not parse those file names and display a warning instead. This will result in empty dictionary in entities.

This function returns a dictionary containing those keys and values.

function parse_path(path; require_modality::Bool=true, strict::Bool=true)

Function to parse path of a File to Dictionary. The argument path can be a File or path (any String object implementing AbstractString). This function implements parse_fname.

The following keyword arguments can be passed:

• require_modality::Bool - defaults to true. If true this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gz
• strict::Bool - defaults to true. If true, BIDSTools will throw an error on invalid BIDS filename, this can be turned to false to not parse those file names and display a warning instead. This will result in empty dictionary in entities.

function print_dataset_description(layout::Layout)

Function to pretty-print dataset description

function total_files(session::Session)

Get number of files in a session. The argument Session can be changed into Subject or Layout.

function total_sessions(subject::Subject)

Get number of session of a subject. The argument Subject can be changed into Layout.

function total_subjects(layout::Layout)

Get number of subject in the layout