tedana.decomposition.tedpca

tedpca(data_cat, data_oc, combmode, mask, t2s, t2sG, ref_img, tes, algorithm='mle', source_tes=-1, kdaw=10.0, rdaw=1.0, out_dir='.', verbose=False, low_mem=False)[source]

Use principal components analysis (PCA) to identify and remove thermal noise from multi-echo data.

Parameters:
  • data_cat ((S x E x T) array_like) – Input functional data
  • data_oc ((S x T) array_like) – Optimally combined time series data
  • combmode ({'t2s', 'paid'} str) – How optimal combination of echos should be made, where ‘t2s’ indicates using the method of Posse 1999 and ‘paid’ indicates using the method of Poser 2006
  • mask ((S,) array_like) – Boolean mask array
  • t2s ((S,) array_like) – Map of voxel-wise T2* estimates.
  • t2sG ((S,) array_like) – Map of voxel-wise T2* estimates.
  • ref_img (str or img_like) – Reference image to dictate how outputs are saved to disk
  • tes (list) – List of echo times associated with data_cat, in milliseconds
  • algorithm ({'mle', 'kundu', 'kundu-stabilize'}, optional) – Method with which to select components in TEDPCA. Default is ‘mle’.
  • source_tes (int or list of int, optional) – Which echos to use in PCA. Values -1 and 0 are special, where a value of -1 will indicate using the optimal combination of the echos and 0 will indicate using all the echos. A list can be provided to indicate a subset of echos. Default: -1
  • kdaw (float, optional) – Dimensionality augmentation weight for Kappa calculations. Must be a non-negative float, or -1 (a special value). Default is 10.
  • rdaw (float, optional) – Dimensionality augmentation weight for Rho calculations. Must be a non-negative float, or -1 (a special value). Default is 1.
  • out_dir (str, optional) – Output directory.
  • verbose (bool, optional) – Whether to output files from fitmodels_direct or not. Default: False
  • low_mem (bool, optional) – Whether to use incremental PCA (for low-memory systems) or not. Default: False
Returns:

  • kept_data ((S x T) numpy.ndarray) – Dimensionally reduced optimally combined functional data
  • n_components (int) – Number of components retained from PCA decomposition

Notes

Notation Meaning
\kappa Component pseudo-F statistic for TE-dependent (BOLD) model.
\rho Component pseudo-F statistic for TE-independent (artifact) model.
v Voxel
V Total number of voxels in mask
\zeta Something
c Component
p Something else

Steps:

  1. Variance normalize either multi-echo or optimally combined data, depending on settings.

  2. Decompose normalized data using PCA or SVD.

  3. Compute {\kappa} and {\rho}:

    {\kappa}_c = \frac{\sum_{v}^V {\zeta}_{c,v}^p * F_{c,v,R_2^*}}{\sum {\zeta}_{c,v}^p} {\rho}_c = \frac{\sum_{v}^V {\zeta}_{c,v}^p * F_{c,v,S_0}}{\sum {\zeta}_{c,v}^p}

  4. Some other stuff. Something about elbows.

  5. Classify components as thermal noise if they meet both of the following criteria:

    • Nonsignificant {\kappa} and {\rho}.
    • Nonsignificant variance explained.

Outputs:

This function writes out several files:

Filename Content
pcastate.pkl Values from PCA results.
comp_table_pca.txt PCA component table.
mepca_mix.1D PCA mixing matrix.