prfmodel.utils

Utility functions.

Attributes

DTYPES

Accepted dtypes for prfmodel.typing.Tensor objects.

Exceptions

UndefinedResponseWarning

Warning for when a response is undefined and contains NaNs.

Classes

ParamsDict

A dictionary-like object that supports dataframe-style column selection but returns Keras tensors.

Functions

convert_parameters_to_tensor(→ prfmodel.typing.Tensor)	Convert model parameters in a dataframe into a tensor.
get_dtype(→ str)	Get the (default) dtype.
batched(→ collections.abc.Callable)	Decorate a model prediction function to make batched predictions.
normalize_response(→ prfmodel.typing.Tensor)	Normalize a response.

Module Contents

prfmodel.utils.DTYPES

Accepted dtypes for prfmodel.typing.Tensor objects.

Accepted dtypes are: “bfloat16”, “float16”, “float32”, and “float64”.

exception prfmodel.utils.UndefinedResponseWarning

Warning for when a response is undefined and contains NaNs.

prfmodel.utils.convert_parameters_to_tensor(parameters: pandas.DataFrame, dtype: str) → prfmodel.typing.Tensor

Convert model parameters in a dataframe into a tensor.

Parameters:

parameters (pandas.DataFrame) – Dataframe with columns containing different model parameters and rows containing parameter values for different voxels.

Returns:

Tensor with the first axis corresponding to voxels and the second axis corresponding to different parameters.

Return type:

Tensor

Examples

Single parameters:

>>> import pandas as pd
>>> params = pd.DataFrame({
>>>     "param_1": [0.0, 1.0, 2.0],
>>> })
>>> x = convert_parameters_to_tensor(params)
>>> print(x.shape)
(3, 1)

Multiple parameters:

>>> params = pd.DataFrame({
>>>     "param_1": [0.0, 1.0, 2.0],
>>>     "param_2": [0.0, -1.0, -2.0],
>>> })
>>> x = covert_parameters_to_tensor(params)
>>> print(x.shape)
(3, 2)

prfmodel.utils.get_dtype(dtype: str | None) → str

Get the (default) dtype.

Utility function to pass through a dtype or get the default dtype set by keras.config.floatx().

Parameters:

dtype (str or None) – The dtype to pass through. If None, returns keras.config.floatx().

Returns:

The dtype.

Return type:

str

Raises:

ValueError – When dtype is not of the values defined in DTYPES.

prfmodel.utils.batched(fn: collections.abc.Callable) → collections.abc.Callable

Decorate a model prediction function to make batched predictions.

Splits the parameters argument (a pandas.DataFrame) along the row (voxel) dimension into chunks of size batch_size, calls fn for each chunk, and concatenates the results along the first axis.

The wrapped function gains a batch_size keyword argument. When batch_size is None (the default), all voxels are processed in a single call.

Parameters:

fn (callable) – A model prediction function with signature fn(stimulus, parameters, **kwargs).

Returns:

Wrapped function with signature fn(stimulus, parameters, *, batch_size=None, **kwargs).

Return type:

callable

Examples

>>> from prfmodel.utils import batched
>>> batched_predict = batched(model)
>>> result = batched_predict(stimulus, parameters, batch_size=128)

As a decorator:

>>> @batched
... def predict(stimulus, parameters, *, dtype=None):
...     ...
>>> result = predict(stimulus, parameters, batch_size=64)

prfmodel.utils.normalize_response(response: prfmodel.typing.Tensor, norm: str | None = 'sum') → prfmodel.typing.Tensor

Normalize a response.

Divides a response by a normalization (e.g., its sum) computed over the second dimension.

Parameters:

• response (Tensor) – Response with shape (num_voxels, num_frames).

• norm (str, optional, default="sum") – Normalization to apply.

Returns:

The normalized response with shape (num_voxels, num_frames).

Return type:

Tensor

Notes

A warning is raised when the normalization is zero which leads to an undefined normalized response.

class prfmodel.utils.ParamsDict(data: dict, dtype: str | None = None)

A dictionary-like object that supports dataframe-style column selection but returns Keras tensors.

Serves as an adapter during fitting to supply parameters to models while avoiding converting tensors into actual dataframes.

Parameters:

• data (dict) – Dictionary of parameter tensors to perform column style selection on.

• dtype (str, optional) – The dtype that parameter tensors are converted to. If None (the default), uses the dtype from prfmodel.utils.get_dtype().

property columns: list[str]

Names of parameter columns.

property shape: tuple[int, int]

Shape of the parameters (rows, columns).

property dtype: str

The dtype of the parameters.

If None, uses keras.config.floatx() which defaults to float32.

copy() → ParamsDict

Create a copy of the object.

to_dataframe() → pandas.DataFrame

Convert the object into a dataframe.