prfmodel.models.impulse¶

Impulse response models.

Classes¶

TwoGammaImpulse

Weighted difference of two gamma distributions impulse response model.

Functions¶

`convolve_prf_impulse_response`(→ prfmodel.typing.Tensor)	Convolve the encoded response from a population receptive field model with an impulse response.
`gamma_density`(→ prfmodel.typing.Tensor)	Calculate the density of a gamma distribution.

Module Contents¶

prfmodel.models.impulse.convolve_prf_impulse_response(prf_response: prfmodel.typing.Tensor, impulse_response: prfmodel.typing.Tensor) → prfmodel.typing.Tensor[source]¶

Convolve the encoded response from a population receptive field model with an impulse response.

Both responses must have the same number of batches but can have different numbers of frames.

Parameters:

prf_response (Tensor) – Encoded population receptive field model response. Must have shape (num_batches, num_response_frames).
impulse_response (Tensor) – Impulse response. Must have shape (num_batches, num_impulse_frames).

Returns:

Convolved response with shape (num_batches, num_response_frames).

Return type:

Tensor

Notes

Before convolving both responses, the prf_response is padded on the left side in the num_frames dimension by repeating the first value of each batch. This ensures that the output of the convolution has the same shape as prf_response and the impulse_response starts at every frame of the prf_response.

Raises:: BatchDimensionError – If prf_response and impulse_response have batch (first) dimensions with different sizes.

prfmodel.models.impulse.gamma_density(value: prfmodel.typing.Tensor, shape: prfmodel.typing.Tensor, rate: prfmodel.typing.Tensor, norm: bool = True) → prfmodel.typing.Tensor[source]¶

Calculate the density of a gamma distribution.

The distribution uses a shape and rate parameterization. Raises an error when evaluated at negative values.

Parameters:

value (Tensor) – The values at which to evaluate the gamma distribution. Must be > 0.
shape (Tensor) – The shape parameter. Must be > 0.
rate (Tensor) – The rate parameter. Must be > 0.
norm (bool, default=True) – Whether to compute the normalized density.

Returns:

The density of the gamma distribution at value.

Return type:

Tensor

Notes

The unnormalized density of the gamma distribution with shape \(\alpha\) and rate \(\lambda\) is given by:

\[f(x) = x^{\mathtt{\alpha} - 1} e^{\mathtt{\lambda} x}.\]

When norm=True, the density is multiplied with a normalizing constant:

\[f_{norm} = \frac{\mathtt{\lambda}^{\mathtt{\alpha}}}{\Gamma(\mathtt{\alpha})} * f(x).\]

Raises:: ValueError – If values, shape, or rate are zero or negative.

class prfmodel.models.impulse.TwoGammaImpulse(duration: float = 32.0, offset: float = 0.0001, resolution: float = 1.0)[source]¶

Weighted difference of two gamma distributions impulse response model.

Predicts an impulse response that is the weighted difference of two gamma distributions. The model has five parameters: shape_1 and rate_1 for the first, shape_2 and rate_2 for the second gamma distribution, and weight for the relative weight of the first gamma distribution.

Parameters:

duration (float, default=32.0) – The duration of the impulse response (in seconds).
offset (float, default=0.0001) – The offset of the impulse response (in seconds). By default a very small offset is added to prevent infinite response values at t = 0.
resolution (float, default=1.0) – The time resultion of the impulse response (in seconds), that is the number of points per second at which the impulse response function is evaluated.
dtype (str, default="float64") – Dtype of the impulse response.

Notes

The predicted impulse response at time \(t\) with shape_1 \(\alpha_1\), rate_1 \(\lambda_1\), shape_2 \(\alpha_2\), rate_2 \(\lambda_2\), and weight \(w\) is:

\[f(t) = \hat{f}_{\text{gamma}}(t; \alpha_1, \lambda_1) - w \hat{f}_{\text{gamma}}(t; \alpha_2, \lambda_2)\]

The gamma distributions are divided by their respective maximum, so that their highest peak has an amplitude of 1:

\[\hat{f}_{\text{gamma}}(t; \alpha, \lambda) = \frac{f_{\text{gamma}}(t; \alpha, \lambda)} {\text{max}(f_{\text{gamma}}(t; \alpha, \lambda))}\]

Examples

>>> import pandas as pd
>>> params = pd.DataFrame({
>>>     "shape_1": [2.0, 1.0, 1.5],
>>>     "rate_1": [1.0, 1.0, 1.0],
>>>     "shape_2": [1.5, 2.0, 1.0],
>>>     "rate_2": [1.0, 1.0, 1.0],
>>>     "weight": [0.7, 0.2, 0.5],
>>> })
>>> impulse_model = TwoGammaImpulse(
>>>     duration=100.0 # 100 seconds
>>> )
>>> resp = impulse_model(params)
>>> print(resp.shape) # (num_rows, duration)
(3, 100)

property parameter_names: list[str]¶

Names of parameters used by the model.

Parameter names are: shape_1, rate_1, shape_2, rate_2, weight.

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

Predict the impulse response.

Parameters:

parameters (pandas.DataFrame) – Dataframe with columns containing different model parameters and rows containing parameter values for different batches. Must contain the columns shape_1, rate_1, shape_2, rate_2, and weight.
dtype (str, optional) – The dtype of the prediction result. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

Returns:

The predicted impulse response with shape (num_batches, num_frames) and dtype dtype.

Return type:

Tensor

property num_frames: int¶: The total number of time frames at which the impulse response function is evaluated.

property frames: prfmodel.typing.Tensor¶

The time frames at which the impulse response function is evaluated.

Time frames are linearly interpolated between offset and duration and have shape (1, num_frames).