prfmodel.stimuli

Stimuli.

Submodules

Classes

Stimulus

Stimulus base class.

CFStimulus

Container for a connective field stimulus distance matrix and source response.

PRFStimulus

Container for a population receptive field stimulus design and its associated grid.

Functions

animate_2d_prf_stimulus(...)

Animate a two-dimensional population receptive field stimulus.

plot_2d_prf_stimulus(→ tuple[matplotlib.figure.Figure, ...)

Plot a single frame of a two-dimensional population receptive field stimulus.

Package Contents

class prfmodel.stimuli.Stimulus[source]

Stimulus base class.

__repr__() → str[source]

Create a round-trippable string representation of the stimulus object.

__str__() → str[source]

Create a human-readable string representation of the stimulus object.

class prfmodel.stimuli.CFStimulus[source]

Container for a connective field stimulus distance matrix and source response.

Parameters:

  • distance_matrix (numpy.ndarray) – A matrix with distances between source units (e.g., voxels).

  • source_response (numpy.ndarray) – Array with responses for each source unit with shape (num_voxels, num_frames). num_voxels is the number of source units and num_frames the number of time frames for each source response. num_voxels must match the number of rows and columns in distance_matrix.

Raises:

  • DistanceMatrixShapeError – If the distance matrix has more or less than two dimensions or dimensions of different size.

  • DistanceMatrixSourceShapeError – If the source response has a first dimension with a different size than the number of rows or columns in the distance matrix.

__repr__() → str

Create a round-trippable string representation of the stimulus object.

__str__() → str

Create a human-readable string representation of the stimulus object.

class prfmodel.stimuli.PRFStimulus[source]

Container for a population receptive field stimulus design and its associated grid.

Parameters:

  • design (numpy.ndarray) – The stimulus design array containing the stimulus value in one or more dimensions over different time frames. The first axis is assumed to be time frames. Additional axes represent design dimensions.

  • grid (numpy.ndarray) – The coordinate system of the design. The last axis is the number of design dimensions excluding the time frame dimension. The shape excluding the last axis must match the shape of the design excluding the first axis.

  • dimension_labels (Sequence[str] or None, optional) – Names of the grid dimensions (e.g., [“y”, “x”]). If given, the number of labels must match the last grid axis.

Raises:

  • GridDesignShapeError – If the design and grid dimensions do not match.

  • GridDimensionsError – If the number of dimensions of the grid except the last does not match the size of the last grid dimension.

  • DimensionLabelsError – If the number of dimensions does not match the grid’s last dimension.

Notes

The shapes of the design and grid must match according to design.shape[1:] == grid.shape[:-1]. That is, all design dimensions but the first must have the same size as the grid dimensions excluding the last grid dimension.

Examples

Create a population receptive field stimulus on a 2D grid.

>>> import numpy as np
>>> num_frames, width, height = 10, 16, 16
>>> design = np.ones((num_frames, width, height))
>>> pixel_size = 0.05
>>> x = (np.arange(width) - (width - 1) / 2) * pixel_size
>>> y = (np.arange(height) - (height - 1) / 2) * pixel_size
>>> xv, yv = np.meshgrid(x, y)
>>> grid = np.stack((xv, yv), axis=-1)  # shape (height, width, 2)
>>> grid = np.stack((xv, yv), axis=-1)  # shape (height, width, 2)
>>> # The coordinates of the bottom-left corner:
>>> grid[0, 0, :]
array([-0.375, -0.375])
>>> # The coordinates of the top-right corner:
>>> grid[15, 15, :]
array([0.375, 0.375])
>>> stimulus = PRFStimulus(design=design, grid=grid, dimension_labels=["y", "x"])
>>> print(stimulus)
PRFStimulus(design=array[10, 16, 16], grid=array[16, 16, 2], dimension_labels=['y', 'x'])
classmethod create_2d_bar_stimulus(num_frames: int = 100, width: int = 128, height: int = 128, bar_width: int = 20, direction: str = 'horizontal', pixel_size: float = 0.05) → PRFStimulus[source]

Create a population receptive field bar stimulus that moves across a 2D screen.

The stimulus starts and ends moving just outside the screen.

Parameters:

  • num_frames (int, optional) – Number of time frames in the stimulus.

  • width (int, optional) – Width of the stimulus grid (in pixels).

  • height (int, optional) – Height of the stimulus grid (in pixels).

  • bar_width (int, optional) – Width of the moving bar (in pixels).

  • direction ({"horizontal", "vertical"}, optional) – Direction in which the bar moves.

  • pixel_size (float, optional) – Size of a pixel in spatial units.

Returns:

A stimulus instance with the generated design and grid.

Return type:

PRFStimulus

Raises:

ValueError – If direction is not “horizontal” or “vertical”.

Examples

>>> stimulus = PRFStimulus.create_2d_bar_stimulus(num_frames=200)
>>> print(stimulus)
PRFStimulus(design=array[200, 128, 128], grid=array[128, 128, 2], dimension_labels=['y', 'x'])
__repr__() → str

Create a round-trippable string representation of the stimulus object.

__str__() → str

Create a human-readable string representation of the stimulus object.

prfmodel.stimuli.animate_2d_prf_stimulus(stimulus: PRFStimulus, title: str | None = None, origin: Literal['upper', 'lower'] = 'lower', interval: int = 50, blit: bool = True, repeat_delay: int = 1000, **kwargs) → matplotlib.animation.ArtistAnimation[source]

Animate a two-dimensional population receptive field stimulus.

Parameters:
Return type:

matplotlib.animation.ArtistAnimation

Raises:

StimulusDimensionError – If stimulus is not 2-dimensional.

Notes

The function uses matplotlib under the hood, and you can use the matplotlib.rcParams to customize the animation, as described on the matplotlib docs.

Examples

>>> from IPython.display import HTML
>>> from prfmodel.stimulus import PRFStimulus, animate_2d_prf_stimulus
>>> bar_stimulus = PRFStimulus.create_2d_bar_stimulus(num_frames=100, width=128, height=64)
>>> ani = animate_2d_prf_stimulus(bar_stimulus)
>>> video = ani.to_html5_video()
>>> HTML(video)
prfmodel.stimuli.plot_2d_prf_stimulus(stimulus: PRFStimulus, frame_idx: int, origin: Literal['upper', 'lower'] = 'lower', title: str | None = None, **kwargs) → tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]

Plot a single frame of a two-dimensional population receptive field stimulus.

Parameters:
Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

Raises:

StimulusDimensionError – If the stimulus is not 2-dimensional.