PESTICA-AFNI-v1.2 release Nov 18, 2010

NOTE TO USERS: the ICA decomposition of a 128x128x31 brain dataset 
will require approx 2-4 hours. This is resolution and CPU speed dependent.
SETUP requires modifying setup_pestica.sh, and then sourcing it once in your
.bashrc or login, like so:
source setup_pestica.sh (you can modify the path to this script)
then, the only other tools you'll need are (in order): 
1. run_pestica_ica.sh
2. run_pestica_est.sh
3. filter_pestica_est.sh
4. run_irfret.sh
Give it a whirl and feel free to contact me with any questions (see below).

PESTICA is a software package that will take EPI data files and produce a
representation of cardiac and respiratory noise (separately) that are roughly
equivalent to parallel monitored pulse and respiration data.  

The AFNI-version of PESTICA only supports PESTICA2, but this is the far more
useful case.  PESTICA1 corresponds to intra-subject estimation (i.e. you've
got pulse ox for scan1 of subject but not for scan2, and PESTICA1 uses
scan1 to create pulse and respiration signals for scan2). PESTICA2
corresponds to inter-subject estimation and is useful when no physiologic 
data exists, as it is (mostly) subject-independent. The resulting estimates
must be filtered and detrended on a case-by-case basis for the best results,
typically these estimators are used as input to RETROICOR, which only requires
the periodicity of those noise sources to be correct.  With this in mind, base
your filtering of the estimates on getting the periodicity alone correct.  You
cannot be certain that PESTICA works unless you validate it at your site with a
few scans taken with parallel measured physiologic data; the template noise 
matrices may be scanner and sequence dependent, although they have been tested 
at TR=250Hz, 2000Hz, 2800Hz, with/without partial Fourier, 2mm in-plane voxels 
versus 4mm voxels, but with TE=29ms in each case (for a 3T Siemens scanner).

To run PESTICA, source the setup file after configuring it to match your local
setup. Hand-edit the file setup_pestica.sh to reflect base directory of this
software directory (the current working directory).

	. setup_pestica.sh

Once matlab is started, the PESTICA ICA decomposition creates a subdirectory in the
current working directory named "pestica/" where all temporary files are stored.
Due to the high computational demands, the temporary files are not deleted.

------------------------------------Details------------------------------------
Caveats: phase encoding must be in AP direction, data must be acquired as EPI
slices with nearly any arbitrary slice timing.  However, a minimal temporal
coverage of the underlying cardiac and respiratory sources must still be met at
~4Hz and ~1Hz for cardiac and respiration respectively.  

PESTICA2
Step 1: run temporal ICA, saving each slice
Step 2: registration to TLRC'ed EPI template with 3dAllineate, using EPI image
Step 3: correlate each component with the coregistered average cardiac/
        respiratory slice to identify likely components
Step 4: re-interleave by slice acquisition timing (default interleaved ascend)
Step 5: examine estimators and apply various filtering and detrending 
	settings with the goal of getting periodicity of physiologic cycles 
	correct, not necessarily the amplitude variations (to be done by user)

There is a manuscript detailing the algorithm:
Beall, E.B.; Lowe, M.J. "Isolating physiologic noise sources with independently
determined spatial measures." NeuroImage. v. 37 p. 1286-1300. 2007

----------------------------Additional software--------------------------------
I have added software to do more efficient correction of physiologic noise.
The physiologic noise signatures are actually very consistent from voxel to 
voxel but in most voxels the physiologic noise plus thermal noise makes this
difficult to see.  If you take RETROICOR's coupling coefficients at each voxel
and convert these into the effect over one heart beat or over one breathing cycle
you'll see a small plurality of consistent responses.  It appears that physiologic
noise isn't the same everywhere but splits into a small degeneracy of responses
depending on where in the brain you're looking (e.g. all arteries have similar response,
all CSF spaces have similar response, etc).  This software is called IRF-RETROICOR and
is described in an e-poster at ISMRM2010 and in the following manuscript:
Beall, E.B. "Adaptive cyclic physiologic noise modeling and correction in functional 
MRI." J Neurosci Methods. 2010 Mar 30;187(2):216-28.

The method starts with a matlab implementation of RETROICOR and uses PCA to determine
this small plurality of "impulse response functions" (hence, IRF) for physiologic noise.
The idea of IRF is based on the idea that each heart beat is assumed to be identical 
in temporal shape ___with respect to the relative phase within the heart cycle___.
The same goes for respiration, albeit there is assumed to be an amplitude modulation.
However, my software discards the amplitude modulation for respiration, with only
selfish reasons (Siemens EPI sequence incorporates the DORK correction, which "resets"
the relative field shift due to breathing at every volume, destroying the temporal
correspondence between amplitude of breathing and apparent image shift/partial voluming 
in the phase-encode direction.  To be accurate it doesn't destroy it, but you'd need to
know the DORK correction shift-value to disambiguate its effects on the regressor.
The validation of PESTICA and IRF-RETROICOR shows that ignoring the amplitude for
respiration is sufficient for Siemens scanners with cartesian EPI. This should be
investigated further (perhaps with amplitude modulation in 3dDeconvolve).

If you find this package useful and would like to use it in your analyses,
please cite the manuscript.  If you'd like more details, please read the
manuscript and feel free to contact the authors for pdfs or any questions:
Erik Beall
ebeall@gmail.com

*******************************************************************************
Changelog

*******************************************************************************
Nov 18th, 2010:
Version 1.2
Added matlab support for AFNI_matlab reading and writing of BRIK and NII files.
The intent of this release is as a general-purpose AFNI-compatible distribution
that people won't have to muck with their file formats as much.

*******************************************************************************
Apr 20th, 2010:
Version 1.1 (version numbers are as on the NITRC download page)
Added support for some AFNI utilities, mainly 3dAllineate and modification of
templates for use with AFNI. Using NIFTI_PAIR format for all images and matlab's
analyze75read() and info() functions (rotates the images by 90 degrees).

*******************************************************************************
Dec 11th, 2008:
Version 1.0b
modifications to assemble+disassemble scripts to handle Siemens even number of
slices, also unified how they get the slice timing, it is more correct now and
takes account of offset by TE (aproximate, look at a pulse sequence timing
to see how far after the trigger pulse is the center of k-space, which is 
probably more like 5-10msec extra for fatsat and dephasing)

*******************************************************************************
Oct 15th, 2008:
Version 1.0a
New PESTICA templates created, new stddev warping templates created, scripts
for making new templates added, assemble+disassemble scripts modified to use
arbitrary slice timing (validated). Code for performing RETROICOR correction
added (and slice-common signal regression and second-order motion correction).
Modification to allow a discard of initial volumes in prepare_ICA_decomp(),
other scripts detect discarded volumes and adjust automatically. However,
if using PESTICA1, any input physiologic data must be adjusted manually to
account for any discarded initial acquisitions.

*******************************************************************************
Sept 25th, 2007:
Version 1
New PESTICA templates, scripts validated on axial, interleaved ascending EPI 
2x2x4mm and 4x4x4mm datasets.

