prfmodel.models.impulse¶

Impulse response models.

Submodules¶

Classes¶

`ShiftedGammaImpulse`	Shifted gamma distribution impulse response model.
`TwoGammaImpulse`	Weighted difference of two gamma distributions impulse response model.
`DerivativeTwoGammaImpulse`	Weighted difference of two derivative 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_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 gamma distribution density.

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 and scalar or with shape (1, m).
shape (Tensor) – The shape parameter. Must be > 0 with shape () and scalar or with shape (n, 1).
rate (Tensor) – The rate parameter. Must be > 0 and scalar or with shape (n, 1).
norm (bool, default=True) – Whether to compute the normalized density.

Returns:

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

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

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

Calculate the density of a shifted gamma distribution.

The gamma distribution is shifted by shift and padded with zeros if necessary.

Parameters:

value (Tensor) – The values at which to evaluate the shifted gamma distribution. Must be scalar or with shape (1, m).
shape (Tensor) – The shape parameter. Must be > 0 and scalar or with shape (n, 1).
rate (Tensor) – The rate parameter. Must be > 0 and scalar or with shape (n, 1).
shift (Tensor) – The shift parameter. When > 0, shifts the distribution to the right.
norm (bool, default=True) – Whether to compute the normalized density.

Returns:

The density of the shifted gamma distribution at value as a scalar or with shape (n, m). The density for shifted values that are zero or lower is zero.

Return type:

Tensor

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, norm: str | None = 'sum', 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: delay refers to the positive peak, dispersion to the rate, and shift to the onset of the 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.
norm (str, optional, default="sum") – The normalization of the response. Can be “sum” (default), “mean”, “max”, “norm”, or None. If None, no normalization is performed.
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 \(\alpha = delay / dispersion\), \(\lambda = dispersion\), and \(\delta = shift\) is:

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

The response prior to the onset of the gamma distribution is set to zero.

See also

shifted_gamma_density: Shifted density of the gamma distribution.

Examples

>>> import pandas as pd
>>> params = pd.DataFrame({
>>>     "delay": [2.0, 1.0, 1.5],
>>>     "dispersion": [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: delay, dispersion, 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 delay, dispersion, 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, norm: str | None = 'sum', 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: delay and undershoot refer to the positive and negative peaks of the response while dispersion and u_dispersion refer to the rate parameters of the two gamma distributions. The ratio parameter indicates the weight of the second 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.
norm (str, optional, default="sum") – The normalization of the response. Can be “sum” (default), “mean”, “max”, “norm”, or None. If None, no normalization is performed.
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 \(\alpha_1 = delay / dispersion\), \(\lambda_1 = dispersion\), \(\alpha_2 = undershoot / u\_dispersion\), \(\lambda_2 = u\_dispersion\), and \(\omega = ratio\) is:

\[f(t) = f_{\text{gamma}}(t; \alpha_1, \lambda_1) - \omega f_{\text{gamma}}(t; \alpha_2, \lambda_2)\]

See also

gamma_density: Density of the gamma distribution.

Examples

>>> import pandas as pd
>>> params = pd.DataFrame({
>>>     "delay": [2.0, 1.0, 1.5],
>>>     "dispersion": [1.0, 1.0, 1.0],
>>>     "undershoot": [1.5, 2.0, 1.0],
>>>     "u_dispersion": [1.0, 1.0, 1.0],
>>>     "ratio": [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: delay, dispersion, undershoot, u_dispersion, ratio.

__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 delay, dispersion, undershoot, u_dispersion, and ratio.
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.DerivativeTwoGammaImpulse(duration: float = 32.0, offset: float = 0.0001, resolution: float = 1.0, norm: str | None = 'sum', default_parameters: dict[str, float] | None = None)[source]¶

Weighted difference of two derivative gamma distributions impulse response model.

Predicts an impulse response that is the weighted derivative difference of two gamma distributions. This weighted derivative difference is added to the weighted difference of the two gamma distributions. The model has six parameters: delay and undershoot refer to the positive and negative peaks of the response while dispersion and u_dispersion refer to the rate parameters of the two gamma distributions. The ratio parameter indicates the weight of the second gamma distribution. The weight_deriv represents the weight of the derivative difference added to the standard difference.

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.
norm (str, optional, default="sum") – The normalization of the response. Can be “sum” (default), “mean”, “max”, “norm”, or None. If None, no normalization is performed.
default_parameters (dict of float, optional) – Dictionary with scalar default parameter values. Keys must be valid parameter names.

Notes

\[f(t) = f_{\text{diff}}(t) - \tau f'_{\text{diff}}(t)\]

\[f_{\text{diff}}(t) = f_{\text{gamma}}(t; \alpha_1, \lambda_1) - \omega f_{\text{gamma}}(t; \alpha_2, \lambda_2)\]

Positive weight_deriv values shift the response to the right.

See also

TwoGammaImpulse: Weighted difference of two gamma distributions impulse response model.
gamma_density: Density of the gamma distribution.
derivative_gamma_density: Derivative density of the gamma distribution.

Examples

>>> import pandas as pd
>>> params = pd.DataFrame({
>>>     "delay": [2.0, 1.0, 1.5],
>>>     "dispersion": [1.0, 1.0, 1.0],
>>>     "undershoot": [1.5, 2.0, 1.0],
>>>     "u_dispersion": [1.0, 1.0, 1.0],
>>>     "ratio": [0.7, 0.2, 0.5],
>>>     "weight_deriv": [0.5, -0.7, 0.9],
>>> })
>>> impulse_model = DerivativeTwoGammaImpulse(
>>>     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: delay, dispersion, undershoot, u_dispersion, ratio, weight_deriv.

__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 delay, dispersion, undershoot, u_dispersion, ratio, and weight_deriv.
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).