prfmodel.regressors.RegressorsList¶

class prfmodel.regressors.RegressorsList(regressors: list[prfmodel.regressors.base.BaseRegressors])¶

Composite regressor model that sums the predictions of multiple regressor models.

Used internally by canonical models to support passing a list of regressor models as the regressors_model argument. The parameter names of all child regressor models are aggregated (preserving insertion order, removing duplicates).

At call time, the supplied design is a single pandas.DataFrame or TensorFrame that is passed to every child, each of which slices the columns it needs by name.

Parameters:

regressors (list of BaseRegressors) – Non-empty list of regressor model instances.

Raises:

ValueError – If regressors is empty.
TypeError – If any element is not a BaseRegressors instance.

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from prfmodel.regressors import AdditiveRegressors, RegressorsList
>>> a = AdditiveRegressors(names=["x"])
>>> b = AdditiveRegressors(names=["y"])
>>> regressors_model = RegressorsList([a, b])
>>> regressors_model.parameter_names
['beta_x', 'beta_y']
>>> params = pd.DataFrame({"beta_x": [1.0], "beta_y": [1.0]})
>>> design = pd.DataFrame({"x": np.ones(5), "y": np.ones(5) * 2.0})
>>> resp = regressors_model(design, params)
>>> print(resp.shape)
(1, 5)

__call__(regressors: pandas.DataFrame, parameters: pandas.DataFrame, dtype: str | None = None) → numpy.ndarray¶

Compute the additive regressor contribution.

This is the public entry point; subclasses implement call() instead. Use call() when a backend tensor is required.

Parameters:

regressors (pandas.DataFrame) – Regressor design with shape (num_frames, num_regressors). Must contain a column for each name in names; extra columns are ignored.
parameters (pandas.DataFrame) – Dataframe with columns containing different model parameters and rows containing parameter values for different units.
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:

numpy.ndarray

Raises:

ValueError – If parameters is missing one or more of parameter_names.

call(regressors: prfmodel.utils.TensorFrame, parameters: prfmodel.utils.TensorFrame) → prfmodel.typing.Tensor¶

Compute the sum of predictions from all child regressor models.

Parameters:

regressors (TensorFrame or None, optional) – Regressor design columns as tensors, supporting the same column selection as a pandas.DataFrame.
parameters (TensorFrame) – Model parameters 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:

Tensor

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_names attribute is not a column in parameters.

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 > 0 is zero or negative.

check_regressor_names(regressors: pandas.DataFrame) → None¶

Check that required columns are supplied in the regressor design.

Parameters:: regressors (pandas.DataFrame) – Regressor design with shape (num_frames, num_regressors). Must contain a column for each name in names; extra columns are ignored.
Raises:: ValueError – When a column is missing in the regressor design.

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:: list of str

models¶

A dictionary with the named submodels.

Parameters:: models (dict of ModelProtocol) – Named submodels.
Raises:: TypeError – When a submodel does not inherit from ModelProtocol.

property parameter_names: list[str]¶: A list with names of unique parameters that are used by the submodels.

property regressor_names: list[str]¶: Columns this model reads from the regressor design.