man pymvpa2-preproc (1): apply preprocessing steps to a PyMVPA dataset

SYNOPSIS

pymvpa2 ,preproc /[,--version/] [,-h/] ,-i DATASET /[,DATASET /...] [,--chunks CHUNKS_ATTR/] [,--strip-invariant-features/] [,--poly-detrend DEG/] [,--detrend-chunks CHUNKS_ATTR/] [,--detrend-coords COORDS_ATTR/] [,--detrend-regrs ATTR /[,ATTR /...]] [,--filter-passband FREQ /[,FREQ /...]] [,--filter-stopband FREQ /[,FREQ /...]] [,--sampling-rate FREQ/] [,--filter-passloss dB/] [,--filter-stopattenuation dB/] [,--zscore/] [,--zscore-chunks CHUNKS_ATTR/] [,--zscore-params PARAM PARAM/] ,-o OUTPUT /[,--hdf5-compression TYPE/]

DESCRIPTION

Preprocess a PyMVPA dataset.

This command can apply a number of preprocessing steps to a dataset. Currently supported are

1. Polynomial de-trending

2. Spectral filtering

3. Feature-wise Z-scoring

All preprocessing steps are applied in the above order. If a different order is required, preprocessing has to be split into two separate command calls.

POLYNOMIAL DE-TRENDING

This type of de-trending can be used to regress out arbitrary signals. In addition to polynomials of any degree arbitrary timecourses stored as sample attributes in a dataset can be used as confound regressors. This detrending functionality is, in contrast to the implementation of spectral filtering, also applicable to sparse-sampled data with potentially irregular inter-sample intervals.

SPECTRAL FILTERING

Several option are provided that are used to construct a Butterworth low-, high-, or band-pass filter. It is advised to inspect the filtered data carefully as inappropriate filter settings can lead to unintented side-effect. Only dataset with a fixed sampling rate are supported. The sampling rate must be provided.

OPTIONS

--version: show program's version and license information and exit
-h, --help, --help-np: show this help message and exit. --help-np forcefully disables the use of a pager for displaying the help.
-i DATASET [DATASET ...], --input DATASET [DATASET ...]: path(s) to one or more PyMVPA dataset files. All datasets will be merged into a single dataset (vstack'ed) in order of specification. In some cases this option may need to be specified more than once if multiple, but separate, input datasets are required.

Common options for all preprocessing:

--chunks CHUNKS_ATTR: shortcut option to enabled uniform chunkwise processing for all relevant preprocessing steps (see --zscore-chunks, --detrend-chunks). This global setting can be overwritten by additionally specifying the corresponding individual "chunk" options.
--strip-invariant-features: After all pre-processing steps are done, strip all invariant features from the dataset.

Options for data detrending:

--poly-detrend DEG: Order of the Legendre polynomial to remove from the data. This will remove every polynomial up to and including the provided value. For example, 3 will remove 0th, 1st, 2nd, and 3rd order polynomials from the data. np.B.: The 0th polynomial is the baseline shift, the 1st is the linear trend. If you specify a single int and the `chunks_attr` parameter is not None, then this value is used for each chunk. You can also specify a different polyord value for each chunk by providing a list or ndarray of polyord values with the length equal to the number of chunks. Constraints: value must be convertible to type 'int'. [Default: 1]
--detrend-chunks CHUNKS_ATTR: If None, the whole dataset is detrended at once. Otherwise, the given samples attribute (given by its name) is used to define chunks of the dataset that are processed individually. In that case, all the samples within a chunk should be in contiguous order and the chunks should be sorted in order from low to high -- unless the dataset provides information about the coordinate of each sample in the space that should be spanned be the polynomials (see `space` argument). Constraints: value must be `None`, or value must be a string. [Default: None]
--detrend-coords COORDS_ATTR: name of a samples attribute that is added to the preprocessed dataset storing the coordinates of each sample in the space spanned by the polynomials. If an attribute of such name is already present in the dataset its values are interpreted as sample coordinates in the space spanned by the polynomials. This can be used to detrend datasets with irregular sample spacing.
--detrend-regrs ATTR [ATTR ...]: List of sample attribute names that should be used as additional regressors. An example use would be to regress out motion parameters. Constraints: value must be `None`, or value must be convertible to list(str). [Default: None]

Options for spectral filtering:

--filter-passband FREQ [FREQ ...]: critical frequencies of a Butterworth filter's pass band. Critical frequencies need to match the unit of the specified sampling rate (see: --sampling-rate). In case of a band pass filter low and high frequency cutoffs need to be specified (in this order). For low and high-pass filters is single cutoff frequency must be provided. The type of filter (low/high-pass) is determined from the relation to the stop band frequency (--filter-stopband).
--filter-stopband FREQ [FREQ ...]: Analog setting to --filter-passband for specifying the filter's stop band.
--sampling-rate FREQ: sampling rate of the dataset. All frequency specifications need to match the unit of the sampling rate.
--filter-passloss dB: maximum loss in the passband (dB). Default: 1 dB
--filter-stopattenuation dB: minimum attenuation in the stopband (dB). Default: 30 dB

Options for data normalization:

--zscore: perform feature normalization by Z-scoring.
--zscore-chunks CHUNKS_ATTR: name of a dataset sample attribute defining chunks of samples that shall be Z-scored independently. By default no chunk-wise normalization is done.
--zscore-params PARAM PARAM: define a fixed parameter set (mean, std) for Z-scoring, instead of computing from actual data.

Output options:

-o OUTPUT, --output OUTPUT: output filename ('.hdf5' extension is added automatically if necessary). NOTE: The output format is suitable for data exchange between PyMVPA commands, but is not recommended for long-term storage or exchange as its specific content may vary depending on the actual software environment. For long-term storage consider conversion into other data formats (see 'dump' command).
--hdf5-compression TYPE: compression type for HDF5 storage. Available values depend on the specific HDF5 installation. Typical values are: 'gzip', 'lzf', 'szip', or integers from 1 to 9 indicating gzip compression levels.

EXAMPLES

Normalize all features in a dataset by Z-scoring

: $ pymvpa2 preproc --zscore -o ds_preprocessed -i dataset.hdf5

Perform Z-scoring and quadratic detrending of all features, but process all samples sharing a unique value of the "chunks" sample attribute individually

: $ pymvpa2 preproc --chunks "chunks" --poly-detrend 2 --zscore -o ds_pp2 -i ds.hdf5

AUTHOR

Written by Michael Hanke & Yaroslav Halchenko, and numerous other contributors.

COPYRIGHT

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.