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=<class 'numpy.float64'>, pyramid_parameters={})[source]

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 (np.dtype) – Defaults to np.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=<class 'numpy.float64'>, dozscore=True)[source]

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 (np.dtype) – Defaults to np.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)[source]

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)[source]

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)[source]
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)[source]

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_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)[source]

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)[source]

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')[source]

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.raw_project_stimulus(stimulus, filters, vhsize=(), dtype='float32')[source]

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