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 fromprf_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
PRFStimulusEncoderinstance.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
DerivativeTwoGammaImpulseinstance with default values. Impulse models without an explicit resolution are sampled at the frame duration of the stimulus.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
Noneto 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
RegressorsListand 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. Usecall()when a backend tensor is required, for example inside a fitter or another model’scall().- 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:
- Raises:
ValueError – If parameters is missing one or more of
parameter_names.- Warns:
ResolutionMismatchWarning – When an impulse submodel has an explicit resolution that differs from the frame duration of the stimulus. See
check_stimulus().
- 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:
- 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_namesattribute is not a column inparameters.
- 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
> 0is zero or negative.
- check_stimulus(stimulus: S) None¶
Check that the impulse submodels are sampled at the frame duration of the stimulus.
Impulse submodels without an explicit
resolutionare sampled at the frame duration of the stimulus incall()and always pass this check. Stimuli without a frame duration (e.g.,CFStimulus) are not checked.- Parameters:
stimulus (Stimulus) – Stimulus object.
- Warns:
ResolutionMismatchWarning – When an impulse submodel has an explicit resolution that differs from the frame duration of stimulus.
- 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:
- 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.