.. AUTO-GENERATED FILE -- DO NOT EDIT!

.. _example_searchlight_minimal:


Minimal Searchlight Example
===========================

.. index:: searchlight, cross-validation

The term :class:`~mvpa.measures.searchlight.Searchlight` refers to an algorithm
that runs a scalar :class:`~mvpa.measures.base.DatasetMeasure` on all possible
spheres of a certain size within a dataset (that provides information about
distances between feature locations).  The measure typically computed is a
cross-validated transfer error (see :ref:`CrossValidatedTransferError
<cross-validation>`). The idea to use a searchlight as a sensitivity analyzer
on fMRI datasets stems from :ref:`Kriegeskorte et al. (2006) <KGB06>`.

A searchlight analysis is can be easily performed. This examples shows a minimal
draft of a complete analysis.

First import a necessary pieces of PyMVPA -- this time each bit individually.

::
  from mvpa.datasets.masked import MaskedDataset
  from mvpa.datasets.splitters import OddEvenSplitter
  from mvpa.clfs.svm import LinearCSVMC
  from mvpa.clfs.transerror import TransferError
  from mvpa.algorithms.cvtranserror import CrossValidatedTransferError
  from mvpa.measures.searchlight import Searchlight
  from mvpa.misc.data_generators import normalFeatureDataset
  

For the sake of simplicity, let's use a small artificial dataset.

::
  
  # overcomplicated way to generate an example dataset
  ds = normalFeatureDataset(perlabel=10, nlabels=2, nchunks=2,
                            nfeatures=10, nonbogus_features=[3, 7],
                            snr=5.0)
  dataset = MaskedDataset(samples=ds.samples, labels=ds.labels,
                          chunks=ds.chunks)
  

Now it only takes three lines for a searchlight analysis.

::
  
  # setup measure to be computed in each sphere (cross-validated
  # generalization error on odd/even splits)
  cv = CrossValidatedTransferError(
           TransferError(LinearCSVMC()),
           OddEvenSplitter())
  
  # setup searchlight with 5 mm radius and measure configured above
  sl = Searchlight(cv, radius=5)
  
  # run searchlight on dataset
  sl_map = sl(dataset)
  
  print 'Best performing sphere error:', max(sl_map)
  

If this analysis is done on a fMRI dataset using `NiftiDataset` the resulting
searchlight map (`sl_map`) can be mapped back into the original dataspace
and viewed as a brain overlay. :ref:`Another example <example_searchlight_2d>`
shows a typical application of this algorithm.

.. Mention the fact that it also is a special `SensitivityAnalyzer`

::
  
  

.. seealso::
  The full source code of this example is included in the PyMVPA source distribution (`doc/examples/searchlight_minimal.py`).
