moten.pyramids module

class moten.pyramids.DefaultPyramids

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')

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)

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)

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()

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)

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)

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)

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)

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')

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)

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')

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')

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')

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)

See MotionEnergyPyramid.project_stimulus()

raw_projection(filters='all', dtype='float32')

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)

Bases: StimulusMotionEnergy