prfmodel.models.base.BaseCanonical¶

class prfmodel.models.base.BaseCanonical(**models: prfmodel.utils.ModelProtocol | None)¶

Generic abstract base class for creating canonical models.

A canonical model combines multiple submodels and defines how they interact to make a combined prediction.

Parameters:: **models – Submodels to be combined into the canonical model. All submodel classes must inherit from ModelProtocol.
Raises:: TypeError – If submodel classes do not inherit from ModelProtocol.

Notes

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

Examples

Create a canonical model that combines a Gaussian2DPRFResponse and a PRFStimulusEncoder. The parameter_names property automatically aggregates the unique parameter names from all submodels.

>>> import pandas as pd
>>> from prfmodel.examples import load_2d_prf_bar_stimulus
>>> from prfmodel.stimuli import PRFStimulus
>>> from prfmodel.models.prf import Gaussian2DPRFResponse, PRFStimulusEncoder
>>> class CanonicalPRFModel(BaseCanonical[PRFStimulus]):
...     def __call__(self, stimulus, parameters, dtype=None):
...         response = self.models["prf_model"](stimulus, parameters, dtype=dtype)
...         return self.models["encoding_model"](stimulus, response, parameters, dtype=dtype)
>>> model = CanonicalPRFModel(
...     prf_model=Gaussian2DPRFResponse(),
...     encoding_model=PRFStimulusEncoder(),
... )
>>> model.parameter_names
['mu_y', 'mu_x', 'sigma']
>>> stimulus = load_2d_prf_bar_stimulus()
>>> params = pd.DataFrame({"mu_y": [0.0, 1.0], "mu_x": [1.0, 0.0], "sigma": [1.0, 1.5]})
>>> resp = model(stimulus, params)
>>> print(resp.shape)  # (num_units, num_frames)
(2, 200)

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

Predict a canonical model response to a stimulus.

Parameters:

stimulus (Stimulus) – Stimulus object.
parameters (pandas.DataFrame) – Dataframe with columns containing different model parameters and rows containing parameter values for different units.
dtype (str, optional) – The dtype of the prediction result. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

The predicted model response with shape (num_units, num_frames) and dtype dtype.

Return type:

Tensor

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