moten.pyramids module

class moten.pyramids.DefaultPyramids[source]

Bases: object

property pyramid15fps512x512
property pyramid15fps96x96
property pyramid24fps128x72
property pyramid24fps256x144
property pyramid24fps640x480
property pyramid24fps800x600
class moten.pyramids.MotionEnergyPyramid(stimulus_vhsize=(576, 1024), stimulus_fps=24, temporal_frequencies=[0, 2, 4], spatial_frequencies=[0, 2, 4, 8, 16], spatial_directions=[0, 45, 90, 135, 180, 225, 270, 315], sf_gauss_ratio=0.6, max_spatial_env=0.3, filter_spacing=3.5, tf_gauss_ratio=10.0, max_temp_env=0.3, include_edges=False, spatial_phase_offset=0.0, filter_temporal_width='auto')[source]

Bases: object

Construct a motion energy pyramid that tiles the stimulus.

Generates motion energy filters at the desired spatio-temporal frequencies and directions of motion. Multiple motion energy filters per spatio-temporal frequency are constructed and each is centered at different locations in the image in order to tile the stimulus.

Parameters
  • stimulus_vhsize (tuple of ints) – Size of the stimulus in pixels (vdim, hdim)

  • stimulus_fps (scalar, [Hz]) – Stimulus playback speed in frames per second.

  • spatial_frequencies (array-like, [cycles-per-image]) – Spatial frequencies for the filters

  • spatial_directions (array-like, [degrees]) – Direction of filter motion. Degree position corresponds to standard unit-circle coordinates (i.e. 0=right, 180=left).

  • temporal_frequencies (array-like, [Hz]) – Temporal frequencies of the filters

  • filter_temporal_width (int) – Temporal window of the motion energy filter (e.g. 10). Defaults to approximately 0.666[secs] (floor(stimulus_fps*(2/3))).

Variables
  • nfilters (int) –

  • filters (list of dicts) –

    Each item is a dict defining a motion energy filter. Each of the nfilters has the following parameters:

    • centerv,centerh : y:vertical and x:horizontal position (‘0,0’ is top left)

    • direction : direction of motion [degrees]

    • spatial_freq : spatial frequency [cpi]

    • spatial_env : spatial envelope (gaussian s.d.)

    • temporal_freq : temporal frequency [Hz]

    • temporal_env : temporal envelope (gaussian s.d.)

    • filter_temporal_width : temporal window of filter [frames]

    • aspect_ratio : width/height

    • stimulus_fps : stimulus playback speed in frames per second

    • spatial_phase_offset : filter phase offset in [degrees]

  • parameters (dict of arrays) – The individual parameter values across all filters. Each item is an array of length nfilters

  • definition (dict) – Parameters used to define the pyramid.

  • parameters_matrix (np.array, (nfilters, 11)) – Parameters that defined the motion energy filter.

  • parameters_names (tuple of strings) –

Notes

See moten.core.mk_moten_pyramid_params() for more details on making the pyramid.

filters_at_vhposition(centerv, centerh)[source]

Center spatio-temporal filters to requested vh-position.

Parameters
  • centerv (scalar) – Vertical filter position from top of frame (min=0, max=1.0).

  • centerh (scalar) – Horizontal filter position from left of frame (min=0, max=aspect_ratio).

Returns

centered_filters – Spatio-temporal filter parameters at vh-position.

Return type

list of dicts

get_filter_mask(filterid=0)[source]

Generate a mask of the filter in the image

Parameters

filterid (int, or dict) – If int, the filter index. If dict, a filter dictionary definition

Returns

mask – Filter spatial mask

Return type

2D np.ndarray, (vdim, hdim)

get_filter_pixel_sizes()[source]

Measure the size of the each filter in the pyramid in pixels.

Returns

filter_npixels – Array containing the size of each filter in pixels.

Return type

2D np.ndarray, (nfilters,)

get_filter_spatial_quadrature(filterid=0)[source]

Generate the spatial arrays that define the motion energy filter.

Parameters

filterid (int, or dict) – If int, the filter index. If dict, a filter dictionary definition

Returns

  • spatial_gabor_sin (2D np.ndarray, (vdim, hdim))

  • spatial_gabor_cos (2D np.ndarray, (vdim, hdim)) – Spatial gabor quadrature pair. spatial_gabor_cos has a 90 degree phase offset relative to spatial_gabor_sin

get_filter_spatiotemporal_quadratures(filterid=0)[source]

Generate the spatial and temporal arrays that define the motion energy filter.

Parameters

filterid (int, or dict) – If int, the filter index. If dict, a filter dictionary definition

Returns

  • spatial_gabor_sin (2D np.ndarray, (vdim, hdim))

  • spatial_gabor_cos (2D np.ndarray, (vdim, hdim)) – Spatial gabor quadrature pair. spatial_gabor_cos has a 90 degree phase offset relative to spatial_gabor_sin

  • temporal_gabor_sin (1D np.ndarray, (filter_temporal_width,))

  • temporal_gabor_cos (1D np.ndarray, (filter_temporal_width,)) – Temporal gabor quadrature pair. temporal_gabor_cos has a 90 degree phase offset relative to temporal_gabor_sin

get_filter_temporal_quadrature(filterid=0)[source]

Generate the temporal arrays that define the motion energy filter.

Parameters

filterid (int, or dict) – If int, the filter index. If dict, a filter dictionary definition

Returns

  • temporal_gabor_sin (1D np.ndarray, (filter_temporal_width,))

  • temporal_gabor_cos (1D np.ndarray, (filter_temporal_width,)) – Temporal gabor quadrature pair. temporal_gabor_cos has a 90 degree phase offset relative to temporal_gabor_sin

project_stimulus(stimulus, filters='all', quadrature_combination=<function sqrt_sum_squares>, output_nonlinearity=<function log_compress>, dtype='float32', use_cuda=False)[source]

Compute the motion energy filter responses to the stimulus.

Parameters
  • stimulus (np.ndarray, (nimages, vdim, hdim) or (nimages, npixels)) – The movie frames. If stimulus is two-dimensional with shape (nimages, npixels), then vhsize=(vdim,hdim) is required and npixels == vdim*hdim.

  • filters (optional, 'all' or list of dicts) – By default compute the responses for all filters. Otherwise, provide a list of filter definitions to use.

  • quadrature_combination (function, optional) – Specifies how to combine the channel reponse quadratures. The function must take the sin and cos as arguments in that order. Defaults to: \((sin^2 + cos^2)^{1/2}\)

  • output_nonlinearity (function, optional) – Passes the channels (after quadrature_combination) through a non-linearity. The function input is the (nimages, nfilters) array. Defaults to: \(log(x + 1e-05)\)

Returns

filter_responses

Return type

np.ndarray, (nimages, nfilters)

raw_project_stimulus(stimulus, filters='all', dtype='float32')[source]

Obtain responses to the stimulus from all filter quadrature-pairs.

Parameters
  • stimulus (np.array, (nimages, vdim, hdim)) – The movie frames.

  • filters (optional, 'all' or list of dicts) – By default compute the responses for all filters. Otherwise, provide a list of filter definitions to use.

Returns

  • output_sin (np.ndarray, (nimages, nfilters))

  • output_cos (np.ndarray, (nimages, nfilters))

show_filter(filterid=0, speed=1.0, background=None)[source]

Display the motion energy filter as an animation.

Parameters

filterid (int, or dict) – If int, it’s the index of the filter to display. If dict, it’s a motion energy filter definition.

Returns

animation

Return type

matplotlib.animation

Examples

>>> import moten
>>> pyramid = moten.get_default_pyramid()
>>> _ = pyramid.show_filter(12)
>>> custom_filter = {'centerh': 0.8888888888888888,
                     'centerv': 0.5,
                     'direction': 45.0,
                     'spatial_freq': 2.0,
                     'spatial_env': 0.3,
                     'temporal_freq': 2.0,
                     'temporal_env': 0.3,
                     'filter_temporal_width': 16.0,
                     'aspect_ratio': 1.7777777777777777,
                     'stimulus_fps': 24.0,
                     'spatial_phase_offset': 0.0}
>>> _ = pyramid.show_filter(custom_filter)
class moten.pyramids.StimulusMotionEnergy(stimulus, stimulus_fps, temporal_frequencies=[0, 2, 4], spatial_frequencies=[0, 2, 4, 8, 16], spatial_directions=[0, 45, 90, 135, 180, 225, 270, 315], sf_gauss_ratio=0.6, max_spatial_env=0.3, filter_spacing=3.5, tf_gauss_ratio=10.0, max_temp_env=0.3, include_edges=False, spatial_phase_offset=0.0, filter_temporal_width='auto')[source]

Bases: object

Parametrize a motion energy pyramid that tiles the stimulus.

Generates motion energy filters at the desired spatio-temporal frequencies and directions of motion. Multiple motion energy filters per spatio-temporal frequency are constructed and each is centered at different locations in the image in order to tile the stimulus.

Parameters
  • stimulus (np.array, (nimages, vdim, hdim)) – The movie frames.

  • stimulus_fps (scalar, [Hz]) – Stimulus playback speed in frames per second.

  • spatial_frequencies (array-like, [cycles-per-image]) – Spatial frequencies for the filters

  • spatial_directions (array-like, [degrees]) – Direction of filter motion. Degree position corresponds to standard unit-circle coordinates (i.e. 0=right, 180=left).

  • temporal_frequencies (array-like, [Hz]) – Temporal frequencies of the filters

  • filter_temporal_width (int) – Temporal window of the motion energy filter (e.g. 10). Defaults to approximately 0.666[secs] (floor(stimulus_fps*(2/3))).

Variables
  • stimulus (2D np.ndarray, (nimages, vdim*hdim)) – Time-space representation of stimulus

  • view (MotionEnergyPyramid) – Full description of the motion energy pyramid.

  • nimages (int) – Number of video frames

  • nfilters (int) –

  • aspect_ratio (scalar, (hdim/vdim)) –

  • stimulus_fps (int (fps)) –

  • stimulus_vhsize (tuple of ints, (vdim, hdim)) –

  • original_stimulus (3D np.ndarray, (nimages, vdim, hdim)) –

project(filters='all', quadrature_combination=<function sqrt_sum_squares>, output_nonlinearity=<function log_compress>, dtype='float32')[source]

Compute the motion energy filter responses to the stimulus.

Parameters
  • filters (optional, 'all' or list of dicts) – By default compute the responses for all filters. Otherwise, provide a list of filter definitions to use.

  • quadrature_combination (function, optional) – Specifies how to combine the channel reponse quadratures. The function must take the sin and cos as arguments in that order. Defaults to: \((sin^2 + cos^2)^{1/2}\)

  • output_nonlinearity (function, optional) – Passes the channels (after quadrature_combination) through a non-linearity. The function input is the (nimages, nfilters) array. Defaults to: \(log(x + 1e-05)\)

Returns

filter_responses

Return type

np.ndarray, (nimages, nfilters)

project_at_vhposition(centerv, centerh, quadrature_combination=<function sqrt_sum_squares>, output_nonlinearity=<function log_compress>, dtype='float32')[source]

Center filters at vh-position and compute their response to the stimulus.

Parameters
  • centerv (scalar) – Vertical filter from top of frame (min=0, max=1.0).

  • centerh (scalar) – Horizontal filter position from left of frame (min=0, max=aspect_ratio).

Returns

  • centered_filters (list of dicts) – Spatio-temporal filter parameters at vh-position.

  • filter_responses (np.ndarray, (nimages, len(vh_centered_filters)))

project_stimulus(*args, **kwargs)[source]

See MotionEnergyPyramid.project_stimulus()

raw_projection(filters='all', dtype='float32')[source]

Obtain responses to the stimulus from all filter quadrature-pairs.

Parameters

filters (optional, 'all' or list of dicts) – By default compute the responses for all filters. Otherwise, provide a list of filter definitions to use.

Returns

  • output_sin (np.ndarray, (nimages, nfilters))

  • output_cos (np.ndarray, (nimages, nfilters))

class moten.pyramids.StimulusStaticGaborPyramid(stimulus, spatial_frequencies=[0, 2, 4, 8, 16], spatial_orientations=(0, 45, 90, 135), sf_gauss_ratio=0.6, max_spatial_env=0.3, filter_spacing=3.5, include_edges=False, spatial_phase_offset=0.0)[source]

Bases: moten.pyramids.StimulusMotionEnergy