nemos.observation_models.CategoricalObservations#

class nemos.observation_models.CategoricalObservations[source]#

Bases: Observations

Model observations as Categorical random variables.

The CategoricalObservations is designed to model an observed categorical variable based on a categorical distribution with given success probability. It provides methods for computing the negative log-likelihood, generating samples, and computing the residual deviance for the given categorical observations. This distribution is equivalent to a multinomial with n=1.

Attributes

`default_inverse_link_function`
`scale`	Getter for the scale parameter of the model.

__init__()[source]#

Methods

`__init__`()
`deviance`(observations, predicted_rate[, scale])	Compute the residual deviance for a Categorical model.
`estimate_scale`(y, predicted_rate, dof_resid)	Assign 1 to the scale parameter of the Categorical model.
`get_params`([deep])	From scikit-learn, get parameters by inspecting init.
`likelihood`(y, predicted_rate[, scale, ...])	Compute the Categorical model likelihood.
`log_likelihood`(y, predicted_rate[, scale, ...])	Compute the Categorical log-likelihood.
`pseudo_r2`(y, predicted_rate[, score_type, ...])	Pseudo-\(R^2\) calculation for a GLM.
`sample_generator`(key, predicted_rate[, scale])	Sample from the Categorical distribution.
`set_params`(**params)	Set the parameters of this estimator.

classmethod __init_subclass__(**kwargs)#

Set the set_{method}_request methods.

This uses PEP-487 [1] to set the set_{method}_request methods. It looks for the information available in the set default values which are set using __metadata_request__* class attributes, or inferred from method signatures.

The __metadata_request__* class attributes are used when a method does not explicitly accept a metadata through its arguments or if the developer would like to specify a request value for those metadata which are different from the default None.

References

property default_inverse_link_function#

deviance(observations, predicted_rate, scale=1.0)[source]#

Compute the residual deviance for a Categorical model.

Parameters:

observations (Array) – One-hot encoded categories. Shape (n_time_bins, n_categories) or (n_time_bins, n_neurons, n_categories).
predicted_rate (Array) – The log-probabilities of each category (output of log_softmax). Shape (n_time_bins, n_categories) or (n_time_bins, n_neurons, n_categories).
scale (Union[float, Array]) – Scale parameter of the model. For Categorical should be equal to 1.

Return type:

Array

Returns:

The residual deviance of the model. Shape (n_time_bins,) or (n_time_bins, n_neurons).

Notes

The deviance is a measure of the goodness of fit of a statistical model. For a Categorical model, the residual deviance is computed as:

\[D(y, \hat{p}) = 2 \left( \text{LL}\left(y | y\right) - \text{LL}\left(y | \hat{p}\right)\right) = -2 \sum_{k=1}^{K} y_{k} \log(\hat{p}_{k})\]

where \(y_k\) is the one-hot encoded observed category (1 if category \(k\) was observed, 0 otherwise), \(\hat{p}_{k}\) is the predicted probability for category \(k\), and \(\text{LL}\) is the model log-likelihood. The saturated model has log-likelihood 0 for categorical (since \(\log(1) = 0\) for the true category). Lower values of deviance indicate a better fit.

estimate_scale(y, predicted_rate, dof_resid)[source]#

Assign 1 to the scale parameter of the Categorical model.

For the Categorical (Multinomial with n=1) exponential family distribution, the scale parameter \(\phi\) is always 1.

Parameters:

y (Array) – One-hot encoded categories. Shape (n_time_bins, n_categories) or (n_time_bins, n_neurons, n_categories).
predicted_rate (Array) – The predicted log-probabilities. This is not used in the Categorical model for estimating scale, but is retained for compatibility with the abstract method signature.
dof_resid (Union[float, Array]) – The DOF of the residuals.

Return type:

Union[float, Array]

get_metadata_routing()#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:: routing – A MetadataRequest encapsulating routing information.
Return type:: MetadataRequest

get_params(deep=True)#

From scikit-learn, get parameters by inspecting init.

Parameters:: deep – If True, will return the parameters for this estimator and contained subobjects that are estimators.
Return type:: dict
Returns:: A dictionary containing the parameters. Key is the parameter name, value is the parameter value.

likelihood(y, predicted_rate, scale=1.0, aggregate_sample_scores=<function CategoricalObservations.<lambda>>)[source]#

Compute the Categorical model likelihood.

This computes the likelihood of the predicted category probabilities for the observed one-hot encoded categories.

Parameters:

y (Array) – One-hot encoded categories. Shape (n_time_bins, n_categories) or (n_time_bins, n_neurons, n_categories).
predicted_rate (Array) – The log-probabilities for each category (output of log_softmax). Shape (n_time_bins, n_categories) or (n_time_bins, n_neurons, n_categories).
scale (Union[float, Array]) – The scale parameter of the model. For Categorical should be equal to 1.
aggregate_sample_scores (Callable) – Function that aggregates the likelihood of each sample.

Returns:

The likelihood. Shape (1,).

Notes

The likelihood is computed as:

\[L(y | p) = \prod_{n=1}^{N} \prod_{t=1}^{T} \prod_{k=1}^{K} p_{tnk}^{y_{tnk}}\]

where \(p_{tnk}\) is the predicted probability of category \(k\) for neuron \(n\) at time \(t\), and \(y_{tnk}\) is the one-hot encoding.

log_likelihood(y, predicted_rate, scale=1.0, aggregate_sample_scores=<function CategoricalObservations.<lambda>>)[source]#

Compute the Categorical log-likelihood.

This computes the Categorical log-likelihood of the predicted category probabilities for the observed one-hot encoded categories.

Parameters:

y (Array) – One-hot encoded categories. Shape (n_time_bins, n_categories) or (n_time_bins, n_neurons, n_categories).
predicted_rate (Array) – The log-probabilities for each category (output of log_softmax). Shape (n_time_bins, n_categories) or (n_time_bins, n_neurons, n_categories).
scale (Union[float, Array]) – The scale parameter of the model. For Categorical should be equal to 1.
aggregate_sample_scores (Callable) – Function that aggregates the log-likelihood of each sample.

Returns:

The Categorical log-likelihood. Shape (1,).

Notes

The formula for the Categorical mean log-likelihood is the following,

\[\text{LL}(y | \log(p)) = \frac{1}{T \cdot N} \sum_{n=1}^{N} \sum_{t=1}^{T} \sum_{k=1}^{K} y_{tnk} \log(p_{tnk})\]

where \(p_{tnk}\) is the predicted probability of category \(k\) for neuron \(n\) at time \(t\), \(y_{tnk}\) is the one-hot encoding (1 if category \(k\) was observed, 0 otherwise), and the predicted_rate input contains \(\log(p_{tnk})\).

pseudo_r2(y, predicted_rate, score_type='pseudo-r2-McFadden', scale=1.0, aggregate_sample_scores=<function Observations.<lambda>>)#

Pseudo-\(R^2\) calculation for a GLM.

Compute the pseudo-\(R^2\) metric for the GLM, as defined by McFadden et al. [2] or by Cohen et al. [3].

This metric evaluates the goodness-of-fit of the model relative to a null (baseline) model that assumes a constant mean for the observations. While the pseudo-\(R^2\) is bounded between 0 and 1 for the training set, it can yield negative values on out-of-sample data, indicating potential over-fitting.

Parameters:

y (Array) – The neural activity. Expected shape: (n_time_bins, )
predicted_rate (Array) – The mean neural activity. Expected shape: (n_time_bins, )
score_type (Literal['pseudo-r2-McFadden', 'pseudo-r2-Cohen']) – The pseudo-\(R^2\) type.
scale (Union[float, Array, ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]]) – The scale parameter of the model.
aggregate_sample_scores (Callable)

Return type:

Array

Returns:

The pseudo-\(R^2\) of the model. A value closer to 1 indicates a better model fit, whereas a value closer to 0 suggests that the model doesn’t improve much over the null model.

Notes

The McFadden pseudo-\(R^2\) is given by:

\[R^2_{\text{mcf}} = 1 - \frac{\log(L_{M})}{\log(L_0)}.\]

Equivalent to statsmodels GLMResults.pseudo_rsquared(kind=’mcf’) .
The Cohen pseudo-\(R^2\) is given by:

\[\begin{split}\begin{aligned} R^2_{\text{Cohen}} &= \frac{D_0 - D_M}{D_0} \\\ &= 1 - \frac{\log(L_s) - \log(L_M)}{\log(L_s)-\log(L_0)}, \end{aligned}\end{split}\]

where \(L_M\), \(L_0\) and \(L_s\) are the likelihood of the fitted model, the null model (a model with only the intercept term), and the saturated model (a model with one parameter per sample, i.e. the maximum value that the likelihood could possibly achieve). \(D_M\) and \(D_0\) are the model and the null deviance, \(D_i = -2 \left[ \log(L_s) - \log(L_i) \right]\) for \(i=M,0\).

References

sample_generator(key, predicted_rate, scale=1.0)[source]#

Sample from the Categorical distribution.

This method generates random category indices from a Categorical distribution based on the given log-probabilities. Note that this returns category indices, not one-hot encodings.

Parameters:

key (Array) – Random key used for the generation of random numbers in JAX.
predicted_rate (Array) – Log-probabilities for each category (output of log_softmax). Shape (n_time_bins, n_categories) or (n_time_bins, n_neurons, n_categories).
scale (Union[float, Array]) – Scale parameter. For Categorical should be equal to 1.

Returns:

Random category indices sampled from the Categorical distribution. Shape (n_time_bins,) or (n_time_bins, n_neurons).

Return type:

Array

property scale#: Getter for the scale parameter of the model.

set_params(**params)#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:: **params (Any) – Estimator parameters.
Returns:: self – Estimator instance.
Return type:: estimator instance