prfmodel.models.prf.canonical.DivNormPRFModel¶

class prfmodel.models.prf.canonical.DivNormPRFModel(prf_model: prfmodel.models.base.BaseTuning, shared_params: list[str] | None = None, encoding_model: prfmodel.models.base.BaseStimulusEncoder | type[prfmodel.models.base.BaseStimulusEncoder] = PRFStimulusEncoder, impulse_model: prfmodel.impulse.base.BaseImpulse | type[prfmodel.impulse.base.BaseImpulse] | None = DerivativeTwoGammaImpulse, scaling_model: prfmodel.scaling.base.BaseScaling | type[prfmodel.scaling.base.BaseScaling] | None = Baseline, regressors_model: prfmodel.regressors.base.BaseRegressors | list[prfmodel.regressors.base.BaseRegressors] | None = None, min_baseline_normalization: float = 1e-10)¶

Divisive normalization population receptive field (pRF) model.

This class performs divisive normalization between an activation (numerator) and a normalization (denominator) pRF tuning profile and combines them with an impulse and scaling model. Both tuning profiles come from the same model class, but their parameters can differ.

Parameters:

prf_model (BaseTuning) – A population receptive field tuning model instance.
shared_params (list of str, optional) – Names of pRF parameters that are shared between the two tuning models. All names must appear in prf_model.parameter_names.
encoding_model (BaseStimulusEncoder or type, default=PRFStimulusEncoder) – An stimulus 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 model class or instance. Model classes will be instantiated during initialization. The default creates a DerivativeTwoGammaImpulse instance with default values.
scaling_model (BaseScaling or type or None, default=Baseline, optional) – A scaling model class or instance. Model classes will be instantiated during initialization. The default creates a Baseline instance.
regressors_model (BaseRegressors or list of BaseRegressors or RegressorsList or None, default=None, optional) – A regressor model instance, a list of regressor model instances, or None. When a list is provided, it is wrapped in a RegressorsList and its contributions are summed. The regressor contribution is added after the scaling model.
min_baseline_normalization (float, default=1e-10) – Lower bound applied to baseline_normalization before it is used. Keeps the b / d offset term finite when baseline_normalization is zero.

Notes

The divisive normalization model follows these steps

The two pRF tuning models make predictions for the stimulus grid.
The encoding model encodes the tuning profiles with the stimulus design.
The two encoded responses are combined through divisive normalization.
The combined response is convolved with an impulse response (optional).
The scaling model modifies the convolved response (optional).
The regressors model adds a linear combination of fixed regressors to the scaled response (optional).

__call__(stimulus: S, parameters: pandas.DataFrame, regressors: pandas.DataFrame | None = None, dtype: str | None = None) → numpy.ndarray¶

Predict a canonical model response to a stimulus.

This is the public entry point; subclasses implement call() instead. Use call() when a backend tensor is required, for example inside a fitter or another model’s call().

Parameters:

stimulus (Stimulus) – Stimulus object.
parameters (pandas.DataFrame) – Dataframe with columns containing different model parameters and rows containing parameter values for different units.
regressors (pandas.DataFrame, optional) – Regressor design data. Required when the canonical model has a regressors model configured. A single data frame with shape (num_frames, num_regressors) whose columns cover the names required by every configured regressor model. Extra columns are ignored.
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:

numpy.ndarray

Raises:

ValueError – If parameters is missing one or more of parameter_names.

call(stimulus: prfmodel.stimuli.PRFStimulusTensors, parameters: prfmodel.utils.TensorFrame, regressors: prfmodel.utils.TensorFrame | None = None) → prfmodel.typing.Tensor¶

Predict the combined model response to a stimulus.

Parameters:

stimulus (PRFStimulusTensors) – Tensor-holding population receptive field stimulus object, from to_tensors().
parameters (TensorFrame) – Model parameters as tensors, supporting the same column selection as a pandas.DataFrame.
regressors (TensorFrame or None, optional) – Regressor design columns as tensors, supporting the same column selection as a pandas.DataFrame.

Returns:

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

Return type:

Tensor

check_parameter_names(parameters: pandas.DataFrame) → None¶

Check that required parameter names are supplied.

Parameters:: parameters (pandas.DataFrame) – Dataframe with columns containing different model parameters and rows containing parameter values for different units.
Raises:: ValueError – When a parameter name in the parameter_names attribute is not a column in parameters.

check_parameter_values(parameters: pandas.DataFrame) → None¶

Check that the parameter values lie inside the domain the model is defined on.

Parameters:: parameters (pandas.DataFrame) – Dataframe with columns containing different model parameters and rows containing parameter values for different units.
Raises:: ValueError – When a parameter that must be > 0 is zero or negative.

get_consumed_parameter_names(parameters: pandas.DataFrame) → list[str]¶

Return the parameter names this model and its submodels read from parameters.

Parameters:: parameters (pandas.DataFrame) – Dataframe with columns containing different model parameters and rows containing parameter values for different units.
Returns:: Names of the parameters this model and its submodels read from parameters.
Return type:: list of str

property models: dict[str, ModelProtocol | None]¶

A dictionary with the named submodels.

Parameters:: models (dict of ModelProtocol) – Named submodels.
Raises:: TypeError – When a submodel does not inherit from ModelProtocol.

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