Module
BIDSTools
parsed a directory into Julia objects Layout
, Subject
, Session
, and File
. Basically, the idea is Layout
consists of Subject
, Subject
consists of Session
(there will always be 1 session in non-longitudinal study), and Session
contains File
.
Main.BIDSTools.File
— TypeFile
has following public fields:
path
- path to the filemetadata
- dictionary parsed from JSON-sidecarentities
- 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 totrue
. Iftrue
, this expects a JSON-sidecar to be present alongside with every BIDS files.require_modality::Bool
- defaults totrue
. Iftrue
this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gzstrict::Bool
- defaults totrue
. Iftrue
,BIDSTools
will throw an error on invalid BIDS filename, this can be turned tofalse
to not parse those file names and display a warning instead. This will result in empty dictionary inentities
.extract_from_full_path::Bool
- defaults totrue
. Iftrue
, will try to extractsub
andses
from full path and append toentities
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
Main.BIDSTools.Layout
— TypeLayout
has following public fields:
root
- the root folder of the datasubjects
- a vector ofSubject
longitudinal
-true
if a longitudinal study, i.e. multi-session/multi-visit per subject.description
- dictionary parsed fromdataset_description.json
.subjects_details
-DataFrame
fromsubjects.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 totrue
. Iftrue
this will search overroot
to findSubject
,Session
andFiles
.load_metadata::Bool
- defaults totrue
. Iftrue
, this expects a JSON-sidecar to be present alongside with every BIDS files.require_modality::Bool
- defaults totrue
. Iftrue
this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gzlongitudinal::Bool
- defaults totrue
. Iftrue
this expects a session directoryses-
exists under subject directory.strict::Bool
- defaults totrue
. Iftrue
,BIDSTools
will throw errors on invalid BIDS filenames, this can be turned tofalse
to not parse those file names and display a warning instead.extract_from_full_path::Bool
- defaults totrue
. Iftrue
, will try to extractsub
andses
from full path and append toentities
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
Main.BIDSTools.Session
— TypeSession
has following public fields:
path
- path to the session directoryidentifier
- identifier of session, extracted from directory nameses-<session_id>
. In non-longitudinal study, this will always be "1".files
- a vector ofFile
scans_details
-DataFrame
parsed from*_scans.tsv
. If the tsv is not exist, this will be an emptyDataFrame
The Subject
can be initialized by specifying only path
. Other behavior can also be tweaked accordingly with the optional parameters:
search::Bool
- defaults totrue
. Iftrue
this will search overroot
to findSubject
,Session
andFiles
.load_metadata::Bool
- defaults totrue
. Iftrue
, this expects a JSON-sidecar to be present alongside with every BIDS files.require_modality::Bool
- defaults totrue
. Iftrue
this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gzlongitudinal::Bool
- defaults totrue
. Iftrue
this expects a session directoryses-
exists under subject directory.strict::Bool
- defaults totrue
. Iftrue
,BIDSTools
will throw errors on invalid BIDS filenames, this can be turned tofalse
to not parse those file names and display a warning instead.extract_from_full_path::Bool
- defaults totrue
. Iftrue
, will try to extractsub
andses
from full path and append toentities
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
Main.BIDSTools.Subject
— TypeSubject
has following public fields:
path
- path to the subject directoryidentifier
- identifier of subject, extracted from directory namesub-<subject_id>
sessions
- a vector ofSession
The Subject
can be initialized by specifying only path
. Other behavior can also be tweaked accordingly with the optional parameters:
search::Bool
- defaults totrue
. Iftrue
this will search overroot
to findSubject
,Session
andFiles
.load_metadata::Bool
- defaults totrue
. Iftrue
, this expects a JSON-sidecar to be present alongside with every BIDS files.require_modality::Bool
- defaults totrue
. Iftrue
this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gzlongitudinal::Bool
- defaults totrue
. Iftrue
this expects a session directoryses-
exists under subject directory.strict::Bool
- defaults totrue
. Iftrue
,BIDSTools
will throw errors on invalid BIDS filenames, this can be turned tofalse
to not parse those file names and display a warning instead.extract_from_full_path::Bool
- defaults totrue
. Iftrue
, will try to extractsub
andses
from full path and append toentities
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
Main.BIDSTools.construct_fname
— Methodfunction 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".
Main.BIDSTools.get_files
— Methodfunction 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")
Main.BIDSTools.get_metadata_path
— Methodfunction get_metadata_path(path)
Get file path of metadata file (json sidecar) for a BIDS path
which can be a string or File
.
Main.BIDSTools.get_ses
— Methodfunction 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. Iftrue
, only looks thesession_id
from filename, otherwise, looks into full path ifsession_id
can't be found in filenamerequire_modality::Bool
- defaults totrue
. Iftrue
this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gzstrict::Bool
- defaults totrue
. Iftrue
,BIDSTools
will throw an error on invalid BIDS filename, this can be turned tofalse
to not parse those file names and display a warning instead. This will result in empty dictionary inentities
.
Returns nothing if no session ID found.
Main.BIDSTools.get_sub
— Methodfunction 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. Iftrue
, only looks thesubject_id
from filename, otherwise, looks into full path ifsubject_id
can't be found in filenamerequire_modality::Bool
- defaults totrue
. Iftrue
this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gzstrict::Bool
- defaults totrue
. Iftrue
,BIDSTools
will throw an error on invalid BIDS filename, this can be turned tofalse
to not parse those file names and display a warning instead. This will result in empty dictionary inentities
.
Returns nothing if no subject ID found.
Main.BIDSTools.list_scans_detail
— Methodfunction list_scans_detail(session::Session)
Function to pretty print scans detail spreadsheet (_scans.tsv) using PrettyTables
Main.BIDSTools.list_subject_detail
— Methodfunction list_subject_detail(layout::Layout)
Function to pretty print subject spreadsheet (subjects.tsv) using PrettyTables
Main.BIDSTools.parse_fname
— Methodfunction 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 totrue
. Iftrue
this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gzstrict::Bool
- defaults totrue
. Iftrue
,BIDSTools
will throw an error on invalid BIDS filename, this can be turned tofalse
to not parse those file names and display a warning instead. This will result in empty dictionary inentities
.
This function returns a dictionary containing those keys and values.
Main.BIDSTools.parse_path
— Methodfunction 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 totrue
. Iftrue
this expects a modality presents in every file name, e.g. sub-subtestses-1run-001_T1w.nii.gzstrict::Bool
- defaults totrue
. Iftrue
,BIDSTools
will throw an error on invalid BIDS filename, this can be turned tofalse
to not parse those file names and display a warning instead. This will result in empty dictionary inentities
.
Main.BIDSTools.print_dataset_description
— Methodfunction print_dataset_description(layout::Layout)
Function to pretty-print dataset description
Main.BIDSTools.total_files
— Methodfunction total_files(session::Session)
Get number of files in a session. The argument Session
can be changed into Subject
or Layout
.
Main.BIDSTools.total_sessions
— Methodfunction total_sessions(subject::Subject)
Get number of session of a subject. The argument Subject
can be changed into Layout
.
Main.BIDSTools.total_subjects
— Methodfunction total_subjects(layout::Layout)
Get number of subject in the layout