tedana.workflows.tedana_workflow

tedana_workflow(data, tes, out_dir='.', mask=None, convention='bids', prefix='', fittype='loglin', combmode='t2s', tree='tedana_orig', tedpca='aic', fixed_seed=42, maxit=500, maxrestart=10, tedort=False, gscontrol=None, no_reports=False, png_cmap='coolwarm', verbose=False, low_mem=False, debug=False, quiet=False, overwrite=False, t2smap=None, mixm=None, tedana_command=None)[source]

Run the “canonical” TE-Dependent ANAlysis workflow.

Please remember to cite DuPre et al.[1].

Parameters:

  • data (str or list of str) – Either a single z-concatenated file (single-entry list or str) or a list of echo-specific files, in ascending order.

  • tes (list) – List of echo times associated with data in milliseconds.

Other Parameters:

  • out_dir (str, optional) – Output directory.

  • mask (str or None, optional) – Binary mask of voxels to include in TE Dependent ANAlysis. Must be spatially aligned with data. If an explicit mask is not provided, then Nilearn’s compute_epi_mask function will be used to derive a mask from the first echo’s data.

  • convention ({‘bids’, ‘orig’}, optional) – Filenaming convention. bids uses the latest BIDS derivatives version (1.5.0). Default is ‘bids’.

  • prefix (str or None, optional) – Prefix for filenames generated. Default is “”

  • fittype ({‘loglin’, ‘curvefit’}, optional) – Monoexponential fitting method. ‘loglin’ uses the the default linear fit to the log of the data. ‘curvefit’ uses a monoexponential fit to the raw data, which is slightly slower but may be more accurate. Default is ‘loglin’.

  • combmode ({‘t2s’}, optional) – Combination scheme for TEs: ‘t2s’ (Posse 1999, default).

  • tree ({‘tedana_orig’, ‘meica’, ‘minimal’, ‘json file’}, optional) – Decision tree to use for component selection. Can be a packaged tree (tedana_orig, meica, minimal) or a user-supplied JSON file that matches the decision tree file specification. tedana_orig is the tree that has been distributed with tedana from the beginning and was designed to match the process in MEICA. A difference between that tree and the older MEICA was identified so the original meica tree is also included. meica will always accept the same or more components, but those accepted components are sometimes high variance so the differences can be non-trivial. Minimal is intented to be a simpler process, but it accepts and rejects some distinct components compared to the others. Testing to better understand the effects of the differences is ongoing. Default is ‘tedana_orig’.

  • tedpca ({‘mdl’, ‘aic’, ‘kic’, ‘kundu’, ‘kundu-stabilize’, float, int}, optional) – Method with which to select components in TEDPCA. If a float is provided, then it is assumed to represent percentage of variance explained (0-1) to retain from PCA. If an int is provided, it will output a fixed number of components defined by the integer between 1 and the number of time points. Default is ‘aic’.

  • fixed_seed (int, optional) – Value passed to mdp.numx_rand.seed(). Set to a positive integer value for reproducible ICA results; otherwise, set to -1 for varying results across calls.

  • maxit (int, optional) – Maximum number of iterations for ICA. Default is 500.

  • maxrestart (int, optional) – Maximum number of attempts for ICA. If ICA fails to converge, the fixed seed will be updated and ICA will be run again. If convergence is achieved before maxrestart attempts, ICA will finish early. Default is 10.

  • tedort (bool, optional) – Orthogonalize rejected components w.r.t. accepted ones prior to denoising. Default is False.

  • gscontrol ({None, ‘mir’, ‘gsr’} or list, optional) – Perform additional denoising to remove spatially diffuse noise. Default is None.

  • no_reports (obj:’bool’, optional) – Do not generate .html reports and .png plots. Default is false such that reports are generated.

  • png_cmap (obj:’str’, optional) – Name of a matplotlib colormap to be used when generating figures. Cannot be used with –no-png. Default is ‘coolwarm’.

  • verbose (bool, optional) – Generate intermediate and additional files. Default is False.

  • low_mem (bool, optional) – Enables low-memory processing, including the use of IncrementalPCA. May increase workflow duration. Default is False.

  • debug (bool, optional) – Whether to run in debugging mode or not. Default is False.

  • t2smap (str, optional) – Precalculated T2* map in the same space as the input data. Values in the map must be in seconds.

  • mixm (str or None, optional) – File containing mixing matrix, to be used when re-running the workflow. If not provided, ME-PCA and ME-ICA are done. Default is None.

  • quiet (bool, optional) – If True, suppresses logging/printing of messages. Default is False.

  • overwrite (bool, optional) – If True, force overwriting of files. Default is False.

  • tedana_command (str, optional) – If the command-line interface was used, this is the command that was run. Default is None.

Notes

This workflow writes out several files. For a complete list of the files generated by this workflow, please visit https://tedana.readthedocs.io/en/latest/outputs.html

References