nemos.observation_models.NegativeBinomialObservations

class nemos.observation_models.NegativeBinomialObservations(scale=1.0)

Bases: Observations

A Negative Binomial model for overdispersed count data using mean-dispersion parameterization.

This model represents a Negative Binomial distribution [4] commonly used to model overdispersed count data [5] [6] (i.e., data where the variance exceeds the mean), which cannot be captured by a standard Poisson model. The distribution is parameterized by the predicted mean rate (\(\mu\)) and a fixed dispersion parameter (\(\phi\)) or scale of the model.

Important: the scale parameter must be estimated from the data for accurately capturing the dispersion. In the context of NeMoS GLM, estimation can be achieved by cross-validating the scale parameter. One may use scikit-learn GridSearchCV for example.

The variance of the Negative Binomial distribution under this parameterization is:

\[\mathrm{Var}(Y) = \mu + \phi \mu^2\]

where \(\mu\) is the predicted mean, and \(\phi\) is the dispersion parameter. This formulation corresponds to the Negative Binomial as a Gamma–Poisson mixture.

The scale parameter \(\phi\) is related to the canonical Negative Binomial shape parameter r as:

\[r = \frac{1}{\phi}\]

As \(\phi \to 0\) (equivalently, \(r \to \infty\)), the distribution approaches a Poisson distribution. This makes the model flexible for handling both equidispersed (Poisson-like) and overdispersed data.

Parameters:

scale – The dispersion parameter \(\phi\). Lower values correspond to lower overdispersion, and as \(\phi \to 0\), the model behaves like a Poisson. The shape parameter of the Negative Binomial is given by r = 1 / scale.

References

[4]

https://en.wikipedia.org/wiki/Negative_binomial_distribution

[5]

Pillow, Jonathan, and James Scott. “Fully Bayesian inference for neural models with negative-binomial spiking.” Advances in neural information processing systems 25 (2012).

[6]

Wei, Ganchao, et al. “Calibrating Bayesian decoders of neural spiking activity.” Journal of Neuroscience 44.18 (2024).

Attributes

default_inverse_link_function
scale	Getter for the scale parameter of the model.

__init__(scale=1.0)

Methods

__init__([scale])
deviance(observations, predicted_rate[, scale])	Compute the residual deviance for a Negative Binomial model.
estimate_scale(y, predicted_rate, dof_resid)	Return the scale parameter of the distribution.
get_params([deep])	From scikit-learn, get parameters by inspecting init.
likelihood(y, predicted_rate[, scale, ...])	Compute the observation model likelihood.
log_likelihood(y, predicted_rate[, scale, ...])	Compute the Negative Binomial 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 Negative Binomial 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

[1]

https://www.python.org/dev/peps/pep-0487

property default_inverse_link_function

deviance(observations, predicted_rate, scale=None)

Compute the residual deviance for a Negative Binomial model.

The deviance measures how well a statistical model fits the data by quantifying the difference between the observed values and the values predicted by the model. Lower values of deviance indicate a better fit.

Parameters:

• observations (Array) – Observed count data. Shape (n_time_bins,) or (n_time_bins, n_observations).

• predicted_rate (Array) – Predicted mean count of the Negative Binomial distribution. Shape matches observations.

• scale (Union[float, Array, None]) – Dispersion parameter of the distribution.

Return type:

Array

Returns:

The residual deviance of the model. Shape matches observations.

Notes

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

\[\begin{split}\begin{aligned} D(y_{tn}, \hat{y}_{tn}) &= 2 \left( \text{LL}\left(y_{tn} | y_{tn}\right) - \text{LL}\left(y_{tn} | \hat{y}_{tn}\right)\right) \\\ &= 2 \left[ y_{tn} \log\left(\frac{y_{tn}}{\hat{y}_{tn}}\right) + (1 - y_{tn}) \log\left(\frac{1 - y_{tn}}{1 - \hat{y}_{tn}}\right) \right] \end{aligned}\end{split}\]

where \(y\) is the observed data, \(\hat{y}\) is the predicted data, and \(\text{LL}\) is the model log-likelihood.

estimate_scale(y, predicted_rate, dof_resid)

Return the scale parameter of the distribution.

The scale parameter of the Negative Binomial distribution is set at initialization and affect the likelihood landscape. This implies that the scale parameter cannot be estimated post-hoc without re-fitting a model.

Note that the arguments of this method are not used but are kept for API consistency—i.e., all Observations.estimate_scale methods have the same signature.

Parameters:

• y (Array) – Observed spike counts.

• predicted_rate (Array) – The predicted mean of the distribution.

• dof_resid (Union[float, Array]) – The DOF of the residuals.

Return type:

Union[float, Array]

Notes

NeMoS currently does not support joint estimation of scale and mean for the negative binomial. For alternatives, see the R package MASS glm.nb for more details.

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

Compute the observation model likelihood.

This computes the likelihood of the predicted rates for the observed neural activity including the normalization constant.

Parameters:

• y (Array) – The target activity to compare against. Shape (n_time_bins, ), or (n_time_bins, n_neurons).

• predicted_rate (Array) – The predicted rate of the current model. Shape (n_time_bins, ), or (n_time_bins, n_neurons).

• scale (Union[float, Array]) – The scale parameter of the model

• aggregate_sample_scores (Callable) – Function that aggregates the log-likelihood of each sample.

Returns:

The likelihood. Shape (1,).

log_likelihood(y, predicted_rate, scale=None, aggregate_sample_scores=<function NegativeBinomialObservations.<lambda>>)

Compute the Negative Binomial log-likelihood.

This computes the Negative Binomial log-likelihood of the predicted mean rate for the observed counts.

Parameters:

• y (Array) – Observed count data. Shape (n_time_bins,) or (n_time_bins, n_observations).

• predicted_rate (Array) – The predicted mean of the Negative Binomial distribution. Shape (n_time_bins,) or (n_time_bins, n_observations).

• scale (Union[float, Array, None]) – The scale (dispersion) parameter of the distribution. It is related to the shape r as r = 1 / scale. Default is the scale provided at initialization self.scale.

• aggregate_sample_scores (Callable) – Function that aggregates the log-likelihood across samples (e.g., jnp.mean or jnp.sum).

Returns:

The log-likelihood of the Negative Binomial model. Shape (1,).

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

[2]

McFadden D (1979). Quantitative methods for analysing travel behavior of individuals: Some recent developments. In D. A. Hensher & P. R. Stopher (Eds.), Behavioural travel modelling (pp. 279-318). London: Croom Helm.

[3]

Jacob Cohen, Patricia Cohen, Steven G. West, Leona S. Aiken. Applied Multiple Regression/Correlation Analysis for the Behavioral Sciences. 3rd edition. Routledge, 2002. p.502. ISBN 978-0-8058-2223-6. (May 2012)

sample_generator(key, predicted_rate, scale=None)

Sample from the Negative Binomial distribution.

This method generates random count data from the Negative Binomial distribution based on the predicted rate and scale (dispersion).

Parameters:

• key (Array) – Random key used for number generation in JAX.

• predicted_rate (Array) – The predicted mean of the Negative Binomial distribution. Shape (n_time_bins,) or (n_time_bins, n_observations).

• scale (Union[float, Array, None]) – Dispersion parameter of the distribution. Smaller values imply higher variance.

Return type:

Array

Returns:

Samples drawn from the Negative Binomial distribution. Same shape as predicted_rate.

Notes

This method uses the Gamma–Poisson mixture representation of the Negative Binomial distribution:

\[Y \sim \text{Poisson}(\lambda), \quad \lambda \sim \text{Gamma}(r, \beta)\]

where \(r = 1 / \phi\) and \(\beta = r / \mu\).

For more information, see the Negative Binomial distribution on Wikipedia.

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