====== ztrans ======

===== Motivation =====
Under certain circumstances (e.g. data that is arbitrarily scaled and comes from several sources has to be compared), one way to normalize (re-scale) the data is to apply z-transformation (setting the mean of values in the desired dimension to 0 and the standard deviation to 1).

===== Function reference ('help ztrans') =====
<file>  ztrans  - perform z-transformation on time course
 
  FORMAT:       [ztc, zf, zsh] = ztrans(tc [, dim [, tp]])
 
  Input fields:
 
        tc          time course data
        dim         temporal dimension (default: first non-singleton)
        tp          time points (indices of dim to use for normalization)
 
  Output fields:
 
        ztc         z-transformed time course
        zf          z-transformation factor
        zsh         z-transformation shift
 
  See also psctrans</file>

===== Usage examples =====
  * z-transforming a single time-course (e.g. of a region or voxel):<code matlab>ztc = ztrans(tc);</code>
  * z-transformation of an entire VTC (ensuring that dimension is 1):<code matlab>vtc.VTCData = ztrans(vtc.VTCData, 1);</code>
  * z-transformation of 4D-NII VoxelData (ensuring that dimension is 4):<code matlab>nii.VoxelData = ztrans(nii.VoxelData, 4);</code>
  * also obtaining the information about the scaling factor and shift:<code matlab>[ztc, zfactor, zshift] = ztrans(tc);</code>
  * only using values where no experimental condition in an SDM is active:<code matlab>% find timepoints to use
tp = all(abs(sdm.SDMMatrix(:, 1:sdm.FirstConfoundPredictor-1)) < 0.1, 2);

% apply z-transformation with those as normalization basis
vtc.VTCData = ztrans(vtc.VTCData, 1, tp);</code>