NAME

       pymvpa2-searchlight -  traveling ROI analysis

SYNOPSIS

       pymvpa2   searchlight   [--version]  [-h]  -i  DATASET  [DATASET  ...]  --payload  PAYLOAD
       --neighbors  SPEC  [--nproc  NPROC]  [--multiproc-backend  {native,hdf5}]  [--aggregate-fx
       AGGREGATE_FX]  [--ds-preproc-fx DS_PREPROC_FX] [--enable-ca NAME [NAME ...]] [--disable-ca
       NAME [NAME ...]] [--scatter-rois  SPEC]  [--roi-attr  ATTR/EXPR  [ATTR/EXPR  ...]]  [--cv-
       learner     CV_LEARNER]     [--cv-learner-space     CV_LEARNER_SPACE]    [--cv-partitioner
       CV_PARTITIONER]  [--cv-errorfx  CV_ERRORFX]   [--cv-avg-datafold-results]   [--cv-balance-
       training  CV_BALANCE_TRAINING]  [--cv-sampling-repetitions CV_SAMPLING_REPETITIONS] [--cv-
       permutations CV_PERMUTATIONS] [--cv-prob-tail {left,right}] -o OUTPUT  [--hdf5-compression
       TYPE]

DESCRIPTION

       Traveling ROI analysis

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.

   Options for searchlight setup:
       --payload PAYLOAD
              switch to select a particular analysis type to be run in a searchlight fashion on a
              dataset. Depending on the choice  the  corresponding  analysis  setup  options  are
              evaluated.  'cv'  computes a cross-validation analysis. Alternatively, the argument
              to this option can also be a script filename in which a  custom  measure  is  built
              that is then ran as a searchlight.

       --neighbors SPEC
              define  the  size  and shape of an ROI with respect to a center/seed location. If a
              single integer number is given, it is interpreted as the radius (in number of  grid
              elements)  around  a  seed  location.  By default grid coordinates for features are
              taken from a 'voxel_indices' feature attribute in the input dataset. If coordinates
              shall  be  taken  from a different attribute, the radius value can be prefixed with
              the attribute name, i.e. 'altcoords:2'. For ROI shapes  other  than  spheres  (with
              potentially  additional  parameters), the shape name can be specified as well, i.e.
              'voxel_indices:HollowSphere:3:2'.    All    neighborhood    objects    from     the
              mvpa2.misc.neighborhood  module  are  supported.  For  custom ROI shapes it is also
              possible to pass a script filename, or  an  attribute  name  plus  script  filename
              combination,  i.e.   'voxel_indices:myownshape.py'  (advanced).  It  is possible to
              specify this option multiple times to define  multi-space  ROI  shapes  for,  e.g.,
              spatiotemporal searchlights.

       --nproc NPROC
              Use the specific number or worker processes for computing.

       --multiproc-backend {native,hdf5}
              Specifies  the  way  results  are  provided back from a processing block in case of
              --nproc > 1. 'native' is pickling/unpickling of results,  while  'hdf5'  uses  HDF5
              based file storage. 'hdf5' might be more time and memory efficient in some cases.

       --aggregate-fx AGGREGATE_FX
              use a custom result aggregation function for the searchlight

       --ds-preproc-fx DS_PREPROC_FX
              custom preprocessing function to be applied immediately after loading the data

   Options for conditional attributes:
       --enable-ca NAME [NAME ...]
              list of conditional attributes to be enabled

       --disable-ca NAME [NAME ...]
              list of conditional attributes to be disabled

   Options for constraining the searchlight:
       --scatter-rois SPEC
              scatter  ROI  locations across the available space. The arguments supported by this
              option are identical to those of --neighbors. ROI  locations  are  randomly  picked
              from  all possible locations with the constraint that the center coordinates of any
              ROI is NOT within the neighborhood (as defined by  this  option's  argument)  of  a
              second  ROI.  Increasing  the  size  of  the  neighborhood  therefore increases the
              scarceness of the sampling.

       --roi-attr ATTR/EXPR [ATTR/EXPR ...]
              name  of  a  feature  attribute  whose  non-zero   values   define   possible   ROI
              seeds/centers. Alternatively, this can also be an expression like: parcellation_roi
              eq 16 (see the 'select' command on information what expressions are supported).

   Options for cross-validation setup:
       --cv-learner CV_LEARNER
              select a learner (trainable node) via its description in the learner warehouse (see
              'info' command for a listing), a colon-separated list of capabilities, or by a file
              path to a Python script that creates a classifier instance (advanced).

       --cv-learner-space CV_LEARNER_SPACE
              name of a sample attribute that defines the model to be learned by  a  learner.  By
              default this is an attribute named 'targets'.

       --cv-partitioner CV_PARTITIONER
              select  a  data  folding  scheme.  Supported  arguments  are: 'half' for split-half
              partitioning, 'oddeven' for partitioning into odd and even chunks, 'group-X'  where
              X  can  be  any positive integer for partitioning in X groups, 'n-X' where X can be
              any positive integer for leave-X-chunks out partitioning. By  default  partitioners
              operate on dataset chunks that are defined by a 'chunks' sample attribute. The name
              of the "chunking" attribute can be changed by appending a colon and the name of the
              attribute  (e.g.  'oddeven:run'). optionally an argument to this option can also be
              a file path  to  a  Python  script  that  creates  a  custom  partitioner  instance
              (advanced).

       --cv-errorfx CV_ERRORFX
              error   function   to   be   applied   to  the  targets  and  predictions  of  each
              cross-validation data fold. This can either be a name  of  any  error  function  in
              PyMVPA's  mvpa2.misc.errorfx module, or a file path to a Python script that creates
              a custom error function (advanced).

       --cv-avg-datafold-results
              average result values across data folds generated by the partitioner.  For  example
              to compute a mean prediction error across all folds of a crossvalidation procedure.

       --cv-balance-training CV_BALANCE_TRAINING
              If  enabled,  training  samples  are balanced within each data fold. If the keyword
              'equal' is given as argument an equal number of  random  samples  for  each  unique
              target  value  is  chosen.  The number of samples per category is determined by the
              category with the least number of  samples  in  the  respective  training  set.  An
              integer  argument  will cause the a corresponding number of samples per category to
              be randomly selected. A floating point number argument (interval  [0,1])  indicates
              what fraction of the available samples shall be selected.

       --cv-sampling-repetitions CV_SAMPLING_REPETITIONS
              If  training  set balancing is enabled, how often should random sample selection be
              performed for each data fold. Default: 1

       --cv-permutations CV_PERMUTATIONS
              Number of Monte-Carlo  permutation  runs  to  be  computed  for  estimating  an  H0
              distribution  for  all  crossvalidation  results.  Enabling  this  option will make
              reports of corresponding p-values available in the result summary and output.

       --cv-prob-tail {left,right}
              which tail of the probability distribution to report p-values from when  evaluating
              permutation test results. For example, a cross-validation computing mean prediction
              error could report left-tail p-value for a single-sided test.

   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.

AUTHOR

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

COPYRIGHT

       Copyright © 2006-2015 PyMVPA developers

       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.