Package mvpa :: Package measures :: Module searchlight :: Class Searchlight
[hide private]
[frames] | no frames]

Class Searchlight

source code


Runs a scalar `DatasetMeasure` on all possible spheres of a certain size
    within a dataset.

    The idea for a searchlight algorithm stems from this paper:

      Kriegeskorte, N., Goebel, R. & Bandettini, P. (2006).
      'Information-based functional brain mapping.' Proceedings of the
      National Academy of Sciences of the United States of America 103,
      3863-3868.
    

Constructor information for `Searchlight` class
_______________________________________________

Initialize Searchlight to compute `datameasure` for each sphere with
        a certain `radius` in a given dataset.

        :Parameters:
            datameasure: callable
                Any object that takes a `Dataset` and returns some measure when
                called.
            radius: float
                All features within the radius around the center will be part
                of a sphere.
            center_ids: list(int)
                List of feature ids (not coordinates) the shall serve as sphere
                centers. By default all features will be used.
            **kwargs:
                In additions this class supports all keyword arguments of its
                base-class `DatasetMeasure`.

        ATTENTION: If `Searchlight` is used as `SensitivityAnalyzer` one has to
        make sure that the specified scalar `DatasetMeasure` returns large
        (absolute) values for high sensitivities and small (absolute) values
        for low sensitivities. Especially when using error functions usually
        low values imply high performance and therefore high sensitivity. This
        would in turn result in sensitivity maps that have low (absolute)
        values indicating high sensitivites and this conflicts with the
        intended behavior of a `SensitivityAnalyzer`.
        


Documentation for base classes of `Searchlight`
================================================

Documentation for class `DatasetMeasure`
----------------------------------------

A measure computed from a `Dataset`

    All dataset measures support arbitrary transformation of the measure
    after it has been computed. Transformation are done by processing the
    measure with a functor that is specified via the `transformer` keyword
    argument of the constructor. Upon request, the raw measure (before
    transformations are applied) is stored in the `raw_result` state variable.

    Additionally all dataset measures support the estimation of the
    probabilit(y,ies) of a measure under some distribution. Typically this will
    be the NULL distribution (no signal), that can be estimated with
    permutation tests. If a distribution estimator instance is passed to the
    `null_dist` keyword argument of the constructor the respective
    probabilities are automatically computed and stored in the `null_prob`
    state variable.

    :Developer note:
      All subclasses shall get all necessary parameters via their constructor,
      so it is possible to get the same type of measure for multiple datasets
      by passing them to the __call__() method successively.
    

Constructor information for `DatasetMeasure` class
__________________________________________________

Does nothing special.

        :Parameter:
          transformer: Functor
            This functor is called in `__call__()` to perform a final
            processing step on the to be returned dataset measure. If None,
            nothing is called
          null_dist : instance of distribution estimator
        


Documentation for base classes of `DatasetMeasure`
===================================================

Documentation for class `Stateful`
----------------------------------

Base class for stateful objects.

    Classes inherited from this class gain ability to provide state
    variables, accessed as simple properties. Access to state variables
    "internals" is done via states property and interface of
    `StateCollection`.

    NB This one is to replace old State base class
    TODO: rename 'descr'? -- it should simply
          be 'doc' -- no need to drag classes docstring imho.
    

Nested Classes [hide private]

Inherited from misc.state.Stateful: __metaclass__

Instance Methods [hide private]
 
__init__(self, datameasure, radius=1.0, center_ids=None, **kwargs)
Initialize Searchlight to compute datameasure for each sphere with a certain radius in a given dataset.
source code
 
_call(self, dataset)
Perform the spheresearch.
source code

Inherited from base.DatasetMeasure: __call__, __str__

Inherited from base.DatasetMeasure (private): _postcall

Inherited from misc.state.Stateful: __getattribute__, __repr__, __setattr__, reset

Inherited from object: __delattr__, __hash__, __new__, __reduce__, __reduce_ex__

Class Variables [hide private]
  spheresizes = StateVariable(enabled= False, doc= "Number of fe...
  __doc__ = enhancedDocString('Searchlight', locals(), DatasetMe...
  _collections_template = {'states': <mvpa.misc.state.StateColle...

Inherited from base.DatasetMeasure: null_prob, raw_result

Inherited from misc.state.Stateful (private): _initargs

Properties [hide private]

Inherited from misc.state.Stateful: descr

Inherited from object: __class__

Method Details [hide private]

__init__(self, datameasure, radius=1.0, center_ids=None, **kwargs)
(Constructor)

source code 

Initialize Searchlight to compute datameasure for each sphere with a certain radius in a given dataset.

ATTENTION: If Searchlight is used as SensitivityAnalyzer one has to make sure that the specified scalar DatasetMeasure returns large (absolute) values for high sensitivities and small (absolute) values for low sensitivities. Especially when using error functions usually low values imply high performance and therefore high sensitivity. This would in turn result in sensitivity maps that have low (absolute) values indicating high sensitivites and this conflicts with the intended behavior of a SensitivityAnalyzer.

Parameters:
  • enable_states - Names of the state variables which should be enabled additionally to default ones
  • disable_states - Names of the state variables which should be disabled
  • descr - Description of the instance
Overrides: object.__init__

Parameters:

datameasure: callable
Any object that takes a Dataset and returns some measure when called.
radius: float
All features within the radius around the center will be part of a sphere.
center_ids: list(int)
List of feature ids (not coordinates) the shall serve as sphere centers. By default all features will be used.
**kwargs:
In additions this class supports all keyword arguments of its base-class DatasetMeasure.

_call(self, dataset)

source code 
Perform the spheresearch.
Overrides: base.DatasetMeasure._call

Class Variable Details [hide private]

spheresizes

Value:
StateVariable(enabled= False, doc= "Number of features in each sphere.\
")

__doc__

Value:
enhancedDocString('Searchlight', locals(), DatasetMeasure)

_collections_template

Value:
{'states': <mvpa.misc.state.StateCollection object at 0x8ca3a8c>}