prfmodel.models¶

Population receptive and connective field models.

Submodules¶

Classes¶

`BaseComposite`	Generic abstract base class for creating composite models.
`BaseEncoder`	Generic abstract base class for encoding model responses.
`BaseModel`	Abstract base class for models.
`BaseResponse`	Generic abstract base class for response models.
`BaseTemporal`	Abstract base class for temporal models.
`Gaussian2DCSSPRFModel`	Two-dimensional isotropic Gaussian population receptive field model with compressive spatial summation (CSS).
`DoG2DPRFModel`	Two-dimensional difference of Gaussians population receptive field model.
`CFStimulusEncoder`	Encoding model for connective field stimuli.
`CompressiveEncoder`	Compressive encoding model.
`PRFStimulusEncoder`	Encoding model for population receptive field stimuli.
`Gaussian2DPRFModel`	Two-dimensional isotropic Gaussian population receptive field model.
`GaussianCFModel`	Gaussian connective field model.

Functions¶

`init_css_from_gaussian`(→ pandas.DataFrame)	Initialize compressive spatial summation parameters from fitted Gaussian parameters.
`init_dog_from_gaussian`(→ pandas.DataFrame)	Initialize DoG model parameters from fitted Gaussian model parameters.
`encode_prf_response`(→ prfmodel.typing.Tensor)	Encode a population receptive field model response with a stimulus design.

Package Contents¶

class prfmodel.models.BaseComposite(**models: BaseModel | None)[source]¶

Generic abstract base class for creating composite models.

Cannot be instantiated on its own. Can only be used as a parent class to create custom composite models. Subclasses must override the abstract __call__ method and must be defined with a specific stimulus type. This class is intended for combining multiple submodels into a composite model with a custom __call__ method that defines how the submodels interact to make a composite prediction.

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: S, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor[source]¶

Predict a composite 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:

Composite 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

class prfmodel.models.BaseEncoder[source]¶

Generic abstract base class for encoding model responses.

Cannot be instantiated on its own. Can only be used as a parent class to create custom encoding models. Subclasses must override the abstract parameter_names property and __call__ method and must be defined with a specific stimulus type.

abstractmethod __call__(stimulus: S, response: prfmodel.typing.Tensor, parameters: pandas.DataFrame, dtype: str | None = None)[source]¶

Encode a model response with a stimulus.

Parameters:

stimulus (Stimulus) – Stimulus object.
response (Tensor) – Model response.
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 encoded response. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

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

Return type:

Tensor

property parameter_names: list[str]¶

Abstractmethod:

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

class prfmodel.models.BaseModel[source]¶

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.BaseResponse[source]¶

Generic abstract base class for 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 and must be defined with a specific stimulus type.

abstractmethod __call__(stimulus: S, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor[source]¶

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

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.

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

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.

class prfmodel.models.Gaussian2DCSSPRFModel(impulse_model: prfmodel.models.base.BaseImpulse | type[prfmodel.models.base.BaseImpulse] | None = DerivativeTwoGammaImpulse, temporal_model: prfmodel.models.base.BaseTemporal | type[prfmodel.models.base.BaseTemporal] | None = BaselineAmplitude)[source]¶

Two-dimensional isotropic Gaussian population receptive field model with compressive spatial summation (CSS).

This is a generic class that combines a 2D isotropic Gaussian population receptive field, impulse, and temporal model response. In contrast to Gaussian2DPRFModel, it encodes the stimulus response using compressive spatial summation (see CompressiveEncoder).

Parameters:

impulse_model (BaseImpulse or type or None, default=DerivativeTwoGammaImpulse, optional) – An impulse response model class or instance. Model classes will be instantiated during initialization. The default creates a DerivativeTwoGammaImpulse instance with default values.
temporal_model (BaseTemporal or type or None, default=BaselineAmplitude, optional) – A temporal model class or instance. Model classes will be instantiated during initialization. The default creates a BaselineAmplitude instance.

Notes

The simple composite model follows five steps:

The 2D Gaussian population receptive field response model makes a prediction for the stimulus grid.
The encoding model encodes the response with the stimulus design and applies compressive spatial summation.
A impulse response model generates an impulse response.
The encoded response is convolved with the impulse response.
The temporal model modifies the convolved response.

__call__(stimulus: prfmodel.stimuli.prf.PRFStimulus, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor¶

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

Parameters:

stimulus (PRFStimulus) – Population receptive field 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.

prfmodel.models.init_css_from_gaussian(gaussian_params: pandas.DataFrame, gain: float = 1.0, n: float = 0.5) → pandas.DataFrame[source]¶

Initialize compressive spatial summation parameters from fitted Gaussian parameters.

Converts the output of a fitted Gaussian2DPRFModel into starting parameters for a Gaussian2DCSSPRFModel.

Parameters:

gaussian_params (pandas.DataFrame) – DataFrame of fitted parameters from a Gaussian2DPRFModel.
gain (float, default=1.0) – Amplification parameter for the CompressiveEncoder.
n (float, default=0.5) – Compression exponent parameter for the CompressiveEncoder. Must be > 0.

Returns:

DataFrame with two additional columns: gain and m.

Return type:

pandas.DataFrame

Raises:

ValueError – If n <= 0 or if n or gain are not finite.

class prfmodel.models.DoG2DPRFModel(encoding_model: prfmodel.models.base.BaseEncoder | type[prfmodel.models.base.BaseEncoder] = PRFStimulusEncoder, impulse_model: prfmodel.models.base.BaseImpulse | type[prfmodel.models.base.BaseImpulse] | None = DerivativeTwoGammaImpulse, temporal_model: prfmodel.models.base.BaseTemporal | type[prfmodel.models.base.BaseTemporal] | None = DoGAmplitude)[source]¶

Two-dimensional difference of Gaussians population receptive field model.

Runs two Gaussian 2D PRF responses (center and surround) through stimulus encoding and impulse response convolution independently, then combines them as a linear model:

y(t) = p1(t) * amplitude_center + p2(t) * amplitude_surround + baseline

Parameters:: encoding_model (BaseEncoder or type, default=PRFStimulusEncoder) – An encoding model class or instance. Model classes will be instantiated during initialization. The default creates a PRFStimulusEncoder instance.

impulse_modelBaseImpulse or type or None, default=DerivativeTwoGammaImpulse: An impulse response model class or instance.
temporal_modelBaseTemporal or type or None, default=DoGAmplitude: A temporal model class or instance.

property parameter_names: list[str]¶: A list with names of unique parameters used by the model.

predict_responses(stimulus: prfmodel.stimuli.prf.PRFStimulus, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor¶

Predict the each of the two responses before applying betas.

Returns:: Stacked predictions of shape (num_voxels, 2, num_frames).
Return type:: Tensor

__call__(stimulus: prfmodel.stimuli.prf.PRFStimulus, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor¶

Predict the composite model response (considering Center and Surround responses).

Applies the temporal model to the stacked responses from predict_responses. When temporal_model=None, returns a simple subtraction (response_center - response_surround)

Parameters:

stimulus (PRFStimulus) – Population receptive field 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).

Return type:

Tensor

prfmodel.models.init_dog_from_gaussian(gaussian_params: pandas.DataFrame, sigma_ratio: float = 5.0, sigma_surround: float | None = None) → pandas.DataFrame[source]¶

Initialize DoG model parameters from fitted Gaussian model parameters.

Converts the output of a fitted Gaussian2DPRFModel into starting parameters for a DoG2DPRFModel, suitable for subsequent SGD.

Parameters:

gaussian_params (pandas.DataFrame) – DataFrame of fitted parameters from a Gaussian2DPRFModel. Must contain columns: sigma and amplitude (plus all shared columns).
sigma_ratio (float, default=5.0) – Ratio used to set the surround size: sigma_surround = sigma_center * sigma_ratio. Ignored when sigma_surround is provided.
sigma_surround (float, optional) – Fixed surround size applied to all rows. Must be >= sigma for every row in gaussian_params. When provided, overrides sigma_ratio.

Returns:

DataFrame of DoG initial parameters with columns: sigma_center (= sigma), sigma_surround, amplitude_center (= amplitude), amplitude_surround (= 0.0), plus all shared columns unchanged.

Return type:

pandas.DataFrame

Raises:

ValueError – If sigma_surround is smaller than sigma for any row in gaussian_params.

Notes

amplitude_surround is initialized to 0.0, which is the boundary of the constraint amplitude_surround < 0 enforced by a ParameterConstraint with upper=0.0. The constraint transform maps amplitude_surround=0 to optimizer variable raw=-1.0 (no NaN), so SGD starts cleanly near zero and moves negative.

class prfmodel.models.CFStimulusEncoder[source]¶

Encoding model for connective field stimuli.

Multiplies a source response with a connective model response and sums over the vertices in the source response.

property parameter_names: list¶: Does not have any parameters. Returns an empty list.

__call__(stimulus: prfmodel.stimuli.cf.CFStimulus, response: prfmodel.typing.Tensor, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor[source]¶

Encode a Connective field model response with a source response.

Parameters:

stimulus (CFStimulus) – Connective field stimulus object.
response (Tensor) – Connective field response.
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 encoded response. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

The stimulus encoded model response with shape (num_voxels, num_frames) dtype dtype. The number of voxels is the number of rows in parameters. The number of frames is the number of time frames in the stimulus design.

Return type:

Tensor

class prfmodel.models.CompressiveEncoder(encoding_model: prfmodel.models.base.BaseEncoder, min_response: float = 1e-10)[source]¶

Compressive encoding model.

Amplifies and compresses an encoded stimulus response. The model has two parameters: gain (amplification amplitude) and n (compression exponent).

Parameters:

encoding_model (BasePRFEncoder) – A encoding model instance.
min_response (float, default=1e-10) – Minimum encoded response (\(\epsilon\)). A small value ensures numerical stability of gradients when \(n < 1\).

Notes

Compressive encoding with gain \(g\) and \(n\) is done according to the equation:

\[p(x) = g \times \text{max}(f(x), \epsilon)^n\]

property parameter_names: list[str]¶

gain and n.

Type:: Names of parameters used by the model

__call__(stimulus: prfmodel.models.base.S, response: prfmodel.typing.Tensor, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor[source]¶

Compress and encode a model response with a stimulus.

Encodes the model response, then compresses and amplifies the encoded response.

Parameters:

stimulus (Stimulus) – Stimulus object.
response (Tensor) – Model response.
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 encoded response. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

The compressed and stimulus encoded model response with shape (num_voxels, …) dtype dtype. The number of voxels is the number of rows in parameters. The number and size of other axes depends on the stimulus and the response.

Return type:

Tensor

class prfmodel.models.PRFStimulusEncoder[source]¶

Encoding model for population receptive field stimuli.

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

See also

encode_prf_response

property parameter_names: list¶: Does not have any parameters. Returns an empty list.

__call__(stimulus: prfmodel.stimuli.prf.PRFStimulus, response: prfmodel.typing.Tensor, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor[source]¶

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

Parameters:

stimulus (PRFStimulus) – Population receptive field stimulus object.
response (Tensor) – Population receptive field response.
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 encoded response. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

Return type:

Tensor

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

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(encoding_model: prfmodel.models.base.BaseEncoder | type[prfmodel.models.base.BaseEncoder] = PRFStimulusEncoder, impulse_model: prfmodel.models.base.BaseImpulse | type[prfmodel.models.base.BaseImpulse] | None = DerivativeTwoGammaImpulse, temporal_model: prfmodel.models.base.BaseTemporal | type[prfmodel.models.base.BaseTemporal] | None = BaselineAmplitude)[source]¶

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:

encoding_model (BaseEncoder or type, default=PRFStimulusEncoder) – An encoding model class or instance. Model classes will be instantiated during initialization. The default creates a PRFStimulusEncoder instance.
impulse_model (BaseImpulse or type or None, default=DerivativeTwoGammaImpulse, optional) – An impulse response model class or instance. Model classes will be instantiated during initialization. The default creates a DerivativeTwoGammaImpulse instance with default values.
temporal_model (BaseTemporal or type or None, default=BaselineAmplitude, optional) – A temporal model class or instance. Model classes will be instantiated during initialization. The default creates a BaselineAmplitude instance.

Notes

The simple composite model follows five steps:

The 2D Gaussian population receptive field response model makes a prediction for the stimulus grid.
The encoding model encodes the response with the stimulus design.
A impulse response model generates an impulse response.
The encoded response is convolved with the impulse response.
The temporal model modifies the convolved response.

__call__(stimulus: prfmodel.stimuli.prf.PRFStimulus, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor¶

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

Parameters:

stimulus (PRFStimulus) – Population receptive field 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.

class prfmodel.models.GaussianCFModel(encoding_model: prfmodel.models.base.BaseEncoder | type[prfmodel.models.base.BaseEncoder] = CFStimulusEncoder, temporal_model: prfmodel.models.base.BaseTemporal | type[prfmodel.models.base.BaseTemporal] | None = BaselineAmplitude)[source]¶

Gaussian connective field model.

This is a generic class that combines a Gaussian connective field and temporal model response.

Parameters:

encoding_model (BaseEncoder or type, default=CFStimulusEncoder) – An encoding model class or instance. Model classes will be instantiated during initialization. The default creates a CFStimulusEncoder instance.
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 three steps:

The Gaussian connective field response model makes a prediction for the stimulus distance matrix.
The encoding model encodes the connective field response with the source response.
The temporal model modifies the encoded response.

__call__(stimulus: prfmodel.stimuli.cf.CFStimulus, parameters: pandas.DataFrame, dtype: str | None = None) → prfmodel.typing.Tensor¶

Predict a simple connective field model response to a stimulus.

Parameters:

stimulus (CFStimulus) – Connective field 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 source response.

Return type:

Tensor

property parameter_names: list[str]¶: A list with names of unique parameters that are used by the submodels.