prfmodel.models.impulse¶

Population receptive field models.

Submodules¶

Classes¶

`ShiftedGammaImpulse`	Shifted gamma distribution impulse response model.
`ShiftedDerivativeGammaImpulse`	Shifted derivative of the gamma distribution impulse response model.
`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.
`derivative_gamma_density`(→ prfmodel.typing.Tensor)	Calculate the derivative density of a gamma distribution.
`gamma_density`(→ prfmodel.typing.Tensor)	Calculate the density of a gamma distribution.
`shifted_derivative_gamma_density`(→ prfmodel.typing.Tensor)	Calculate the density of a shifted derivative gamma distribution.
`shifted_gamma_density`(→ prfmodel.typing.Tensor)	Calculate the density of a shifted gamma distribution.

Package Contents¶

prfmodel.models.impulse.convolve_prf_impulse_response(prf_response: prfmodel.typing.Tensor, impulse_response: prfmodel.typing.Tensor, dtype: str | None = None) → 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).
dtype (str, optional) – The dtype of the prediction result. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

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.derivative_gamma_density(value: prfmodel.typing.Tensor, shape: prfmodel.typing.Tensor, rate: prfmodel.typing.Tensor) → prfmodel.typing.Tensor[source]¶

Calculate the derivative 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 derivative gamma distribution. Must be > 0 and scalar or with shape (1, m).
shape (Tensor) – The shape parameter. Must be > 0 and scalar or with shape (n, m).
rate (Tensor) – The rate parameter. Must be > 0 and scalar or with shape (n, m).

Returns:

The derivative density of the gamma distribution at value as a scalar or with shape (n, m).

Return type:

Tensor

Notes

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

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

The derivative of the density with respect to \(x\) can be defined as a function of the original density \(f(x)\):

\[f(x)' = f(x) \frac{(\alpha - 1)}{t} - \lambda\]

See also

gamma_density: The (unshifted) gamma distribution density.

class prfmodel.models.impulse.ShiftedGammaImpulse(duration: float = 32.0, offset: float = 0.0001, resolution: float = 1.0, default_parameters: dict[str, float] | None = None)[source]¶

Shifted gamma distribution impulse response model.

Predicts an impulse response that is a shifted gamma distribution. The model has three parameters: shape, rate, and shift.

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.
default_parameters (dict of float, optional) – Dictionary with scalar default parameter values. Keys must be valid parameter names.

Notes

The predicted impulse response at time \(t\) with shape \(\alpha\), rate \(\lambda\), and shift \(\delta\) is:

\[f(t) = \hat{f}_{\text{gamma}}(t - \delta; \alpha, \lambda)\]

The density of the gamma distribution is divided by its maximum, so that its highest peak has an amplitude of 1:

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

Examples

>>> import pandas as pd
>>> params = pd.DataFrame({
>>>     "shape": [2.0, 1.0, 1.5],
>>>     "rate": [1.0, 1.0, 1.0],
>>>     "shift": [1.0, 2.0, 5.0],
>>> })
>>> impulse_model = ShiftedGammaImpulse(
>>>     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, rate, and shift.

__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, rate, and shift.
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).

class prfmodel.models.impulse.ShiftedDerivativeGammaImpulse(duration: float = 32.0, offset: float = 0.0001, resolution: float = 1.0, default_parameters: dict[str, float] | None = None)[source]¶

Shifted derivative of the gamma distribution impulse response model.

Predicts an impulse response that is a shifted derivative of the gamma distribution. The model has three parameters: shape, rate, and shift.

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.
default_parameters (dict of float, optional) – Dictionary with scalar default parameter values. Keys must be valid parameter names.

Notes

The predicted impulse response at time \(t\) with shape \(\alpha\), rate \(\lambda\), and shift \(\delta\) is:

\[f(t) = \hat{f}_{\text{gamma}}'(t - \delta; \alpha, \lambda)\]

The derivative of the gamma distribution density is divided by its maximum, so that its highest peak has an amplitude of 1:

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

The derivative of the gamma distribution density with respect to time \(t\) is calculated analytically as a function of the original gamma distribution density \(f_{\text{gamma}}(t; \alpha, \lambda)\):

\[f_{\text{gamma}}'(t; \alpha, \lambda) = f_{\text{gamma}}(t; \alpha, \lambda) \frac{(\alpha - 1)}{t} - \lambda\]

Examples

>>> import pandas as pd
>>> params = pd.DataFrame({
>>>     "shape": [2.0, 1.0, 1.5],
>>>     "rate": [1.0, 1.0, 1.0],
>>>     "shift": [1.0, 2.0, 5.0],
>>> })
>>> impulse_model = ShiftedDerivativeGammaImpulse(
>>>     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, rate, and shift.

__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, rate, and shift.
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).

class prfmodel.models.impulse.TwoGammaImpulse(duration: float = 32.0, offset: float = 0.0001, resolution: float = 1.0, default_parameters: dict[str, float] | None = None)[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.
default_parameters (dict of float, optional) – Dictionary with scalar default parameter values. Keys must be valid parameter names.

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).