prfmodel.models

Population receptive field models.

Submodules

• prfmodel.models.base
• prfmodel.models.composite
• prfmodel.models.encoding
• prfmodel.models.gaussian
• prfmodel.models.impulse
• prfmodel.models.temporal

Classes

BaseModel	Abstract base class for models.
BasePRFModel	Abstract base class for creating composite population receptive field models.
BasePRFResponse	Abstract base class for population receptive field response models.
BaseTemporal	Abstract base class for temporal models.
Gaussian2DPRFModel	Two-dimensional isotropic Gaussian population receptive field model.

Functions

encode_prf_response(→ prfmodel.typing.Tensor)

Encode a population receptive field model response with a stimulus design.

Package Contents

class prfmodel.models.BaseModel

Abstract base class for models.

Cannot be instantiated on its own. Can only be used as a parent class to create custom model classes. Subclasses must override the abstract parameter_names property.

parameter_names

Examples

Create a custom model class that inherits from the base class:

>>> class CustomModel(BaseModel):
>>>     @property
>>>     def parameter_names(self):
>>>         return ["a", "b"]
>>> model = CustomModel()
>>> print(model.parameter_names)
["a", "b"]

property parameter_names: list[str]

Abstractmethod:

A list with names of parameters that are used by the model.

class prfmodel.models.BasePRFModel(**models: BaseModel | None)

Abstract base class for creating composite population receptive field models.

Cannot be instantiated on its own. Can only be used as a parent class for creating custom composite population receptive field models. Subclasses must override the __call__ method. This class is intented for combining multiple submodels into a composite model with a custom __call__ method that defines how the submodels interact to make a composite prediction.

#TODO: Link to Example on how to create custom composite models.

Parameters:

**models – Submodels to be combined into the composite model. All submodel classes must inherit from BaseModel.

Raises:

TypeError – If submodel classes do not inherit from BaseModel.

property parameter_names: list[str]

A list with names of unique parameters that are used by the submodels.

abstractmethod __call__(stimulus: prfmodel.stimulus.Stimulus, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor

Predict a composite population receptive field response to a stimulus.

Parameters:

• stimulus (Stimulus) – Stimulus object.

• parameters (pandas.DataFrame) – Dataframe with columns containing different (sub-) model parameters and rows containing parameter values for different voxels.

• dtype (str, optional) – The dtype of the prediction result. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

Model predictions with the same shape as inputs and dtype dtype. Model predictions of shape (num_voxels, num_frames). The number of voxels is the number of rows in parameters. The number of frames is the number of frames in the stimulus design.

Return type:

Tensor

class prfmodel.models.BasePRFResponse

Abstract base class for population receptive field response models.

Cannot be instantiated on its own. Can only be used as a parent class to create custom population receptive field models. Subclasses must override the abstract __call__ method.

#TODO: Link to Example on how to create custom response models.

abstractmethod __call__(stimulus: prfmodel.stimulus.Stimulus, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor

Predict the model response for a stimulus.

Parameters:

• stimulus (Stimulus) – Stimulus object.

• parameters (pandas.DataFrame) – Dataframe with columns containing different model parameters and rows containing parameter values for different voxels.

• dtype (str, optional) – The dtype of the prediction result. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

Model predictions of shape (num_voxels, …) and dtype dtype. The number of voxels is the number of rows in parameters. The number and size of other axes depends on the stimulus.

Return type:

Tensor

property parameter_names: list[str]

Abstractmethod:

A list with names of parameters that are used by the model.

class prfmodel.models.BaseTemporal

Abstract base class for temporal models.

Cannot be instantiated on its own. Can only be used as a parent class to create custom temporal models. Subclasses must override the abstract __call__ method.

#TODO: Link to Example on how to create custom temporal models.

abstractmethod __call__(inputs: prfmodel.typing.Tensor, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor

Make predictions with the temporal model.

Parameters:

• inputs (Tensor) – Input tensor with temporal response and shape (num_batches, num_frames).

• parameters (pandas.DataFrame) – Dataframe with columns containing different model parameters and rows containing parameter values for different batches.

• dtype (str, optional) – The dtype of the prediction result. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

Model predictions of shape (num_voxels, num_frames) and dtype dtype. The number of voxels is the number of rows in parameters.

Return type:

Tensor

property parameter_names: list[str]

Abstractmethod:

A list with names of parameters that are used by the model.

prfmodel.models.encode_prf_response(response: prfmodel.typing.Tensor, design: prfmodel.typing.Tensor, dtype: str | None = None) → prfmodel.typing.Tensor

Encode a population receptive field model response with a stimulus design.

Multiplies a stimulus design with a model response along the stimulus dimensions and sums over them.

Parameters:

• response (Tensor) – The population receptive field model response. The first dimension corresponds to the number of batches. Additional dimensions correspond to the stimulus dimensions.

• design (Tensor) – The stimulus design 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 stimulus dimensions.

• dtype (str, optional) – The dtype of the prediction result. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

The stimulus encoded model response with shape (num_batches, num_frames) and dtype dtype.

Return type:

Tensor

Raises:

ResponseDesignShapeError – If the shape of the model response and the stimulus design do not match.

Examples

Encode a 1D model response:

>>> import numpy as np
>>> num_batches = 3
>>> num_frames = 10
>>> height = 5
>>> # Create a dummy stimulus design
>>> design = np.ones((num_frames, height))
>>> # Create a dummy model response that varies with the height of a stimulus grid
>>> resp = np.ones((num_batches, height)) * np.expand_dims(np.sin(np.arange(height)), 0)
>>> print(resp.shape) # (num_batches, height)
(3, 5)
>>> resp_encoded = encode_prf_response(resp, design)
>>> print(resp_encoded.shape) (num_batches, num_frames)
(3, 10)

Encode a 2D model response:

>>> # Add width dimension
>>> width = 4
>>> # Create a dummy stimulus design
>>> design = np.ones((num_frames, height, width))
>>> # Create a dummy model response that varies with the width of a stimulus grid
>>> resp = np.ones((num_batches, height, width)) * np.expand_dims(np.sin(np.arange(width)), (0, 1))
>>> print(resp.shape) # (num_batches, height, width)
(3, 5, 4)
>>> resp_encoded = encode_prf_response(resp, design)
>>> print(resp_encoded.shape) (num_batches, num_frames)
(3, 10)

class prfmodel.models.Gaussian2DPRFModel(impulse_model: prfmodel.models.base.BaseImpulse | type[prfmodel.models.base.BaseImpulse] | None = TwoGammaImpulse, temporal_model: prfmodel.models.base.BaseTemporal | type[prfmodel.models.base.BaseTemporal] | None = BaselineAmplitude)

Two-dimensional isotropic Gaussian population receptive field model.

This is a generic class that combines a 2D isotropic Gaussian population receptive field, impulse, and temporal model response.

Parameters:

• impulse_model (BaseImpulse or type or None, default=TwoGammaImpulse, optional) – An impulse response model class or instance. Reponse model classes will be instantiated during object initialization. The default creates a TwoGammaImpulse instance with default values. values.

• temporal_model (BaseTemporal or type or None, default=BaselineAmplitude, optional) – A temporal model class or instance. Temporal model instances will be instantiated during initialization. The default creates a BaselineAmplitude instance.

Notes

The simple composite model follows five steps:

1. The 2D Gaussian population receptive field response model makes a prediction for the stimulus grid.

2. The response is encoded with the stimulus design.

3. A impulse response model generates an impulse response.

4. The encoded response is convolved with the impulse response.

5. The temporal model modifies the convolved response.

__call__(stimulus: prfmodel.stimulus.Stimulus, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor

Predict a simple population receptive field model response to a stimulus.

Parameters:

• stimulus (Stimulus) – Stimulus object.

• parameters (pandas.DataFrame) – Dataframe with columns containing different (sub-) model parameters and rows containing parameter values for different voxels.

• dtype (str, optional) – The dtype of the prediction result. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

Model predictions of shape (num_voxels, num_frames) and dtype dtype. The number of voxels is the number of rows in parameters. The number of frames is the number of frames in the stimulus design.

Return type:

Tensor

property parameter_names: list[str]

A list with names of unique parameters that are used by the submodels.