moten.core module

moten.core.compute_filter_responses(stimulus, stimulus_fps, aspect_ratio='auto', filter_temporal_width='auto', quadrature_combination=<function sqrt_sum_squares>, output_nonlinearity=<function log_compress>, dozscore=True, dtype='float64', pyramid_parameters={})

Compute the motion energy filters’ response to the stimuli.

Parameters:

• stimulus (3D np.array (n, vdim, hdim)) – The movie frames.

• stimulus_fps (scalar) – The temporal frequency of the stimulus

• aspect_ratio (bool, or scalar) – Defaults to hdim/vdim. Otherwise, pass as scalar

• filter_temporal_width (int, None) – The number of frames in one filter. Defaults to approximately 0.666[secs] (floor(stimulus_fps*(2/3))).

• quadrature_combination (function, optional) – Specifies how to combine the channel reponses quadratures. The function must take the sin and cos as arguments in 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 (n,`nfilters`) array. Defaults to: ln(x + 1e-05)

• dozscore (bool, optional) – Whether to z-score the channel responses in time

• dtype (str or dtype) – Defaults to ‘float64’

• pyramid_parameters (dict) – See mk_moten_pyramid_params() for details on parameters specifiying a motion energy pyramid.

Returns:

filter_responses

Return type:

np.array, (n, nfilters)

moten.core.compute_spatial_gabor_responses(stimulus, aspect_ratio='auto', spatial_frequencies=[0, 2, 4, 8, 16, 32], quadrature_combination=<function sqrt_sum_squares>, output_nonlinearity=<function log_compress>, dtype='float64', dozscore=True)

Compute the spatial gabor filters’ response to each stimulus.

Parameters:

• stimulus (3D np.array (n, vdim, hdim)) – The stimulus frames.

• spatial_frequencies (array-like) – The spatial frequencies to compute. The spatial envelope is determined by this.

• quadrature_combination (function, optional) – Specifies how to combine the channel reponses quadratures. The function must take the sin and cos as arguments in 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 (n,`nfilters`) array. Defaults to: ln(x + 1e-05)

• dozscore (bool, optional) – Whether to z-score the channel responses in time

• dtype (str or dtype) – Defaults to ‘float64’

Returns:

filter_responses

Return type:

np.array, (n, nfilters)

moten.core.dotdelay_frames(spatial_gabor_sin, spatial_gabor_cos, temporal_gabor_sin, temporal_gabor_cos, stimulus, masklimit=0.001)

Convolve the motion energy filter with a stimulus

Parameters:

• spatial_gabor_sin (np.array, (vdim,hdim))

• spatial_gabor_cos (np.array, (vdim,hdim)) – Spatial gabor quadrature pair

• temporal_gabor_sin (np.array, (temporal_filter_width,))

• temporal_gabor_cos (np.array, (temporal_filter_width,)) – Temporal gabor quadrature pair

• stimulus (2D np.array (nimages, vdim*hdim)) – The movie frames with the spatial dimension collapsed.

Returns:

• channel_sin (np.ndarray, (nimages, ))

• channel_cos (np.ndarray, (nimages, )) – The filter response to the stimulus at each time point The quadrature pair can be combined: (x^2 + y^2)^0.5

moten.core.dotspatial_frames(spatial_gabor_sin, spatial_gabor_cos, stimulus, masklimit=0.001)

Dot the spatial gabor filters filter with the stimulus

Parameters:

• spatial_gabor_sin (np.array, (vdim,hdim))

• spatial_gabor_cos (np.array, (vdim,hdim)) – Spatial gabor quadrature pair

• stimulus (2D np.array (nimages, vdim*hdim)) – The movie frames with the spatial dimension collapsed.

• masklimit (float-like) – Threshold to find the non-zero filter region

Returns:

• channel_sin (np.ndarray, (nimages, ))

• channel_cos (np.ndarray, (nimages, )) – The filter response to each stimulus The quadrature pair can be combined: (x^2 + y^2)^0.5

moten.core.generate_3dgabor_array(vhsize=(576, 1024), stimulus_fps=24, aspect_ratio='auto', filter_temporal_width='auto', centerh=0.5, centerv=0.5, direction=45.0, spatial_freq=16.0, spatial_env=0.3, temporal_freq=2.0, temporal_env=0.3, phase_offset=0.0)

moten.core.mk_3d_gabor(vhsize, stimulus_fps, aspect_ratio='auto', filter_temporal_width='auto', centerh=0.5, centerv=0.5, direction=45.0, spatial_freq=16.0, spatial_env=0.3, temporal_freq=2.0, temporal_env=0.3, spatial_phase_offset=0.0)

Make a motion energy filter.

A motion energy filter is a 3D gabor with two spatial and one temporal dimension. Each dimension is defined by two sine waves which differ in phase by 90 degrees. The sine waves are then multiplied by a gaussian.

Parameters:

• vhsize (tuple of ints, (vdim, hdim)) – Size of the stimulus in pixels (vdim, hdim) vdim : vertical dimension hdim : horizontal dimension

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

• 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).

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

• spatial_freq (float, [cycles-per-image]) – Spatial frequency of the filter.

• temporal_freq (float, [Hz]) – Temporal frequency of the filter

• 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))).

• aspect_ratio (optional, 'auto' or float-like,) – Defaults to stimulus aspect ratio: hdim/vdim Useful for preserving the spatial gabors circular even when images have non-square aspect ratios. For example, a 16:9 image would have `aspect_ratio`=16/9.

• spatial_env (float) – Spatial envelope (s.d. of the gaussian)

• temporal_env (float) – Temporal envelope (s.d. of gaussian)

• spatial_phase_offset (float, [degrees) – Phase offset for the spatial sinusoid

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

Notes

Same method as Nishimoto, et al., 2011.

moten.core.mk_3d_gabor_batched(vhsize, filters_batch)

Build spatial and temporal gabor filter banks for a batch of filters.

Vectorizes mk_3d_gabor() across multiple filters so that all gabor arrays are constructed with batched tensor operations instead of a Python for-loop.

Parameters:

• vhsize (tuple of ints, (vdim, hdim))

• filters_batch (list of dicts) – Each dict has the same keys accepted by mk_3d_gabor().

Returns:

• spatial_gabors_sin (array, (B, npixels))

• spatial_gabors_cos (array, (B, npixels))

• temporal_gabors_sin (array, (B, T))

• temporal_gabors_cos (array, (B, T))

moten.core.mk_moten_pyramid_params(stimulus_fps, filter_temporal_width='auto', aspect_ratio='auto', temporal_frequencies=[0, 2, 4], spatial_frequencies=[0, 2, 4, 8, 16, 32], spatial_directions=[0, 45, 90, 135, 180, 225, 270, 315], sf_gauss_ratio=0.6, max_spatial_env=0.3, gabor_spacing=3.5, tf_gauss_ratio=10.0, max_temp_env=0.3, spatial_phase_offset=0.0, include_edges=False)

Parametrize a motion energy pyramid that tiles the stimulus.

Parameters:

• 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))).

• aspect_ratio (optional, 'auto' or float-like,) – Defaults to stimulus aspect ratio: hdim/vdim Useful for preserving the spatial gabors circular even when images have non-square aspect ratios. For example, a 16:9 image would have `aspect_ratio`=16/9.

• sf_gauss_ratio (scalar) – The ratio of spatial frequency to gaussian s.d. This controls the number of cycles in a filter

• max_spatial_env (scalar) – Defines the maximum s.d. of the gaussian

• gabor_spacing (scalar) – Defines the spacing between spatial gabors (in s.d. units)

• tf_gauss_ratio (scalar) – The ratio of temporal frequency to gaussian s.d. This controls the number of temporal cycles

• max_temp_env (scalar) – Defines the maximum s.d. of the temporal gaussian

• include_edges (bool) – Determines whether to include filters at the edge of the image which might be partially outside the stimulus field-of-view

Returns:

• parameter_names (list of strings) – The name of the parameters

• gabor_parameters (2D np.ndarray, (nfilters, 11)) – Parameters that define the 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]

Notes

Same method as Nishimoto, et al., 2011.

moten.core.mk_spatiotemporal_gabor(spatial_gabor_sin, spatial_gabor_cos, temporal_gabor_sin, temporal_gabor_cos)

Make 3D motion energy filter defined by the spatial and temporal gabors.

Takes the output of mk_3d_gabor() and constructs the 3D filter. This is useful for visualization.

Parameters:

• spatial_gabor_sin (np.array, (vdim,hdim))

• spatial_gabor_cos (np.array, (vdim,hdim)) – Spatial gabor quadrature pair

• temporal_gabor_sin (np.array, (filter_temporal_width,))

• temporal_gabor_cos (np.array, (filter_temporal_width,)) – Temporal gabor quadrature pair

Returns:

motion_energy_filter – The motion energy filter

Return type:

np.array, (vdim, hdim, filter_temporal_width)

moten.core.project_stimulus(stimulus, filters, quadrature_combination=<function sqrt_sum_squares>, output_nonlinearity=<function log_compress>, vhsize=(), dtype='float32')

Compute the motion energy filter responses to the stimuli.

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.

Returns:

filter_responses

Return type:

np.ndarray, (nimages, nfilters)

moten.core.project_stimulus_batched(stimulus, filters, quadrature_combination=<function sqrt_sum_squares>, output_nonlinearity=<function log_compress>, vhsize=(), dtype='float32', batch_size=128, stimulus_batch_size=None, masklimit=0.001)

Compute motion energy responses using batched operations.

Functionally equivalent to project_stimulus() but constructs spatial and temporal gabor filter banks in batches and uses a single large matrix multiply per batch instead of per-filter dot products. This is significantly faster on GPU backends and can also be faster on CPU for large filter sets.

Parameters:

• stimulus (array, (nimages, vdim, hdim) or (nimages, npixels)) – The movie frames.

• filters (list of dicts) – Filter parameter dictionaries (as produced by a pyramid).

• quadrature_combination (callable, optional) – Defaults to sqrt_sum_squares.

• output_nonlinearity (callable, optional) – Defaults to log_compress.

• vhsize (tuple of ints) – (vdim, hdim) required when stimulus is 2-D.

• dtype (str) – Output dtype.

• batch_size (int) – Number of filters to process simultaneously. Larger values use more memory but reduce Python-loop overhead.

• stimulus_batch_size (int or None) – Number of stimulus frames to process at a time. When None (default), all frames are processed together, preserving the original behaviour. When set, the stimulus is split into overlapping temporal batches to reduce VRAM usage for long stimuli. The overlap is computed automatically from the temporal filter width to avoid edge artifacts.

• masklimit (float) – Threshold for zeroing near-zero gabor pixels. Matches the masklimit parameter of dotspatial_frames().

Returns:

filter_responses

Return type:

array, (nimages, nfilters)

moten.core.raw_project_stimulus(stimulus, filters, vhsize=(), dtype='float32')

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

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.

Returns:

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

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