prfmodel.models.prf.DelayedNormPRFModel¶

class prfmodel.models.prf.DelayedNormPRFModel(prf_model: prfmodel.models.base.BaseTuning, 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 = BaselineAmplitude, regressors_model: prfmodel.regressors.base.BaseRegressors | list[prfmodel.regressors.base.BaseRegressors] | None = None)¶

Delayed gain normalization population receptive field (pRF) model.

Combines a pRF tuning model, stimulus encoding, and an impulse response (h₁) with an inline delayed normalization stage (h₂ = exponential decay) to form a complete DGN model. The computation and all DGN-specific parameters (n, dispersion_normalization, sigma_saturation, amplitude, baseline) live in this class; pRF tuning-specific parameters come from prf_model.

Parameters:

prf_model (BaseTuning) – A population receptive field tuning model instance.
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=BaselineAmplitude) – Scaling model applied to R(t) after the nonlinear stage. Model classes are instantiated during initialisation. Set to None to return R(t) unscaled.
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.

Notes

The delayed gain normalization model follows [1]:

Linear — pRF tuning profile encoded with the stimulus design, then convolved with the impulse response h₁ to produce L(t).

Normalization — L(t) is convolved with h₂ = exp(-t/τ₂) to produce g(t).

Nonlinear — R(t) = |L(t)|ⁿ / (sigmaⁿ + |g(t)|ⁿ).

Output — amplitude * R(t) + baseline.

Paper-recommended starting values (Fig. 2): n=2, dispersion_normalization=0.1, sigma_saturation=1, delay=0.05 (τ₁), weight_deriv=0.

References

__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 delayed gain normalization model response.

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.