cubmods package#

Submodules#

cubmods.cub module#

CUB models in Python. Module for CUB (Combination of Uniform and Binomial).

Description#

This module contains methods and classes for CUB model family.

Manual, Examples and References:#

See the Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cub.CUBresCUB00(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([ci, saveas, figsize])	Main function to plot an object of the Class.
`plot_confell`([figsize, ci, equal, ...])	Plots the estimated parameter values in the parameter space and the asymptotic confidence ellipse.
`plot_ordinal`([figsize, kind, ax, saveas])	Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(ci=0.95, saveas=None, figsize=(7, 15))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
ci (float) – level \((1-\alpha/2)\) for the confidence ellipse
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_confell(figsize=(7, 5), ci=0.95, equal=True, magnified=False, ax=None, saveas=None)#

Plots the estimated parameter values in the parameter space and the asymptotic confidence ellipse.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
ci (float) – level \((1-\alpha/2)\) for the confidence ellipse
equal (bool) – if the plot must have equal aspect
magnified (bool) – if False the limits will be the entire parameter space, otherwise let matplotlib choose the limits
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), kind='bar', ax=None, saveas=None)#

Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cub.cmf(m, pi, xi)#

Cumulative probability of a specified CUB model.

\(\Pr(R \leq r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)

Returns:

an array of the CMF for the specified model

Return type:

numpy array

cubmods.cub.draw(m, pi, xi, n, df, formula, seed=None)#

Draw a random sample from a specified CUB model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
n (int) – number of ordinal responses to be drawn
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cub.gini(m, pi, xi)#

The Gini index of a specified CUB model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)

Returns:

the Gini index of the model

Return type:

float

cubmods.cub.init_theta(f, m)#

Preliminary estimators for CUB models without covariates.

Computes preliminary parameter estimates of a CUB model without covariates for given ordinal responses. These preliminary estimators are used within the package code to start the E-M algorithm.

Parameters:

f (array of int) – array of the absolute frequencies of given ordinal responses
m (int) – number of ordinal categories

Returns:

a tuple of \((\pi^{(0)}, \xi^{(0)})\)

cubmods.cub.laakso(m, pi, xi)#

The Laakso index of a specified CUB model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)

Returns:

the Laakso index of the model

Return type:

float

cubmods.cub.loglik(m, pi, xi, f)#

Compute the log-likelihood function of a CUB model without covariates for a given absolute frequency distribution.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
f (array of int) – array of absolute frequency distribution

Returns:

the log-likelihood value

Return type:

float

cubmods.cub.mean(m, pi, xi)#

Expected value of a specified CUB model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)

Returns:

the expected value of the model

Return type:

float

cubmods.cub.median(m, pi, xi)#

The median of a specified CUB model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)

Returns:

the median of the model

Return type:

float

cubmods.cub.mle(sample, m, df, formula, ass_pars=None, maxiter=500, tol=0.0001)#

Main function for CUB models without covariates.

Function to estimate and validate a CUB model without covariates for given ordinal responses.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (int) – maximum number of iterations allowed for running the optimization algorithm
tol (float) – fixed error tolerance for final estimates

Returns:

an instance of CUBresCUB00 (see the Class for details)

Return type:

object

cubmods.cub.pmf(m, pi, xi)#

Probability distribution of a specified CUB model.

\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)

Returns:

the vector of the probability distribution of a CUB model.

Return type:

numpy array

cubmods.cub.prob(m, pi, xi, r)#

Probability \(\Pr(R = r | \pmb\theta)\) of a specified CUB model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
r (int) – ordinal value (must be \(1 \leq r \leq m\))

Returns:

the probability \(\Pr(R = r | \pmb\theta)\)

Return type:

float

cubmods.cub.skew(pi, xi)#

Skewness normalized \(\eta\) index

Parameters:

pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)

Returns:

the skewness of the model

Return type:

float

cubmods.cub.std(m, pi, xi)#

Standard deviation of a specified CUB model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)

Returns:

the standard deviation of the model

Return type:

float

cubmods.cub.var(m, pi, xi)#

Variance of a specified CUB model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)

Returns:

the variance of the model

Return type:

float

cubmods.cub.varcov(m, pi, xi, ordinal)#

Compute the variance-covariance matrix of parameter estimates of a CUB model without covariates.

References:

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
ordinal (array of int) – array of ordinal responses

Returns:

the variance-covariance matrix of the CUB model

Return type:

numpy ndarray

cubmods.cub_0w module#

CUB models in Python. Module for CUB (Combination of Uniform and Binomial) with covariates for the feeling component.

Description:#

This module contains methods and classes for CUB_0W model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cub_0w.CUBresCUB0W(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(saveas=None, figsize=(7, 5))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cub_0w.draw(m, pi, gamma, W, df, formula, seed=None)#

Draw a random sample from a specified CUB model with covariates for the feeling component.

Parameters:

m (int) – number of ordinal categories
n (int) – number of ordinal responses to be drawn
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None; it must be \(\neq 0\)

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cub_0w.effe01(gamma, esterno01, m)#

Auxiliary function for the log-likelihood estimation of CUB models with covariates for the feeling component.

Compute the opposite of the scalar function that is maximized when running the E-M algorithm for CUB models with covariates for the feeling parameter.

It is called as an argument for minimize within CUB function for models with covariates for feeling or for both feeling and uncertainty.

Parameters:

gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
esterno01 – a matrix binding together: the vector \(\pmb\tau\) of the posterior probabilities that each observation has been generated by the first component distribution of the mixture, the ordinal data \(\pmb r\) and the matrix \(\pmb w\) of the selected covariates accounting for an intercept term
m (int) – number of ordinal categories

Returns:

the expected value of the inconplete log-likelihood

Return type:

float

cubmods.cub_0w.init_gamma(sample, m, W)#

Preliminary parameter estimates of a CUB model with covariates for the feeling component.

Compute preliminary parameter estimates for the feeling component of a CUB model fitted to ordinal responses. These estimates are set as initial values for parameters to start the E-M algorithm.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

an array \(\pmb\gamma^{(0)}\)

Return type:

array of float

cubmods.cub_0w.loglik(sample, m, pi, gamma, W)#

Log-likelihood function of a CUB model with covariates for the feeling component

Compute the log-likelihood function of a CUB model fitting ordinal data, with covariates for explaining the feeling component.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the log-likelihood value

Return type:

float

cubmods.cub_0w.mle(sample, m, W, df, formula, ass_pars=None, maxiter=500, tol=0.0001)#

Main function for CUB models with covariates for the feeling component.

Function to estimate and validate a CUB model for given ordinal responses, with covariates for explaining the feeling component.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (int) – maximum number of iterations allowed for running the optimization algorithm
tol (float) – fixed error tolerance for final estimates

Returns:

an instance of CUBresCUB0W (see the Class for details)

Return type:

object

cubmods.cub_0w.pmf(m, pi, gamma, W)#

Average probability distribution of a specified CUB model with covariates for the feeling component.

\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the vector of the probability distribution.

Return type:

numpy array

cubmods.cub_0w.pmfi(m, pi, gamma, W)#

Probability distribution for each subject of a specified CUB model with covariates for the feeling component.

Auxiliary function of .draw().

\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the matrix of the probability distribution of dimension \(n \times r\)

Return type:

numpy ndarray

cubmods.cub_0w.prob(sample, m, pi, gamma, W)#

Probability distribution of a CUB model with covariates for the feeling component given an observed sample

Compute the probability distribution of a CUB model with covariates for the feeling component, given an observed sample.

\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the array of the probability distribution.

Return type:

numpy array

cubmods.cub_0w.varcov(sample, m, pi, gamma, W)#

Variance-covariance matrix of CUB models with covariates for the feeling component

Compute the variance-covariance matrix of parameter estimates of a CUB model with covariates for the feeling component.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the variance-covariance matrix of the CUB model

Return type:

numpy ndarray

cubmods.cub_y0 module#

CUB models in Python. Module for CUB (Combination of Uniform and Binomial) with covariates for the uncertainty component.

Description:#

This module contains methods and classes for CUB_Y0 model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cub_y0.CUBresCUBY0(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(saveas=None, figsize=(7, 5))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cub_y0.draw(m, beta, xi, Y, df, formula, seed=None)#

Draw a random sample from a specified CUB model with covariates for the uncertainty component.

Parameters:

m (int) – number of ordinal categories
n (int) – number of ordinal responses to be drawn
xi (float) – uncertainty parameter \(\xi\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None; it must be \(\neq 0\)

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cub_y0.effe10(beta, esterno10)#

Auxiliary function for the log-likelihood estimation of CUB models.

Compute the opposite of the scalar function that is maximized when running the E-M algorithm for CUB models with covariates for the uncertainty parameter.

It is called as an argument for optim within CUB function for models with covariates for: uncertainty or for both feeling and uncertainty.

Parameters:

beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
esterno10 – A matrix binding together: the matrix \(\pmb y\) of the selected covariates (accounting for an intercept term) and a vector \(\tau\) (whose length equals the number of observations) of the posterior probabilities that each observation has been generated by the first component distribution of the mixture

Returns:

the expected value of the inconplete log-likelihood

Return type:

float

cubmods.cub_y0.loglik(m, sample, Y, beta, xi)#

Log-likelihood function of a CUB model with covariates for the uncertainty component

Compute the log-likelihood function of a CUB model fitting ordinal responses with covariates for explaining the uncertainty component.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
xi (float) – uncertainty parameter \(\xi\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component

Returns:

the log-likelihood value

Return type:

float

cubmods.cub_y0.mle(sample, m, Y, df, formula, ass_pars=None, maxiter=500, tol=0.0001)#

Main function for CUB models with covariates for the uncertainty component.

Estimate and validate a CUB model for given ordinal responses, with covariates for explaining the uncertainty component.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (int) – maximum number of iterations allowed for running the optimization algorithm
tol (float) – fixed error tolerance for final estimates

Returns:

an instance of CUBresCUBY0 (see the Class for details)

Return type:

object

cubmods.cub_y0.pmf(m, beta, xi, Y)#

Average probability distribution of a specified CUB model with covariates.

\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
xi (float) – feeling parameter \(\xi\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component

Returns:

the vector of the probability distribution.

Return type:

numpy array

cubmods.cub_y0.pmfi(m, beta, xi, Y)#

Probability distribution for each subject of a specified CUB model with covariates.

Auxiliary function of .draw().

\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
xi (float) – feeling parameter \(\xi\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component

Returns:

the matrix of the probability distribution of dimension \(n \times r\)

Return type:

numpy ndarray

cubmods.cub_y0.prob(m, sample, Y, beta, xi)#

Probability distribution of a CUB model with covariates for the uncertainty component given an observed sample

Compute the probability distribution of a CUB model with covariates for the feeling component, given an observed sample.

\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
xi (float) – uncertainty parameter \(\xi\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component

Returns:

the array of the probability distribution.

Return type:

numpy array

cubmods.cub_y0.varcov(m, sample, Y, beta, xi)#

Variance-covariance matrix of CUB model with covariates for the uncertainty parameter.

Compute the variance-covariance matrix of parameter estimates of a CUB model with covariates for the uncertainty component.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
xi (float) – uncertainty parameter \(\xi\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component

Returns:

the variance-covariance matrix of the CUB model

Return type:

numpy ndarray

cubmods.cub_yw module#

CUB models in Python. Module for CUB (Combination of Uniform and Binomial) with covariates for both feeling and uncertainty.

Description:#

This module contains methods and classes for CUB_YW model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cub_yw.CUBresCUBYW(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

“Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(saveas=None, figsize=(7, 5))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cub_yw.draw(m, beta, gamma, Y, W, df, formula, seed=None)#

Draw a random sample from a specified CUB model with covariates for both feeling and uncertainty.

Parameters:

n (int) – number of ordinal responses to be drawn
m (int) – number of ordinal categories
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
df (DataFrame) – original DataFrame
formula (str) – the formula used

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cub_yw.loglik(m, sample, Y, W, beta, gamma)#

Log-likelihood function of a CUB model with covariates for both feeling and uncertainty.

Compute the log-likelihood function of a CUB model fitting ordinal data with covariates for explaining both the feeling and the uncertainty components.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the log-likelihood value

Return type:

float

cubmods.cub_yw.mle(sample, m, Y, W, df, formula, ass_pars=None, maxiter=500, tol=0.0001)#

Main function for CUB models with covariates for both the uncertainty and the feeling components.

Estimate and validate a CUB model for given ordinal responses, with covariates for explaining both the feeling and the uncertainty components by means of logistic transform.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (int) – maximum number of iterations allowed for running the optimization algorithm
tol (float) – fixed error tolerance for final estimates

Returns:

an instance of CUBresCUBYW (see the Class for details)

Return type:

object

cubmods.cub_yw.pmf(m, beta, gamma, Y, W)#

Average probability distribution of a specified CUB model with covariates for both feeling and uncertainty.

\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the vector of the probability distribution.

Return type:

numpy array

cubmods.cub_yw.pmfi(m, beta, gamma, Y, W)#

Probability distribution for each subject of a specified CUB model with covariates for both feeling and uncertainty.

Auxiliary function of .draw().

\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the matrix of the probability distribution of dimension \(n \times r\)

Return type:

numpy ndarray

cubmods.cub_yw.prob(m, sample, Y, W, beta, gamma)#

Probability distribution of a CUB model with covariates for both feeling and uncertainty.

Compute the probability distribution of a CUB model with covariates for both the feeling and the uncertainty components.

\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the array of the probability distribution.

Return type:

numpy array

cubmods.cub_yw.varcov(m, sample, Y, W, beta, gamma)#

Variance-covariance matrix of a CUB model with covariates for both uncertainty and feeling.

Compute the variance-covariance matrix of parameter estimates of a CUB model with covariates for both the uncertainty and the feeling components.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the variance-covariance matrix of the CUB model

Return type:

numpy ndarray

cubmods.cube module#

CUB models in Python. Module for CUBE (Combination of Uniform and Beta-Binomial).

Description:#

This module contains methods and classes for CUBE model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

TODO: adjust 3d plots legend

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cube.CUBresCUBE(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([ci, saveas, confell, test3, figsize])	Main function to plot an object of the Class.
`plot3d`(ax[, ci, magnified])	Plots the estimated parameter values in the parameter space and the asymptotic confidence ellipsoid with its projections.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(ci=0.95, saveas=None, confell=False, test3=True, figsize=(7, 15))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
ci (float) – level \((1-\alpha/2)\) for the confidence ellipsoid
confell (bool) – DEPRECATED, defaults to False
test3 (bool) – DEPRECATED, defaults to True
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot3d(ax, ci=0.95, magnified=False)#

Plots the estimated parameter values in the parameter space and the asymptotic confidence ellipsoid with its projections.

Parameters:

ci (float) – level \((1-\alpha/2)\) for the confidence ellipsoid
magnified (bool) – if False the limits will be the entire parameter space, otherwise let matplotlib choose the limits
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cube.betar(m, xi, phi)#

Beta-Binomial distribution.

Return the Beta-Binomial distribution with given parameters.

Parameters:

m (int) – number of ordinal categories
xi (float) – feeling parameter \(\xi\)
phi (float) – overdispersion parameter \(\phi\)

Returns:

array of length \(m\) of the Beta-Binomial distribution.

Return type:

numpy array

cubmods.cube.cmf(m, pi, xi, phi)#

Cumulative probability of a specified CUBE model.

\(\Pr(R \leq r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
phi (float) – overdispersion parameter \(\phi\)

Returns:

array of length \(m\) of the cumulative probability of a CUBE model without covariates.

Return type:

numpy array

cubmods.cube.draw(m, pi, xi, phi, n, df, formula, seed=None)#

Draw a random sample from a specified CUBE model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
phi (float) – overdispersion parameter \(\phi\)
n (int) – number of ordinal responses to be drawn
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cube.effecube(params, tau, f, m)#

Auxiliary function for the log-likelihood estimation of CUBE models without covariates.

Define the opposite of the scalar function that is maximized when running the E-M algorithm for CUBE models without covariates.

Parameters:

params (array of float) – array of initial estimates for the feeling and the overdispersion parameters
tau (array) – a column vector of length \(m\) containing the posterior probabilities that each observed category has been generated by the first component distribution of the mixture
f (array) – array of the absolute frequencies of the observations
m (int) – number of ordinal categories

Returns:

the expected value of the inconplete log-likelihood

Return type:

float

cubmods.cube.init_theta(sample, m)#

Naive estimates for CUBE models without covariates.

Compute naive parameter estimates of a CUBE model without covariates for given ordinal responses. These preliminary estimators are used within the package code to start the E-M algorithm.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories

Returns:

a tuple of \((\pi^{(0)}, \xi^{(0)}, \phi^{(0)})\)

Return type:

tuple of float

cubmods.cube.loglik(m, pi, xi, phi, f)#

Log-likelihood function of a CUBE model without covariates.

Compute the log-likelihood function of a CUBE model without covariates fitting the given absolute frequency distribution.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
phi (float) – overdispersion parameter \(\phi\)
f (array of int) – array of absolute frequency distribution

Returns:

the log-likelihood value

Return type:

float

cubmods.cube.mean(m, pi, xi)#

Mean of a CUBE model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)

Returns:

the expected value of the model

Return type:

float

cubmods.cube.mle(sample, m, df, formula, ass_pars=None, maxiter=1000, tol=1e-06)#

Main function for CUBE models without covariates.

Estimate and validate a CUBE model without covariates.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (int) – maximum number of iterations allowed for running the optimization algorithm
tol (float) – fixed error tolerance for final estimates

Returns:

an instance of CUBresCUBE (see the Class for details)

Return type:

object

cubmods.cube.pmf(m, pi, xi, phi)#

Probability distribution of a specified CUBE model.

\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
phi (float) – overdispersion parameter \(\phi\)

Returns:

array of length \(m\) of the distribution of a CUBE model without covariates.

Return type:

numpy array

cubmods.cube.prob(m, pi, xi, phi, r)#

Probability \(\Pr(R = r | \pmb\theta)\) of a CUBE model without covariates.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
phi (float) – overdispersion parameter \(\phi\)
r (int) – ordinal response

Returns:

the probability \(\Pr(R = r | \pmb\theta)\) of a CUBE model without covariates.

Return type:

numpy array

cubmods.cube.var(m, pi, xi, phi)#

Variance of a CUBE model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
phi (float) – overdispersion parameter \(\phi\)

Returns:

the variance of the model

Return type:

float

cubmods.cube.varcov(m, pi, xi, phi, sample)#

Variance-covariance matrix for CUBE models based on the observed information matrix.

Compute the variance-covariance matrix of parameter estimates for a CUBE model without covariates as the inverse of the observed information matrix.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
xi (float) – feeling parameter \(\xi\)
phi (float) – overdispersion parameter \(\phi\)
sample (array of int) – array of ordinal responses

Returns:

the variance-covariance matrix of the CUBE model

Return type:

numpy ndarray

cubmods.cube_0w0 module#

CUB models in Python. Module for CUBE (Combination of Uniform and Beta-Binomial) with covariates for the feeling component.

Description:#

This module contains methods and classes for CUBE_0W0 model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cube_0w0.CUBresCUBE0W0(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(saveas=None, figsize=(7, 5))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cube_0w0.betabinomialxi(m, sample, xivett, phi)#

Beta-Binomial probabilities of ordinal responses, given feeling parameter for each observation.

Compute the Beta-Binomial probabilities of given ordinal responses, with feeling parameter specified for each observation, and with the same overdispersion parameter for all the responses.

Parameters:

m (int) – number of ordinal categories
sample (array) – array of ordinal responses. Missing values are not allowed: they should be preliminarily deleted
xivett (array) – array of feeling parameters of the Beta-Binomial distribution for given ordinal responses
phi (float) – overdispersion parameter \(\phi\)

Returns:

array of the same length as ordinal: each entry is the Beta-Binomial probability for the given observation for the corresponding feeling and overdispersion parameters.

Return type:

array

cubmods.cube_0w0.draw(m, pi, gamma, phi, W, df, formula, seed=None)#

Draw a random sample from a specified CUBE model.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
phi (float) – overdispersion parameter \(\phi\)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
n (int) – number of ordinal responses to be drawn
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cube_0w0.effe(pars, sample, W, m)#

Auxiliary function for the log-likelihood estimation of CUBE models with covariates only for the feeling component.

Compute the opposite of the scalar function that is maximized when running the E-M algorithm for CUBE models with covariates only for the feeling component.

Parameters:

pars (array) – array of length equal to W.index.size+3 whose entries are the initial parameters estimates
sample (array of int) – array of ordinal responses
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
m (int) – number of ordinal categories

Returns:

negative log-likelihood

Return type:

float

cubmods.cube_0w0.init_theta(m, sample, W, maxiter, tol)#

Preliminary estimates of parameters for CUBE models with covariates only for feeling.

Compute preliminary parameter estimates of a CUBE model with covariates only for feeling, given ordinal responses. These estimates are set as initial values to start the corresponding E-M algorithm within the package. Preliminary estimates for the uncertainty and the overdispersion parameters are computed by short runs of EM. As to the feeling component, it considers the nested CUB model with covariates and calls code{link{inibestgama}} to derive initial estimates for the coefficients of the selected covariates for feeling.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
maxiter (int) – maximum number of iterations allowed for preliminary iterations
tol (float) – fixed error tolerance for final estimates for preliminary iterations

Returns:

a tuple of \((\pi^{(0)}, \pmb \gamma^{(0)}, \phi^{(0)})\), where \(\pi^{(0)}\) is the initial estimate for the uncertainty parameter, \(\pmb \gamma^{(0)}\) is the vector of initial estimates for the feeling component (including an intercept term in the first entry), and \(\phi^{(0)}\) is the initial estimate for the overdispersion parameter.

“rtype”: tuple

cubmods.cube_0w0.loglik(m, sample, W, pi, gamma, phi)#

Log-likelihood function of CUBE model with covariates only for feeling.

Compute the log-likelihood function of a CUBE model for ordinal data with subjects’ covariates only for feeling.

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
phi (float) – overdispersion parameter \(\phi\)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
sample (array of int) – array of ordinal responses

Returns:

the log-likelihood value

Return type:

float

cubmods.cube_0w0.mle(sample, m, W, df, formula, ass_pars=None, maxiter=1000, tol=1e-06)#

Main function for CUBE models with covariates only for feeling

Estimate and validate a CUBE model for ordinal data, with covariates only for explaining the feeling component.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (int) – maximum number of iterations allowed for preliminary iterations
tol (float) – fixed error tolerance for final estimates for preliminary iterations; the informatio matrix (to compute the variance-covariance matrix) is approximated with approx_hess() (see statsmodels.tools.numdiff for details)

Returns:

an instance of CUBresCUBE0W0 (see the Class for details)

Return type:

object

cubmods.cube_0w0.pmf(m, pi, gamma, phi, W)#

Average probability distribution of a specified CUB model with covariates for the feeling component.

\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
phi (float) – overdispersion parameter \(\phi\)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the array of the average probability distribution

Return type:

numpy array

cubmods.cube_0w0.pmfi(m, pi, gamma, phi, W)#

Probability distribution for each subject of a specified CUBE model with covariates for feeling only.

Auxiliary function of .draw().

\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
phi (float) – overdispersion parameter \(\phi\)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

the matrix of the probability distribution of dimension \(n \times r\)

Return type:

numpy ndarray

cubmods.cube_0w0.prob(m, sample, W, pi, gamma, phi)#

Probability distribution of a CUBE model with covariates for feeling.

Compute the probability distribution of a CUB model with covariates for both the feeling and the uncertainty components. Auxiliary function of .loglik()

\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
phi (float) – overdispersion parameter \(\phi\)
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
sample (array of int) – array of ordinal responses

Returns:

the array of the probability distribution.

Return type:

numpy array

cubmods.cube_ywz module#

CUB models in Python. Module for CUBE (Combination of Uniform and Beta-Binomial) with covariates.

Description:#

This module contains methods and classes for CUB_YWZ model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cube_ywz.CUBresCUBEYWZ(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(saveas=None, figsize=(7, 5))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cube_ywz.Qdue(pars, tauno, sample, W, Z, m)#

Auxiliary function for the log-likelihood estimation of CUBE models with covariates.

Define the opposite of one of the two scalar functions that are maximized when running the E-M algorithm for CUBE models with covariates for feeling, uncertainty and overdispersion.

Parameters:

pars (array) – array of initial estimates of parameters for the feeling component and the overdispersion effect
tauno (array) – the column vector of the posterior probabilities that each observed rating has been generated by the distribution of the first component of the mixture
sample (array of int) – array of ordinal responses
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
Z (pandas dataframe) – dataframe of covariates for explaining the overdispersion
m (int) – number of ordinal categories

cubmods.cube_ywz.Quno(beta, esterno1)#

Auxiliary function for the log-likelihood estimation of CUBE models with covariates.

Define the opposite one of the two scalar functions that are maximized when running the E-M algorithm for CUBE models with covariates for feeling, uncertainty and overdispersion.

It is iteratively called as an argument of “optim” within CUBE function (with covariates) as the function to minimize to compute the maximum likelihood estimates for the feeling and the overdispersion components.

Parameters:

beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
esterno1 (ndarray) – matrix binding together the column vector of the posterior probabilities that each observed rating has been generated by the first component distribution of the mixture, with the matrix \(\pmb y\) of explicative variables for the uncertainty component, expanded with a unitary vector in the first column to consider also an intercept term

cubmods.cube_ywz.auxmat(m, xi, phi, a, b, c, d, e)#

Auxiliary matrix.

Returns an auxiliary matrix needed for computing the variance-covariance matrix of a CUBE model with covariates.

Parameters:

m (int) – number of ordinal categories
xi (array of float) – feeling parameters \(\pmb\xi\)
phi (array of float) – overdispersion parameter \(\pmb\phi\)
a,b,c,d,e (float) – see the reference paper Piccolo, 2015 for details

cubmods.cube_ywz.betabinomial(m, sample, xi, phi)#

Beta-Binomial probabilities of ordinal responses, with feeling and overdispersion parameters for each observation.

Compute the Beta-Binomial probabilities of ordinal responses, given feeling and overdispersion parameters for each observation.

The Beta-Binomial distribution is the Binomial distribution in which the probability of success at each trial is random and follows the Beta distribution. It is frequently used in Bayesian statistics, empirical Bayes methods and classical statistics as an overdispersed binomial distribution.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
xi (float) – feeling parameter \(\xi\)
phi (float) – overdispersion parameter \(\phi\)

Returns:

array of the same length as sample, containing the Beta-Binomial probabilities of each observation, for the corresponding feeling and overdispersion parameters.

Return type:

array

cubmods.cube_ywz.draw(m, beta, gamma, alpha, df, formula, Y, W, Z, seed=None)#

Draw a random sample from a specified CUBE model.

Parameters:

m (int) – number of ordinal categories
n (int) – number of ordinal responses to be drawn
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
alpha (array of float) – array \(\pmb \alpha\) of parameters for the overdispersion, whose length equals Z.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
Z (pandas dataframe) – dataframe of covariates for explaining the overdispersion
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cube_ywz.init_theta(m, sample, W, p, v)#

Preliminary parameter estimates for CUBE models with covariates.

Compute preliminary parameter estimates for a CUBE model with covariates for all the three parameters. These estimates are set as initial values to start the E-M algorithm within maximum likelihood estimation.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
p (int) – number of covariates for the uncertainty component
v (int) – number of covariates for the overdispersion

Returns:

a tuple of \((\pmb \beta^{(0)}, \pmb \gamma^{(0)}, \pmb \alpha^{(0)})\) of preliminary estimates of parameter vectors for \(\pi = \pi(\pmb{\beta})\), ; xi=xi(pmb{gamma}),; phi=phi(pmb{alpha})` respectively, of a CUBE model with covariates for all the three parameters. In details, they have length equal to Y.columns.size+1, W.columns.size+1 and Z.columns.size+1, respectively, to account for an intercept term for each component.

Return type:

tuple of arrays

cubmods.cube_ywz.loglik(m, sample, Y, W, Z, beta, gamma, alpha)#

Log-likelihood function of a CUBE model with covariates.

Compute the log-likelihood function of a CUBE model for ordinal responses, with covariates for explaining all the three parameters.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
Z (pandas dataframe) – dataframe of covariates for explaining the overdispersion
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
alpha (array of float) – array \(\pmb \alpha\) of parameters for the overdispersion, whose length equals Z.columns.size+1 to include an intercept term in the model (first entry)

Returns:

the log-likelihood value

Return type:

float

cubmods.cube_ywz.mle(m, sample, Y, W, Z, df, formula, ass_pars=None, maxiter=1000, tol=0.01)#

Main function for CUBE models with covariates.

Function to estimate and validate a CUBE model with explicative covariates for all the three parameters.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
Z (pandas dataframe) – dataframe of covariates for explaining the overdispersion
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (int) – maximum number of iterations allowed for running the optimization algorithm
tol (float) – fixed error tolerance for final estimates

Returns:

an instance of CUBresCUBEYWZ (see the Class for details)

Return type:

object

cubmods.cube_ywz.pmf(m, beta, gamma, alpha, Y, W, Z)#

Average probability distribution of a specified CUB model with covariates for the feeling component.

\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
alpha (array of float) – array \(\pmb \alpha\) of parameters for the overdispersion, whose length equals Z.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
Z (pandas dataframe) – dataframe of covariates for explaining the overdispersion

Returns:

the array of the average probability distribution

Return type:

numpy array

cubmods.cube_ywz.pmfi(m, beta, gamma, alpha, Y, W, Z)#

Probability distribution for each subject of a specified CUBE model with covariates.

Auxiliary function of .draw().

\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
alpha (array of float) – array \(\pmb \alpha\) of parameters for the overdispersion, whose length equals Z.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
Z (pandas dataframe) – dataframe of covariates for explaining the overdispersion

Returns:

the matrix of the probability distribution of dimension \(n \times r\)

Return type:

numpy ndarray

cubmods.cube_ywz.varcov(m, sample, beta, gamma, alpha, Y, W, Z)#

Variance-covariance matrix of a CUBE model with covariates.

Compute the variance-covariance matrix of parameter estimates of a CUBE model with covariates for all the three parameters.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
Z (pandas dataframe) – dataframe of covariates for explaining the overdispersion
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
alpha (array of float) – array \(\pmb \alpha\) of parameters for the overdispersion, whose length equals Z.columns.size+1 to include an intercept term in the model (first entry)

Returns:

the variance-covariance matrix

Return type:

ndarray

cubmods.cubsh module#

CUB models in Python. Module for CUBSH (Combination of Uniform and Binomial with Shelter Effect).

Description:#

This module contains methods and classes for CUBSH model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

TODO: fix 3d plots legend

TODO: test all def _*(): (optional functions)

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cubsh.CUBresCUBSH(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([ci, saveas, confell, debug, test3, ...])	Main function to plot an object of the Class.
`plot3d`(ax[, ci, magnified])	Plots the estimated parameter values in the parameter space and the asymptotic confidence ellipsoid with its projections.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(ci=0.95, saveas=None, confell=False, debug=False, test3=True, figsize=(7, 15))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
ci (float) – level \((1-\alpha/2)\) for the confidence ellipsoid
confell (bool) – DEPRECATED, defaults to False
test3 (bool) – DEPRECATED, defaults to True
debug (bool) – DEPRECATED, defaults to False
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot3d(ax, ci=0.95, magnified=False)#

Plots the estimated parameter values in the parameter space and the asymptotic confidence ellipsoid with its projections.

Parameters:

ci (float) – level \((1-\alpha/2)\) for the confidence ellipsoid
magnified (bool) – if False the limits will be the entire parameter space, otherwise let matplotlib choose the limits
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cubsh.cmf(m, sh, pi1, pi2, xi)#

Cumulative probability of a specified CUBSH model, using alternative parametrization \((\pi_1, \pi_2)\).

\(\Pr(R \leq r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi1 (float) – Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)
pi2 (float) – Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)
xi (float) – feeling parameter \(\xi\)

Returns:

the cumulative probability distribution

Return type:

array

cubmods.cubsh.cmf_delta(m, sh, pi, xi, delta)#

Cumulative probability of a specified CUBSH model, using canonic parametrization \((\pi, \delta)\).

\(\Pr(R \leq r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi (float) – uncertainty parameter \(\pi\)
delta (float) – shelter choice parameter \(\delta\)
xi (float) – feeling parameter \(\xi\)

Returns:

the cumulative probability distribution

Return type:

array

cubmods.cubsh.draw(m, sh, pi, xi, delta, n, df, formula, seed=None)#

Draw a random sample from a specified CUBSH model, using canonic parametrization \((\pi, \delta)\).

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi (float) – uncertainty parameter \(\pi\)
delta (float) – shelter choice parameter \(\delta\)
xi (float) – feeling parameter \(\xi\)
n (int) – number of ordinal responses
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cubsh.draw2(m, sh, pi1, pi2, xi, n, df, formula, seed=None)#

Draw a random sample from a specified CUBSH model, using alternative parametrization \((\pi_1, \pi_2)\).

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi1 (float) – Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)
pi2 (float) – Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)
xi (float) – feeling parameter \(\xi\)
n (int) – number of ordinal responses
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cubsh.init_theta(f, m, sh)#

Preliminary estimators for CUBSH models.

Computes preliminary parameter estimates of a CUBSH model without covariates for given ordinal responses. These preliminary estimators are used within the package code to start the E-M algorithm.

Parameters:

f (array of int) – array of the absolute frequencies of given ordinal responses
m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)

Returns:

a tuple of \((\pi_1^{(0)}, \pi_2^{(0)}, \xi^{(0)})\)

cubmods.cubsh.loglik(m, sh, pi1, pi2, xi, f)#

Log-likelihood of a CUB model with shelter effect

Compute the log-likelihood of a CUB model with a shelter effect for the given absolute frequency distribution.

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi1 (float) – Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)
pi2 (float) – Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)
xi (float) – feeling parameter \(\xi\)
f (array) – Vector of the absolute frequency distribution

Returns:

the log-likehood value

Return type:

float

cubmods.cubsh.mean_delta(m, sh, pi, xi, delta)#

Expected value of a specified CUBSH model, using canonic parametrization \((\pi, \delta)\).

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi (float) – uncertainty parameter \(\pi\)
delta (float) – shelter choice parameter \(\delta\)
xi (float) – feeling parameter \(\xi\)

Returns:

the expected value of the model

Return type:

float

cubmods.cubsh.mle(sample, m, sh, df, formula, maxiter=500, tol=0.0001, ass_pars=None)#

Main function for CUB models with a shelter effect

Estimate and validate a CUB model with a shelter effect.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (int) – maximum number of iterations allowed for running the optimization algorithm
tol (float) – fixed error tolerance for final estimates

Returns:

an instance of CUBresCUBSH (see the Class for details)

Return type:

object

Raise:

Exception if \(m \leq 4\)

cubmods.cubsh.pi1pi2_to_pidelta(pi1, pi2)#

Compute \((\pi, \delta)\) from \((\pi_1, \pi_2)\)

\(\pi = \dfrac{\pi_1}{\pi_1 + \pi_2}\)

\(\delta = 1 - \pi_1 - \pi_2\)

Parameters:

pi1 (float) – Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)
pi2 (float) – Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)

Returns:

a tuple of \((\pi, \delta)\) the parameters of uncertainty and shelter choice, respectively

Return type:

tuple

cubmods.cubsh.pidelta_to_pi1pi2(pi, delta)#

Compute \((\pi_1, \pi_2)\) from \((\pi, \delta)\)

\(\pi_1 = (1 - \delta) \pi\)

\(\pi_2 = (1 - \delta)(1 - \pi)\)

Parameters:

pi (float) – uncertainty parameter \(\pi\)
delta (float) – shelter choice parameter \(\delta\)

Returns:

a tuple of \((\pi_1, \pi_2)\) the mixing coefficient of the shifted Binomial and the Uniform components, respectively

Return type:

tuple

cubmods.cubsh.plot_simplex(pi1pi2list, ax=None, fname=None)#

Plot simplex of parameters of a CUBSH model.

Note

see the reference Iannario, 2012 for details

Warning

this function still needs several fixes

Parameters:

pi1pi2list (list) – list of [pi1, pi2] parameters
ax – matplotlib axis
fname – if provided, save the plot to fname, defaults to None
fname – str

cubmods.cubsh.pmf(m, sh, pi1, pi2, xi)#

Probability distribution of a specified CUBSH model, using alternative parametrization \((\pi_1, \pi_2)\).

\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi1 (float) – Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)
pi2 (float) – Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)
xi (float) – feeling parameter \(\xi\)

Returns:

the probability distribution

Return type:

array

cubmods.cubsh.pmf_delta(m, sh, pi, xi, delta)#

Probability distribution of a specified CUBSH model, using canonic parametrization \((\pi, \delta)\).

\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi (float) – uncertainty parameter \(\pi\)
delta (float) – shelter choice parameter \(\delta\)
xi (float) – feeling parameter \(\xi\)

Returns:

the probability distribution

Return type:

array

cubmods.cubsh.prob(m, sh, pi1, pi2, xi, r)#

Probability \(\Pr(R = r | \pmb\theta)\) of a CUBSH model without covariates, using alternative parametrization \((\pi_1, \pi_2)\).

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi1 (float) – Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)
pi2 (float) – Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)
xi (float) – feeling parameter \(\xi\)
r (int) – ordinal response

Returns:

the probability \(\Pr(R = r | \pmb\theta)\)

Return type:

float

cubmods.cubsh.proba_delta(m, sh, pi, xi, delta, r)#

Probability \(\Pr(R = r | \pmb\theta)\) of a CUBSH model without covariates, using canonic parametrization \((\pi, \delta)\).

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi (float) – uncertainty parameter \(\pi\)
delta (float) – shelter choice parameter \(\delta\)
xi (float) – feeling parameter \(\xi\)
r (int) – ordinal response

Returns:

the probability \(\Pr(R = r | \pmb\theta)\)

Return type:

float

cubmods.cubsh.std_delta(m, pi, xi, delta)#

Standard deviation of a specified CUB model, using canonic parametrization \((\pi, \delta)\).

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
delta (float) – shelter choice parameter \(\delta\)
xi (float) – feeling parameter \(\xi\)

Returns:

the standard deviation of the model

Return type:

float

cubmods.cubsh.var_delta(m, pi, xi, delta)#

Variance of a specified CUBSH model, using canonic parametrization \((\pi, \delta)\).

Parameters:

m (int) – number of ordinal categories
pi (float) – uncertainty parameter \(\pi\)
delta (float) – shelter choice parameter \(\delta\)
xi (float) – feeling parameter \(\xi\)

Returns:

the variance of the model

Return type:

float

cubmods.cubsh.varcov(m, sh, pi1, pi2, xi, n)#

Variance-covariance matrix for CUB models with shelter effect, using alternative parametrization \((\pi_1, \pi_2)\).

Compute the variance-covariance matrix of parameter estimates of a CUB model with shelter effect.

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi1 (float) – Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)
pi2 (float) – Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)
xi (float) – feeling parameter \(\xi\)
n (int) – number of ordinal responses

Returns:

the variance-covariance matrix

Return type:

numpy ndarray

cubmods.cubsh.varcov_pxd(m, sh, pi, xi, de, n)#

Variance-covariance matrix for CUB models with shelter effect, using canonic parametrization \((\pi, \delta)\).

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
pi (float) – uncertainty parameter \(\pi\)
de (float) – shelter choice parameter \(\delta\)
xi (float) – feeling parameter \(\xi\)
n (int) – number of ordinal responses

Returns:

the variance-covariance matrix

Return type:

numpy ndarray

cubmods.cubsh_ywx module#

CUB models in Python. Module for CUBSH (Combination of Uniform and Binomial with Shelter Effect) with covariates.

Description:#

This module contains methods and classes for CUBSH_YWX model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cubsh_ywx.CUBresCUBSHYWX(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(saveas=None, figsize=(7, 5))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cubsh_ywx.Q1(param, dati1, p)#

Auxiliary function for the log-likelihood estimation of GeCUB models.

Define the opposite one of the two scalar functions that are maximized when running the E-M algorithm for GeCUB models with covariates for feeling, uncertainty and shelter effect.

Parameters:

param (array) – array of initial estimates of parameters for the uncertainty component
dati1 (ndarray or dataframe) – auxiliary matrix
p (int) – number of covariates for the uncertainty component

cubmods.cubsh_ywx.Q2(param, dati2, m)#

Auxiliary function for the log-likelihood estimation of GeCUB models.

Define the opposite one of the two scalar functions that are maximized when running the E-M algorithm for GeCUB models with covariates for feeling, uncertainty and shelter effect.

Parameters:

param (array) – array of initial estimates of parameters for the feeling component
dati2 (ndarray or dataframe) – auxiliary matrix
m (int) – number of ordinal categories

cubmods.cubsh_ywx.draw(m, sh, beta, gamma, omega, Y, W, X, df, formula, seed=None)#

Draw a random sample from a specified CUBSH model with covariates (aka GeCUB model).

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect
n (int) – number of ordinal responses to be drawn
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cubsh_ywx.init_theta(m, sample, p, s, W)#

Preliminary estimators for CUBSH models with covariates.

Computes preliminary parameter estimates of a CUBSH model without covariates for given ordinal responses. These preliminary estimators are used within the package code to start the E-M algorithm.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
p (int) – number of covariates for the uncertainty component
s (int) – number of covariates for the shelter effect
W (pandas dataframe) – dataframe of covariates for explaining the feeling component

Returns:

a tuple of \((\pmb \beta^{(0)}, \pmb \gamma^{(0)}, \pmb \omega^{(0)})\) of preliminary estimates of parameter vectors for \(\pi = \pi(\pmb{\beta})\), ; xi=xi(pmb{gamma}),; delta=delta(pmb{omega})` respectively, of a CUBSH model with covariates for all the three parameters. In details, they have length equal to Y.columns.size+1, W.columns.size+1 and X.columns.size+1, respectively, to account for an intercept term for each component.

Return type:

tuple of arrays

cubmods.cubsh_ywx.loglik(m, sample, sh, Y, W, X, beta, gamma, omega)#

Log-likelihood function of a CUBSH model with covariates.

Compute the log-likelihood function of a CUBE model for ordinal responses, with covariates for explaining all the three parameters (GeCUB model).

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect
sample (array of int) – array of ordinal responses

Returns:

the log-likelihood value

Return type:

float

cubmods.cubsh_ywx.mle(m, sample, sh, Y, W, X, df, formula, ass_pars=None, maxiter=500, tol=0.0001)#

Main function for CUBSH models with covariates for all the components

Function to estimate and validate a CUBSH model for given ordinal responses, with covariates for explaining all the components and the shelter effect.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
sh (int) – Category corresponding to the shelter choice \([1,m]\)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (int) – maximum number of iterations allowed for running the optimization algorithm
tol (float) – fixed error tolerance for final estimates

Returns:

an instance of CUBresCUBSHYWZ (see the Class for details)

Return type:

object

cubmods.cubsh_ywx.pmf(m, sh, beta, gamma, omega, Y, W, X)#

Average probability distribution of a specified CUBSH model with covariates (aka GeCUB model).

\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect

Returns:

the probability distribution

Return type:

array

cubmods.cubsh_ywx.pmfi(m, sh, beta, gamma, omega, Y, W, X)#

Probability distribution for each subject of a specified CUBSH model with covariates (aka GeCUB model).

Auxiliary function of .draw().

\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect

Returns:

the matrix of the probability distribution of dimension \(n \times r\)

Return type:

numpy ndarray

cubmods.cubsh_ywx.prob(m, sample, sh, Y, W, X, beta, gamma, omega)#

Probability distribution of a CUBSH model with covariates.

Compute the probability distribution of a CUBSH model with covariates.

\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect
sample (array of int) – array of ordinal responses

Returns:

the array of the probability distribution.

Return type:

numpy array

cubmods.cubsh_ywx.varcov(sample, m, sh, Y, W, X, beta, gamma, omega)#

Variance-covariance matrix of a CUBSH model with covariates

Compute the variance-covariance matrix of parameter estimates of a CUBSH model with covariates.

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
beta (array of float) – array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals Y.columns.size+1 to include an intercept term in the model (first entry)
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
Y (pandas dataframe) – dataframe of covariates for explaining the uncertainty component
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect
sample (array of int) – array of ordinal responses

Returns:

the variance-covariance matrix of the model

Return type:

numpy ndarray

cubmods.cush module#

CUB models in Python. Module for CUSH (Combination of Uniform and Shelter effect).

Description:#

This module contains methods and classes for CUSH model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

TODO: check and fix gini & laakso

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cush.CUBresCUSH(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([ci, saveas, figsize])	Main function to plot an object of the Class.
`plot_estim`([ci, ax, magnified, figsize, saveas])	Plots the estimated parameter values in the parameter space and the asymptotic standard error.
`plot_ordinal`([figsize, kind, ax, saveas])	Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(ci=0.95, saveas=None, figsize=(7, 8))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
ci (float) – level \((1-\alpha/2)\) for the standard error
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_estim(ci=0.95, ax=None, magnified=False, figsize=(7, 7), saveas=None)#

Plots the estimated parameter values in the parameter space and the asymptotic standard error.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
ci (float) – level \((1-\alpha/2)\) for the confidence ellipse
magnified (bool) – if False the limits will be the entire parameter space, otherwise let matplotlib choose the limits
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 7), kind='bar', ax=None, saveas=None)#

Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cush.LRT(m, fc, n)#

Likelihood Ratio Test between the CUSH model and the null model.

Parameters:

m (int) – number of ordinal categories
fc (float) – relative frequency of the shelter category
n (int) – number of observations

Returns:

the value of the LRT

Return type:

float

cubmods.cush.draw(m, sh, delta, n, df, formula, seed=None)#

Draw a random sample from a specified CUSH model.

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
delta (float) – shelter choice parameter \(\delta\)
n (int) – number of ordinal responses
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cush.gini(delta)#

The Gini index of a specified CUSH model.

Parameters:: delta (float) – shelter choice parameter \(\delta\)
Returns:: the Gini index of the model
Return type:: float

cubmods.cush.laakso(m, delta)#

The Laakso index of a specified CUSH model.

Parameters:

m (int) – number of ordinal categories
delta (float) – shelter choice parameter \(\delta\)

Returns:

the Laakso index of the model

Return type:

float

cubmods.cush.loglik(sample, m, sh, delta)#

Log-likelihood function for a CUSH model without covariates

Compute the log-likelihood function for a CUSH model without covariate for the given ordinal responses.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
delta (float) – shelter choice parameter \(\delta\)

Returns:

the log-likehood value

Return type:

float

cubmods.cush.mean(m, sh, delta)#

Expected value of a specified CUSH model.

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
delta (float) – shelter choice parameter \(\delta\)

Returns:

the expected value of the model

Return type:

float

cubmods.cush.mle(sample, m, sh, df, formula, ass_pars=None, maxiter=None, tol=None)#

Main function for CUSH model without covariates.

Estimate and validate a CUSH model for given ordinal responses, without covariates.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (None) – default to None; ensure compatibility with gem.from_formula()
tol (None) – default to None; ensure compatibility with gem.from_formula()

Returns:

an instance of CUBresCUSH (see the Class for details)

Return type:

object

cubmods.cush.pmf(m, sh, delta)#

Probability distribution of a specified CUSH model.

\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
delta (float) – shelter choice parameter \(\delta\)

Returns:

the probability distribution

Return type:

array

cubmods.cush.var(m, sh, delta)#

Variance of a specified CUSH model.

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
delta (float) – shelter choice parameter \(\delta\)

Returns:

the variance of the model

Return type:

float

cubmods.cush2 module#

CUB models in Python. Module for CUSH2 (Combination of Uniform and 2 Shelter Choices).

Description:#

This module contains methods and classes for CUSH2 model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cush2.CUBresCUSH2(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([ci, saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
`plot_par_space`([figsize, ax, ci, saveas])	Plots the estimated parameter values in the parameter space and the asymptotic standard error.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(ci=0.95, saveas=None, figsize=(7, 11))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
ci (float) – level \((1-\alpha/2)\) for the standard error
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_par_space(figsize=(7, 5), ax=None, ci=0.95, saveas=None)#

Plots the estimated parameter values in the parameter space and the asymptotic standard error.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
ci (float) – level \((1-\alpha/2)\) for the confidence ellipse
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cush2.draw(m, sh1, sh2, df, formula, delta1, delta2, n, seed=None)#

Draw a random sample from a specified CUSH2 model.

Parameters:

m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
delta1 (float) – 1st shelter choice parameter \(\delta_1\)
delta2 (float) – 2nd shelter choice parameter \(\delta_2\)
n (int) – number of ordinal responses
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cush2.loglik(sample, m, c1, c2)#

Log-likelihood function for a CUSH2 model without covariates.

Compute the log-likelihood function for a CUSH2 model without covariate for the given ordinal responses.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
c1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
c2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)

Returns:

the log-likehood value

Return type:

float

cubmods.cush2.mle(sample, m, c1, c2, df, formula, ass_pars=None, maxiter=None, tol=None)#

Main function for CUSH2 models without covariates.

Estimate and validate a CUSH2 model for ordinal responses, without covariates.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
c1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
c2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (None) – default to None; ensure compatibility with gem.from_formula()
tol (None) – default to None; ensure compatibility with gem.from_formula()

Returns:

an instance of CUBresCUSH2 (see the Class for details)

Return type:

object

cubmods.cush2.pmf(m, c1, c2, d1, d2)#

Probability distribution of a specified CUSH2 model.

\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
c1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
c2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
d1 (float) – 1st shelter choice parameter \(\delta_1\)
d2 (float) – 2nd shelter choice parameter \(\delta_2\)

Returns:

the probability distribution

Return type:

array

cubmods.cush2.varcov(m, n, d1, d2, fc1, fc2)#

Compute the variance-covariance matrix of parameter estimates of a CUSH2 model without covariates.

Parameters:

m (int) – number of ordinal categories
n (int) – number of ordinal responses
d1 (float) – 1st shelter choice parameter \(\delta_1\)
d2 (float) – 2nd shelter choice parameter \(\delta_2\)
fc1 (float) – relative frequency of 1st shelter choice
fc2 (float) – relative frequency of 2nd shelter choice

Returns:

the variance-covariance matrix

Return type:

numpy ndarray

cubmods.cush2_x0 module#

CUB models in Python. Module for CUSH2 (Combination of Uniform and 2 Shelter Choices) with covariates for the 1st shelter choice.

Description:#

This module contains methods and classes for CUSH2 model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cush2_x0.CUBresCUSH2X0(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(saveas=None, figsize=(7, 5))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cush2_x0.draw(m, sh1, sh2, omega1, delta2, X1, df, formula, seed=None)#

Draw a random sample from a specified CUSH2 model, with covariates for the 1st shelter choice only.

Parameters:

m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
omega1 (array) – array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals X1.columns.size+1 to include an intercept term in the model (first entry)
delta2 (float) – 2nd shelter choice parameter \(\delta_2\)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cush2_x0.effe(pars, sample, m, sh1, sh2, X1)#

Auxiliary function for the log-likelihood estimation of CUSH2 models.

Compute the opposite of the scalar function that is maximized when running the E-M algorithm for CUSH2 models with covariates for the 1st shelter choice.

Parameters:

pars (array) – array of parameters
sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect

cubmods.cush2_x0.loglik(sample, m, sh1, sh2, omega1, delta2, X1)#

Log-likelihood function for a CUSH2 model with covariates for the 1st shelter choice only.

Compute the log-likelihood function for a CUSH2 model with covariates for the 1st shelter choice only, for the given ordinal responses.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
omega1 (array) – array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals X1.columns.size+1 to include an intercept term in the model (first entry)
delta2 (float) – 2nd shelter choice parameter \(\delta_2\)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect

Returns:

the log-likehood value

Return type:

float

cubmods.cush2_x0.mle(sample, m, sh1, sh2, X1, df, formula, ass_pars=None)#

Main function for CUSH2 models with covariates for the 1st shelter choice only.

Estimate and validate a CUSH2 model for given ordinal responses, with covariates for the 1st shelter choice only.

Parameters:

sample (array of int) – array of ordinal responses
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None

Returns:

an instance of CUBresCUSH2X0 (see the Class for details)

Return type:

object

cubmods.cush2_x0.pmf(m, sh1, sh2, omega1, delta2, X1)#

Average probability distribution of a specified CUSH2 model with covariates for the 1st shelter choice.

\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
omega1 (array) – array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals X1.columns.size+1 to include an intercept term in the model (first entry)
delta2 (float) – 2nd shelter choice parameter \(\delta_2\)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect

Returns:

the average probability distribution

Return type:

array

cubmods.cush2_x0.pmfi(m, sh1, sh2, omega1, delta2, X1)#

Probability distribution for each subject of a specified CUSH2 model with covariates for the first shelter choice only.

Auxiliary function of .draw().

\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
omega1 (array) – array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals X1.columns.size+1 to include an intercept term in the model (first entry)
delta2 (float) – 2nd shelter choice parameter \(\delta_2\)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect

Returns:

the matrix of the probability distribution of dimension \(n \times r\)

Return type:

numpy ndarray

cubmods.cush2_xx module#

CUB models in Python. Module for CUSH2 (Combination of Uniform and 2 Shelter Choices) with covariates.

Description:#

This module contains methods and classes for CUSH2 model family with covariates for both shelter choices.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cush2_xx.CUBresCUSH2XX(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(saveas=None, figsize=(7, 5))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cush2_xx.draw(m, sh1, sh2, omega1, omega2, X1, X2, df, formula, seed=None)#

Draw a random sample from a specified CUSH2 model, with covariates for both shelter choices.

Parameters:

m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
omega1 (array) – array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals X1.columns.size+1 to include an intercept term in the model (first entry)
omega2 (array) – array \(\pmb \omega_2\) of parameters for the 2nd shelter effect, whose length equals X2.columns.size+1 to include an intercept term in the model (first entry)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect
X2 (DataFrame) – dataframe of covariates for explaining the 2nd shelter effect
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cush2_xx.effe(pars, sample, m, sh1, sh2, X1, X2)#

Auxiliary function for the log-likelihood estimation of CUSH2 models.

Compute the opposite of the scalar function that is maximized when running the E-M algorithm for CUSH2 models with covariates for both shelter choices.

Parameters:

pars (array) – array of parameters
sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect
X2 (DataFrame) – dataframe of covariates for explaining the 2nd shelter effect

cubmods.cush2_xx.loglik(sample, m, sh1, sh2, omega1, omega2, X1, X2)#

Log-likelihood function for a CUSH2 model with covariates for both shelter choices.

Compute the log-likelihood function for a CUSH2 model with covariates for both shelter choices, for the given ordinal responses.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
omega1 (array) – array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals X1.columns.size+1 to include an intercept term in the model (first entry)
omega2 (array) – array \(\pmb \omega_2\) of parameters for the 2nd shelter effect, whose length equals X2.columns.size+1 to include an intercept term in the model (first entry)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect
X2 (DataFrame) – dataframe of covariates for explaining the 2nd shelter effect

Returns:

the log-likehood value

Return type:

float

cubmods.cush2_xx.mle(sample, m, sh1, sh2, X1, X2, df, formula, ass_pars=None)#

Main function for CUSH2 models with covariates for both shelter choices.

Estimate and validate a CUSH2 model for given ordinal responses, with covariates for both shelter choices.

Parameters:

sample (array of int) – array of ordinal responses
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect
X2 (DataFrame) – dataframe of covariates for explaining the 2nd shelter effect
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None

Returns:

an instance of CUBresCUSH2XX (see the Class for details)

Return type:

object

cubmods.cush2_xx.pmf(m, sh1, sh2, omega1, omega2, X1, X2)#

Average probability distribution of a specified CUSH2 model with covariates for both shelter choices.

\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
omega1 (array) – array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals X1.columns.size+1 to include an intercept term in the model (first entry)
omega2 (array) – array \(\pmb \omega_2\) of parameters for the 2nd shelter effect, whose length equals X2.columns.size+1 to include an intercept term in the model (first entry)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect
X2 (DataFrame) – dataframe of covariates for explaining the 2nd shelter effect

Returns:

the average probability distribution

Return type:

array

cubmods.cush2_xx.pmfi(m, sh1, sh2, omega1, omega2, X1, X2)#

Probability distribution for each subject of a specified CUSH2 model with covariates for both shelter choices.

Auxiliary function of .draw().

\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh1 (int) – Category corresponding to the 1st shelter choice \([1,m]\)
sh2 (int) – Category corresponding to the 2nd shelter choice \([1,m]\)
omega1 (array) – array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals X1.columns.size+1 to include an intercept term in the model (first entry)
omega2 (array) – array \(\pmb \omega_2\) of parameters for the 2nd shelter effect, whose length equals X2.columns.size+1 to include an intercept term in the model (first entry)
X1 (DataFrame) – dataframe of covariates for explaining the 1st shelter effect
X2 (DataFrame) – dataframe of covariates for explaining the 2nd shelter effect

Returns:

the matrix of the probability distribution of dimension \(n \times r\)

Return type:

numpy ndarray

cubmods.cush_x module#

CUB models in Python. Module for CUSH (Combination of Uniform and Shelter effect) with covariates.

Description:#

This module contains methods and classes for CUSH model family.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.cush_x.CUBresCUSHX(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots avreage relative frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(saveas=None, figsize=(7, 5))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots avreage relative frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.cush_x.draw(m, sh, omega, X, df, formula, seed=None)#

Draw a random sample from a specified CUSH model with covariates

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
sh (int) – Category corresponding to the shelter choice \([1,m]\)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.cush_x.effe(pars, esterno, m, sh)#

Auxiliary function for the log-likelihood estimation of CUSH models with covariates

Compute the opposite of the loglikelihood function for CUSH models with covariates to explain the shelter effect. It is called as an argument for “optim” within .mle() function as the function to minimize.

Parameters:

pars (array) – array of the initial parameters estimates
esterno (ndarray) – matrix binding together the vector of ordinal data and the matrix XX of explanatory variables whose first column is a column of ones needed to consider an intercept term
m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)

cubmods.cush_x.loglik(m, sample, X, omega, sh)#

Log-likelihood function for CUSH models with covariates.

Compute the log-likelihood function for CUSH models with covariates to explain the shelter effect.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
sh (int) – Category corresponding to the shelter choice \([1,m]\)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect

Returns:

the log-likelihood value

Return type:

float

cubmods.cush_x.mle(m, sample, X, sh, df, formula, ass_pars=None, maxiter=None, tol=None)#

Main function for CUSH models with covariates.

Estimate and validate a CUSH model for ordinal responses, with covariates to explain the shelter effect.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
sh (int) – Category corresponding to the shelter choice \([1,m]\)
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
maxiter (None) – default to None; ensure compatibility with gem.from_formula()
tol (None) – default to None; ensure compatibility with gem.from_formula()

Returns:

an instance of CUBresCUSHX (see the Class for details)

Return type:

object

cubmods.cush_x.pmf(m, sh, omega, X)#

Average probability distribution of a specified CUSH model with covariates.

\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect

Returns:

the probability distribution

Return type:

array

cubmods.cush_x.pmfi(m, sh, omega, X)#

Probability distribution for each subject of a specified CUSH model with covariates

\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
sh (int) – Category corresponding to the shelter choice \([1,m]\)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect

Returns:

the matrix of the probability distribution of dimension \(n \times r\)

Return type:

numpy ndarray

cubmods.cush_x.prob(m, sample, X, omega, sh)#

Probability distribution of a specified CUSH model with covariates.

\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\;i = 1 \ldots n\)

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
sh (int) – Category corresponding to the shelter choice \([1,m]\)
omega (array) – array \(\pmb \omega\) of parameters for the shelter effect, whose length equals X.columns.size+1 to include an intercept term in the model (first entry)
X (pandas dataframe) – dataframe of covariates for explaining the shelter effect

Returns:

the probability array \(\Pr(R = r | \pmb\theta)\) for observed responses

Return type:

float

cubmods.gem module#

CUB models in Python. Module for GEM (Generalized Mixtures).

Description:#

This module contains methods and classes for GEM maximum likelihood estimation and sample drawing.

Manual, Examples and References:#

Models manual

List of TODOs:#

TODO: implement best shelter search

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

cubmods.gem.draw(formula, df=None, m=7, model='cub', n=500, sh=None, seed=None, **params)#

Main function to draw a sample from GEneralized Mixture models.

Parameters:

formula (str) – a formula used to draw the sample, see Manual for details
df (DataFrame) – the DataFrame with covariates (if any)
m (int) – number of ordinal categories
model (str) – the model family; default to "cub"; options "cube" and "cush"
sh (int) – category corresponding to the shelter choice \([1,m]\)
n (int) – number of ordinal responses; it is only effective if the model is without covariates
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
options (dict) – a dictionary of extra options maxiter and tol; see the reference guide for details
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

Return type:

obj

cubmods.gem.estimate(formula, df, m=None, model='cub', sh=None, ass_pars=None, options={})#

Main function to estimate and validate GEneralized Mixture models.

Parameters:

formula (str) – a formula used to estimate the model’s parameters, see Manual for details
df (DataFrame) – the DataFrame with observed ordinal sample and covariates (if any)
m (int) – number of ordinal categories
model (str) – the model family; default to "cub"; options "cube" and "cush"
sh (int) – category corresponding to the shelter choice \([1,m]\)
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None
options (dict) – a dictionary of extra options maxiter and tol; see the reference guide for details

Returns:

an instance of the Base Class CUBres extended by the family module; see each module for details

Return type:

obj

cubmods.general module#

CUB models in Python. Module for General functions.

Description:#

This module contains methods and classes for general functions.

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

exception cubmods.general.InvalidCategoriesError(m, model)#

Bases: Exception

Exception: if m is not suitable for model.

exception cubmods.general.InvalidSampleSizeError(n)#

Bases: Exception

Exception: if the sample size is not strictly greater than zero.

exception cubmods.general.NoShelterError(model)#

Bases: Exception

Exception: if a shelter choice is needed but it hasn’t been provided.

exception cubmods.general.NotImplementedModelError(model, formula)#

Bases: Exception

Exception: if the requested model is known but not yet implemented.

exception cubmods.general.ParameterOutOfBoundsError(param, value)#

Bases: Exception

Exception: if the provided parameter value is out of bounds.

exception cubmods.general.ShelterGreaterThanM(m, sh)#

Bases: Exception

Exception: if the provided shelter choice is greater than \(m\).

exception cubmods.general.UnknownModelError(model)#

Bases: Exception

Exception: if the requested family is unknown.

cubmods.general.addones(A)#

Expand with a unitary vector in the first column of the given matrix to consider also an intercept term for CUB models with covariates.

Parameters:: A – a matrix to be expanded
Returns:: the expanded matrix
Return type:: same of A

cubmods.general.aic(l, p)#

Akaike Information Criterion.

Parameters:

l (float) – log-likelihood
p (int) – number of parameters

Returns:

the AIC value

Return type:

float

cubmods.general.bic(l, p, n)#

Bayesian Information Criterion.

Parameters:

l (float) – log-likelihood
p (int) – number of parameters
n (int) – number of observations

Returns:

the BIC value

Return type:

float

cubmods.general.bitgamma(sample, m, W, gamma)#

Shifted Binomial distribution with covariates.

Return the shifted Binomial probabilities of ordinal responses where the feeling component is explained by covariates via a logistic link.

Parameters:

sample (array) – array of ordinal responses
m (int) – number of ordinal categories
W (pandas dataframe) – dataframe of covariates for explaining the feeling component
gamma (array of float) – array \(\pmb \gamma\) of parameters for the feeling component, whose length equals W.columns.size+1 to include an intercept term in the model (first entry)

Returns:

an array of the same length as sample, where each entry is the shifted Binomial probability for the corresponding observation and feeling value.

Return type:

array

cubmods.general.bitxi(m, sample, xi)#

Shifted Binomial probabilities of ordinal responses

Compute the shifted Binomial probabilities of ordinal responses.

Parameters:

m (int) – number of ordinal categories
sample (array) – array of ordinal responses
xi (float) – feeling parameter \(\xi\)

Returns:

A vector of the same length as sample, where each entry is the shifted Binomial probability of the corresponding observation.

Return type:

array

cubmods.general.choices(m)#

Array of ordinal categories.

Parameters:: m (int) – number of ordinal categories
Returns:: array of int from 1 to m
Return type:: array

cubmods.general.colsof(A)#

Number of columns of the given matrix or dataframe.

Parameters:: A (ndarray, dataframe) – the matrix or dataframe
Returns:: number of columns
Return type:: int

cubmods.general.conf_border(Sigma, mx, my, ax, conf=0.95, plane='z', xyz0=(0, 0, 0))#

Plot the bivariate projection of a trivariate confidence ellipse on a plane.

Auxiliary function of plot_ellipsoid().

Note

Solution by https://gist.github.com/randolf-scholz.

Parameters:

Sigma (ndarray) – bivariate variance-covariance matrix
mx (float) – center of the ellipse on the \(x\) axies
my (float) – center of the ellipse on the \(y\) axies
ax – matpplotlib axis
conf (float) – confidence level of the trivariate ellipsoid.
plane (str) – plane for the projection; could be x, y or z
xyz0 (tuple) – tuple of the bivariate ellipse position

cubmods.general.conf_ell(vcov, mux, muy, ci, ax, color='b', label=True, alpha=0.25)#

Plot bivariate confidence ellipse of estimated parameters at level ci\(=(1 - \alpha/2)\)

Parameters:

vcov (ndarray) – Variance-covariance matrix \(2 \times 2\)
mux (float) – estimate of first parameter
muy (float) – estimate of second parameter
ci (float) – confidence level \(=(1 - \alpha/2)\)
ax – matplotlib axis
color (str) – color of confidence ellipse
label (bool) – whether to add a label of confidence level
alpha (float) – transparency of confidence ellipse

cubmods.general.dissimilarity(p_obs, p_est)#

Normalized dissimilarity measure.

Compute the normalized dissimilarity measure between observed relative frequencies and estimated (theoretical) probabilities of a discrete distribution.

Parameters:

p_obs (array) – Vector of observed relative frequencies
p_est (array) – Vector of estimated (theoretical) probabilities

Returns:

Numeric value of the dissimilarity index, assessing the distance to a perfect fit.

Return type:

float

cubmods.general.dummies2(df, DD)#

Create dummy variables from polychotomous variables.

Auxiliary function of cubmods.gem.from_formula(). A dummy variable is created for all polychotomous variables named C(<varname>).

Parameters:

df (DataFrame) – a DataFrame with all the covariates and the ordinal response
DD (list) – the list of all covariates for each component

Returns:

a tuple of the DataFrame with the dummy variables and the column names

Return type:

tuple

cubmods.general.equal3d(ax)#

Equalize 3d axes.

Auxiliary function of .plot_ellipsoid().

cubmods.general.expit(x)#

Expit function.

It is the inverse of logit. Aka sigmoid or standard logistic.

Parameters:: x (float) – the argument
Returns:: the expit of x
Return type:: float

cubmods.general.formula_parser(formula, model='cub')#

Parse a CUB class formula.

Auxiliary function of cubmods.gem functions.

TODO: add specific Exceptions for formula

Parameters:

formula (str) – the formula to be parsed
model (str) – the model family

Returns:

a tuple of the ordinal response column name and a list of all covariates’ column names for each component

Return type:

tuple

cubmods.general.freq(sample, m, dataframe=False)#

Absolute frequecies of an observed sample of ordinal responses.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
dataframe (bool) – if True return a DataFrame instead of an array, defaults to False

Returns:

the absolute frequencies of the observed sample

Return type:

array or dataframe

cubmods.general.get_cov_ellipsoid(cov, mu=array([0., 0., 0.]), ci=0.95)#

Return the 3d points representing the covariance matrix cov centred at mu, at confidence level ci\(=(1 - \alpha/2)\).

Auxiliary function of .plot_ellipsoid().

Parameters:

cov (ndarray) – Variance-covariance matrix \(3 \times 3\)
mu (array) – ellispoid center \((x_0, y_0, z_0)\)
ci (float) – confidence level \(=(1 - \alpha/2)\)

Returns:

a tuple of 3d points (X, Y, Z)

Return type:

tuple

cubmods.general.get_minor(A, i, j)#

Get a minor of a matrix.

Auxiliary function of .plot_ellipsoid().

Note

Solution by PaulDong

Parameters:

A (ndarray) – a generic matrix
i (int) – row of the minor
j (int) – column of the minor

Returns:

the minor of A

Return type:

ndarray

cubmods.general.hadprod(Amat, xvett)#

Hadamard product of a matrix with a vector

Return the Hadamard product between the given matrix and vector: this operation corresponds to multiply every row of the matrix by the corresponding element of the vector, and it is equivalent to the standard matrix multiplication to the right with the diagonal matrix whose diagonal is the given vector. It is possible only if the length of the vector equals the number of rows of the matrix. It is an auxiliary function needed for computing the variance-covariance matrix of the estimated model with covariates.

Note

if xvett is a row vector, reshapes it to column vector

Parameters:

Amat (ndarray) – A generic matrix
xvett (array) – A generic vector

Returns:

the Hadamard product \(\pmb A \odot \pmb x\)

Return type:

ndarray

cubmods.general.kkk(sample, m)#

Sequence of combinatorial coefficients

Compute the sequence of binomial coefficients \(\binom{m-1}{r-1}\), for \(r= 1, \ldots m\), and then returns a vector of the same length as ordinal, whose i-th component is the corresponding binomial coefficient \(\binom{m-1}{r_i-1}\)

Parameters:

sample (array) – array of ordinal responses
m (int) – number of ordinal categories

Returns:

an array of \(\binom{m-1}{r_i-1}\)

Return type:

array

cubmods.general.load_object(fname)#

Load a saved object from file.

It can used be used to load a CUBsample or a CUBres object, previously saved on a file.

Note

see the Classes for details about these objects

Parameters:: fname (str) – filename
Returns:: the loaded object, instance of CUBsample or CUBres
Return type:: object

cubmods.general.logis(Y, param)#

The logistic transform.

Create a matrix YY binding array Y with a vector of ones, placed as the first column of YY. It applies the logistic transform componentwise to the standard matrix multiplication between YY and param.

Parameters:

Y (ndarray, dataframe) – A generic matrix or a dataframe
param (array) – Vector of coefficients, whose length is Y.columns.size+1 (to consider also an intercept term)

Returns:

a vector whose length is Y.index.size and whose i-th component is the logistic function

cubmods.general.logit(x)#

Logit function.

It is the inverse of the standard logistic function, aka log-odds.

Parameters:: x (float) – the argument
Returns:: the logit of x
Return type:: float

cubmods.general.lsat(f, n)#

Log-likelihood of saturated model.

Saturated level ,that is the theoretically maximum information that can be obtained by a model using as many parameters as possible. Then, the saturated log-likelihood is computed by assuming that the model is specified by as many parameters as available observations. This is the extreme benchmark for comparing previous log-likelihood quantities.

Parameters:

f (array) – absolute frequencies of observed ordinal responses
n (int) – number of observations

Returns:

log-likelihood of saturated model

Return type:

float

cubmods.general.luni(m, n)#

Log-likelihood of null model.

Null level, that is when no structure is searched for. Specifically, this is equivalent to assume a discrete Uniform over the support so that any category has the same probability.

Parameters:

m (int) – number of ordinal categories
n (int) – number of observations

Returns:

the log-likelihood of null model

Return type:

float

cubmods.general.plot_ellipsoid(V, E, ax, zlabel, ci=0.95, magnified=False)#

Plot a trivariate confidence ellipsoid.

Parameters:

V (ndarray) – Variance-covariance matrix
E (array) – Vector of estimated parameters
ax – matplotlib axis
zlabel (str) – label for \(z\) axis
ci (float) – confidence level \((1 - \alpha/2)\)
magnified (bool) – if False plots in the full parameter space

cubmods.general.probbit(m, xi)#

Probability distribution of shifted binomial random variable.

Parameters:

m (int) – number of ordinal categories
xi (float) – feeling parameter \(\xi\)

Returns:

the vector of the probability distribution of a shifted Binomial model.

Return type:

array

cubmods.general.unique(l)#

Unique elements in a 3-dimensional list.

Auxiliary function of .dummies2().

Parameters:: l (list) – the list to analyze
Returns:: the list of unique elements
Return type:: list

cubmods.ihg module#

CUB models in Python. Module for IHG (Inverse HyperGeometric).

Description:#

This module contains methods and classes for IHG model family without covariates.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.ihg.CUBresIHG(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Object returned by .mle() function. See here the Base for details.

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([ci, saveas, figsize])	Main function to plot an object of the Class.
`plot_estim`([ci, ax, magnified])	Plots the estimated parameter values in the parameter space and the asymptotic standard error.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(ci=0.95, saveas=None, figsize=(7, 8))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
ci (float) – level \((1-\alpha/2)\) for the standard error
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_estim(ci=0.95, ax=None, magnified=False)#

Plots the estimated parameter values in the parameter space and the asymptotic standard error.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
ci (float) – level \((1-\alpha/2)\) for the confidence ellipse
magnified (bool) – if False the limits will be the entire parameter space, otherwise let matplotlib choose the limits
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.ihg.draw(m, theta, n, df, formula, seed=None)#

Draw a random sample from a specified IHG model.

Parameters:

m (int) – number of ordinal categories
theta (float) – parameter \(\theta\) (probability of 1st shelter category)
n (int) – number of ordinal responses to be drawn
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.ihg.effe(theta, m, f)#

Compute the negative log-likelihood function of a IHG model without covariates for a given absolute frequency distribution. Auxiliary function of mle() for optimization algorithm.

Parameters:

theta (float) – parameter \(\theta\) (probability of 1st shelter category)
m (int) – number of ordinal categories
f (array of int) – array of absolute frequency distribution

Returns:

the log-likelihood value

Return type:

float

cubmods.ihg.init_theta(m, f)#

Preliminary estimators for IHG models without covariates.

Computes preliminary parameter estimates of a IHG model without covariates for given ordinal responses. These preliminary estimators are used within the package code to start the E-M algorithm.

Parameters:

f (array of int) – array of the absolute frequencies of given ordinal responses
m (int) – number of ordinal categories

Returns:

the value of \(\theta^{(0)}\)

cubmods.ihg.loglik(m, theta, f)#

Compute the log-likelihood function of a IHG model without covariates for a given absolute frequency distribution.

Parameters:

theta (float) – parameter :math:` heta` (probability of 1st shelter category)
m (int) – number of ordinal categories
f (array of int) – array of absolute frequency distribution

Returns:

the log-likelihood value

Return type:

float

cubmods.ihg.mle(m, sample, df, formula, ass_pars=None)#

Main function for CUB models without covariates.

Function to estimate and validate a CUB model without covariates for given ordinal responses.

Parameters:

sample (array of int) – array of ordinal responses
m (int) – number of ordinal categories
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None

Returns:

an instance of CUBresIHG (see the Class for details)

Return type:

object

cubmods.ihg.pmf(m, theta)#

Probability distribution of a specified IHG model without covariates.

\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
theta (float) – parameter \(\theta\) (probability of 1st shelter category)

Returns:

the vector of the probability distribution of a CUB model.

Return type:

numpy array

cubmods.ihg.var(m, theta)#

Variance of a specified IHG model.

Parameters:

m (int) – number of ordinal categories
theta (float) – parameter \(\theta\) (probability of 1st shelter category)

Returns:

the variance of the model

Return type:

float

cubmods.ihg_v module#

CUB models in Python. Module for IHG (Inverse HyperGeometric) with covariates.

Description:#

This module contains methods and classes for IHG model family with covariates.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.ihg_v.CUBresIHGV(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: CUBres

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`plot`([saveas, figsize])	Main function to plot an object of the Class.
`plot_ordinal`([figsize, ax, kind, saveas])	Plots avreage relative frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

plot(saveas=None, figsize=(7, 5))#

Main function to plot an object of the Class.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

plot_ordinal(figsize=(7, 5), ax=None, kind='bar', saveas=None)#

Plots avreage relative frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

cubmods.ihg_v.draw(m, nu, V, df, formula, seed=None)#

Draw a random sample from a specified IHG model with covariates

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
nu (array) – array \(\pmb \nu\) of parameters for \(\theta\), whose length equals V.columns.size+1 to include an intercept term in the model (first entry)
V (pandas dataframe) – dataframe of covariates for explaining the parameter \(\theta\)
df (DataFrame) – original DataFrame
formula (str) – the formula used
seed (int, optional) – the seed to ensure reproducibility, defaults to None

Returns:

an instance of CUBsample (see here) containing ordinal responses drawn from the specified model

cubmods.ihg_v.effe(nu, m, sample, V)#

Auxiliary function for the log-likelihood estimation of IHG models with covariates

Compute the opposite of the loglikelihood function for IHG models with covariates. It is called as an argument for “optim” within .mle() function as the function to minimize.

Parameters:

nu (float) – initial parameter estimate
V (pandas dataframe) – dataframe of covariates for explaining the parameter \(\theta\)
m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses

cubmods.ihg_v.init_theta(m, f)#

Preliminary estimators for IHG models without covariates.

Computes preliminary parameter estimates of a IHG model without covariates for given ordinal responses. These preliminary estimators are used within the package code to start the E-M algorithm.

Parameters:

f (array of int) – array of the absolute frequencies of given ordinal responses
m (int) – number of ordinal categories

Returns:

the array of \(\pmb\nu^{(0)}\)

cubmods.ihg_v.loglik(m, sample, V, nu)#

Log-likelihood function for IHG models with covariates.

Compute the log-likelihood function for CUSH models with covariates to explain the shelter effect.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
nu (array) – array \(\pmb \nu\) of parameters for \(\theta\), whose length equals V.columns.size+1 to include an intercept term in the model (first entry)
V (pandas dataframe) – dataframe of covariates for explaining the parameter \(\theta\)

Returns:

the log-likelihood value

Return type:

float

cubmods.ihg_v.mle(m, sample, V, df, formula, ass_pars=None)#

Main function for IHG models with covariates.

Estimate and validate a IHG model for ordinal responses, with covariates.

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
V (pandas dataframe) – dataframe of covariates for explaining the parameter \(\theta\)
df (DataFrame) – original DataFrame
formula (str) – the formula used
ass_pars (dictionary, optional) – dictionary of hypothesized parameters, defaults to None

Returns:

an instance of CUBresIHGV (see the Class for details)

Return type:

object

cubmods.ihg_v.pmf(m, V, nu)#

Average probability distribution of a specified IHG model with covariates.

\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
nu (array) – array \(\pmb \nu\) of parameters for \(\theta\), whose length equals V.columns.size+1 to include an intercept term in the model (first entry)
V (pandas dataframe) – dataframe of covariates for explaining the parameter \(\theta\)

Returns:

the probability distribution

Return type:

array

cubmods.ihg_v.pmfi(m, V, nu)#

Probability distribution for each subject of a specified IHG model with covariates

\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)

Parameters:

m (int) – number of ordinal categories
nu (array) – array \(\pmb \nu\) of parameters for \(\theta\), whose length equals V.columns.size+1 to include an intercept term in the model (first entry)
V (pandas dataframe) – dataframe of covariates for explaining the parameter \(\theta\)

Returns:

the matrix of the probability distribution of dimension \(n \times r\)

Return type:

numpy ndarray

cubmods.ihg_v.prob(m, sample, V, nu)#

Probability distribution of a IHG model with covariates given an observed sample.

Compute the probability distribution of a IHG model with covariates, given an observed sample.

\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)

Parameters:

m (int) – number of ordinal categories
sample (array of int) – array of ordinal responses
nu (array) – array \(\pmb \nu\) of parameters for \(\theta\), whose length equals V.columns.size+1 to include an intercept term in the model (first entry)
V (pandas dataframe) – dataframe of covariates for explaining the parameter \(\theta\)

Returns:

the array of the probability distribution.

Return type:

numpy array

cubmods.multicub module#

CUB models in Python. Module for MULTICUB and MULTICUBE.

Description:#

This module contains methods and classes for MULTICUB and MULTICUBE tool.

Manual, Examples and References:#

Models manual

List of TODOs:#

…

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

cubmods.multicub.multi(ords, ms=None, model='cub', title=None, labels=None, shs=None, plot=True, print_res=False, pos=None, xlim=(0, 1), ylim=(0, 1), equal=True, confell=True, alpha=0.2, ci=0.95, figsize=(7, 7), ax=None)#

Joint plot of estimated CUB models in the parameter space

Return a plot of estimated CUB models represented as points in the parameter space.

Parameters:

ords (list) – list of arrays of observed ordinal responses
model (str) – model; defaults to cub; options cube
title (str) – title of the plot
labels (list) – labels of the points
shs (int or list) – shelter effect(s); can be an int if the same shelter effect is valid for all samples or a list to specify different shelter choices
plot (bool) – if True (default) plot the results;
print_res (bool) – if True print the results; defaults to False
pos (list) – position of the \(\delta\) or \(\phi\) estimated values
xlim (tuple) – x-axis limits
ylim (tuple) – y-axis limits
equal (bool) – if the plot must have equal aspect; defaults to True
alpha (float) – confidence ellipse transparency
confell (bool) – if True (default) plot confidence ellipse (for CUB model only)
ci (float) – level \((1-\alpha/2)\) for the confidence ellipse
figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None

Returns:

ax

cubmods.multicub.pos_kwargs(pos)#

Position of the \(\delta\) or \(\phi\) estimated values

Parameters:: pos (int) – position (1..8)
Returns:: a dictionary for matplotlib
Return type:: dict

cubmods.smry module#

CUB models in Python. Module for summary tools.

Description:#

This module contains methods and classes for summary tools.

List of TODOs:#

TODO: risultati inferenziali come DataFrame nel Manuale e negli esempi

TODO: bounds opzionali in CUBE mle (anche CUBSH?)

TODO: 2 decimali nei 3d plot?

TODO: dissim in multicub plot (aggiungere opzione)

TODO: grandezza punti phi in multicube

Credits#

Author:

Massimo Pierini

Date:

2023-24

Credits:

Domenico Piccolo, Rosaria Simone

Contacts:

cub@maxpierini.it

Classes and Functions#

class cubmods.smry.CUBres(model, df, formula, m, n, sample, f, theoric, diss, est_names, estimates, e_types, varmat, stderrs, pval, wald, loglike, muloglik, loglikuni, AIC, BIC, seconds, time_exe, logliksat=None, dev=None, logliksatcov=None, niter=None, maxiter=None, tol=None, sh=None, rho=None, ass_pars=None)#

Bases: object

Default Class for MLE results; each model module extends this Class to an ad hoc Class with specific functions. An instance of the extended Class is returned by .mle() functions of model modules.

Variables:

model – the model family
df – the original DataFrame with observed sample and covariates (if any)
formula – the formula used to fit the data
m – number of ordinal categories
n – number of observed ordinal responses
sample – the observed sample of ordinal resposes
f – absolute frequecies of the sample
theoric – estimated probabilty distribution
diss – dissimilarity index
est_names – name of estimated parameters
estimates – values of estimated parameters
e_types – parameters’ component
varmat – variance-covariance matrix of estimated parameters
srtderrs – standard errors of estimated parameters
pval – p-values of estimated parameters
wald – Wald test statistics of estimated parameters
loglike – log-likelihood value
muloglik – average log-likelihood for each observation
loglikuni – log-likelihood of null model
AIC – Akaike Information Criterion
BIC – Bayesian Information Criterino
seconds – execution time of the algorithm
time_exe – when the algorithm has been executed
logliksat – log-likelihood of saturated model (for models without covariates only)
logliksatcov – deprecated
dev – deviance
niter – number of iterations of the EM algorithm
maxiter – maximum number of iterations of the EM algorithm
tol – fixed error tolerance
sh – shelter choice(s), if any
rho – coefficient of correlation between \(\pi\) and \(\xi\)
ass_pars – parameters of known model to be compared with the estimates

Methods

`as_dataframe`()	DataFrame of estimated parameters
`as_txt`()	Print the summary.
`save`(fname)	Save a CUBresult object to file named `fname` + `.cub.fit`
`summary`()	Call `as_txt()`

as_dataframe()#: DataFrame of estimated parameters

as_txt()#: Print the summary. Auxiliary function of summary().

save(fname)#: Save a CUBresult object to file named fname + .cub.fit

summary()#: Call as_txt()

class cubmods.smry.CUBsample(rv, m, pars, model, df, formula, diss, theoric, par_names, p_types, sh=None, seed=None)#

Bases: object

An instance of this Class is returned by .draw() functions. See the corresponding model’s function for details.

Variables:

rv – array of drawn ordinal responses
m – number of ordinal categories
n – number of drawn responses
p – number of model’s parameters
pars – parameters’ values array
model – the model family
df – original DataFrame (if provided) with a column of the drawn sample
formula – the formula used to draw the sample
diss – dissimilarity index between drawn and theoretical distribution
theoric – theoretical distribution
par_names – names of the parameters
p_types – parameters’ component
sh – shelter choice(s), if any
seed – the seed used to ensure reproducibility

Methods

`as_dataframe`()	The parameters' values specified.
`plot`([figsize, kind, ax, saveas])	Basic plot function.
`save`(fname)	Save a CUBsample object to file named `fname` + `cub.sample`
`summary`()	Print the summary of the drawn sample.

as_dataframe()#

The parameters’ values specified.

Returns:: a DataFrame with parameters’ names and values
Return type:: DataFrame

plot(figsize=(7, 5), kind='bar', ax=None, saveas=None)#

Basic plot function.

Parameters:

figsize (tuple of float) – tuple of (length, height) for the figure (useful only if ax is not None)
kind (str) – choose a barplot ('bar' default) of a scatterplot ('scatter')
ax (matplolib ax, optional) – matplotlib axis, if None a new figure will be created, defaults to None
saveas (str) – if provided, name of the file to save the plot

Returns:

ax or a tuple (fig, ax)

save(fname)#: Save a CUBsample object to file named fname + cub.sample

summary()#: Print the summary of the drawn sample.