tedana.utils.io

Functions to handle file input/output

Functions

ctabsel(ctabfile) Loads a pre-existing component table file
gscontrol_mmix(optcom_ts, mmix, mask, acc, …) Perform global signal regression.
split_ts(data, mmix, mask, acc) Splits data time series into accepted component time series and remainder
write_split_ts(data, mmix, mask, acc, rej, …) Splits data into denoised / noise / ignored time series and saves to disk
writect(comptable, n_vols, fixed_seed, acc, …) Saves component table to disk
writefeats(data, mmix, mask, ref_img[, suffix]) Converts data to component space with mmix and saves to disk
writeresults(ts, mask, comptable, mmix, …) Denoises ts and saves all resulting files to disk
writeresults_echoes(catd, mmix, mask, acc, …) Saves individually denoised echos to disk
ctabsel(ctabfile)[source]

Loads a pre-existing component table file

Parameters:ctabfile (str) – Filepath to existing component table
Returns:ctab – Tuple containing arrays of (1) accepted, (2) rejected, (3) mid, and (4) ignored components
Return type:(4,) tuple of numpy.ndarray
gscontrol_mmix(optcom_ts, mmix, mask, acc, ref_img)[source]

Perform global signal regression.

Parameters:
  • optcom_ts ((S x T) array_like) – Optimally combined time series data
  • mmix ((C x T) array_like) – Mixing matrix for converting input data to component space, where C is components and T is the same as in optcom_ts
  • mask ((S,) array_like) – Boolean mask array
  • acc (list) – Indices of accepted (BOLD) components in mmix
  • ref_img (str or img_like) – Reference image to dictate how outputs are saved to disk

Notes

This function writes out several files:

Filename Content
sphis_hik.nii T1-like effect.
hik_ts_OC_T1c.nii T1 corrected time series.
dn_ts_OC_T1c.nii Denoised version of T1 corrected time series
betas_hik_OC_T1c.nii T1-GS corrected components
meica_mix_T1c.1D T1-GS corrected mixing matrix
split_ts(data, mmix, mask, acc)[source]

Splits data time series into accepted component time series and remainder

Parameters:
  • data ((S x T) array_like) – Input data, where S is samples and T is time
  • mmix ((T x C) array_like) – Mixing matrix for converting input data to component space, where C is components and T is the same as in data
  • mask ((S,) array_like) – Boolean mask array
  • acc (list) – List of accepted components used to subset mmix
Returns:

  • hikts ((S x T) numpy.ndarray) – Time series reconstructed using only components in acc
  • rest ((S x T) numpy.ndarray) – Original data with hikts removed
write_split_ts(data, mmix, mask, acc, rej, midk, ref_img, suffix='')[source]

Splits data into denoised / noise / ignored time series and saves to disk

Parameters:
  • data ((S x T) array_like) – Input time series
  • mmix ((C x T) array_like) – Mixing matrix for converting input data to component space, where C is components and T is the same as in data
  • mask ((S,) array_like) – Boolean mask array
  • acc (list) – Indices of accepted (BOLD) components in mmix
  • rej (list) – Indices of rejected (non-BOLD) components in mmix
  • midk (list) – Indices of mid-K (questionable) components in mmix
  • ref_img (str or img_like) – Reference image to dictate how outputs are saved to disk
  • suffix (str, optional) – Appended to name of saved files (before extension). Default: ‘’
Returns:

varexpl – Percent variance of data explained by extracted + retained components
Return type:

float

Notes

This function writes out several files:

Filename Content
hik_ts_[suffix].nii High-Kappa time series.
midk_ts_[suffix].nii Mid-Kappa time series.
low_ts_[suffix].nii Low-Kappa time series.
dn_ts_[suffix].nii Denoised time series.
writect(comptable, n_vols, fixed_seed, acc, rej, midk, empty, ctname='comp_table.txt', varexpl='-1')[source]

Saves component table to disk

Parameters:
  • comptable ((N x 5) array_like) – Array with columns denoting (1) index of component, (2) Kappa score of component, (3) Rho score of component, (4) variance explained by component, and (5) normalized variance explained by component
  • n_vols (int) – Number of volumes in original time series
  • fixed_seed (int) – Integer value used in seeding ICA
  • acc (list) – Indices of accepted (BOLD) components in mmix
  • rej (list) – Indices of rejected (non-BOLD) components in mmix
  • midk (list) – Indices of mid-K (questionable) components in mmix
  • empty (list) – Indices of ignored components in mmix
  • ctname (str, optional) – Filename to save comptable to disk. Default ‘comp_table.txt’
  • varexpl (str) – Variance explained by original data

Notes

This function writes out several files:

Filename Content
accepted.txt A comma-separated list of the accepted component indices.
rejected.txt A comma-separated list of the rejected component indices.
midk_rejected.txt A comma-separated list of middle-kappa components which were ultimately rejected.
[ctname] (comp_table.txt) Component table file.
writefeats(data, mmix, mask, ref_img, suffix='')[source]

Converts data to component space with mmix and saves to disk

Parameters:
  • data ((S x T) array_like) – Input time series
  • mmix ((C x T) array_like) – Mixing matrix for converting input data to component space, where C is components and T is the same as in data
  • mask ((S,) array_like) – Boolean mask array
  • ref_img (str or img_like) – Reference image to dictate how outputs are saved to disk
  • suffix (str, optional) – Appended to name of saved files (before extension). Default: ‘’
Returns:

fname – Filepath to saved file
Return type:

str

Notes

This function writes out a file:

Filename Content
feats_[suffix].nii Z-normalized spatial component maps.
writeresults(ts, mask, comptable, mmix, n_vols, fixed_seed, acc, rej, midk, empty, ref_img)[source]

Denoises ts and saves all resulting files to disk

Parameters:
  • ts ((S x T) array_like) – Time series to denoise and save to disk
  • mask ((S,) array_like) – Boolean mask array
  • comptable ((N x 5) array_like) – Array with columns denoting (1) index of component, (2) Kappa score of component, (3) Rho score of component, (4) variance explained by component, and (5) normalized variance explained by component
  • mmix ((C x T) array_like) – Mixing matrix for converting input data to component space, where C is components and T is the same as in data
  • n_vols (int) – Number of volumes in original time series
  • fixed_seed (int) – Integer value used in seeding ICA
  • acc (list) – Indices of accepted (BOLD) components in mmix
  • rej (list) – Indices of rejected (non-BOLD) components in mmix
  • midk (list) – Indices of mid-K (questionable) components in mmix
  • empty (list) – Indices of ignored components in mmix
  • ref_img (str or img_like) – Reference image to dictate how outputs are saved to disk

Notes

This function writes out several files:

Filename Content
ts_OC.nii Optimally combined 4D time series.
hik_ts_OC.nii High-Kappa time series. Generated by tedana.utils.io.write_split_ts().
midk_ts_OC.nii Mid-Kappa time series. Generated by tedana.utils.io.write_split_ts().
low_ts_OC.nii Low-Kappa time series. Generated by tedana.utils.io.write_split_ts().
dn_ts_OC.nii Denoised time series. Generated by tedana.utils.io.write_split_ts().
betas_OC.nii Full ICA coefficient feature set.
betas_hik_OC.nii Denoised ICA coefficient feature set.
feats_OC2.nii Z-normalized spatial component maps. Generated by tedana.utils.io.writefeats().
comp_table.txt Component table. Generated by tedana.utils.io.writect().
writeresults_echoes(catd, mmix, mask, acc, rej, midk, ref_img)[source]

Saves individually denoised echos to disk

Parameters:
  • catd ((S x E x T) array_like) – Input data time series
  • mmix ((C x T) array_like) – Mixing matrix for converting input data to component space, where C is components and T is the same as in data
  • mask ((S,) array_like) – Boolean mask array
  • acc (list) – Indices of accepted (BOLD) components in mmix
  • rej (list) – Indices of rejected (non-BOLD) components in mmix
  • midk (list) – Indices of mid-K (questionable) components in mmix
  • ref_img (str or img_like) – Reference image to dictate how outputs are saved to disk

Notes

This function writes out several files:

Filename Content
hik_ts_e[echo].nii High-Kappa timeseries for echo number echo. Generated by tedana.utils.io.write_split_ts().
midk_ts_e[echo].nii Mid-Kappa timeseries for echo number echo. Generated by tedana.utils.io.write_split_ts().
lowk_ts_e[echo].nii Low-Kappa timeseries for echo number echo. Generated by tedana.utils.io.write_split_ts().
dn_ts_e[echo].nii Denoised timeseries for echo number echo. Generated by tedana.utils.io.write_split_ts().