prfmodel.PRFStimulus

class prfmodel.PRFStimulus

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:

  • ShapeError – If the number of grid axes (excluding the last) does not match the last grid dimension.

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

  • ValueError – If the number of dimension labels does not match the last grid 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'])
__repr__() → str

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

__str__() → str

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

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

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