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
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
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
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
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".
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")
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
.
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.
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.
BIDSTools.list_scans_detail
— Methodfunction list_scans_detail(session::Session)
Function to pretty print scans detail spreadsheet (_scans.tsv) using PrettyTables
BIDSTools.list_subject_detail
— Methodfunction list_subject_detail(layout::Layout)
Function to pretty print subject spreadsheet (subjects.tsv) using PrettyTables
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.
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
.
BIDSTools.print_dataset_description
— Methodfunction print_dataset_description(layout::Layout)
Function to pretty-print dataset description
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
.
BIDSTools.total_sessions
— Methodfunction total_sessions(subject::Subject)
Get number of session of a subject. The argument Subject
can be changed into Layout
.
BIDSTools.total_subjects
— Methodfunction total_subjects(layout::Layout)
Get number of subject in the layout
BIDSTools.check_entities_meta
— Methodfunction check_entities_meta(file::File; kws...)
Private function to check whether keywords argument in metadata or in entities. Return false if the key could not be found anywhere or the value of given key is not the same.