%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
   \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax
\ifdefined\pdfimageresolution
    \pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax
\fi
%% let collapsible pdf bookmarks panel have high depth per default
\PassOptionsToPackage{bookmarksdepth=5}{hyperref}

\PassOptionsToPackage{booktabs}{sphinx}
\PassOptionsToPackage{colorrows}{sphinx}

\PassOptionsToPackage{warn}{textcomp}
\usepackage[utf8]{inputenc}
\ifdefined\DeclareUnicodeCharacter
% support both utf8 and utf8x syntaxes
  \ifdefined\DeclareUnicodeCharacterAsOptional
    \def\sphinxDUC#1{\DeclareUnicodeCharacter{"#1}}
  \else
    \let\sphinxDUC\DeclareUnicodeCharacter
  \fi
  \sphinxDUC{00A0}{\nobreakspace}
  \sphinxDUC{2500}{\sphinxunichar{2500}}
  \sphinxDUC{2502}{\sphinxunichar{2502}}
  \sphinxDUC{2514}{\sphinxunichar{2514}}
  \sphinxDUC{251C}{\sphinxunichar{251C}}
  \sphinxDUC{2572}{\textbackslash}
\fi
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb,amstext}
\usepackage{babel}



\usepackage{tgtermes}
\usepackage{tgheros}
\renewcommand{\ttdefault}{txtt}



\usepackage[Bjarne]{fncychap}
\usepackage{sphinx}

\fvset{fontsize=auto}
\usepackage{geometry}


% Include hyperref last.
\usepackage{hyperref}
% Fix anchor placement for figures with captions.
\usepackage{hypcap}% it must be loaded after hyperref.
% Set up styles of URL: it should be placed after hyperref.
\urlstyle{same}

\addto\captionsenglish{\renewcommand{\contentsname}{Contents:}}

\usepackage{sphinxmessages}
\setcounter{tocdepth}{1}


    \usepackage{upgreek}
    

\title{CUBmods}
\date{Oct 04, 2024}
\release{0.0.1}
\author{Massimo Pierini}
\newcommand{\sphinxlogo}{\vbox{}}
\renewcommand{\releasename}{Release}
\makeindex
\begin{document}

\ifdefined\shorthandoff
  \ifnum\catcode`\=\string=\active\shorthandoff{=}\fi
  \ifnum\catcode`\"=\active\shorthandoff{"}\fi
\fi

\pagestyle{empty}
\sphinxmaketitle
\pagestyle{plain}
\sphinxtableofcontents
\pagestyle{normal}
\phantomsection\label{\detokenize{index::doc}}


\sphinxstepscope


\chapter{Introduction}
\label{\detokenize{intro:introduction}}\label{\detokenize{intro::doc}}

\section{Preface}
\label{\detokenize{intro:preface}}
\sphinxAtStartPar
This package has been implemented by Massimo Pierini as a Bachelor’s thesis (\hyperlink{cite.references:id42}{Pierini, 2024}).

\sphinxAtStartPar
It is the first implementation of CUB class models in Python and is mainly based upon
the work of Domenico Piccolo and the \sphinxcode{\sphinxupquote{CUB}} package in R (\hyperlink{cite.references:id23}{Iannario \sphinxstyleemphasis{et al.}, 2022}),
mainteined by Rosaria Simone.


\section{Background}
\label{\detokenize{intro:background}}
\sphinxAtStartPar
The class of CUB (Combination of Uniform and Binomial) models, proposed by Professor Domenico Piccolo in
2003 (\hyperlink{cite.references:id4}{Piccolo, 2003}) within the cotext of rating and preference data analysis, hypothesizes that
the ordinal responses provided by the raters are not the simple result of a reasoned choice, but rather the
complex combination of a multitude of factors, both internal and external.

\sphinxAtStartPar
Simplifying, two main components can be distinguished:
\sphinxstyleemphasis{feeling} and \sphinxstyleemphasis{uncertainty}.

\sphinxAtStartPar
The primary component of feeling
is due to sufficient awareness and understanding of the topic based on
knowledge and experience.
The secondary component of uncertainty is instead generated by an \sphinxstyleemphasis{intrinsic fuzziness}, due to
various circumstances: limited knowledge, lack of interest, timing of the survey, method of
administration, boredom, and so on.

\sphinxAtStartPar
The simplest way to consider these
two aspects is a distribution resulting from a
mixture of a shifted Binomial component for the first and Uniform Discrete for the
second which takes the form of the CUB family models, subsequently
extended to consider further factors such as the overdispersion of
Binomial component, the effect of shelter choice, and so on.

\sphinxAtStartPar
The most updated paper by \hyperlink{cite.references:id3}{Piccolo and Simone, 2019} will be used as a reference for
terminology, theory and inferential issues.


\section{Motivation}
\label{\detokenize{intro:motivation}}
\sphinxAtStartPar
Currently the class of CUB models has been implemented in statistical and econometric programming languages
such as R (\hyperlink{cite.references:id23}{Iannario \sphinxstyleemphasis{et al.}, 2022}), Stata (\hyperlink{cite.references:id29}{Cerulli \sphinxstyleemphasis{et al.}, 2021}),
Gretl (\hyperlink{cite.references:id30}{Simone \sphinxstyleemphasis{et al.}, 2019})
and GAUSS (\hyperlink{cite.references:id7}{Piccolo, 2006}).  However, given the recent increase in the development
of the Python programming language also in the statistical field (\hyperlink{cite.references:id28}{Pittard and Li, 2020}),
their implementation in
this environment could be useful to the scientific community.


\section{Notes}
\label{\detokenize{intro:notes}}
\sphinxAtStartPar
To simplify the notation, the complete matrix of the covariates will be occasionally
indicated by \(\pmb T\) and the column vector of model’s parameters by \(\pmb\theta\).

\sphinxAtStartPar
Generally speaking, for models with covariates three different probability functions are available:
\begin{enumerate}
\sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}%
\item {} \begin{description}
\sphinxlineitem{\sphinxcode{\sphinxupquote{.pmfi()}} (probability distribution matrix)}\begin{equation*}
\begin{split}\Pr(R_i=r|\pmb\theta; \pmb T_i),
\left\{
\begin{array}{l}
i=1,\ldots,n
\\
r=1,\ldots,m
\end{array}
\right.\end{split}
\end{equation*}
\sphinxAtStartPar
which is a matrix \(n \times m\) of the probability distribution for each \(i\)\sphinxhyphen{}th subject
given the estimated parameters and the covariates. This is an auxiliary function
for \sphinxcode{\sphinxupquote{.draw()}}. Notice that each row sums to 1, i.e.
\begin{equation*}
\begin{split}\sum_{r=1}^m \Pr(R_i=r|\pmb\theta; \pmb T_i) = 1,\; \forall i\end{split}
\end{equation*}
\end{description}

\item {} \begin{description}
\sphinxlineitem{\sphinxcode{\sphinxupquote{.pmf()}} (average probability distribution)}\begin{equation*}
\begin{split}\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1,\ldots,m\end{split}
\end{equation*}
\sphinxAtStartPar
which is a row vector \(1 \times m\) of the average probability given the
estimated parameters and the covariates. This is an auxiliary function
of \sphinxcode{\sphinxupquote{.plot\_ordinal()}} and used to compute the Dissimilarity index for models
with covariates. Notice that it always sums to 1 because
\begin{equation*}
\begin{split}\begin{align*}
\sum_{r=1}^m \frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i)
&= \frac{1}{n} \sum_{i=1}^n \; \sum_{r=1}^m \Pr(R_i=r|\pmb\theta; \pmb T_i)
\\&= \frac{1}{n} \sum_{i=1}^n 1 = \frac{1}{n} n = 1
\end{align*}\end{split}
\end{equation*}
\end{description}

\item {} \begin{description}
\sphinxlineitem{\sphinxcode{\sphinxupquote{.prob()}} (observed sample probability)}\begin{equation*}
\begin{split}\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1,\ldots,n\end{split}
\end{equation*}
\sphinxAtStartPar
which is a column vector \(n \times 1\) of the probabilities for each \(i\)\sphinxhyphen{}th subject
of the observed response \(r_i\) given the estimated parameters and the covariates.
This has not been implemented for all models and can be an auxiliary function
of \sphinxcode{\sphinxupquote{.loglik()}}. Notice that usually it doesn’t sum to 1.

\end{description}

\end{enumerate}

\begin{DUlineblock}{0em}
\item[] 
\item[] 
\item[] 
\end{DUlineblock}

\sphinxstepscope


\chapter{Manual}
\label{\detokenize{manual:manual}}\label{\detokenize{manual::doc}}
\sphinxAtStartPar
The package \sphinxcode{\sphinxupquote{cubmods}} can be used to build models within the CUB class
given an observed sample (and, eventually, the covariance matrix)
in order to estimate the parameters. Also, for each family,
random samples can be drawn from a specified model.

\sphinxAtStartPar
Currently, six families have been defined and implemented:
\begin{itemize}
\item {} 
\sphinxAtStartPar
CUB (Combination of Uniform and Binomial)

\item {} 
\sphinxAtStartPar
CUBSH (CUB + a SHelter choice)

\item {} 
\sphinxAtStartPar
CUSH (Combination of Uniform and a SHelter choice)

\item {} 
\sphinxAtStartPar
CUSH2 (Combination of Uniform and 2 SHelter choices)

\item {} 
\sphinxAtStartPar
CUBE (Combination of Uniform and BEta\sphinxhyphen{}binomial)

\item {} 
\sphinxAtStartPar
IHG (Inverse HyperGeometric)

\end{itemize}

\sphinxAtStartPar
For each family, a model can be defined with or without covariates for one or more parameters.

\sphinxAtStartPar
Details about each family and examples are provided in the following sections.

\sphinxAtStartPar
Even if each family has got its own \sphinxstyleemphasis{Maximum Likelihood Estimation} function \sphinxcode{\sphinxupquote{mle()}} that
could be called directly, for example \sphinxcode{\sphinxupquote{cub.mle()}}, the function \sphinxcode{\sphinxupquote{gem.estimate()}} provides a
simplified and generalised procedure for MLE.

\sphinxAtStartPar
Similarly, even if each family has got its own \sphinxstyleemphasis{Random Sample Drawing} function \sphinxcode{\sphinxupquote{draw()}} that
could be called directly, for example \sphinxcode{\sphinxupquote{cub.draw()}}, the function \sphinxcode{\sphinxupquote{gem.draw()}} provides a
simplified and generalised procedure to draw a random sample.

\sphinxAtStartPar
In this manual \sphinxcode{\sphinxupquote{gem}} functions will be used for the examples.

\sphinxAtStartPar
Notice that, the Dissimilarity index is computed for models with covariates also:
it should be interpreted as the fraction of the sample to be changed to achive a
perfect fit to the estimated average probability distribution (see
\sphinxhref{intro.html}{Introduction} Notes).

\sphinxAtStartPar
The last section, shows the basic usage for the tool \sphinxcode{\sphinxupquote{multicub}}.


\section{GeM usage}
\label{\detokenize{manual:gem-usage}}\label{\detokenize{manual:gem-manual}}
\sphinxAtStartPar
GeM (Generalized Mixture) is the main module of \sphinxcode{\sphinxupquote{cubmods}} package, which provides simplified and
generalized functions to both estimate a model from an observed sample and draw a random sample from a
specified model.

\sphinxAtStartPar
The function \sphinxcode{\sphinxupquote{gem.estimate()}} is the main function for the estimation and
validation of a model from an observed sample, calling for the corresponding \sphinxcode{\sphinxupquote{.mle()}} function of
the specified family module, with or without covariates.

\sphinxAtStartPar
The function \sphinxcode{\sphinxupquote{gem.draw()}} is the main function for drawing a random sample from a specified model,
calling for the corresponding \sphinxcode{\sphinxupquote{.draw()}} function of the corresponding family module,
with or without covariates.

\sphinxAtStartPar
\sphinxhref{cubmods.html\#gem-module}{Reference guide}


\subsection{The \sphinxstyleemphasis{formula} syntax}
\label{\detokenize{manual:the-formula-syntax}}
\sphinxAtStartPar
Both functions need a \sphinxcode{\sphinxupquote{formula}} that is a \sphinxstylestrong{string} specifying the name of the ordinal
variable (before the tilde \sphinxcode{\sphinxupquote{\textasciitilde{}}} symbol)
and of the covariates of the components (after the tilde symbol \sphinxcode{\sphinxupquote{\textasciitilde{}}}).
Covariates for each component are
separated by the pipeline symbol \sphinxcode{\sphinxupquote{|}}.
The \sphinxstyleemphasis{zero} symbol \sphinxcode{\sphinxupquote{0}} indicates no covariates for a certain component.
The \sphinxstyleemphasis{one} symbol \sphinxcode{\sphinxupquote{1}} indicates that we want to estimate the parameter of the constant term only.
If more covariates explain a single component, the symbol \sphinxcode{\sphinxupquote{+}} concatenates the names.
Qualitative variables names, must be placed between brackets \sphinxcode{\sphinxupquote{()}} leaded by a \sphinxcode{\sphinxupquote{C}},
for example \sphinxcode{\sphinxupquote{C(varname)}}.

\begin{sphinxadmonition}{warning}{Warning:}
\sphinxAtStartPar
No columns in the DataFrame should be named \sphinxcode{\sphinxupquote{constant}}, \sphinxcode{\sphinxupquote{1}} or \sphinxcode{\sphinxupquote{0}}.
In the column names, only letters, numbers, and underscores \sphinxcode{\sphinxupquote{\_}} are allowed.
Spaces \sphinxstylestrong{SHOULD NOT BE} used in the column names, but discarded (i.e. replaced di \sphinxcode{\sphinxupquote{""}})
or replaced with \sphinxcode{\sphinxupquote{\_}}.
Similarly, any other symbol
or special character (for instance, \sphinxcode{\sphinxupquote{\sphinxhyphen{}}}, \sphinxcode{\sphinxupquote{!}}, \sphinxcode{\sphinxupquote{@}}, etc) \sphinxstylestrong{SHOULD BE} avoided and discarded
or replaced with underscore \sphinxcode{\sphinxupquote{\_}}.
\end{sphinxadmonition}

\sphinxAtStartPar
For example, let’s suppose we have a DataFrame where \sphinxcode{\sphinxupquote{response}} is the ordinal variable,
\sphinxcode{\sphinxupquote{age}} and \sphinxcode{\sphinxupquote{sex}} are respectively a quantitative and a qualitative variable to explain the \sphinxstyleemphasis{feeling} component
only, in a \sphinxcode{\sphinxupquote{cub}} family model. The formula will be \sphinxcode{\sphinxupquote{formula = "response \textasciitilde{} 0 | age + C(sex)"}}.

\begin{sphinxadmonition}{note}{Note:}
\sphinxAtStartPar
Python will automatically order qualitative variables in alphanumeric order. So, for
instance, a variable \sphinxcode{\sphinxupquote{sex}} with two categories \sphinxcode{\sphinxupquote{"M"}} and \sphinxcode{\sphinxupquote{"F"}} will be ordered as
\sphinxcode{\sphinxupquote{{[}"F", "M"{]}}} thus the dummy variabile will be equal to \sphinxcode{\sphinxupquote{0}} where \sphinxcode{\sphinxupquote{sex=="F"}} and equal
to \sphinxcode{\sphinxupquote{1}} where otherwise \sphinxcode{\sphinxupquote{sex=="M"}}. Consequently, the estimated parameters will be the
\sphinxcode{\sphinxupquote{constant}} for \sphinxcode{\sphinxupquote{sex=="F"}} and \sphinxcode{\sphinxupquote{C.sex\_M}} for \sphinxcode{\sphinxupquote{sex=="M"}}. If you want a different order
for the categorical variables, you must specify it in the \sphinxstyleemphasis{DataFrame}, for instance with the
\sphinxcode{\sphinxupquote{pandas}} class \sphinxcode{\sphinxupquote{Categorical}}. In the example:
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id42}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{n}{df}\PYG{p}{[}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{sex}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{]} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{Categorical}\PYG{p}{(}
    \PYG{n}{df}\PYG{p}{[}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{sex}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{categories}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{M}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{F}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{ordered}\PYG{o}{=}\PYG{k+kc}{True}
\PYG{p}{)}
\end{sphinxVerbatim}
\end{sphinxadmonition}

\sphinxAtStartPar
Notice that spaces are allowed between symbols and variable names in the formula but they aren’t
needed: a formula \sphinxcode{\sphinxupquote{"ord \textasciitilde{} X | Y1 + Y2 | Z"}} is the same as \sphinxcode{\sphinxupquote{"ord\textasciitilde{}X|Y1+Y2|Z"}}.

\begin{sphinxadmonition}{warning}{Warning:}
\sphinxAtStartPar
The number of fields separated by the pipeline \sphinxcode{\sphinxupquote{|}} in a formula \sphinxstylestrong{MUST BE} equal to
the number of parameters specifying the model family. Therefore: two for \sphinxcode{\sphinxupquote{cub}} and \sphinxcode{\sphinxupquote{cush2}},
three for \sphinxcode{\sphinxupquote{cube}} and \sphinxcode{\sphinxupquote{cub}} with shelter effect, one for \sphinxcode{\sphinxupquote{cush}} and \sphinxcode{\sphinxupquote{ihg}}.
\end{sphinxadmonition}


\subsection{Arguments of \sphinxstyleliteralintitle{\sphinxupquote{estimate}} and \sphinxstyleliteralintitle{\sphinxupquote{draw}}}
\label{\detokenize{manual:arguments-of-estimate-and-draw}}
\sphinxAtStartPar
Within the function \sphinxcode{\sphinxupquote{estimate}} the number of ordinal categories \sphinxcode{\sphinxupquote{m}} is internally retrieved if not specified
(taking the maximum observed category)
but it is advisable to pass it as an argument to the call if some category has zero frequency.
Within the function \sphinxcode{\sphinxupquote{draw}} instead, the number of ordinal categories \sphinxcode{\sphinxupquote{m}}
will default to \sphinxcode{\sphinxupquote{7}} if not otherwise specified.

\sphinxAtStartPar
A \sphinxcode{\sphinxupquote{pandas}} DataFrame must always be passed to the function \sphinxcode{\sphinxupquote{estimate}}, with the \sphinxstyleemphasis{kwarg}
(keyword argument) \sphinxcode{\sphinxupquote{df}}.
It should contain, at least, a column of the observed sample and the columns of the covariates (if any).
If no \sphinxcode{\sphinxupquote{df}} is passed to the function \sphinxcode{\sphinxupquote{draw}} for a model without covariates
instead, an empty DataFrame will be created.

\sphinxAtStartPar
The number \sphinxcode{\sphinxupquote{n}} of ordinal responses to be drawn will default to \sphinxcode{\sphinxupquote{500}} if not otherwise specified
in the function \sphinxcode{\sphinxupquote{draw}}
for models without covariates. For model with covariates instead, \sphinxcode{\sphinxupquote{n}} is not effective because
the number of drawn ordinal responses will be equal to the passed DataFrame rows.

\sphinxAtStartPar
A \sphinxcode{\sphinxupquote{seed}} could be specified for the function \sphinxcode{\sphinxupquote{draw}} to ensure reproducibility.
Notice that, for models with covariates, \sphinxcode{\sphinxupquote{seed}} cannot be \sphinxcode{\sphinxupquote{0}} (in case, it will be
automatically set to \sphinxcode{\sphinxupquote{1}}).

\sphinxAtStartPar
If no \sphinxcode{\sphinxupquote{model}} is declared, the function takes \sphinxcode{\sphinxupquote{"cub"}} as default.
Currently implemented models are: \sphinxcode{\sphinxupquote{"cub"}} (default), \sphinxcode{\sphinxupquote{"cush"}}, \sphinxcode{\sphinxupquote{"cube"}},
and \sphinxcode{\sphinxupquote{"ihg"}}. CUB models with shelter effect are automatically
implemented using \sphinxcode{\sphinxupquote{model="cub"}} and specifying a shelter choice with the
\sphinxstyleemphasis{kwarg} \sphinxcode{\sphinxupquote{sh}}. CUSH2 models are automatically
implemented using \sphinxcode{\sphinxupquote{model="cush"}} and passing a list of two categories to
the \sphinxstyleemphasis{kwarg} \sphinxcode{\sphinxupquote{sh}} instead of an integer, for instance \sphinxcode{\sphinxupquote{sh={[}2, 7{]}}}.

\sphinxAtStartPar
To the \sphinxcode{\sphinxupquote{draw}} method, the parameters’ values (with the \sphinxstyleemphasis{kwargs} of the corresponding
family) must always be passed:
for example, \sphinxcode{\sphinxupquote{pi}} and \sphinxcode{\sphinxupquote{xi}} for CUB models without covariates, \sphinxcode{\sphinxupquote{beta}} and \sphinxcode{\sphinxupquote{gamma}}
for CUB models with covariates for both feeling and uncertainty, etc. See the
\sphinxcode{\sphinxupquote{.draw()}} function reference of the corresponding family module for details.

\sphinxAtStartPar
If  \sphinxcode{\sphinxupquote{model="cub"}} (or nothing), then a CUB mixture model is fitted to the data to explain uncertainty,
feeling (\sphinxcode{\sphinxupquote{ordinal\textasciitilde{}Y|W}}) and possible shelter effect by further passing the extra argument \sphinxcode{\sphinxupquote{sh}} for the corresponding category.
Subjects’ covariates can be included by specifying covariates matrices in the
formula as \sphinxcode{\sphinxupquote{ordinal\textasciitilde{}Y|W|X}},  to explain uncertainty (Y), feeling (W) or shelter (X).
Notice that
covariates for the shelter effect can be included only if specified for both feeling and uncertainty too (GeCUB models)
because, as in the R package \sphinxcode{\sphinxupquote{CUB}}, only the models without covariates and with covariates for all components
have been implemented.
Nevertheless, the symbol \sphinxcode{\sphinxupquote{1}} could be used to specify a different combination of components with covariates.
For example, if we want to specify a CUB model with the covariate \sphinxcode{\sphinxupquote{cov}} for uncertainty only, we could pass the
formula \sphinxcode{\sphinxupquote{ordinal \textasciitilde{} cov | 1 | 1}}: in this case, for feeling and shelter effect, the constant terms only
(\(\gamma_0\) and \(\omega_0\)) will be estimated and the values of the estimated \(\xi\) and
\(\delta\) could be computed as \(\hat\xi=\mathrm{expit}(\hat\gamma_0)\) and
\(\hat\delta=\mathrm{expit}(\hat\omega_0)\), where \(\mathrm{expit}(x) = 1 / (1 + \exp(-x))\).
See {\hyperref[\detokenize{manual:cubsh-with-covariates}]{\sphinxsamedocref{this example}}} for the GeCUB model.

\sphinxAtStartPar
If \sphinxcode{\sphinxupquote{family="cube"}}, then a CUBE mixture model (Combination of Uniform and Beta\sphinxhyphen{}Binomial) is fitted to the data
to explain uncertainty, feeling and overdispersion. Subjects’ covariates can also be included to explain the
feeling component or all the three components by  specifying covariates matrices in the Formula as
\sphinxcode{\sphinxupquote{ordinal\textasciitilde{}Y|W|Z}} to explain uncertainty (Y), feeling (W) or
overdispersion (Z). For different combinations of components with covariates, the symbol \sphinxcode{\sphinxupquote{1}} can be used.
Notice that \(\hat\phi=e^{\hat\alpha_0}\).

\sphinxAtStartPar
If \sphinxcode{\sphinxupquote{family="ihg"}}, then an IHG model is fitted to the data. IHG models (Inverse HyperGeometric) are a peculiar case of
CUBE models, for \(\phi = 1 - \xi\) (\hyperlink{cite.references:id16}{Iannario, 2012}). The parameter \(\theta\) gives the probability of observing
the first category and is therefore a direct measure of preference, attraction, pleasantness toward the
investigated item. This is the reason why \(\theta\) is customarily referred to as the
preference parameter of the
IHG model. Covariates for the preference parameter \(\theta\) have to be specified
in matrix form in the Formula as \sphinxcode{\sphinxupquote{ordinal\textasciitilde{}V}}.

\sphinxAtStartPar
If \sphinxcode{\sphinxupquote{family="cush"}}, then a CUSH model is fitted to the data (Combination of Uniform and SHelter effect).
If a category corresponding to the inflation should be
passed via argument \sphinxcode{\sphinxupquote{sh}} a CUSH model is called and
covariates for the shelter parameter \(\delta\)
are specified in matrix form Formula as \sphinxcode{\sphinxupquote{ordinal\textasciitilde{}X}}.
If two category corresponding to the inflation should be
passed via argument \sphinxcode{\sphinxupquote{sh}} (as a \sphinxstyleemphasis{list} or \sphinxstyleemphasis{array}) a CUSH2 model is called and
covariates for the shelters’ parameters \((\delta_1,\delta_2)\)
are specified in matrix form Formula as \sphinxcode{\sphinxupquote{ordinal\textasciitilde{}X1|X2}}.
Notice that, to specify covariates for a
single shelter choice in a CUSH2 model,
the formula should be \sphinxcode{\sphinxupquote{ordinal\textasciitilde{}X1|0}} and not \sphinxcode{\sphinxupquote{ordinal\textasciitilde{}0|X2}}.

\sphinxAtStartPar
Extra arguments include the maximum
number of iterations \sphinxcode{\sphinxupquote{maxiter}} for the optimization algorithm,
the required error tolerance \sphinxcode{\sphinxupquote{tol}}, and a dictionary of parameters of a known model
\sphinxcode{\sphinxupquote{ass\_pars}} (assumed parameters) to be compared with the estimates: these could be
the parameters used to draw the sample, theoretical parameters, or howsoever specified
parameters we want to (graphically) compare with the estimates.

\begin{sphinxadmonition}{note}{Note:}
\sphinxAtStartPar
The \sphinxcode{\sphinxupquote{ass\_pars}} argument is effective for models with covariates too.
The \sphinxcode{\sphinxupquote{.plot()}} method will show the average probability distribution of the model specified
with the assumed parameters.
\end{sphinxadmonition}


\subsection{Methods of \sphinxstyleliteralintitle{\sphinxupquote{estimate}} and \sphinxstyleliteralintitle{\sphinxupquote{draw}}}
\label{\detokenize{manual:methods-of-estimate-and-draw}}
\sphinxAtStartPar
For both functions, the methods \sphinxcode{\sphinxupquote{.summary()}} and \sphinxcode{\sphinxupquote{.plot()}} are always available calling the
main functions to print a summary and plot the results, respectively. For \sphinxcode{\sphinxupquote{.plot()}} arguments
and options, see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here} the \sphinxcode{\sphinxupquote{CUBsample}} Class
(for object returned by \sphinxcode{\sphinxupquote{draw}})
and the extended \sphinxcode{\sphinxupquote{CUBres}} Classes of the corresponding
family (for objects returned by \sphinxcode{\sphinxupquote{estimate}}), defined in each family module.

\sphinxAtStartPar
The method \sphinxcode{\sphinxupquote{.summary()}} of objects returned by \sphinxcode{\sphinxupquote{estimate}} function, will print a summary
of the inferential method applied to the observed sample. Along with estimated parameters,
standard errors, Wald tests, and p\sphinxhyphen{}values, it will show some model metrics:
\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{Correlation}}: available for CUB family models without covariates only; it is the correlation between
\(\hat{\pi}\) and \(\hat{\xi}\)

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{Dissimilarity}}: the dissimilarity index that can be interpreted as the fraction of sample to be
change to achieve a perfect fit given the estimated parameters; available for all models with and
without covariates; for models with covariates, the average estimated probability is used

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{Loglik(sat)}}: the log\sphinxhyphen{}likelihood of the \sphinxstyleemphasis{saturated} model; see \sphinxhref{cubmods.html\#cubmods.general.lsat}{here}
and the reference paper
\hyperlink{cite.references:id3}{Piccolo and Simone, 2019}; available for models without covariates only

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{Loglik(MOD)}}: the log\sphinxhyphen{}likelihood of the estimated model

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{Loglik(uni)}}: the log\sphinxhyphen{}likelihood of the \sphinxstyleemphasis{null} model; see \sphinxhref{cubmods.html\#cubmods.general.luni}{here}
and the reference paper
\hyperlink{cite.references:id3}{Piccolo and Simone, 2019}

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{Mean\sphinxhyphen{}loglik}}: mean log\sphinxhyphen{}likelihood, i.e. the log\sphinxhyphen{}likelihood of the estimated model divided
by the number \(n\) of observed ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{Deviance}}: Likelihood Ratio Test (LRT) between the saturated and the estimated models; available
for models without covariates only

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{AIC}}: Akaike Information Criterion

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{BIC}}: Bayesian Information Criterion.

\end{itemize}

\sphinxAtStartPar
Calling \sphinxcode{\sphinxupquote{.as\_dataframe()}} will return a DataFrame of parameters’ names and values for objects
of the Class \sphinxcode{\sphinxupquote{CUBsample}} returned by \sphinxcode{\sphinxupquote{draw}}. For objects of the extended Base Class \sphinxcode{\sphinxupquote{CUBres}} returned
by \sphinxcode{\sphinxupquote{estimate}} instead, will return a DataFrame with parameters’ component, name, estimated value,
standard error, Wald test statistics and p\sphinxhyphen{}value.

\sphinxAtStartPar
Calling the method \sphinxcode{\sphinxupquote{.save(fname)}} the object can be saved on a file called \sphinxcode{\sphinxupquote{fname.cub.sample}}
(for \sphinxcode{\sphinxupquote{draw}}) or \sphinxcode{\sphinxupquote{fname.cub.fit}} (for \sphinxcode{\sphinxupquote{estimate}}).
Saved objects can then be loaded using the function \sphinxcode{\sphinxupquote{general.load\_object(fname)}}.
See {\hyperref[\detokenize{manual:save-load-example}]{\sphinxsamedocref{this example}}}.


\subsection{Attributes of \sphinxstyleliteralintitle{\sphinxupquote{estimate}} and \sphinxstyleliteralintitle{\sphinxupquote{draw}}}
\label{\detokenize{manual:attributes-of-estimate-and-draw}}
\sphinxAtStartPar
For both objects returned by \sphinxcode{\sphinxupquote{estimate}} and \sphinxcode{\sphinxupquote{draw}}, the attributes \sphinxcode{\sphinxupquote{.formula}} and
\sphinxcode{\sphinxupquote{.df}} are always available. The function \sphinxcode{\sphinxupquote{draw}} will return the original DataFrame (if provided)
with an extra column of the drawn ordinal response called as specified in the formula.

\sphinxAtStartPar
Many other attributes can be called from objects of the Base Class \sphinxcode{\sphinxupquote{CUBres}} returned by
\sphinxcode{\sphinxupquote{estimate}}, such as the computed loglikelihood, the AIC and BIC, etc. For details,
see \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base Class \sphinxcode{\sphinxupquote{CUBres}} reference guide.


\section{CUB family}
\label{\detokenize{manual:cub-family}}
\sphinxAtStartPar
Basic family of the class CUB. See the references for details:
\hyperlink{cite.references:id4}{Piccolo, 2003}; \hyperlink{cite.references:id5}{D\textquotesingle{}Elia and Piccolo, 2005}; \hyperlink{cite.references:id7}{Piccolo, 2006};
\hyperlink{cite.references:id8}{Iannario and Piccolo, 2010}; \hyperlink{cite.references:id21}{Iannario and Piccolo, 2009}; \hyperlink{cite.references:id22}{Iannario \sphinxstyleemphasis{et al.}, 2014};
\hyperlink{cite.references:id23}{Iannario \sphinxstyleemphasis{et al.}, 2022}; \hyperlink{cite.references:id3}{Piccolo and Simone, 2019}.


\subsection{Without covariates}
\label{\detokenize{manual:without-covariates}}\label{\detokenize{manual:cub-without-covariates}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#cub00-module}{Reference guide}

\sphinxAtStartPar
A model of the CUB family for responses with \(m\) ordinal categories, without covariates is specified as
\begin{equation*}
\begin{split}\Pr(R=r|\boldsymbol{\theta}) = \pi \dbinom{m-1}{r-1}(1-\xi)^{r-1}\xi^{m-r}+\dfrac{1-\pi}{m},
\; r = 1,2,\ldots,m\end{split}
\end{equation*}
\sphinxAtStartPar
where \(\pi\) and \(\xi\) are the parameters for respectively the \sphinxstyleemphasis{uncertainty} and the
\sphinxstyleemphasis{feeling} components.

\sphinxAtStartPar
Note that \((1-\pi)\) is the weight of the Uncertainty component and
\((1-\xi)\) is the Feeling component for common \sphinxstyleemphasis{positive wording}.

\sphinxAtStartPar
In the following example, a sample will be drawn from a CUB model of \(n=500\) observations of an ordinal
variable with \(m=10\) ordinal categories
and parameters \((\pi=.7, \xi=.2)\). A \sphinxcode{\sphinxupquote{seed=1}} will be set to ensure reproducibility.

\sphinxAtStartPar
Notice that a Dissimilarity index is computed: this should be interpreted as the fraction of the
drawn sample to be changed to achieve a perfect fit to the theoretical specified model the sample
has been drawn from.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id43}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}

\PYG{c+c1}{\PYGZsh{} draw a sample}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord \PYGZti{} 0 | 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{10}\PYG{p}{,} \PYG{n}{pi}\PYG{o}{=}\PYG{l+m+mf}{.7}\PYG{p}{,} \PYG{n}{xi}\PYG{o}{=}\PYG{l+m+mf}{.2}\PYG{p}{,}
    \PYG{n}{n}\PYG{o}{=}\PYG{l+m+mi}{500}\PYG{p}{,} \PYG{n}{seed}\PYG{o}{=}\PYG{l+m+mi}{1}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} print the summary of the drawn sample}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} show the plot of the drawn sample}
\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUB model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== Drawn random sample
=======================================================================
m=10  Sample size=500  seed=1
formula: ord\PYGZti{}0|0
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
  component parameter  value
Uncertainty        pi    0.7
    Feeling        xi    0.2
=======================================================================
Sample metrics
Mean     = 7.368000
Variance = 5.687952
Std.Dev. = 2.384943
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Dissimilarity = 0.0650938
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cub00draw}.png}

\sphinxAtStartPar
Notice that, since the default value of the \sphinxstyleemphasis{kwarg} \sphinxcode{\sphinxupquote{model}} is
\sphinxcode{\sphinxupquote{"cub"}} we do not need to specify it.

\sphinxAtStartPar
Calling \sphinxcode{\sphinxupquote{drawn.as\_dataframe()}} will return a DataFrame with
the specified parameters of the theoretical model

\begin{sphinxVerbatim}[commandchars=\\\{\}]
     component parameter  value
0  Uncertainty        pi    0.7
1      Feeling        xi    0.2
\end{sphinxVerbatim}

\sphinxAtStartPar
Using the previously drawn sample, in the next example the parameters \((\hat\pi, \hat\xi)\) will be estimated.

\sphinxAtStartPar
Note that in the function \sphinxcode{\sphinxupquote{gem.estimate}}:
\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{df}} needs to be a \sphinxcode{\sphinxupquote{pandas}} DataFrame; the attribute \sphinxcode{\sphinxupquote{drawn.df}} will return a DataFrame with \sphinxcode{\sphinxupquote{ord}} as column name of the drawn ordinal response (as previuosly speficied in the formula)

\item {} 
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{formula}} needs the ordinal variable name (\sphinxcode{\sphinxupquote{ord}} in this case) and the covariates for each component (none in this case, so \sphinxcode{\sphinxupquote{"0|0"}})

\item {} 
\sphinxAtStartPar
if \sphinxcode{\sphinxupquote{m}} is not provided, the maximum observed ordinal value will be assumed and a warning will be raised

\item {} 
\sphinxAtStartPar
with \sphinxcode{\sphinxupquote{ass\_pars}} dictionary, the parameters of a known model (if any) can be specified; in this case, we’ll specify the known parameters used to draw the sample

\end{itemize}
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id44}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} inferential method on drawn sample}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord\PYGZti{}0|0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{pi}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{xi}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} print the summary of MLE}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} show the plot of MLE}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUB model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=10  Size=500  Iterations=13  Maxiter=500  Tol=1E\PYGZhy{}04
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Uncertainty
    Estimates  StdErr    Wald  p\PYGZhy{}value
pi      0.675  0.0340  19.872   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Feeling
    Estimates  StdErr    Wald  p\PYGZhy{}value
xi      0.188  0.0090  20.808   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Correlation   = 0.2105
=======================================================================
Dissimilarity = 0.0599
Loglik(sat)   = \PYGZhy{}994.063
Loglik(MOD)   = \PYGZhy{}1000.111
Loglik(uni)   = \PYGZhy{}1151.293
Mean\PYGZhy{}loglik   = \PYGZhy{}2.000
Deviance      = 12.096
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 2004.22
BIC = 2012.65
=======================================================================
Elapsed time=0.00202 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Thu Sep 26 18:00:53 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cub00mle}.png}

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\sphinxAtStartPar
See \sphinxhref{cubmods.html\#module-cubmods.general}{here} the reference guide
of \sphinxcode{\sphinxupquote{general}} module and the reference paper
\hyperlink{cite.references:id3}{Piccolo and Simone, 2019}
for details about log\sphinxhyphen{}likelihoods,
deviance and information criteria.

\sphinxAtStartPar
Calling \sphinxcode{\sphinxupquote{fit.as\_dataframe()}} will return a DataFrame with
parameters’ estimated values and standard errors

\begin{sphinxVerbatim}[commandchars=\\\{\}]
     component parameter  estimate    stderr       wald        pvalue
0  Uncertainty        pi   0.67476  0.033954  19.872485  7.042905e\PYGZhy{}88
1      Feeling        xi   0.18817  0.009043  20.807551  3.697579e\PYGZhy{}96
\end{sphinxVerbatim}
\phantomsection\label{\detokenize{manual:save-load-example}}
\sphinxAtStartPar
As an example, we can now save the \sphinxcode{\sphinxupquote{fit}} object to file. By default,
it will be saved as a \sphinxcode{\sphinxupquote{pickle}} file.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id45}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{save}\PYG{p}{(}\PYG{n}{fname}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cub\PYGZus{}mle\PYGZus{}results}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
The previous code, will save a file \sphinxcode{\sphinxupquote{cub\_mle\_results.cub.fit}}.

\sphinxAtStartPar
We can then load the saved file with the code
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id46}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{general} \PYG{k+kn}{import} \PYG{n}{load\PYGZus{}object}

\PYG{n}{myfit} \PYG{o}{=} \PYG{n}{load\PYGZus{}object}\PYG{p}{(}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cub\PYGZus{}mle\PYGZus{}results.cub.fit}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{)}
\end{sphinxVerbatim}

\sphinxAtStartPar
and we can apply to \sphinxcode{\sphinxupquote{myfit}} the same methods and attributes of the original \sphinxcode{\sphinxupquote{fit}} object.


\subsection{With covariates}
\label{\detokenize{manual:with-covariates}}\label{\detokenize{manual:cub-with-covariates}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#cub0w-module}{Reference guide (0|W)}

\sphinxAtStartPar
\sphinxhref{cubmods.html\#cuby0-module}{Reference guide (Y|0)}

\sphinxAtStartPar
\sphinxhref{cubmods.html\#cubyw-module}{Reference guide (Y|W)}
\begin{equation*}
\begin{split}\Pr(R_i=r|\pmb\theta, \pmb y_i, \pmb w_i) = \pi_i \dbinom{m-1}{r-1}(1-\xi_i)^{r-1}\xi_i^{m-r}+\dfrac{1-\pi_i}{m}
,\; r = 1,2,\ldots,m\end{split}
\end{equation*}\begin{equation*}
\begin{split}\left\{
\begin{array}{l}
    \pi_i = \dfrac{1}{1+\exp\{-\pmb y_i \pmb \beta\}}
    \\
    \xi_i = \dfrac{1}{1+\exp\{-\pmb w_i \pmb \gamma\}}
\end{array}
\right.
\quad \equiv \quad
\left\{
\begin{array}{l}
    \mathrm{logit}(1-\pi_i) = - \pmb y_i \pmb \beta
    \vphantom{\dfrac{1}{1+\exp\{-\pmb y_i \pmb \beta\}}}
    \\
    \mathrm{logit}(1-\xi_i) = - \pmb w_i \pmb \gamma
    \vphantom{\dfrac{1}{1+\exp\{-\pmb w_i \pmb \gamma\}}}
\end{array}
\right.\end{split}
\end{equation*}
\sphinxAtStartPar
All three combinations of covariates has been implemented for CUB family in both Python and R:
for \sphinxstyleemphasis{uncertainty} only, for \sphinxstyleemphasis{feeling} only, and for \sphinxstyleemphasis{both}.

\sphinxAtStartPar
Here we’ll show an example with covariates for \sphinxstyleemphasis{feeling} only.

\sphinxAtStartPar
First of all, we’ll draw a random sample with two covariates for the \sphinxstyleemphasis{feeling} component:
\sphinxcode{\sphinxupquote{W1}} and \sphinxcode{\sphinxupquote{W2}}. Note that, having two covariates, we’ll need three \(\gamma\) parameters,
to consider the constant term too.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id47}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{numpy} \PYG{k}{as} \PYG{n+nn}{np}
\PYG{k+kn}{import} \PYG{n+nn}{pandas} \PYG{k}{as} \PYG{n+nn}{pd}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}

\PYG{c+c1}{\PYGZsh{} Draw a random sample}
\PYG{n}{n} \PYG{o}{=} \PYG{l+m+mi}{1000}
\PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{seed}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{)}
\PYG{n}{W1} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{randint}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{10}\PYG{p}{,} \PYG{n}{n}\PYG{p}{)}
\PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{seed}\PYG{p}{(}\PYG{l+m+mi}{42}\PYG{p}{)}
\PYG{n}{W2} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{random}\PYG{p}{(}\PYG{n}{n}\PYG{p}{)}
\PYG{n}{df} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{p}{\PYGZob{}}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{W1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{W1}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{W2}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{W2}
\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{response \PYGZti{} 0 | W1 + W2}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{10}\PYG{p}{,} \PYG{n}{n}\PYG{o}{=}\PYG{n}{n}\PYG{p}{,}
    \PYG{n}{pi}\PYG{o}{=}\PYG{l+m+mf}{0.8}\PYG{p}{,}
    \PYG{n}{gamma}\PYG{o}{=}\PYG{p}{[}\PYG{l+m+mf}{2.3}\PYG{p}{,} \PYG{l+m+mf}{0.2}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mi}{5}\PYG{p}{]}\PYG{p}{,}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} print the summary}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUB(0W) model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== Drawn random sample
=======================================================================
m=10  Sample size=1000  seed=None
formula: res\PYGZti{}0|W1+W2
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
  component parameter  value
Uncertainty        pi    0.8
    Feeling  constant    2.3
    Feeling        W1    0.2
    Feeling        W2   \PYGZhy{}5.0
=======================================================================
Sample metrics
Mean     = 4.566000
Variance = 8.089734
Std.Dev. = 2.844246
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Dissimilarity = 0.0307673
=======================================================================
\end{sphinxVerbatim}
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id48}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} plot the drawn sample}
\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cub0wdraw}.png}
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id49}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} print the parameters\PYGZsq{} values}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{as\PYGZus{}dataframe}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
     component parameter  value
0  Uncertainty        pi    0.8
1      Feeling  constant    2.3
2      Feeling        W1    0.2
3      Feeling        W2   \PYGZhy{}5.0
\end{sphinxVerbatim}
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id50}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} print the updated DataFrame}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
     W1        W2  res
0     6  0.374540    2
1     9  0.950714    7
2     6  0.731994    8
3     1  0.598658    8
4     1  0.156019    4
..   ..       ...  ...
995   3  0.091582    2
996   9  0.917314    9
997   4  0.136819    1
998   7  0.950237    3
999   8  0.446006    2

[1000 rows x 3 columns]
\end{sphinxVerbatim}

\sphinxAtStartPar
Finally, we’ll call \sphinxcode{\sphinxupquote{estimate}} to estimate the parameters
given the observed (actually, drawn) sample.
We’ll pass the parameters used to drawn the sample with
\sphinxcode{\sphinxupquote{ass\_pars}} (as a dictionary) to graphically compare the
assumed and the estimated average probability distribution.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id51}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} MLE estimation}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{res \PYGZti{} 0 | W1+W2}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{pi}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{gamma}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{:}\PYG{p}{]}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} Print MLE summary}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} plot the results}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUB(0W) model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=10  Size=1000  Iterations=18  Maxiter=500  Tol=1E\PYGZhy{}04
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Uncertainty
          Estimates  StdErr     Wald  p\PYGZhy{}value
pi            0.800  0.0198   40.499   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Feeling
          Estimates  StdErr     Wald  p\PYGZhy{}value
constant      2.353  0.1001   23.514   0.0000
W1            0.194  0.0138   14.034   0.0000
W2           \PYGZhy{}5.076  0.1454  \PYGZhy{}34.909   0.0000
=======================================================================
Dissimilarity = 0.0292
Loglik(MOD)   = \PYGZhy{}1807.052
Loglik(uni)   = \PYGZhy{}2302.585
Mean\PYGZhy{}loglik   = \PYGZhy{}1.807
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 3622.10
BIC = 3641.74
=======================================================================
Elapsed time=0.09656 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Thu Aug 15 18:31:21 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cub0wmle}.png}


\section{CUBSH family}
\label{\detokenize{manual:cubsh-family}}
\sphinxAtStartPar
Basic family of the class CUB with shelter effect.

\sphinxAtStartPar
See the references for details: \hyperlink{cite.references:id10}{Corduas \sphinxstyleemphasis{et al.}, 2009};
\hyperlink{cite.references:id9}{Iannario, 2012};
\hyperlink{cite.references:id3}{Piccolo and Simone, 2019}.


\subsection{Without covariates}
\label{\detokenize{manual:cubsh-without-covariates}}\label{\detokenize{manual:id16}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#cubsh000-module}{Reference guide}

\sphinxAtStartPar
A model of the CUB family with shelter effect
for responses with \(m\) ordinal categories, without covariates is specified as
\begin{equation*}
\begin{split}\Pr(R=r|\boldsymbol{\theta}) = \delta D_r^{(c)} + (1-\delta)\left(\pi b_r(\xi) + \frac{1-\pi}{m} \right)
,\; r=1,2,\ldots,m\end{split}
\end{equation*}
\sphinxAtStartPar
where \(\pi\) and \(\xi\) are the parameters for respectively the \sphinxstyleemphasis{uncertainty} and the
\sphinxstyleemphasis{feeling} components, and \(\delta\) is the weight of the shelter effect.

\sphinxAtStartPar
Other parametrizations have been proposed, such as
\begin{equation*}
\begin{split}\Pr(R=r|\boldsymbol{\theta}) = \lambda b_r(\xi) + (1-\lambda) \left[ \eta/m + (1-\eta) D_r^{(c)} \right]
,\; r=1,2,\ldots,m\end{split}
\end{equation*}
\sphinxAtStartPar
where
\begin{equation*}
\begin{split}\left\{
\begin{array}{l}
    \lambda = \pi(1-\delta)
    \\
    \eta = \dfrac{(1-\pi)(1-\delta)}{1 - \pi(1-\delta)}
\end{array}
\right.\end{split}
\end{equation*}
\sphinxAtStartPar
See \hyperlink{cite.references:id3}{Piccolo and Simone, 2019} (pp 412\sphinxhyphen{}413) for the parameters’ interpretation.

\sphinxAtStartPar
Another parametrization, particularly useful for inferential issues is
\begin{equation*}
\begin{split}\Pr(R=r|\boldsymbol{\theta}) = \pi_1 b_r{\xi} + \pi_2 /m  + (1-\pi_1-\pi_2) D_r^{(c)}\end{split}
\end{equation*}
\sphinxAtStartPar
where
\begin{equation*}
\begin{split}\left\{
\begin{array}{l}
    \pi_1 = (1-\delta)\pi
    \\
    \pi_2 = (1-\delta)(1-\pi)
\end{array}
\right.\end{split}
\end{equation*}
\sphinxAtStartPar
See the references for further details.

\sphinxAtStartPar
In the next example, we’ll draw an ordinal response
and then estimate the parameters given the sample.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id52}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}

\PYG{c+c1}{\PYGZsh{} draw a sample}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord \PYGZti{} 0 | 0 | 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{7}\PYG{p}{,} \PYG{n}{sh}\PYG{o}{=}\PYG{l+m+mi}{1}\PYG{p}{,}
    \PYG{n}{pi}\PYG{o}{=}\PYG{l+m+mf}{.8}\PYG{p}{,} \PYG{n}{xi}\PYG{o}{=}\PYG{l+m+mf}{.4}\PYG{p}{,} \PYG{n}{delta}\PYG{o}{=}\PYG{l+m+mf}{.15}\PYG{p}{,}
    \PYG{n}{n}\PYG{o}{=}\PYG{l+m+mi}{1500}\PYG{p}{,} \PYG{n}{seed}\PYG{o}{=}\PYG{l+m+mi}{42}\PYG{p}{)}

\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{as\PYGZus{}dataframe}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
     component parameter  value
0      Uniform       pi1   0.68
1     Binomial       pi2   0.17
2      Feeling        xi   0.40
3  Uncertainty       *pi   0.80
4      Shelter    *delta   0.15
\end{sphinxVerbatim}

\sphinxAtStartPar
Notice that:
\begin{itemize}
\item {} 
\sphinxAtStartPar
since \sphinxcode{\sphinxupquote{"cub"}} is default value of the \sphinxstyleemphasis{kwarg} \sphinxcode{\sphinxupquote{model}}, we do not need to specify it

\item {} 
\sphinxAtStartPar
we’ll pass to \sphinxcode{\sphinxupquote{estimate}} \sphinxstyleemphasis{kwarg} values taken from the object \sphinxcode{\sphinxupquote{drawn}}

\end{itemize}
\phantomsection\label{\detokenize{manual:confidence-ellipsoid}}
\sphinxAtStartPar
The method \sphinxcode{\sphinxupquote{.plot()}} (of the \sphinxcode{\sphinxupquote{fit}} object)
shows, in the parameters space, the trivariate confidence ellipsoid too, which has not
been implemented yet in the \sphinxcode{\sphinxupquote{CUB}} package in R.
The plot includes the marginal bivariate confidence ellipses too. Notice that, as proven in
\hyperlink{cite.references:id42}{Pierini, 2024} pp 28\sphinxhyphen{}30, the confidence level of the marginal ellipses is greater
than the ellipsoid’s confidence level. Indeed, the radius \(r\) of a
standardized sphere at confidence
level \((1-\alpha_3)\) is equal to \(r = \sqrt{ F^{-1}_{\chi^2_{(3)}}(1-\alpha_3) }\), thus
the confidence level of the bivariate marginal ellipses (which are sections of trivariate
cylinders) is \((1-\alpha_2) = F_{\chi^2_{(2)}}(r^2)\).
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id53}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} inferential method on drawn sample}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,} \PYG{n}{sh}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{sh}\PYG{p}{,}
    \PYG{n}{formula}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{formula}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{pi1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{pi2}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{xi}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{p}{,}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} print the summary of MLE}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} show the plot of MLE}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUBSH model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=7  Shelter=1  Size=1500  Iterations=59  Maxiter=500  Tol=1E\PYGZhy{}04
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Alternative parametrization
       Estimates  StdErr    Wald  p\PYGZhy{}value
pi1        0.661  0.0307  21.508   0.0000
pi2        0.174  0.0344   5.041   0.0000
xi         0.388  0.0077  50.592   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Uncertainty
       Estimates  StdErr    Wald  p\PYGZhy{}value
pi         0.792  0.0400  19.813   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Feeling
       Estimates  StdErr    Wald  p\PYGZhy{}value
xi         0.388  0.0077  50.592   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Shelter effect
       Estimates  StdErr    Wald  p\PYGZhy{}value
delta      0.166  0.0116  14.327   0.0000
=======================================================================
Dissimilarity = 0.0049
Loglik(sat)   = \PYGZhy{}2734.302
Loglik(MOD)   = \PYGZhy{}2734.433
Loglik(uni)   = \PYGZhy{}2918.865
Mean\PYGZhy{}loglik   = \PYGZhy{}1.823
Deviance      = 0.263
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 5474.87
BIC = 5490.81
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cubsh00mle}.png}


\subsection{With covariates}
\label{\detokenize{manual:cubsh-with-covariates}}\label{\detokenize{manual:id19}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#cubshywx-module}{Reference guide}
\begin{equation*}
\begin{split}\Pr(R_i=r|\pmb\theta, \pmb y_i, \pmb w_i, \pmb x_i) = \delta_i D_r^{(c)} + (1-\delta_i)\left(\pi_i b_r(\xi_i) + \frac{1-\pi_i}{m} \right)
,\; r=1,2,\ldots,m\end{split}
\end{equation*}\begin{equation*}
\begin{split}\left\{
\begin{array}{l}
    \pi_i = \dfrac{1}{1+\exp\{-\pmb y_i \pmb \beta\}}
    \\
    \xi_i = \dfrac{1}{1+\exp\{-\pmb w_i \pmb \gamma\}}
    \\
    \delta_i = \dfrac{1}{1+\exp\{-\pmb x_i \pmb \omega\}}
\end{array}
\right.
\quad \equiv \quad
\left\{
\begin{array}{l}
    \mathrm{logit}(1-\pi_i) = -\pmb y_i \pmb \beta
    \vphantom{\dfrac{1}{1+\exp\{-\pmb y_i \pmb \beta\}}}
    \\
    \mathrm{logit}(1-\xi_i) = -\pmb w_i \pmb \gamma
    \vphantom{\dfrac{1}{1+\exp\{-\pmb w_i \pmb \gamma\}}}
    \\
    \mathrm{logit}(\delta_i) = \pmb x_i \pmb \omega
    \vphantom{\dfrac{1}{1+\exp\{-\pmb x_i \pmb \omega\}}}
\end{array}
\right.\end{split}
\end{equation*}
\sphinxAtStartPar
Only the model with covariates for all components (GeCUB) has been
currently defined and implemented, as in the R package \sphinxcode{\sphinxupquote{CUB}}.

\sphinxAtStartPar
Nevertheless, thanks to the symbol \sphinxcode{\sphinxupquote{1}} provided by the
\sphinxstyleemphasis{formula}, we can specify a different combination
of covariates.

\sphinxAtStartPar
For example, we’ll specifiy a model CUB with shelter effect,
with covariates for uncertainty only. We’ll use the function
\sphinxcode{\sphinxupquote{logit}} to have better ‘control’ of the parameters values,
because \(\gamma_0 = \mathrm{logit}(\xi)\) and
similarly for \(\pi\) and \(\delta\).
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id54}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{numpy} \PYG{k}{as} \PYG{n+nn}{np}
\PYG{k+kn}{import} \PYG{n+nn}{pandas} \PYG{k}{as} \PYG{n+nn}{pd}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{general} \PYG{k+kn}{import} \PYG{n}{expit}\PYG{p}{,} \PYG{n}{logit}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}

\PYG{c+c1}{\PYGZsh{} Draw a random sample}
\PYG{n}{n} \PYG{o}{=} \PYG{l+m+mi}{1000}
\PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{seed}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{)}
\PYG{n}{W1} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{randint}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{10}\PYG{p}{,} \PYG{n}{n}\PYG{p}{)}
\PYG{n}{df} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{p}{\PYGZob{}}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{W1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{W1}\PYG{p}{,}
\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{fee \PYGZti{} W1 | 1 | 1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{9}\PYG{p}{,} \PYG{n}{sh}\PYG{o}{=}\PYG{l+m+mi}{2}\PYG{p}{,}
    \PYG{n}{beta}\PYG{o}{=}\PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{l+m+mf}{.8}\PYG{p}{)}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{.2}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{gamma}\PYG{o}{=}\PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{l+m+mf}{.3}\PYG{p}{)}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{omega}\PYG{o}{=}\PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{l+m+mf}{.12}\PYG{p}{)}\PYG{p}{]}\PYG{p}{,}
\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} MLE estimation}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{fee \PYGZti{} W1 | 1 | 1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,} \PYG{n}{sh}\PYG{o}{=}\PYG{l+m+mi}{2}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{beta}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:}\PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{l+m+mf}{.8}\PYG{p}{)}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{.2}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{gamma}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:}\PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{l+m+mf}{.3}\PYG{p}{)}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{omega}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:}\PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{l+m+mf}{.12}\PYG{p}{)}\PYG{p}{]}\PYG{p}{,}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} Print MLE summary}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} plot the results}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUBSH(YWX) model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=9  Shelter=2  Size=1000  Iterations=25  Maxiter=500  Tol=1E\PYGZhy{}04
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Uncertainty
          Estimates  StdErr     Wald  p\PYGZhy{}value
constant      0.992  0.3314    2.994   0.0028
W1           \PYGZhy{}0.127  0.0569   \PYGZhy{}2.228   0.0259
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Feeling
          Estimates  StdErr     Wald  p\PYGZhy{}value
constant     \PYGZhy{}0.902  0.0381  \PYGZhy{}23.662   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Shelter effect
          Estimates  StdErr     Wald  p\PYGZhy{}value
constant     \PYGZhy{}2.074  0.1260  \PYGZhy{}16.462   0.0000
=======================================================================
Dissimilarity = 0.0139
Loglik(MOD)   = \PYGZhy{}2069.978
Loglik(uni)   = \PYGZhy{}2197.225
Mean\PYGZhy{}loglik   = \PYGZhy{}2.070
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 4147.96
BIC = 4167.59
=======================================================================
Elapsed time=1.43850 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Thu Aug 15 19:39:49 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cubshywxmle}.png}

\sphinxAtStartPar
To get the estimated values of \(\hat\xi\) and \(\hat\delta\)
we can use the function \sphinxcode{\sphinxupquote{expit}} because \(\hat\xi = \mathrm{expit}(\hat\gamma_0)\)
and similarly for \(\hat\delta\). Then, we can use the delta\sphinxhyphen{}method
to compute the standard errors of both \(\hat\xi\) and \(\hat\delta\), for instance
\(\widehat{es}(\xi) = \mathrm{expit}[\hat\gamma_0+\widehat{es}(\gamma_0)] - \hat\xi\).
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id55}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{n}{est\PYGZus{}xi} \PYG{o}{=} \PYG{n}{expit}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{estimates}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{p}{)}
\PYG{n}{est\PYGZus{}de} \PYG{o}{=} \PYG{n}{expit}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{estimates}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{)}
\PYG{n}{est\PYGZus{}xi\PYGZus{}se} \PYG{o}{=} \PYG{n}{expit}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{estimates}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{o}{+}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{stderrs}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{p}{)} \PYG{o}{\PYGZhy{}} \PYG{n}{est\PYGZus{}xi}
\PYG{n}{est\PYGZus{}de\PYGZus{}se} \PYG{o}{=} \PYG{n}{expit}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{estimates}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{o}{+}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{stderrs}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{)} \PYG{o}{\PYGZhy{}} \PYG{n}{est\PYGZus{}de}
\PYG{n+nb}{print}\PYG{p}{(}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{     estimates  stderr}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s+s2}{\PYGZdq{}}
    \PYG{l+s+sa}{f}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{xi      }\PYG{l+s+si}{\PYGZob{}}\PYG{n}{est\PYGZus{}xi}\PYG{l+s+si}{:}\PYG{l+s+s2}{.4f}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{  }\PYG{l+s+si}{\PYGZob{}}\PYG{n}{est\PYGZus{}xi\PYGZus{}se}\PYG{l+s+si}{:}\PYG{l+s+s2}{.4f}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{\PYGZdq{}}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s+s2}{\PYGZdq{}}
    \PYG{l+s+sa}{f}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{delta   }\PYG{l+s+si}{\PYGZob{}}\PYG{n}{est\PYGZus{}de}\PYG{l+s+si}{:}\PYG{l+s+s2}{.4f}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{  }\PYG{l+s+si}{\PYGZob{}}\PYG{n}{est\PYGZus{}de\PYGZus{}se}\PYG{l+s+si}{:}\PYG{l+s+s2}{.4f}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{\PYGZdq{}}
\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
     estimates  stderr
xi      0.2886  0.0079
delta   0.1116  0.0131
\end{sphinxVerbatim}

\sphinxAtStartPar
which, in fact, match the values used to draw the sample.


\section{CUSH family}
\label{\detokenize{manual:cush-family}}
\sphinxAtStartPar
Basic family of the class CUSH with a single shelter effect.

\sphinxAtStartPar
See the references for details: \hyperlink{cite.references:id11}{Capecchi and Piccolo, 2017}; \hyperlink{cite.references:id3}{Piccolo and Simone, 2019}.


\subsection{Without covariates}
\label{\detokenize{manual:cush-without-covariates}}\label{\detokenize{manual:id22}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#cush0-module}{Reference guide}
\begin{equation*}
\begin{split}\Pr(R=r|\pmb\theta) = \delta D_r^{(c)} + (1-\delta)/m
,\; r=1,2,\ldots,m\end{split}
\end{equation*}
\sphinxAtStartPar
In the example, we’ll draw a sample from a CUSH model without covariates and
then estimate the parameter \(\delta\) given the observed sample.

\sphinxAtStartPar
Notice that, since the \sphinxcode{\sphinxupquote{model}} is not the default \sphinxcode{\sphinxupquote{"cub"}}, we need to specify it.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id56}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}

\PYG{c+c1}{\PYGZsh{} draw a sample}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord \PYGZti{} 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cush}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{sh}\PYG{o}{=}\PYG{l+m+mi}{7}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{7}\PYG{p}{,} \PYG{n}{delta}\PYG{o}{=}\PYG{l+m+mf}{.15}\PYG{p}{,}
    \PYG{n}{n}\PYG{o}{=}\PYG{l+m+mi}{1500}\PYG{p}{,} \PYG{n}{seed}\PYG{o}{=}\PYG{l+m+mi}{76}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} inferential method on drawn sample}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cush}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord\PYGZti{}0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{sh}\PYG{o}{=}\PYG{l+m+mi}{7}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{delta}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{,}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} print the summary of MLE}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} show the plot of MLE}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUSH model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=7  Shelter=7  Size=1500
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Shelter effect
       Estimates  StdErr   Wald  p\PYGZhy{}value
delta      0.124  0.0130  9.532   0.0000
=======================================================================
Dissimilarity = 0.0236
Loglik(sat)   = \PYGZhy{}2856.039
Loglik(MOD)   = \PYGZhy{}2859.923
Loglik(uni)   = \PYGZhy{}2918.865
Mean\PYGZhy{}loglik   = \PYGZhy{}1.907
Deviance      = 7.768
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 5721.85
BIC = 5727.16
=======================================================================
Elapsed time=0.00113 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Fri Aug 16 10:44:07 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cush0mle}.png}


\subsection{With covariates}
\label{\detokenize{manual:cush-with-covariates}}\label{\detokenize{manual:id23}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#cushx-module}{Reference guide}
\begin{equation*}
\begin{split}\Pr(R_i=r|\pmb\theta,\pmb x_i) = \delta_i D_r^{(c)} + (1-\delta_i)/m
,\; r=1,2,\ldots,m\end{split}
\end{equation*}\begin{equation*}
\begin{split}\delta_i = \dfrac{1}{1+\exp\{ - \pmb x_i \pmb\omega \}}
\quad \equiv \quad
\mathrm{logit}(\delta_i) = \pmb x_i \pmb\omega\end{split}
\end{equation*}
\sphinxAtStartPar
In the example, we’ll draw a sample from a CUSH model with covariates and
then estimate the parameter given the observed sample.

\sphinxAtStartPar
Notice that, since the \sphinxcode{\sphinxupquote{model}} is not the default \sphinxcode{\sphinxupquote{"cub"}}, we need to specify it.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id57}}}
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{numpy} \PYG{k}{as} \PYG{n+nn}{np}
\PYG{k+kn}{import} \PYG{n+nn}{pandas} \PYG{k}{as} \PYG{n+nn}{pd}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{general} \PYG{k+kn}{import} \PYG{n}{logit}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}

\PYG{c+c1}{\PYGZsh{} Draw a random sample}
\PYG{n}{n} \PYG{o}{=} \PYG{l+m+mi}{1000}
\PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{seed}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{)}
\PYG{n}{X} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{randint}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{10}\PYG{p}{,} \PYG{n}{n}\PYG{p}{)}
\PYG{n}{df} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{p}{\PYGZob{}}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{X}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{X}\PYG{p}{,}
\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{fee \PYGZti{} X}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cush}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{9}\PYG{p}{,} \PYG{n}{sh}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{,}
    \PYG{n}{omega}\PYG{o}{=}\PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{l+m+mf}{.05}\PYG{p}{)}\PYG{p}{,} \PYG{l+m+mf}{.2}\PYG{p}{]}\PYG{p}{,}
\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} MLE estimation}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{fee \PYGZti{} X}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cush}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,} \PYG{n}{sh}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{omega}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} Print MLE summary}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} plot the results}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUSH(X) model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=9  Shelter=5  Size=1000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Shelter effect
          Estimates  StdErr    Wald  p\PYGZhy{}value
constant     \PYGZhy{}3.131  0.4361  \PYGZhy{}7.180   0.0000
X             0.229  0.0629   3.642   0.0003
=======================================================================
Dissimilarity = 0.0395
Loglik(MOD)   = \PYGZhy{}2130.030
Loglik(uni)   = \PYGZhy{}2197.225
Mean\PYGZhy{}loglik   = \PYGZhy{}2.130
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 4264.06
BIC = 4273.87
=======================================================================
Elapsed time=0.01704 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Fri Aug 16 10:54:11 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cushxmle}.png}


\section{CUSH2 family}
\label{\detokenize{manual:cush2-family}}
\sphinxAtStartPar
Family of the class CUSH with two shelter effects (CUSH2).

\sphinxAtStartPar
This family has been introduced by \hyperlink{cite.references:id42}{Pierini, 2024} (pp 16\sphinxhyphen{}20) and first
implemented in this Python package. See \hyperlink{cite.references:id3}{Piccolo and Simone, 2019} as a reference
for the CUB class models.

\sphinxAtStartPar
These models are particularly useful whenever the shelter choices are not
\sphinxstyleemphasis{polarized}, i.e. they’re not at the extremes of the ordinal variable support.
In case of \sphinxstyleemphasis{polarized} responses,
finite mixtures based on the Discretized Beta distribution
(see \hyperlink{cite.references:id13}{Simone and Tutz, 2018} and \hyperlink{cite.references:id12}{Simone, 2022})
can be used, which have not been implemented in this package yet.


\subsection{Without covariates}
\label{\detokenize{manual:cush2-without-covariates}}\label{\detokenize{manual:id28}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#cush200-module}{Reference guide}
\begin{equation*}
\begin{split}\Pr(R=r|\pmb\theta) = \delta_1 D_r^{(c_1)} + \delta_2 D_r^{(c_2)} + (1-\delta_1-\delta_2)/m
,\; r=1,2,\ldots,m\end{split}
\end{equation*}
\sphinxAtStartPar
In the example, we’ll draw a sample from a CUSH2 model without covariates and
then estimate the parameters given the observed sample.

\sphinxAtStartPar
Notice that, since the \sphinxcode{\sphinxupquote{model}} is not the default \sphinxcode{\sphinxupquote{"cub"}}, we need to specify it.
Passing a list of two shelter categories with the \sphinxstyleemphasis{kwarg} \sphinxcode{\sphinxupquote{sh}}, a CUSH2 model will be
called.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id58}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}

\PYG{c+c1}{\PYGZsh{} draw a sample}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord \PYGZti{} 0 | 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cush}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{sh}\PYG{o}{=}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{,}\PYG{l+m+mi}{4}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{7}\PYG{p}{,}
    \PYG{n}{delta1}\PYG{o}{=}\PYG{l+m+mf}{.15}\PYG{p}{,} \PYG{n}{delta2}\PYG{o}{=}\PYG{l+m+mf}{.1}\PYG{p}{,}
    \PYG{n}{n}\PYG{o}{=}\PYG{l+m+mi}{1000}\PYG{p}{,} \PYG{n}{seed}\PYG{o}{=}\PYG{l+m+mi}{42}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} inferential method on drawn sample}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cush}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord\PYGZti{}0|0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{sh}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{sh}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{delta1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{delta2}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{p}{,}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} print the summary of MLE}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} show the plot of MLE}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUSH2 model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=7  Shelter=[1 4]  Size=1000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Shelter effects
        Estimates  StdErr    Wald  p\PYGZhy{}value
delta1      0.172  0.0149  11.512   0.0000
delta2      0.113  0.0163   6.930   0.0000
=======================================================================
Dissimilarity = 0.0176
Loglik(sat)   = \PYGZhy{}1849.206
Loglik(MOD)   = \PYGZhy{}1850.709
Loglik(uni)   = \PYGZhy{}1945.910
Mean\PYGZhy{}loglik   = \PYGZhy{}1.851
Deviance      = 3.006
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 3705.42
BIC = 3715.23
=======================================================================
Elapsed time=0.00247 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Fri Sep 27 11:32:02 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cush200mle}.png}


\subsection{With covariates}
\label{\detokenize{manual:cush2-with-covariates}}\label{\detokenize{manual:id29}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#cush2x0-module}{Reference guide (X1|0)}

\sphinxAtStartPar
\sphinxhref{cubmods.html\#cush2xx-module}{Reference guide (X1|X2)}
\begin{equation*}
\begin{split}\Pr(R_i=r|\pmb\theta,\pmb x_{1i}, \pmb x_{2i}) = \delta_{1i} D_r^{(c_1)} + \delta_{2i} D_r^{(c_2)} + (1-\delta_{1i}- \delta_{2i})/m
,\; r=1,2,\ldots,m\end{split}
\end{equation*}\begin{equation*}
\begin{split}\left\{
\begin{array}{l}
    \delta_{1i} = \dfrac{1}{1+\exp\{ - \pmb x_{1i} \pmb\omega_1 \}}
    \\
    \delta_{2i} = \dfrac{1}{1+\exp\{ - \pmb x_{2i} \pmb\omega_2 \}}
\end{array}
\right.
\quad \equiv \quad
\left\{
\begin{array}{l}
    \mathrm{logit}(\delta_{1i}) = \pmb x_{1i} \pmb\omega_1
    \vphantom{\dfrac{1}{1+\exp\{ - \pmb x_{1i} \pmb\omega_1 \}}}
    \\
    \mathrm{logit}(\delta_{2i}) = \pmb x_{2i} \pmb\omega_2
    \vphantom{\dfrac{1}{1+\exp\{ - \pmb x_{2i} \pmb\omega_2 \}}}
\end{array}
\right.\end{split}
\end{equation*}
\sphinxAtStartPar
Two CUSH2 models with covariates have been defined and implemented:
for the first shelter choice only and for both.

\sphinxAtStartPar
In this example we’ll draw a sample from a CUSH2 model with
covariates for the first shelter choice only and will then
estimate the parameters with a CUSH2 model with covariates
for both shelter choices but using the symbol \sphinxcode{\sphinxupquote{1}} in the
formula for the second shelter choice to estimate the
constant parameter only. This is usually not needed, but
we do it here to confirm that \(\mathrm{expit}(\hat\omega_{20})=\hat\delta_2\).

\sphinxAtStartPar
Notice that, since the \sphinxcode{\sphinxupquote{model}} is not the default \sphinxcode{\sphinxupquote{"cub"}}, we need to specify it.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id59}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{numpy} \PYG{k}{as} \PYG{n+nn}{np}
\PYG{k+kn}{import} \PYG{n+nn}{pandas} \PYG{k}{as} \PYG{n+nn}{pd}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{general} \PYG{k+kn}{import} \PYG{n}{logit}\PYG{p}{,} \PYG{n}{expit}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}

\PYG{c+c1}{\PYGZsh{} Draw a random sample}
\PYG{n}{n} \PYG{o}{=} \PYG{l+m+mi}{1000}
\PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{seed}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{)}
\PYG{n}{X} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{randint}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{10}\PYG{p}{,} \PYG{n}{n}\PYG{p}{)}
\PYG{n}{df} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{p}{\PYGZob{}}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{X}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{X}\PYG{p}{,}
\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{fee \PYGZti{} X | 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cush}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{9}\PYG{p}{,} \PYG{n}{sh}\PYG{o}{=}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{8}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{omega1}\PYG{o}{=}\PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{l+m+mf}{.05}\PYG{p}{)}\PYG{p}{,} \PYG{l+m+mf}{.2}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{delta2}\PYG{o}{=}\PYG{l+m+mf}{.1}
\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} MLE estimation}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{fee \PYGZti{} X | 1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cush}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,} \PYG{n}{sh}\PYG{o}{=}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{8}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{omega1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{p}{:}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{omega2}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{o}{\PYGZhy{}}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{p}{)}\PYG{p}{]}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} Print MLE summary}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} plot the results}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}

\PYG{n}{est\PYGZus{}de2} \PYG{o}{=} \PYG{n}{expit}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{estimates}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{p}{)}
\PYG{n}{est\PYGZus{}de2\PYGZus{}es} \PYG{o}{=} \PYG{n}{expit}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{estimates}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{o}{+}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{stderrs}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{p}{)} \PYG{o}{\PYGZhy{}} \PYG{n}{est\PYGZus{}de2}
\PYG{n+nb}{print}\PYG{p}{(}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{     estimates  stderr}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s+s2}{\PYGZdq{}}
    \PYG{l+s+sa}{f}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{delta2  }\PYG{l+s+si}{\PYGZob{}}\PYG{n}{est\PYGZus{}de2}\PYG{l+s+si}{:}\PYG{l+s+s2}{.4f}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{  }\PYG{l+s+si}{\PYGZob{}}\PYG{n}{est\PYGZus{}de2\PYGZus{}es}\PYG{l+s+si}{:}\PYG{l+s+s2}{.4f}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{\PYGZdq{}}
\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUSH2(X1,X2) model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=9  Shelter=[2 8]  Size=1000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Shelter effect 1
          Estimates  StdErr     Wald  p\PYGZhy{}value
constant     \PYGZhy{}3.170  0.4216   \PYGZhy{}7.519   0.0000
X             0.207  0.0613    3.379   0.0007
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Shelter effect 2
          Estimates  StdErr     Wald  p\PYGZhy{}value
constant     \PYGZhy{}2.276  0.1609  \PYGZhy{}14.149   0.0000
=======================================================================
Dissimilarity = 0.0305
Loglik(MOD)   = \PYGZhy{}2122.463
Loglik(uni)   = \PYGZhy{}2197.225
Mean\PYGZhy{}loglik   = \PYGZhy{}2.122
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 4250.93
BIC = 4265.65
=======================================================================
Elapsed time=0.06553 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Fri Aug 16 11:29:11 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cush2xxmle}.png}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
     estimates  stderr
delta2  0.0931  0.0145
\end{sphinxVerbatim}

\sphinxAtStartPar
Notice that, as proven by \hyperlink{cite.references:id9}{Iannario, 2012} (pp 7\sphinxhyphen{}8), CUB models with shelter effect
generate a perfect fit at \(R=c\). It can be easily proven that
CUSH2 models too generate perfect fits at both \(R=c_1\) and \(R=c_2\).
Indeed, we can also graphically see that the estimated probability distribution is
closer to the observed sample than the assumed model used to draw the sample, because
of the perfect fits generated at \(R=2\) and \(R=8\).


\section{CUBE family}
\label{\detokenize{manual:cube-family}}
\sphinxAtStartPar
Family of the class CUBE (Combination of Uniform and BEtaBinomial).
CUB models are nested into CUBE models: in fact, a CUB model is equal to
a CUBE model with the overdispersion parameter \(\phi=0\).
Notiche that \(0\leq\phi\leq0.2\) is the usual range of the overdispersion parameter.

\sphinxAtStartPar
See the references for details: \hyperlink{cite.references:id17}{Iannario, 2014}; \hyperlink{cite.references:id15}{Piccolo, 2015};
\hyperlink{cite.references:id3}{Piccolo and Simone, 2019}.


\subsection{Without covariates}
\label{\detokenize{manual:cube-without-covariates}}\label{\detokenize{manual:id34}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#cube000-module}{Reference guide}
\begin{equation*}
\begin{split}\Pr(R=r|\pmb{\theta}) = \pi \beta e(\xi,\phi)+\dfrac{1-\pi}{m}
,\; r=1,2,\ldots,m\end{split}
\end{equation*}
\sphinxAtStartPar
In this example, we’ll draw a sample from a CUBE model and then
will estimate the parameters given the observed sample.

\sphinxAtStartPar
Notice that, since the \sphinxcode{\sphinxupquote{model}} is not the default \sphinxcode{\sphinxupquote{"cub"}}, we need to specify it.

\sphinxAtStartPar
The \sphinxcode{\sphinxupquote{.plot()}} method of the object \sphinxcode{\sphinxupquote{fit}} will show trivariate and bivariate confidence
regions too, as in CUBSH models. See {\hyperref[\detokenize{manual:confidence-ellipsoid}]{\sphinxsamedocref{here}}} for the values of confidence levels.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id60}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}

\PYG{c+c1}{\PYGZsh{} draw a sample}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord \PYGZti{} 0 | 0 | 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cube}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{9}\PYG{p}{,} \PYG{n}{pi}\PYG{o}{=}\PYG{l+m+mf}{.7}\PYG{p}{,} \PYG{n}{xi}\PYG{o}{=}\PYG{l+m+mf}{.3}\PYG{p}{,} \PYG{n}{phi}\PYG{o}{=}\PYG{l+m+mf}{.15}\PYG{p}{,}
    \PYG{n}{n}\PYG{o}{=}\PYG{l+m+mi}{500}\PYG{p}{,} \PYG{n}{seed}\PYG{o}{=}\PYG{l+m+mi}{1}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} inferential method on drawn sample}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord\PYGZti{}0|0|0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cube}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{pi}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{xi}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{phi}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{2}\PYG{p}{]}\PYG{p}{,}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} print the summary of MLE}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} show the plot of MLE}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUBE model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=9  Size=500  Iterations=62  Maxiter=1000  Tol=1E\PYGZhy{}06
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Uncertainty
     Estimates  StdErr    Wald  p\PYGZhy{}value
pi       0.577  0.0633   9.108   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Feeling
     Estimates  StdErr    Wald  p\PYGZhy{}value
xi       0.251  0.0217  11.560   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Overdispersion
     Estimates  StdErr    Wald  p\PYGZhy{}value
phi      0.111  0.0402   2.754   0.0059
=======================================================================
Dissimilarity = 0.0426
Loglik(sat)   = \PYGZhy{}1037.855
Loglik(MOD)   = \PYGZhy{}1041.100
Loglik(uni)   = \PYGZhy{}1098.612
Mean\PYGZhy{}loglik   = \PYGZhy{}2.082
Deviance      = 6.491
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 2088.20
BIC = 2100.84
=======================================================================
Elapsed time=0.07919 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Fri Aug 16 12:18:49 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cube000mle}.png}


\subsection{With covariates}
\label{\detokenize{manual:cube-with-covariates}}\label{\detokenize{manual:id35}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#cube0w0-module}{Reference guide (0|W|0)}

\sphinxAtStartPar
\sphinxhref{cubmods.html\#cubeywz-module}{Reference guide (Y|W|Z)}
\begin{equation*}
\begin{split}\Pr(R_i=r|\pmb{\theta};\pmb y_i, \pmb w_i; \pmb z_i) = \pi_i \beta e(\xi_i,\phi_i)+\dfrac{1-\pi_i}{m},
,\; r=1,2,\ldots,m\end{split}
\end{equation*}\begin{equation*}
\begin{split}\left\{
\begin{array}{l}
    \pi_i = \dfrac{1}{1+\exp\{ -\pmb y_i \pmb\beta\}}
    \\
    \xi_i = \dfrac{1}{1+\exp\{ -\pmb w_i \pmb\gamma\}}
    \\
    \phi_i = \exp\{ \pmb z_i \pmb \alpha \}
\end{array}
\right.
\quad \equiv \quad
\left\{
\begin{array}{l}
    \mathrm{logit}(1-\pi_i) = -\pmb y_i \pmb\beta
    \vphantom{\dfrac{1}{1+\exp\{ -\pmb y_i \pmb\beta\}}}
    \\
    \mathrm{logit}(1-\xi_i) = -\pmb w_i \pmb\gamma
    \vphantom{\dfrac{1}{1+\exp\{ -\pmb w_i \pmb\gamma\}}}
    \\
    \log \phi_i = \pmb z_i \pmb \alpha
    \vphantom{\exp\{ \pmb z_i \pmb \alpha \}}
\end{array}
\right.\end{split}
\end{equation*}
\sphinxAtStartPar
Currently, as in the R package \sphinxcode{\sphinxupquote{CUB}}, two CUBE models with covariates have been defined and implemented:
for the \sphinxstyleemphasis{feeling} only and for all components.
Nevertheless, the symbol \sphinxcode{\sphinxupquote{1}} can always be used in the
formula for different combinations of covariates.

\sphinxAtStartPar
In this example, we’ll draw a sample with covariates for
\sphinxstyleemphasis{feeling} only and then will estimate the parameters given
the observed sample.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id61}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{numpy} \PYG{k}{as} \PYG{n+nn}{np}
\PYG{k+kn}{import} \PYG{n+nn}{pandas} \PYG{k}{as} \PYG{n+nn}{pd}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{general} \PYG{k+kn}{import} \PYG{n}{expit}\PYG{p}{,} \PYG{n}{logit}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}

\PYG{c+c1}{\PYGZsh{} Draw a random sample}
\PYG{n}{n} \PYG{o}{=} \PYG{l+m+mi}{1000}
\PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{seed}\PYG{p}{(}\PYG{l+m+mi}{76}\PYG{p}{)}
\PYG{n}{W} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{randint}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{10}\PYG{p}{,} \PYG{n}{n}\PYG{p}{)}
\PYG{n}{df} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{p}{\PYGZob{}}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{W}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{W}\PYG{p}{,}
\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{fee \PYGZti{} 0 | W | 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cube}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{9}\PYG{p}{,}
    \PYG{n}{pi}\PYG{o}{=}\PYG{l+m+mf}{.8}\PYG{p}{,}
    \PYG{n}{gamma}\PYG{o}{=}\PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{l+m+mf}{.3}\PYG{p}{)}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{.1}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{phi}\PYG{o}{=}\PYG{l+m+mf}{.12}\PYG{p}{,}
\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} MLE estimation}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{fee \PYGZti{} 0 | W | 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cube}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{pi}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{gamma}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{:}\PYG{o}{\PYGZhy{}}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{phi}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{o}{\PYGZhy{}}\PYG{l+m+mi}{1}\PYG{p}{]}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} Print MLE summary}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} plot the results}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUBE(0W0) model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=9  Size=1000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Uncertainty
          Estimates  StdErr    Wald  p\PYGZhy{}value
pi            0.815  0.0343  23.733   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Feeling
          Estimates  StdErr    Wald  p\PYGZhy{}value
constant     \PYGZhy{}0.770  0.1012  \PYGZhy{}7.612   0.0000
W            \PYGZhy{}0.116  0.0191  \PYGZhy{}6.052   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Overdisperson
          Estimates  StdErr    Wald  p\PYGZhy{}value
phi           0.150  0.0260   5.779   0.0000
=======================================================================
Dissimilarity = 0.0183
Loglik(MOD)   = \PYGZhy{}1886.654
Loglik(uni)   = \PYGZhy{}2197.225
Mean\PYGZhy{}loglik   = \PYGZhy{}1.887
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 3781.31
BIC = 3800.94
=======================================================================
Elapsed time=2.30903 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Fri Aug 16 12:31:10 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cube0w0mle}.png}

\sphinxAtStartPar
Notice that the same results can be achieved using a CUBE
model with covariates for all components and passing
the symbol \sphinxcode{\sphinxupquote{1}} to the \sphinxstyleemphasis{uncertainty} and \sphinxstyleemphasis{overdispersion}
components.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id62}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} MLE estimation}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{fee \PYGZti{} 1 | W | 1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cube}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{beta}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{)}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{gamma}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{:}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{,}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{alpha}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{p}{[}\PYG{n}{np}\PYG{o}{.}\PYG{n}{log}\PYG{p}{(}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{)}\PYG{p}{]}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} Print MLE summary}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} plot the results}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} CUBE(YWZ) model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=9  Size=1000  Iterations=29  Maxiter=1000  Tol=1E\PYGZhy{}02
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Uncertainty
          Estimates  StdErr     Wald  p\PYGZhy{}value
constant      1.423  0.2183    6.518   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Feeling
          Estimates  StdErr     Wald  p\PYGZhy{}value
constant     \PYGZhy{}0.778  0.1018   \PYGZhy{}7.639   0.0000
W            \PYGZhy{}0.117  0.0193   \PYGZhy{}6.074   0.0000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Overdispersion
          Estimates  StdErr     Wald  p\PYGZhy{}value
constant     \PYGZhy{}1.930  0.1756  \PYGZhy{}10.989   0.0000
=======================================================================
Dissimilarity = 0.0239
Loglik(MOD)   = \PYGZhy{}1886.690
Loglik(uni)   = \PYGZhy{}2197.225
Mean\PYGZhy{}loglik   = \PYGZhy{}1.887
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 3781.38
BIC = 3801.01
=======================================================================
Elapsed time=50.02969 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Fri Aug 16 12:33:36 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{cubeywzmle}.png}

\sphinxAtStartPar
In fact:
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id63}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{n}{est\PYGZus{}pi} \PYG{o}{=} \PYG{n}{expit}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{estimates}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{)}
\PYG{n}{est\PYGZus{}ph} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{exp}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{estimates}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{)}
\PYG{n}{est\PYGZus{}pi\PYGZus{}se} \PYG{o}{=} \PYG{n}{expit}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{estimates}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{o}{+}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{stderrs}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{)} \PYG{o}{\PYGZhy{}} \PYG{n}{est\PYGZus{}pi}
\PYG{n}{est\PYGZus{}ph\PYGZus{}se} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{exp}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{estimates}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{o}{+}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{stderrs}\PYG{p}{[}\PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{)} \PYG{o}{\PYGZhy{}} \PYG{n}{est\PYGZus{}ph}
\PYG{n+nb}{print}\PYG{p}{(}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{     estimates  stderr}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s+s2}{\PYGZdq{}}
    \PYG{l+s+sa}{f}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{pi      }\PYG{l+s+si}{\PYGZob{}}\PYG{n}{est\PYGZus{}pi}\PYG{l+s+si}{:}\PYG{l+s+s2}{.4f}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{  }\PYG{l+s+si}{\PYGZob{}}\PYG{n}{est\PYGZus{}pi\PYGZus{}se}\PYG{l+s+si}{:}\PYG{l+s+s2}{.4f}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{\PYGZdq{}}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s+s2}{\PYGZdq{}}
    \PYG{l+s+sa}{f}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{phi     }\PYG{l+s+si}{\PYGZob{}}\PYG{n}{est\PYGZus{}ph}\PYG{l+s+si}{:}\PYG{l+s+s2}{.4f}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{  }\PYG{l+s+si}{\PYGZob{}}\PYG{n}{est\PYGZus{}ph\PYGZus{}se}\PYG{l+s+si}{:}\PYG{l+s+s2}{.4f}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{\PYGZdq{}}
\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
     estimates  stderr
pi      0.8058  0.0319
phi     0.1451  0.0279
\end{sphinxVerbatim}


\section{IHG family}
\label{\detokenize{manual:ihg-family}}
\sphinxAtStartPar
Family of the class IHG (Inverse HyperGeometric).

\sphinxAtStartPar
See the references for details: \hyperlink{cite.references:id18}{D’Elia, 2003}; \hyperlink{cite.references:id19}{D\textquotesingle{}Elia \sphinxstyleemphasis{et al.}, 2005};
\hyperlink{cite.references:id3}{Piccolo and Simone, 2019}.


\subsection{Without covariates}
\label{\detokenize{manual:ihg-without-covariates}}\label{\detokenize{manual:id39}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#ihg0-module}{Reference guide}
\begin{equation*}
\begin{split}\left\{
\begin{array}{l}
    \Pr(R=1|\theta) = \theta
    \\
    \Pr(R=r+1|\theta) = \Pr(R=r|\theta)(1-\theta)\dfrac{m-r}{m-1-r(1-\theta)},\; r= 1,2, \ldots, m-1
\end{array}
\right.\end{split}
\end{equation*}
\sphinxAtStartPar
which is equivalent to
\begin{equation*}
\begin{split}\begin{array}{l}
\Pr(R=r|\theta) = \frac{ \dbinom{m+B-r-1}{m-r} }{ \dbinom{m+B-1}{m-1} },\; r= 1,2, \ldots, m
\\
\textrm{with } B = (m-1)\theta / (1 - \theta)
\end{array}\end{split}
\end{equation*}
\sphinxAtStartPar
In this example, we’ll draw a sample from an IHG model
and the estimate the parameter from the observed sample.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}

\PYG{c+c1}{\PYGZsh{} draw a sample}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord \PYGZti{} 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ihg}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{10}\PYG{p}{,} \PYG{n}{theta}\PYG{o}{=}\PYG{l+m+mf}{.2}\PYG{p}{,}
    \PYG{n}{n}\PYG{o}{=}\PYG{l+m+mi}{500}\PYG{p}{,} \PYG{n}{seed}\PYG{o}{=}\PYG{l+m+mi}{42}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} inferential method on drawn sample}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord \PYGZti{} 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ihg}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{theta}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{,}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} print the summary of MLE}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} show the plot of MLE}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} IHG model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=10  Size=500
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Theta
       Estimates  StdErr    Wald  p\PYGZhy{}value
theta      0.200  0.0086  23.292   0.0000
=======================================================================
Dissimilarity = 0.0639
Loglik(sat)   = \PYGZhy{}1044.100
Loglik(MOD)   = \PYGZhy{}1050.513
Loglik(uni)   = \PYGZhy{}1151.293
Mean\PYGZhy{}loglik   = \PYGZhy{}2.101
Deviance      = 12.824
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 2103.03
BIC = 2107.24
=======================================================================
Elapsed time=0.00464 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Fri Aug 16 12:47:55 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{ihg0mle}.png}


\subsection{With covariates}
\label{\detokenize{manual:ihg-with-covariates}}\label{\detokenize{manual:id40}}
\sphinxAtStartPar
\sphinxhref{cubmods.html\#ihgv-module}{Reference guide}
\begin{equation*}
\begin{split}\left\{
\begin{array}{l}
    \Pr(R_i=1|\pmb\theta;\pmb v_i) = \theta_i
    \\
    \Pr(R_i=r+1|\pmb\theta;\pmb v_i) = \Pr(R_i=r|\pmb\theta;\pmb v_i)(1-\theta_i)\dfrac{m-r}{m-1-r(1-\theta_i)},\; r= 1, \ldots, m-1
\end{array}
\right.\end{split}
\end{equation*}\begin{equation*}
\begin{split}\theta_i = \dfrac{1}{1 + \exp\{ - \pmb v_i \pmb \nu \}}
\quad \equiv \quad
\mathrm{logit}(\theta_i) = \pmb v_i \pmb \nu\end{split}
\end{equation*}
\sphinxAtStartPar
In this example we’ll draw a sample from an IHG with two covariates
and then will estimate the parameters given the observed sample.
Notice that IHG models without covariates are unimodals but, however,
IHG models with covariates can be bimodal, as the one in the following example.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id64}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{c+c1}{\PYGZsh{} import libraries}
\PYG{k+kn}{import} \PYG{n+nn}{numpy} \PYG{k}{as} \PYG{n+nn}{np}
\PYG{k+kn}{import} \PYG{n+nn}{pandas} \PYG{k}{as} \PYG{n+nn}{pd}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}\PYG{p}{,} \PYG{n}{estimate}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{general} \PYG{k+kn}{import} \PYG{n}{logit}

\PYG{c+c1}{\PYGZsh{} Draw a random sample}
\PYG{n}{n} \PYG{o}{=} \PYG{l+m+mi}{1000}
\PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{seed}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{)}
\PYG{n}{V1} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{random}\PYG{p}{(}\PYG{n}{n}\PYG{p}{)}
\PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{seed}\PYG{p}{(}\PYG{l+m+mi}{42}\PYG{p}{)}
\PYG{n}{V2} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{random}\PYG{o}{.}\PYG{n}{random}\PYG{p}{(}\PYG{n}{n}\PYG{p}{)}
\PYG{n}{df} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{p}{\PYGZob{}}
    \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{V1}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{V1}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{V2}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{V2}
\PYG{p}{\PYGZcb{}}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} draw a sample}
\PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord \PYGZti{} V1 + V2}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ihg}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{m}\PYG{o}{=}\PYG{l+m+mi}{10}\PYG{p}{,}
    \PYG{n}{nu}\PYG{o}{=}\PYG{p}{[}\PYG{n}{logit}\PYG{p}{(}\PYG{l+m+mf}{.1}\PYG{p}{)}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{]}\PYG{p}{,}
    \PYG{n}{seed}\PYG{o}{=}\PYG{l+m+mi}{42}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} inferential method on drawn sample}
\PYG{n}{fit} \PYG{o}{=} \PYG{n}{estimate}\PYG{p}{(}
    \PYG{n}{df}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{df}\PYG{p}{,}
    \PYG{n}{formula}\PYG{o}{=}\PYG{n}{drawn}\PYG{o}{.}\PYG{n}{formula}\PYG{p}{,}
    \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ihg}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
    \PYG{n}{ass\PYGZus{}pars}\PYG{o}{=}\PYG{p}{\PYGZob{}}
        \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{nu}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{:} \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{pars}\PYG{p}{,}
    \PYG{p}{\PYGZcb{}}
\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} print the summary of MLE}
\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{fit}\PYG{o}{.}\PYG{n}{summary}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} show the plot of MLE}
\PYG{n}{fit}\PYG{o}{.}\PYG{n}{plot}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\begin{sphinxVerbatim}[commandchars=\\\{\}]
warnings.warn(\PYGZdq{}No m given, max(ordinal) has been taken\PYGZdq{})
=======================================================================
=====\PYGZgt{}\PYGZgt{}\PYGZgt{} IHG(V) model \PYGZlt{}\PYGZlt{}\PYGZlt{}===== ML\PYGZhy{}estimates
=======================================================================
m=10  Size=1000
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
Theta
          Estimates  StdErr     Wald  p\PYGZhy{}value
constant     \PYGZhy{}2.368  0.0998  \PYGZhy{}23.741   0.0000
V1           \PYGZhy{}1.973  0.1438  \PYGZhy{}13.721   0.0000
V2            3.230  0.1451   22.261   0.0000
=======================================================================
Dissimilarity = 0.0455
Loglik(MOD)   = \PYGZhy{}1958.475
Loglik(uni)   = \PYGZhy{}2302.585
Mean\PYGZhy{}loglik   = \PYGZhy{}1.958
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
AIC = 3922.95
BIC = 3937.67
=======================================================================
Elapsed time=1.10664 seconds =====\PYGZgt{}\PYGZgt{}\PYGZgt{} Fri Aug 16 12:53:12 2024
=======================================================================
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{ihgvmle}.png}


\section{MULTICUB}
\label{\detokenize{manual:multicub}}\label{\detokenize{manual:multicub-manual}}
\sphinxAtStartPar
See the \hyperlink{cite.references:id3}{Piccolo and Simone, 2019} as a reference.

\sphinxAtStartPar
\sphinxhref{cubmods.html\#multicub-module}{Reference guide}

\sphinxAtStartPar
With the \sphinxstylestrong{multicub} tool, parameters estimated from
multiple observed samples can be shown in a single plot.

\sphinxAtStartPar
In this example, we’ll draw three samples from CUBE
models and \sphinxstyleemphasis{manually} add a shelter category. Then we’ll
use the \sphinxstylestrong{multicub} tool for CUB models, CUBE models and
CUBSH models (that aren’t yet implemented in the R package \sphinxcode{\sphinxupquote{CUB}}
for the \sphinxstylestrong{multicub} tool).

\sphinxAtStartPar
Notice that, since the samples are drawn from a “CUBE model with shelter effect”
(which has not been implemented yet), the estimated parameters’ values will
differ from the theoretical ones of the speficied CUBE model used to draw the sample.

\sphinxAtStartPar
The \sphinxstylestrong{multicub} tool in \sphinxcode{\sphinxupquote{cubmods}} package can also show confidence
ellipses for CUB models.
\sphinxSetupCaptionForVerbatim{Script}
\def\sphinxLiteralBlockLabel{\label{\detokenize{manual:id65}}}
\begin{sphinxVerbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{import} \PYG{n+nn}{numpy} \PYG{k}{as} \PYG{n+nn}{np}
\PYG{k+kn}{import} \PYG{n+nn}{pandas} \PYG{k}{as} \PYG{n+nn}{pd}
\PYG{k+kn}{import} \PYG{n+nn}{matplotlib}\PYG{n+nn}{.}\PYG{n+nn}{pyplot} \PYG{k}{as} \PYG{n+nn}{plt}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{gem} \PYG{k+kn}{import} \PYG{n}{draw}
\PYG{k+kn}{from} \PYG{n+nn}{cubmods}\PYG{n+nn}{.}\PYG{n+nn}{multicub} \PYG{k+kn}{import} \PYG{n}{multi}

\PYG{c+c1}{\PYGZsh{} draw random samples}
\PYG{n}{df} \PYG{o}{=} \PYG{n}{pd}\PYG{o}{.}\PYG{n}{DataFrame}\PYG{p}{(}\PYG{p}{)}
\PYG{k}{for} \PYG{n}{i}\PYG{p}{,} \PYG{p}{(}\PYG{n}{pi}\PYG{p}{,} \PYG{n}{xi}\PYG{p}{,} \PYG{n}{phi}\PYG{p}{)} \PYG{o+ow}{in} \PYG{n+nb}{enumerate}\PYG{p}{(}
    \PYG{n+nb}{zip}\PYG{p}{(}\PYG{p}{[}\PYG{l+m+mf}{.9}\PYG{p}{,} \PYG{l+m+mf}{.8}\PYG{p}{,} \PYG{l+m+mf}{.7}\PYG{p}{]}\PYG{p}{,} \PYG{p}{[}\PYG{l+m+mf}{.3}\PYG{p}{,} \PYG{l+m+mf}{.5}\PYG{p}{,} \PYG{l+m+mf}{.7}\PYG{p}{]}\PYG{p}{,} \PYG{p}{[}\PYG{l+m+mf}{.05}\PYG{p}{,} \PYG{l+m+mf}{.1}\PYG{p}{,} \PYG{l+m+mf}{.15}\PYG{p}{]}\PYG{p}{)}
    \PYG{p}{)}\PYG{p}{:}
    \PYG{n}{drawn} \PYG{o}{=} \PYG{n}{draw}\PYG{p}{(}
        \PYG{n}{formula}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord \PYGZti{} 0 | 0 | 0}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,}
        \PYG{n}{m} \PYG{o}{=} \PYG{l+m+mi}{9}\PYG{p}{,} \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cube}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{n}\PYG{o}{=}\PYG{l+m+mi}{1000}\PYG{p}{,}
        \PYG{n}{pi}\PYG{o}{=}\PYG{n}{pi}\PYG{p}{,} \PYG{n}{xi}\PYG{o}{=}\PYG{n}{xi}\PYG{p}{,} \PYG{n}{phi}\PYG{o}{=}\PYG{n}{phi}\PYG{p}{,}
        \PYG{n}{seed}\PYG{o}{=}\PYG{l+m+mi}{1976}
    \PYG{p}{)}
    \PYG{c+c1}{\PYGZsh{} add a shelter category at c=1}
    \PYG{n}{df}\PYG{p}{[}\PYG{l+s+sa}{f}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ord}\PYG{l+s+si}{\PYGZob{}}\PYG{n}{i}\PYG{o}{+}\PYG{l+m+mi}{1}\PYG{l+s+si}{\PYGZcb{}}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{]} \PYG{o}{=} \PYG{n}{np}\PYG{o}{.}\PYG{n}{concatenate}\PYG{p}{(}\PYG{p}{(}
        \PYG{n}{drawn}\PYG{o}{.}\PYG{n}{rv}\PYG{p}{,} \PYG{n}{np}\PYG{o}{.}\PYG{n}{repeat}\PYG{p}{(}\PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{25}\PYG{p}{)}
    \PYG{p}{)}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} MULTI\PYGZhy{}CUB}
\PYG{n}{multi}\PYG{p}{(}
    \PYG{n}{ords}\PYG{o}{=}\PYG{n}{df}\PYG{p}{,} \PYG{n}{ms}\PYG{o}{=}\PYG{l+m+mi}{9}\PYG{p}{,} \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cub}\PYG{l+s+s2}{\PYGZdq{}}
\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} MULTI\PYGZhy{}CUBE}
\PYG{n}{multi}\PYG{p}{(}
    \PYG{n}{ords}\PYG{o}{=}\PYG{n}{df}\PYG{p}{,} \PYG{n}{ms}\PYG{o}{=}\PYG{l+m+mi}{9}\PYG{p}{,} \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cube}\PYG{l+s+s2}{\PYGZdq{}}
\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\PYG{c+c1}{\PYGZsh{} MULTI\PYGZhy{}CUBSH}
\PYG{n}{multi}\PYG{p}{(}
    \PYG{n}{ords}\PYG{o}{=}\PYG{n}{df}\PYG{p}{,} \PYG{n}{ms}\PYG{o}{=}\PYG{l+m+mi}{9}\PYG{p}{,} \PYG{n}{model}\PYG{o}{=}\PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cub}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{n}{shs}\PYG{o}{=}\PYG{l+m+mi}{1}\PYG{p}{,}
    \PYG{n}{pos}\PYG{o}{=}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{6}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{]}
\PYG{p}{)}
\PYG{n}{plt}\PYG{o}{.}\PYG{n}{show}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics{{multicub}.png}

\noindent\sphinxincludegraphics{{multicube}.png}

\noindent\sphinxincludegraphics{{multicubsh}.png}

\sphinxstepscope


\chapter{cubmods}
\label{\detokenize{modules:cubmods}}\label{\detokenize{modules::doc}}
\sphinxstepscope


\section{cubmods package}
\label{\detokenize{cubmods:cubmods-package}}\label{\detokenize{cubmods::doc}}

\subsection{Submodules}
\label{\detokenize{cubmods:submodules}}

\subsection{cubmods.cub module}
\label{\detokenize{cubmods:module-cubmods.cub}}\label{\detokenize{cubmods:cubmods-cub-module}}\index{module@\spxentry{module}!cubmods.cub@\spxentry{cubmods.cub}}\index{cubmods.cub@\spxentry{cubmods.cub}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cub00-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUB (Combination of Uniform
and Binomial).


\subsubsection{Description}
\label{\detokenize{cubmods:description}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUB model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:manual-examples-and-references}}\begin{itemize}
\item {} 
\sphinxAtStartPar
See the \sphinxhref{manual.html\#cub-without-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:list-of-todos}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:credits}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:classes-and-functions}}\index{CUBresCUB00 (class in cubmods.cub)@\spxentry{CUBresCUB00}\spxextra{class in cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.CUBresCUB00}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{CUBresCUB00}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cub.CUBresCUB00.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}ci, saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cub.CUBresCUB00.plot_confell}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_confell}}}}}({[}figsize, ci, equal, ...{]})
&
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and the asymptotic confidence ellipse.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cub.CUBresCUB00.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, kind, ax, saveas{]})
&
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cub.CUBresCUB00 method)@\spxentry{plot()}\spxextra{cubmods.cub.CUBresCUB00 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.CUBresCUB00.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 15)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the confidence ellipse

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_confell() (cubmods.cub.CUBresCUB00 method)@\spxentry{plot\_confell()}\spxextra{cubmods.cub.CUBresCUB00 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.CUBresCUB00.plot_confell}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_confell}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{equal}\DUrole{o}{=}\DUrole{default_value}{True}}\sphinxparamcomma \sphinxparam{\DUrole{n}{magnified}\DUrole{o}{=}\DUrole{default_value}{False}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and
the asymptotic confidence ellipse.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the confidence ellipse

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{equal}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if the plot must have equal aspect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{magnified}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if False the limits will be the entire parameter space, otherwise let matplotlib choose the limits

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cub.CUBresCUB00 method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cub.CUBresCUB00 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.CUBresCUB00.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and,
if provided, probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{cmf() (in module cubmods.cub)@\spxentry{cmf()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.cmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{cmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Cumulative probability of a specified CUB model.

\sphinxAtStartPar
\(\Pr(R \leq r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an array of the CMF for the specified model

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{draw() (in module cubmods.cub)@\spxentry{draw()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUB model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses to be drawn

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{gini() (in module cubmods.cub)@\spxentry{gini()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.gini}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{gini}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
The Gini index of a specified CUB model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the Gini index of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{init\_theta() (in module cubmods.cub)@\spxentry{init\_theta()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.init_theta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{init\_theta}}}{\sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Preliminary estimators for CUB models without covariates.

\sphinxAtStartPar
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\sphinxhyphen{}M algorithm.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of the absolute frequencies of given ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\end{itemize}

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

\end{description}\end{quote}

\end{fulllineitems}

\index{laakso() (in module cubmods.cub)@\spxentry{laakso()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.laakso}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{laakso}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
The Laakso index of a specified CUB model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the Laakso index of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cub)@\spxentry{loglik()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function of a CUB model without 
covariates for a given absolute frequency distribution.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of absolute frequency distribution

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mean() (in module cubmods.cub)@\spxentry{mean()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.mean}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{mean}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Expected value of a specified CUB model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the expected value of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{median() (in module cubmods.cub)@\spxentry{median()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.median}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{median}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
The median of a specified CUB model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the median of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cub)@\spxentry{mle()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{500}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{0.0001}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUB models without covariates.

\sphinxAtStartPar
Function to estimate and validate a CUB model without covariates for given ordinal responses.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} maximum number of iterations allowed for running the optimization algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} fixed error tolerance for final estimates

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUB00}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cub)@\spxentry{pmf()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a specified CUB model.

\sphinxAtStartPar
\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the vector of the probability distribution of a CUB model.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{prob() (in module cubmods.cub)@\spxentry{prob()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.prob}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{prob}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{r}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability \(\Pr(R = r | \pmb\theta)\) of a specified CUB model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{r}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} ordinal value (must be \(1 \leq r \leq m\))

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability \(\Pr(R = r | \pmb\theta)\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{skew() (in module cubmods.cub)@\spxentry{skew()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.skew}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{skew}}}{\sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Skewness normalized \(\eta\) index
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the skewness of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{std() (in module cubmods.cub)@\spxentry{std()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.std}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{std}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Standard deviation of a specified CUB model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the standard deviation of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{var() (in module cubmods.cub)@\spxentry{var()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.var}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{var}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance of a specified CUB model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{varcov() (in module cubmods.cub)@\spxentry{varcov()}\spxextra{in module cubmods.cub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub.varcov}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub.}}\sphinxbfcode{\sphinxupquote{varcov}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ordinal}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Compute the variance\sphinxhyphen{}covariance matrix of parameter 
estimates of a CUB model without covariates.
\begin{quote}\begin{description}
\sphinxlineitem{References}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ordinal}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance\sphinxhyphen{}covariance matrix of the CUB model

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cub\_0w module}
\label{\detokenize{cubmods:module-cubmods.cub_0w}}\label{\detokenize{cubmods:cubmods-cub-0w-module}}\index{module@\spxentry{module}!cubmods.cub\_0w@\spxentry{cubmods.cub\_0w}}\index{cubmods.cub\_0w@\spxentry{cubmods.cub\_0w}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cub0w-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUB (Combination of Uniform
and Binomial) with covariates for the feeling component.


\subsubsection{Description:}
\label{\detokenize{cubmods:id1}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUB\_0W model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id2}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cub-with-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id3}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id4}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id5}}\index{CUBresCUB0W (class in cubmods.cub\_0w)@\spxentry{CUBresCUB0W}\spxextra{class in cubmods.cub\_0w}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.CUBresCUB0W}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cub\_0w.}}\sphinxbfcode{\sphinxupquote{CUBresCUB0W}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cub_0w.CUBresCUB0W.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cub_0w.CUBresCUB0W.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cub\_0w.CUBresCUB0W method)@\spxentry{plot()}\spxextra{cubmods.cub\_0w.CUBresCUB0W method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.CUBresCUB0W.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cub\_0w.CUBresCUB0W method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cub\_0w.CUBresCUB0W method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.CUBresCUB0W.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and,
if provided, average probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{draw() (in module cubmods.cub\_0w)@\spxentry{draw()}\spxextra{in module cubmods.cub\_0w}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_0w.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUB model with covariates for
the feeling component.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses to be drawn

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None;
it must be \(\neq 0\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{effe01() (in module cubmods.cub\_0w)@\spxentry{effe01()}\spxextra{in module cubmods.cub\_0w}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.effe01}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_0w.}}\sphinxbfcode{\sphinxupquote{effe01}}}{\sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{esterno01}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of CUB models
with covariates for the feeling component.

\sphinxAtStartPar
Compute the opposite of the scalar function that is maximized when running 
the E\sphinxhyphen{}M algorithm for CUB models with covariates for the feeling parameter.

\sphinxAtStartPar
It is called as an argument for \sphinxcode{\sphinxupquote{minimize}} within CUB function for models with covariates for
feeling or for both feeling and uncertainty.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{esterno01}} \textendash{} 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

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the expected value of the inconplete log\sphinxhyphen{}likelihood

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{init\_gamma() (in module cubmods.cub\_0w)@\spxentry{init\_gamma()}\spxextra{in module cubmods.cub\_0w}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.init_gamma}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_0w.}}\sphinxbfcode{\sphinxupquote{init\_gamma}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Preliminary parameter estimates of a CUB model with covariates for the feeling component.

\sphinxAtStartPar
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\sphinxhyphen{}M algorithm.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an array \(\pmb\gamma^{(0)}\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
array of float

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cub\_0w)@\spxentry{loglik()}\spxextra{in module cubmods.cub\_0w}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_0w.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function of a CUB model with covariates for the feeling component

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function of a CUB model fitting ordinal data, with
covariates for explaining the feeling component.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cub\_0w)@\spxentry{mle()}\spxextra{in module cubmods.cub\_0w}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_0w.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{500}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{0.0001}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUB models with covariates for the feeling component.

\sphinxAtStartPar
Function to estimate and validate a CUB model for given ordinal responses, with covariates for
explaining the feeling component.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} maximum number of iterations allowed for running the optimization algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} fixed error tolerance for final estimates

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUB0W}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cub\_0w)@\spxentry{pmf()}\spxextra{in module cubmods.cub\_0w}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_0w.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Average probability distribution of a specified CUB model 
with covariates for the feeling component.

\sphinxAtStartPar
\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the vector of the probability distribution.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmfi() (in module cubmods.cub\_0w)@\spxentry{pmfi()}\spxextra{in module cubmods.cub\_0w}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.pmfi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_0w.}}\sphinxbfcode{\sphinxupquote{pmfi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution for each subject of a specified CUB model 
with covariates for the feeling component.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.draw()}}.

\sphinxAtStartPar
\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the matrix of the probability distribution of dimension \(n \times r\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{prob() (in module cubmods.cub\_0w)@\spxentry{prob()}\spxextra{in module cubmods.cub\_0w}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.prob}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_0w.}}\sphinxbfcode{\sphinxupquote{prob}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a CUB model with covariates for the feeling component
given an observed sample

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

\sphinxAtStartPar
\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the array of the probability distribution.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{varcov() (in module cubmods.cub\_0w)@\spxentry{varcov()}\spxextra{in module cubmods.cub\_0w}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_0w.varcov}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_0w.}}\sphinxbfcode{\sphinxupquote{varcov}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance\sphinxhyphen{}covariance matrix of CUB models with covariates for the feeling component

\sphinxAtStartPar
Compute the variance\sphinxhyphen{}covariance matrix of parameter estimates of a CUB model
with covariates for the feeling component.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance\sphinxhyphen{}covariance matrix of the CUB model

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cub\_y0 module}
\label{\detokenize{cubmods:module-cubmods.cub_y0}}\label{\detokenize{cubmods:cubmods-cub-y0-module}}\index{module@\spxentry{module}!cubmods.cub\_y0@\spxentry{cubmods.cub\_y0}}\index{cubmods.cub\_y0@\spxentry{cubmods.cub\_y0}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cuby0-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUB (Combination of Uniform
and Binomial) with covariates for the uncertainty component.


\subsubsection{Description:}
\label{\detokenize{cubmods:id6}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUB\_Y0 model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id7}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cub-with-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id8}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id9}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id10}}\index{CUBresCUBY0 (class in cubmods.cub\_y0)@\spxentry{CUBresCUBY0}\spxextra{class in cubmods.cub\_y0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.CUBresCUBY0}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cub\_y0.}}\sphinxbfcode{\sphinxupquote{CUBresCUBY0}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cub_y0.CUBresCUBY0.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cub_y0.CUBresCUBY0.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cub\_y0.CUBresCUBY0 method)@\spxentry{plot()}\spxextra{cubmods.cub\_y0.CUBresCUBY0 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.CUBresCUBY0.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cub\_y0.CUBresCUBY0 method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cub\_y0.CUBresCUBY0 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.CUBresCUBY0.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and,
if provided, average probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{draw() (in module cubmods.cub\_y0)@\spxentry{draw()}\spxextra{in module cubmods.cub\_y0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_y0.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUB model with covariates for
the uncertainty component.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses to be drawn

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None;
it must be \(\neq 0\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{effe10() (in module cubmods.cub\_y0)@\spxentry{effe10()}\spxextra{in module cubmods.cub\_y0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.effe10}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_y0.}}\sphinxbfcode{\sphinxupquote{effe10}}}{\sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{esterno10}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of CUB models.

\sphinxAtStartPar
Compute the opposite of the scalar function that is maximized when running
the E\sphinxhyphen{}M algorithm for CUB models with covariates for the uncertainty parameter.
\begin{description}
\sphinxlineitem{It is called as an argument for optim within CUB function for models with covariates for}
\sphinxAtStartPar
uncertainty or for both feeling and uncertainty.

\end{description}
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{esterno10}} \textendash{} 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

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the expected value of the inconplete log\sphinxhyphen{}likelihood

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cub\_y0)@\spxentry{loglik()}\spxextra{in module cubmods.cub\_y0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_y0.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function of a CUB model with covariates for the uncertainty component

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function of a CUB model fitting ordinal responses with covariates 
for explaining the uncertainty component.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cub\_y0)@\spxentry{mle()}\spxextra{in module cubmods.cub\_y0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_y0.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{500}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{0.0001}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUB models with covariates for the uncertainty component.

\sphinxAtStartPar
Estimate and validate a CUB model for given ordinal responses, with covariates for explaining 
the uncertainty component.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} maximum number of iterations allowed for running the optimization algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} fixed error tolerance for final estimates

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUBY0}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cub\_y0)@\spxentry{pmf()}\spxextra{in module cubmods.cub\_y0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_y0.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Average probability distribution of a specified CUB model 
with covariates.

\sphinxAtStartPar
\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the vector of the probability distribution.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmfi() (in module cubmods.cub\_y0)@\spxentry{pmfi()}\spxextra{in module cubmods.cub\_y0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.pmfi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_y0.}}\sphinxbfcode{\sphinxupquote{pmfi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution for each subject of a specified CUB model 
with covariates.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.draw()}}.

\sphinxAtStartPar
\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the matrix of the probability distribution of dimension \(n \times r\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{prob() (in module cubmods.cub\_y0)@\spxentry{prob()}\spxextra{in module cubmods.cub\_y0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.prob}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_y0.}}\sphinxbfcode{\sphinxupquote{prob}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a CUB model with covariates for the uncertainty component
given an observed sample

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

\sphinxAtStartPar
\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the array of the probability distribution.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{varcov() (in module cubmods.cub\_y0)@\spxentry{varcov()}\spxextra{in module cubmods.cub\_y0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_y0.varcov}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_y0.}}\sphinxbfcode{\sphinxupquote{varcov}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance\sphinxhyphen{}covariance matrix of CUB model with covariates for the uncertainty parameter.

\sphinxAtStartPar
Compute the variance\sphinxhyphen{}covariance matrix of parameter estimates of a CUB model with 
covariates for the uncertainty component.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance\sphinxhyphen{}covariance matrix of the CUB model

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cub\_yw module}
\label{\detokenize{cubmods:module-cubmods.cub_yw}}\label{\detokenize{cubmods:cubmods-cub-yw-module}}\index{module@\spxentry{module}!cubmods.cub\_yw@\spxentry{cubmods.cub\_yw}}\index{cubmods.cub\_yw@\spxentry{cubmods.cub\_yw}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cubyw-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUB (Combination of Uniform
and Binomial) with covariates
for both feeling and uncertainty.


\subsubsection{Description:}
\label{\detokenize{cubmods:id11}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUB\_YW model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id12}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cub-with-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id13}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id14}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id15}}\index{CUBresCUBYW (class in cubmods.cub\_yw)@\spxentry{CUBresCUBYW}\spxextra{class in cubmods.cub\_yw}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_yw.CUBresCUBYW}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cub\_yw.}}\sphinxbfcode{\sphinxupquote{CUBresCUBYW}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
“Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cub_yw.CUBresCUBYW.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cub_yw.CUBresCUBYW.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cub\_yw.CUBresCUBYW method)@\spxentry{plot()}\spxextra{cubmods.cub\_yw.CUBresCUBYW method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_yw.CUBresCUBYW.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cub\_yw.CUBresCUBYW method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cub\_yw.CUBresCUBYW method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_yw.CUBresCUBYW.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and,
if provided, average probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{draw() (in module cubmods.cub\_yw)@\spxentry{draw()}\spxextra{in module cubmods.cub\_yw}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_yw.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_yw.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUB model with covariates for
both feeling and uncertainty.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses to be drawn

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cub\_yw)@\spxentry{loglik()}\spxextra{in module cubmods.cub\_yw}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_yw.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_yw.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function of a CUB model with covariates for both feeling and uncertainty.

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function of a CUB model fitting ordinal data
with covariates for explaining both the feeling and the uncertainty components.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cub\_yw)@\spxentry{mle()}\spxextra{in module cubmods.cub\_yw}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_yw.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_yw.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{500}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{0.0001}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUB models with covariates for both the uncertainty and the feeling components.

\sphinxAtStartPar
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.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} maximum number of iterations allowed for running the optimization algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} fixed error tolerance for final estimates

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUBYW}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cub\_yw)@\spxentry{pmf()}\spxextra{in module cubmods.cub\_yw}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_yw.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_yw.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Average probability distribution of a specified CUB model 
with covariates for both feeling and uncertainty.

\sphinxAtStartPar
\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the vector of the probability distribution.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmfi() (in module cubmods.cub\_yw)@\spxentry{pmfi()}\spxextra{in module cubmods.cub\_yw}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_yw.pmfi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_yw.}}\sphinxbfcode{\sphinxupquote{pmfi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution for each subject of a specified CUB model 
with covariates for both feeling and uncertainty.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.draw()}}.

\sphinxAtStartPar
\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the matrix of the probability distribution of dimension \(n \times r\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{prob() (in module cubmods.cub\_yw)@\spxentry{prob()}\spxextra{in module cubmods.cub\_yw}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_yw.prob}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_yw.}}\sphinxbfcode{\sphinxupquote{prob}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a CUB model with covariates for both feeling and uncertainty.

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

\sphinxAtStartPar
\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the array of the probability distribution.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{varcov() (in module cubmods.cub\_yw)@\spxentry{varcov()}\spxextra{in module cubmods.cub\_yw}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cub_yw.varcov}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cub\_yw.}}\sphinxbfcode{\sphinxupquote{varcov}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance\sphinxhyphen{}covariance matrix of a CUB model with covariates for both uncertainty and feeling.

\sphinxAtStartPar
Compute the variance\sphinxhyphen{}covariance matrix of parameter estimates of a CUB model with covariates for
both the uncertainty and the feeling components.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance\sphinxhyphen{}covariance matrix of the CUB model

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cube module}
\label{\detokenize{cubmods:module-cubmods.cube}}\label{\detokenize{cubmods:cubmods-cube-module}}\index{module@\spxentry{module}!cubmods.cube@\spxentry{cubmods.cube}}\index{cubmods.cube@\spxentry{cubmods.cube}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cube000-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUBE (Combination of Uniform
and Beta\sphinxhyphen{}Binomial).


\subsubsection{Description:}
\label{\detokenize{cubmods:id16}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUBE model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id17}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cube-without-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id18}}\begin{itemize}
\item {} 
\sphinxAtStartPar
TODO: adjust 3d plots legend

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id19}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id20}}\index{CUBresCUBE (class in cubmods.cube)@\spxentry{CUBresCUBE}\spxextra{class in cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.CUBresCUBE}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{CUBresCUBE}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cube.CUBresCUBE.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}ci, saveas, confell, test3, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cube.CUBresCUBE.plot3d}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot3d}}}}}(ax{[}, ci, magnified{]})
&
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and the asymptotic confidence ellipsoid with its projections.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cube.CUBresCUBE.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cube.CUBresCUBE method)@\spxentry{plot()}\spxextra{cubmods.cube.CUBresCUBE method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.CUBresCUBE.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{confell}\DUrole{o}{=}\DUrole{default_value}{False}}\sphinxparamcomma \sphinxparam{\DUrole{n}{test3}\DUrole{o}{=}\DUrole{default_value}{True}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 15)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the confidence ellipsoid

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{confell}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} \sphinxstylestrong{DEPRECATED}, defaults to False

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{test3}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} \sphinxstylestrong{DEPRECATED}, defaults to True

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot3d() (cubmods.cube.CUBresCUBE method)@\spxentry{plot3d()}\spxextra{cubmods.cube.CUBresCUBE method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.CUBresCUBE.plot3d}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot3d}}}{\sphinxparam{\DUrole{n}{ax}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{magnified}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and
the asymptotic confidence ellipsoid with its projections.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the confidence ellipsoid

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{magnified}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if False the limits will be the entire parameter space, otherwise let matplotlib choose the limits

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cube.CUBresCUBE method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cube.CUBresCUBE method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.CUBresCUBE.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and,
if provided, probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{betar() (in module cubmods.cube)@\spxentry{betar()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.betar}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{betar}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Beta\sphinxhyphen{}Binomial distribution.

\sphinxAtStartPar
Return the Beta\sphinxhyphen{}Binomial distribution with given parameters.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
array of length \(m\) of the Beta\sphinxhyphen{}Binomial distribution.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{cmf() (in module cubmods.cube)@\spxentry{cmf()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.cmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{cmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Cumulative probability of a specified CUBE model.

\sphinxAtStartPar
\(\Pr(R \leq r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
array of length \(m\) of the cumulative probability of a CUBE model without covariates.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{draw() (in module cubmods.cube)@\spxentry{draw()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUBE model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses to be drawn

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{effecube() (in module cubmods.cube)@\spxentry{effecube()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.effecube}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{effecube}}}{\sphinxparam{\DUrole{n}{params}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tau}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of CUBE models without covariates.

\sphinxAtStartPar
Define the opposite of the scalar function that is maximized when running the E\sphinxhyphen{}M 
algorithm for CUBE models without covariates.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{params}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array of initial estimates for the feeling and the overdispersion parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tau}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} 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

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of the absolute frequencies of the observations

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the expected value of the inconplete log\sphinxhyphen{}likelihood

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{init\_theta() (in module cubmods.cube)@\spxentry{init\_theta()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.init_theta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{init\_theta}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Naive estimates for CUBE models without covariates.

\sphinxAtStartPar
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\sphinxhyphen{}M algorithm.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\end{itemize}

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

\sphinxlineitem{Return type}
\sphinxAtStartPar
tuple of float

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cube)@\spxentry{loglik()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function of a CUBE model without covariates.

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function of a CUBE model without covariates fitting 
the given absolute frequency distribution.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of absolute frequency distribution

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mean() (in module cubmods.cube)@\spxentry{mean()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.mean}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{mean}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Mean of a CUBE model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the expected value of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cube)@\spxentry{mle()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{1000}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{1e\sphinxhyphen{}06}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUBE models without covariates.

\sphinxAtStartPar
Estimate and validate a CUBE model without covariates.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} maximum number of iterations allowed for running the optimization algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} fixed error tolerance for final estimates

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUBE}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cube)@\spxentry{pmf()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a specified CUBE model.

\sphinxAtStartPar
\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
array of length \(m\) of the distribution of a CUBE model without covariates.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{prob() (in module cubmods.cube)@\spxentry{prob()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.prob}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{prob}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{r}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability \(\Pr(R = r | \pmb\theta)\) of a CUBE model without covariates.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{r}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} ordinal response

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability \(\Pr(R = r | \pmb\theta)\) of a CUBE model without covariates.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{var() (in module cubmods.cube)@\spxentry{var()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.var}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{var}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance of a CUBE model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{varcov() (in module cubmods.cube)@\spxentry{varcov()}\spxextra{in module cubmods.cube}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube.varcov}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube.}}\sphinxbfcode{\sphinxupquote{varcov}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance\sphinxhyphen{}covariance matrix for CUBE models based on the observed information matrix.

\sphinxAtStartPar
Compute the variance\sphinxhyphen{}covariance matrix of parameter estimates for a CUBE model without covariates 
as the inverse of the observed information matrix.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance\sphinxhyphen{}covariance matrix of the CUBE model

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cube\_0w0 module}
\label{\detokenize{cubmods:module-cubmods.cube_0w0}}\label{\detokenize{cubmods:cubmods-cube-0w0-module}}\index{module@\spxentry{module}!cubmods.cube\_0w0@\spxentry{cubmods.cube\_0w0}}\index{cubmods.cube\_0w0@\spxentry{cubmods.cube\_0w0}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cube0w0-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUBE (Combination of Uniform
and Beta\sphinxhyphen{}Binomial) with covariates for the feeling component.


\subsubsection{Description:}
\label{\detokenize{cubmods:id21}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUBE\_0W0 model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id22}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cube-with-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id23}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id24}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id25}}\index{CUBresCUBE0W0 (class in cubmods.cube\_0w0)@\spxentry{CUBresCUBE0W0}\spxextra{class in cubmods.cube\_0w0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.CUBresCUBE0W0}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cube\_0w0.}}\sphinxbfcode{\sphinxupquote{CUBresCUBE0W0}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cube_0w0.CUBresCUBE0W0.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cube_0w0.CUBresCUBE0W0.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cube\_0w0.CUBresCUBE0W0 method)@\spxentry{plot()}\spxextra{cubmods.cube\_0w0.CUBresCUBE0W0 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.CUBresCUBE0W0.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cube\_0w0.CUBresCUBE0W0 method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cube\_0w0.CUBresCUBE0W0 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.CUBresCUBE0W0.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and,
if provided, average probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{betabinomialxi() (in module cubmods.cube\_0w0)@\spxentry{betabinomialxi()}\spxextra{in module cubmods.cube\_0w0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.betabinomialxi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_0w0.}}\sphinxbfcode{\sphinxupquote{betabinomialxi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xivett}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Beta\sphinxhyphen{}Binomial probabilities of ordinal responses, given feeling parameter for each observation.

\sphinxAtStartPar
Compute the Beta\sphinxhyphen{}Binomial probabilities of given ordinal responses, with feeling 
parameter specified for each observation, 
and with the same overdispersion parameter for all the responses.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of ordinal responses. Missing values are not allowed: they should be preliminarily deleted

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xivett}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of feeling parameters of the Beta\sphinxhyphen{}Binomial distribution for given ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
array of the same length as ordinal: each entry is the Beta\sphinxhyphen{}Binomial probability for the given observation 
for the corresponding feeling and overdispersion parameters.

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{draw() (in module cubmods.cube\_0w0)@\spxentry{draw()}\spxextra{in module cubmods.cube\_0w0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_0w0.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUBE model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses to be drawn

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{effe() (in module cubmods.cube\_0w0)@\spxentry{effe()}\spxextra{in module cubmods.cube\_0w0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.effe}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_0w0.}}\sphinxbfcode{\sphinxupquote{effe}}}{\sphinxparam{\DUrole{n}{pars}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of CUBE models with covariates 
only for the feeling component.

\sphinxAtStartPar
Compute the opposite of the scalar function that is maximized when running the 
E\sphinxhyphen{}M algorithm for CUBE models with covariates only for the feeling component.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of length equal to \sphinxcode{\sphinxupquote{W.index.size+3}} whose entries are the initial parameters estimates

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
negative log\sphinxhyphen{}likelihood

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{init\_theta() (in module cubmods.cube\_0w0)@\spxentry{init\_theta()}\spxextra{in module cubmods.cube\_0w0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.init_theta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_0w0.}}\sphinxbfcode{\sphinxupquote{init\_theta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Preliminary estimates of parameters for CUBE models with covariates only for feeling.

\sphinxAtStartPar
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\sphinxhyphen{}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.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} maximum number of iterations allowed for preliminary iterations

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} fixed error tolerance for final estimates for preliminary iterations

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
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.

\end{description}\end{quote}

\sphinxAtStartPar
“rtype”: tuple

\end{fulllineitems}

\index{loglik() (in module cubmods.cube\_0w0)@\spxentry{loglik()}\spxextra{in module cubmods.cube\_0w0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_0w0.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function of CUBE model with covariates only for feeling.

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function of a CUBE model for ordinal data with subjects’ 
covariates only for feeling.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cube\_0w0)@\spxentry{mle()}\spxextra{in module cubmods.cube\_0w0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_0w0.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{1000}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{1e\sphinxhyphen{}06}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUBE models with covariates only for feeling

\sphinxAtStartPar
Estimate and validate a CUBE model for ordinal data, with covariates only for explaining the
feeling component.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} maximum number of iterations allowed for preliminary iterations

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} fixed error tolerance for final estimates for preliminary iterations;
the informatio matrix (to compute the variance\sphinxhyphen{}covariance matrix) is approximated with \sphinxcode{\sphinxupquote{approx\_hess()}}
(see \sphinxcode{\sphinxupquote{statsmodels.tools.numdiff}} for details)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUBE0W0}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cube\_0w0)@\spxentry{pmf()}\spxextra{in module cubmods.cube\_0w0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_0w0.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Average probability distribution of a specified CUB model 
with covariates for the feeling component.

\sphinxAtStartPar
\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the array of the average probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmfi() (in module cubmods.cube\_0w0)@\spxentry{pmfi()}\spxextra{in module cubmods.cube\_0w0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.pmfi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_0w0.}}\sphinxbfcode{\sphinxupquote{pmfi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution for each subject of a specified CUBE model 
with covariates for feeling only.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.draw()}}.

\sphinxAtStartPar
\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the matrix of the probability distribution of dimension \(n \times r\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{prob() (in module cubmods.cube\_0w0)@\spxentry{prob()}\spxextra{in module cubmods.cube\_0w0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_0w0.prob}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_0w0.}}\sphinxbfcode{\sphinxupquote{prob}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a CUBE model with covariates for feeling.

\sphinxAtStartPar
Compute the probability distribution of a CUB model with covariates for both the feeling 
and the uncertainty components. Auxiliary function of \sphinxcode{\sphinxupquote{.loglik()}}

\sphinxAtStartPar
\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the array of the probability distribution.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cube\_ywz module}
\label{\detokenize{cubmods:module-cubmods.cube_ywz}}\label{\detokenize{cubmods:cubmods-cube-ywz-module}}\index{module@\spxentry{module}!cubmods.cube\_ywz@\spxentry{cubmods.cube\_ywz}}\index{cubmods.cube\_ywz@\spxentry{cubmods.cube\_ywz}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cubeywz-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUBE (Combination of Uniform
and Beta\sphinxhyphen{}Binomial) with covariates.


\subsubsection{Description:}
\label{\detokenize{cubmods:id26}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUB\_YWZ model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id27}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cube-with-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id28}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id29}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id30}}\index{CUBresCUBEYWZ (class in cubmods.cube\_ywz)@\spxentry{CUBresCUBEYWZ}\spxextra{class in cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.CUBresCUBEYWZ}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{CUBresCUBEYWZ}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cube_ywz.CUBresCUBEYWZ.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cube_ywz.CUBresCUBEYWZ.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cube\_ywz.CUBresCUBEYWZ method)@\spxentry{plot()}\spxextra{cubmods.cube\_ywz.CUBresCUBEYWZ method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.CUBresCUBEYWZ.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cube\_ywz.CUBresCUBEYWZ method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cube\_ywz.CUBresCUBEYWZ method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.CUBresCUBEYWZ.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and,
if provided, average probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{Qdue() (in module cubmods.cube\_ywz)@\spxentry{Qdue()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.Qdue}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{Qdue}}}{\sphinxparam{\DUrole{n}{pars}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tauno}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Z}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of CUBE models with covariates.

\sphinxAtStartPar
Define the opposite of one of the two scalar functions that are maximized when running the E\sphinxhyphen{}M 
algorithm for CUBE models with covariates for feeling, uncertainty and overdispersion.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of initial estimates of parameters for the feeling component and the overdispersion effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tauno}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} the column vector of the posterior probabilities that each observed rating
has been generated by the distribution of the first component of the mixture

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Z}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the overdispersion

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{Quno() (in module cubmods.cube\_ywz)@\spxentry{Quno()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.Quno}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{Quno}}}{\sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{esterno1}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of CUBE models with covariates.

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

\sphinxAtStartPar
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.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{esterno1}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}) \textendash{} 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

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{auxmat() (in module cubmods.cube\_ywz)@\spxentry{auxmat()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.auxmat}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{auxmat}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{a}}\sphinxparamcomma \sphinxparam{\DUrole{n}{b}}\sphinxparamcomma \sphinxparam{\DUrole{n}{c}}\sphinxparamcomma \sphinxparam{\DUrole{n}{d}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary matrix.

\sphinxAtStartPar
Returns an auxiliary matrix needed for computing the variance\sphinxhyphen{}covariance matrix of a CUBE model with covariates.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameters \(\pmb\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\pmb\phi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{a}}\sphinxstyleliteralstrong{\sphinxupquote{,}}\sphinxstyleliteralstrong{\sphinxupquote{b}}\sphinxstyleliteralstrong{\sphinxupquote{,}}\sphinxstyleliteralstrong{\sphinxupquote{c}}\sphinxstyleliteralstrong{\sphinxupquote{,}}\sphinxstyleliteralstrong{\sphinxupquote{d}}\sphinxstyleliteralstrong{\sphinxupquote{,}}\sphinxstyleliteralstrong{\sphinxupquote{e}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} see the reference paper \hyperlink{cite.references:id15}{Piccolo, 2015} for details

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{betabinomial() (in module cubmods.cube\_ywz)@\spxentry{betabinomial()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.betabinomial}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{betabinomial}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{phi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Beta\sphinxhyphen{}Binomial probabilities of ordinal responses, with feeling and overdispersion parameters
for each observation.

\sphinxAtStartPar
Compute the Beta\sphinxhyphen{}Binomial probabilities of ordinal responses, given feeling and overdispersion
parameters for each observation.

\sphinxAtStartPar
The Beta\sphinxhyphen{}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.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{phi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} overdispersion parameter \(\phi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
array of the same length as \sphinxcode{\sphinxupquote{sample}}, containing the Beta\sphinxhyphen{}Binomial probabilities of each observation,
for the corresponding feeling and overdispersion parameters.

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{draw() (in module cubmods.cube\_ywz)@\spxentry{draw()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{alpha}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Z}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUBE model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses to be drawn

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{alpha}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \alpha\) of parameters for the overdispersion, whose length equals 
\sphinxcode{\sphinxupquote{Z.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Z}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the overdispersion

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{init\_theta() (in module cubmods.cube\_ywz)@\spxentry{init\_theta()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.init_theta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{init\_theta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{p}}\sphinxparamcomma \sphinxparam{\DUrole{n}{v}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Preliminary parameter estimates for CUBE models with covariates.

\sphinxAtStartPar
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\sphinxhyphen{}M algorithm within maximum likelihood estimation.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{p}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of covariates for the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{v}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of covariates for the overdispersion

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
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\})\textasciigrave{} respectively, of a CUBE model with covariates for all the three
parameters. In details, they have length equal to \sphinxcode{\sphinxupquote{Y.columns.size+1}}, \sphinxcode{\sphinxupquote{W.columns.size+1}} and
\sphinxcode{\sphinxupquote{Z.columns.size+1}}, respectively, to account for an intercept term for each component.

\sphinxlineitem{Return type}
\sphinxAtStartPar
tuple of arrays

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cube\_ywz)@\spxentry{loglik()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Z}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{alpha}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function of a CUBE model with covariates.

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function of a CUBE model for ordinal responses,
with covariates for explaining all the three parameters.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Z}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the overdispersion

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{alpha}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \alpha\) of parameters for the overdispersion, whose length equals 
\sphinxcode{\sphinxupquote{Z.columns.size+1}} to include an intercept term in the model (first entry)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cube\_ywz)@\spxentry{mle()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Z}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{1000}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{0.01}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUBE models with covariates.

\sphinxAtStartPar
Function to estimate and validate a CUBE model with 
explicative covariates for all the three parameters.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Z}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the overdispersion

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} maximum number of iterations allowed for running the optimization algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} fixed error tolerance for final estimates

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUBEYWZ}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cube\_ywz)@\spxentry{pmf()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{alpha}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Z}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Average probability distribution of a specified CUB model 
with covariates for the feeling component.

\sphinxAtStartPar
\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{alpha}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \alpha\) of parameters for the overdispersion, whose length equals 
\sphinxcode{\sphinxupquote{Z.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Z}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the overdispersion

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the array of the average probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmfi() (in module cubmods.cube\_ywz)@\spxentry{pmfi()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.pmfi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{pmfi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{alpha}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Z}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution for each subject of a specified CUBE model 
with covariates.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.draw()}}.

\sphinxAtStartPar
\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{alpha}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \alpha\) of parameters for the overdispersion, whose length equals 
\sphinxcode{\sphinxupquote{Z.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Z}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the overdispersion

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the matrix of the probability distribution of dimension \(n \times r\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{varcov() (in module cubmods.cube\_ywz)@\spxentry{varcov()}\spxextra{in module cubmods.cube\_ywz}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cube_ywz.varcov}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cube\_ywz.}}\sphinxbfcode{\sphinxupquote{varcov}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{alpha}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Z}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance\sphinxhyphen{}covariance matrix of a CUBE model with covariates.

\sphinxAtStartPar
Compute the variance\sphinxhyphen{}covariance matrix of parameter estimates of a CUBE model with covariates
for all the three parameters.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Z}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the overdispersion

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{alpha}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \alpha\) of parameters for the overdispersion, whose length equals 
\sphinxcode{\sphinxupquote{Z.columns.size+1}} to include an intercept term in the model (first entry)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance\sphinxhyphen{}covariance matrix

\sphinxlineitem{Return type}
\sphinxAtStartPar
ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cubsh module}
\label{\detokenize{cubmods:module-cubmods.cubsh}}\label{\detokenize{cubmods:cubmods-cubsh-module}}\index{module@\spxentry{module}!cubmods.cubsh@\spxentry{cubmods.cubsh}}\index{cubmods.cubsh@\spxentry{cubmods.cubsh}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cubsh000-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUBSH (Combination of Uniform
and Binomial with Shelter Effect).


\subsubsection{Description:}
\label{\detokenize{cubmods:id32}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUBSH model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id33}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cubsh-without-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id34}}\begin{itemize}
\item {} 
\sphinxAtStartPar
TODO: fix 3d plots legend

\item {} 
\sphinxAtStartPar
TODO: test all \sphinxcode{\sphinxupquote{def \_*():}} (optional functions)

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id35}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id36}}\index{CUBresCUBSH (class in cubmods.cubsh)@\spxentry{CUBresCUBSH}\spxextra{class in cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.CUBresCUBSH}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{CUBresCUBSH}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cubsh.CUBresCUBSH.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}ci, saveas, confell, debug, test3, ...{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cubsh.CUBresCUBSH.plot3d}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot3d}}}}}(ax{[}, ci, magnified{]})
&
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and the asymptotic confidence ellipsoid with its projections.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cubsh.CUBresCUBSH.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cubsh.CUBresCUBSH method)@\spxentry{plot()}\spxextra{cubmods.cubsh.CUBresCUBSH method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.CUBresCUBSH.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{confell}\DUrole{o}{=}\DUrole{default_value}{False}}\sphinxparamcomma \sphinxparam{\DUrole{n}{debug}\DUrole{o}{=}\DUrole{default_value}{False}}\sphinxparamcomma \sphinxparam{\DUrole{n}{test3}\DUrole{o}{=}\DUrole{default_value}{True}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 15)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the confidence ellipsoid

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{confell}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} \sphinxstylestrong{DEPRECATED}, defaults to False

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{test3}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} \sphinxstylestrong{DEPRECATED}, defaults to True

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{debug}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} \sphinxstylestrong{DEPRECATED}, defaults to False

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot3d() (cubmods.cubsh.CUBresCUBSH method)@\spxentry{plot3d()}\spxextra{cubmods.cubsh.CUBresCUBSH method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.CUBresCUBSH.plot3d}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot3d}}}{\sphinxparam{\DUrole{n}{ax}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{magnified}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and
the asymptotic confidence ellipsoid with its projections.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the confidence ellipsoid

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{magnified}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if False the limits will be the entire parameter space, otherwise let matplotlib choose the limits

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cubsh.CUBresCUBSH method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cubsh.CUBresCUBSH method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.CUBresCUBSH.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and,
if provided, probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{cmf() (in module cubmods.cubsh)@\spxentry{cmf()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.cmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{cmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Cumulative probability of a specified CUBSH model,
using alternative parametrization \((\pi_1, \pi_2)\).

\sphinxAtStartPar
\(\Pr(R \leq r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the cumulative probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{cmf\_delta() (in module cubmods.cubsh)@\spxentry{cmf\_delta()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.cmf_delta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{cmf\_delta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Cumulative probability of a specified CUBSH model,
using canonic parametrization \((\pi, \delta)\).

\sphinxAtStartPar
\(\Pr(R \leq r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the cumulative probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{draw() (in module cubmods.cubsh)@\spxentry{draw()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUBSH model,
using canonic parametrization \((\pi, \delta)\).
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{draw2() (in module cubmods.cubsh)@\spxentry{draw2()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.draw2}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{draw2}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUBSH model,
using alternative parametrization \((\pi_1, \pi_2)\).
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{init\_theta() (in module cubmods.cubsh)@\spxentry{init\_theta()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.init_theta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{init\_theta}}}{\sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Preliminary estimators for CUBSH models.

\sphinxAtStartPar
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\sphinxhyphen{}M algorithm.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of the absolute frequencies of given ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\end{itemize}

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

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cubsh)@\spxentry{loglik()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood of a CUB model with shelter effect

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood of a CUB model with a shelter effect
for the given absolute frequency distribution.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} Vector of the absolute frequency distribution

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likehood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mean\_delta() (in module cubmods.cubsh)@\spxentry{mean\_delta()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.mean_delta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{mean\_delta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Expected value of a specified CUBSH model,
using canonic parametrization \((\pi, \delta)\).
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the expected value of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cubsh)@\spxentry{mle()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{500}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{0.0001}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUB models with a shelter effect

\sphinxAtStartPar
Estimate and validate a CUB model with a shelter effect.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} maximum number of iterations allowed for running the optimization algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} fixed error tolerance for final estimates

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUBSH}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\sphinxlineitem{Raise}
\sphinxAtStartPar
Exception if \(m \leq 4\)

\end{description}\end{quote}

\end{fulllineitems}

\index{pi1pi2\_to\_pidelta() (in module cubmods.cubsh)@\spxentry{pi1pi2\_to\_pidelta()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.pi1pi2_to_pidelta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{pi1pi2\_to\_pidelta}}}{\sphinxparam{\DUrole{n}{pi1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi2}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Compute \((\pi, \delta)\) from \((\pi_1, \pi_2)\)

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

\sphinxAtStartPar
\(\delta = 1 - \pi_1 - \pi_2\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
a tuple of \((\pi, \delta)\) the parameters of 
uncertainty and shelter choice, respectively

\sphinxlineitem{Return type}
\sphinxAtStartPar
tuple

\end{description}\end{quote}

\end{fulllineitems}

\index{pidelta\_to\_pi1pi2() (in module cubmods.cubsh)@\spxentry{pidelta\_to\_pi1pi2()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.pidelta_to_pi1pi2}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{pidelta\_to\_pi1pi2}}}{\sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Compute \((\pi_1, \pi_2)\) from \((\pi, \delta)\)

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

\sphinxAtStartPar
\(\pi_2 = (1 - \delta)(1 - \pi)\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
a tuple of \((\pi_1, \pi_2)\) the mixing coefficient of the shifted
Binomial and the Uniform components, respectively

\sphinxlineitem{Return type}
\sphinxAtStartPar
tuple

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_simplex() (in module cubmods.cubsh)@\spxentry{plot\_simplex()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.plot_simplex}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{plot\_simplex}}}{\sphinxparam{\DUrole{n}{pi1pi2list}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{fname}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot simplex of parameters of a CUBSH model.

\begin{sphinxadmonition}{note}{Note:}
\sphinxAtStartPar
see the reference \hyperlink{cite.references:id9}{Iannario, 2012} for details
\end{sphinxadmonition}

\begin{sphinxadmonition}{warning}{Warning:}
\sphinxAtStartPar
this function still needs several fixes
\end{sphinxadmonition}
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi1pi2list}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} list of \sphinxcode{\sphinxupquote{{[}pi1, pi2{]}}} parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} \textendash{} matplotlib axis

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{fname}} \textendash{} if provided, save the plot to \sphinxcode{\sphinxupquote{fname}}, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{fname}} \textendash{} str

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cubsh)@\spxentry{pmf()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a specified CUBSH model,
using alternative parametrization \((\pi_1, \pi_2)\).

\sphinxAtStartPar
\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf\_delta() (in module cubmods.cubsh)@\spxentry{pmf\_delta()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.pmf_delta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{pmf\_delta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a specified CUBSH model,
using canonic parametrization \((\pi, \delta)\).

\sphinxAtStartPar
\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{prob() (in module cubmods.cubsh)@\spxentry{prob()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.prob}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{prob}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{r}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability \(\Pr(R = r | \pmb\theta)\) of a CUBSH model without covariates,
using alternative parametrization \((\pi_1, \pi_2)\).
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{r}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} ordinal response

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability \(\Pr(R = r | \pmb\theta)\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{proba\_delta() (in module cubmods.cubsh)@\spxentry{proba\_delta()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.proba_delta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{proba\_delta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{r}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability \(\Pr(R = r | \pmb\theta)\) of a CUBSH model without covariates,
using canonic parametrization \((\pi, \delta)\).
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{r}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} ordinal response

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability \(\Pr(R = r | \pmb\theta)\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{std\_delta() (in module cubmods.cubsh)@\spxentry{std\_delta()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.std_delta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{std\_delta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Standard deviation of a specified CUB model,
using canonic parametrization \((\pi, \delta)\).
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the standard deviation of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{var\_delta() (in module cubmods.cubsh)@\spxentry{var\_delta()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.var_delta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{var\_delta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance of a specified CUBSH model,
using canonic parametrization \((\pi, \delta)\).
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{varcov() (in module cubmods.cubsh)@\spxentry{varcov()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.varcov}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{varcov}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance\sphinxhyphen{}covariance matrix for CUB models with shelter effect,
using alternative parametrization \((\pi_1, \pi_2)\).

\sphinxAtStartPar
Compute the variance\sphinxhyphen{}covariance matrix of parameter estimates of a CUB model with shelter effect.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the shifted Binomial component of the mixture distribution \(\pi_1\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} Mixing coefficient for the discrete Uniform component of the mixture distribution \(\pi_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance\sphinxhyphen{}covariance matrix

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{varcov\_pxd() (in module cubmods.cubsh)@\spxentry{varcov\_pxd()}\spxextra{in module cubmods.cubsh}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh.varcov_pxd}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh.}}\sphinxbfcode{\sphinxupquote{varcov\_pxd}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}\sphinxparamcomma \sphinxparam{\DUrole{n}{de}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance\sphinxhyphen{}covariance matrix for CUB models with shelter effect,
using canonic parametrization \((\pi, \delta)\).
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} uncertainty parameter \(\pi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{de}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance\sphinxhyphen{}covariance matrix

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cubsh\_ywx module}
\label{\detokenize{cubmods:module-cubmods.cubsh_ywx}}\label{\detokenize{cubmods:cubmods-cubsh-ywx-module}}\index{module@\spxentry{module}!cubmods.cubsh\_ywx@\spxentry{cubmods.cubsh\_ywx}}\index{cubmods.cubsh\_ywx@\spxentry{cubmods.cubsh\_ywx}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cubshywx-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUBSH (Combination of Uniform
and Binomial with Shelter Effect) with covariates.


\subsubsection{Description:}
\label{\detokenize{cubmods:id38}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUBSH\_YWX model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id39}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cubsh-with-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id40}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id41}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id42}}\index{CUBresCUBSHYWX (class in cubmods.cubsh\_ywx)@\spxentry{CUBresCUBSHYWX}\spxextra{class in cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.CUBresCUBSHYWX}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{CUBresCUBSHYWX}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cubsh_ywx.CUBresCUBSHYWX.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cubsh_ywx.CUBresCUBSHYWX.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cubsh\_ywx.CUBresCUBSHYWX method)@\spxentry{plot()}\spxextra{cubmods.cubsh\_ywx.CUBresCUBSHYWX method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.CUBresCUBSHYWX.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cubsh\_ywx.CUBresCUBSHYWX method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cubsh\_ywx.CUBresCUBSHYWX method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.CUBresCUBSHYWX.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and,
if provided, average probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{Q1() (in module cubmods.cubsh\_ywx)@\spxentry{Q1()}\spxextra{in module cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.Q1}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{Q1}}}{\sphinxparam{\DUrole{n}{param}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dati1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{p}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of GeCUB models.

\sphinxAtStartPar
Define the opposite one of the two scalar functions that are maximized when running the E\sphinxhyphen{}M algorithm
for GeCUB models with covariates for feeling, uncertainty and shelter effect.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{param}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of initial estimates of parameters for the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{dati1}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{dataframe}}) \textendash{} auxiliary matrix

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{p}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of covariates for the uncertainty component

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{Q2() (in module cubmods.cubsh\_ywx)@\spxentry{Q2()}\spxextra{in module cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.Q2}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{Q2}}}{\sphinxparam{\DUrole{n}{param}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dati2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of GeCUB models.

\sphinxAtStartPar
Define the opposite one of the two scalar functions that are maximized when running the E\sphinxhyphen{}M algorithm
for GeCUB models with covariates for feeling, uncertainty and shelter effect.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{param}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of initial estimates of parameters for the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{dati2}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{dataframe}}) \textendash{} auxiliary matrix

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{draw() (in module cubmods.cubsh\_ywx)@\spxentry{draw()}\spxextra{in module cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUBSH model with covariates
(aka GeCUB model).
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses to be drawn

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{init\_theta() (in module cubmods.cubsh\_ywx)@\spxentry{init\_theta()}\spxextra{in module cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.init_theta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{init\_theta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{p}}\sphinxparamcomma \sphinxparam{\DUrole{n}{s}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Preliminary estimators for CUBSH models with covariates.

\sphinxAtStartPar
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\sphinxhyphen{}M algorithm.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{p}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of covariates for the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{s}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of covariates for the shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
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\})\textasciigrave{} respectively, of a CUBSH model with covariates for all the three
parameters. In details, they have length equal to \sphinxcode{\sphinxupquote{Y.columns.size+1}}, \sphinxcode{\sphinxupquote{W.columns.size+1}} and
\sphinxcode{\sphinxupquote{X.columns.size+1}}, respectively, to account for an intercept term for each component.

\sphinxlineitem{Return type}
\sphinxAtStartPar
tuple of arrays

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cubsh\_ywx)@\spxentry{loglik()}\spxextra{in module cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function of a CUBSH model with covariates.

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function of a CUBE model for ordinal responses,
with covariates for explaining all the three parameters (GeCUB model).
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cubsh\_ywx)@\spxentry{mle()}\spxextra{in module cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{500}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{0.0001}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUBSH models with covariates for all the components

\sphinxAtStartPar
Function to estimate and validate a CUBSH model for given ordinal responses, with covariates for
explaining all the components and the shelter effect.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} maximum number of iterations allowed for running the optimization algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} fixed error tolerance for final estimates

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUBSHYWZ}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cubsh\_ywx)@\spxentry{pmf()}\spxextra{in module cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Average probability distribution of a specified CUBSH model with covariates
(aka GeCUB model).

\sphinxAtStartPar
\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmfi() (in module cubmods.cubsh\_ywx)@\spxentry{pmfi()}\spxextra{in module cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.pmfi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{pmfi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution for each subject of a specified CUBSH model with covariates
(aka GeCUB model).

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.draw()}}.

\sphinxAtStartPar
\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the matrix of the probability distribution of dimension \(n \times r\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{prob() (in module cubmods.cubsh\_ywx)@\spxentry{prob()}\spxextra{in module cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.prob}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{prob}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a CUBSH model with covariates.

\sphinxAtStartPar
Compute the probability distribution of a CUBSH model with covariates.

\sphinxAtStartPar
\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the array of the probability distribution.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{varcov() (in module cubmods.cubsh\_ywx)@\spxentry{varcov()}\spxextra{in module cubmods.cubsh\_ywx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cubsh_ywx.varcov}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cubsh\_ywx.}}\sphinxbfcode{\sphinxupquote{varcov}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}\sphinxparamcomma \sphinxparam{\DUrole{n}{beta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance\sphinxhyphen{}covariance matrix of a CUBSH model with covariates

\sphinxAtStartPar
Compute the variance\sphinxhyphen{}covariance matrix of parameter estimates of a CUBSH model with covariates.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{beta}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \beta\) of parameters for the uncertainty component, whose length equals 
\sphinxcode{\sphinxupquote{Y.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the uncertainty component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance\sphinxhyphen{}covariance matrix of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cush module}
\label{\detokenize{cubmods:module-cubmods.cush}}\label{\detokenize{cubmods:cubmods-cush-module}}\index{module@\spxentry{module}!cubmods.cush@\spxentry{cubmods.cush}}\index{cubmods.cush@\spxentry{cubmods.cush}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cush0-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUSH (Combination of Uniform
and Shelter effect).


\subsubsection{Description:}
\label{\detokenize{cubmods:id43}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUSH model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id44}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cush-without-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id45}}\begin{itemize}
\item {} 
\sphinxAtStartPar
TODO: check and fix gini \& laakso

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id46}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id47}}\index{CUBresCUSH (class in cubmods.cush)@\spxentry{CUBresCUSH}\spxextra{class in cubmods.cush}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.CUBresCUSH}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cush.}}\sphinxbfcode{\sphinxupquote{CUBresCUSH}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush.CUBresCUSH.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}ci, saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush.CUBresCUSH.plot_estim}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_estim}}}}}({[}ci, ax, magnified, figsize, saveas{]})
&
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and the asymptotic standard error.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush.CUBresCUSH.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, kind, ax, saveas{]})
&
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cush.CUBresCUSH method)@\spxentry{plot()}\spxextra{cubmods.cush.CUBresCUSH method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.CUBresCUSH.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 8)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the standard error

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_estim() (cubmods.cush.CUBresCUSH method)@\spxentry{plot\_estim()}\spxextra{cubmods.cush.CUBresCUSH method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.CUBresCUSH.plot_estim}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_estim}}}{\sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{magnified}\DUrole{o}{=}\DUrole{default_value}{False}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 7)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and
the asymptotic standard error.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the confidence ellipse

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{magnified}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if False the limits will be the entire parameter space, otherwise let matplotlib choose the limits

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cush.CUBresCUSH method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cush.CUBresCUSH method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.CUBresCUSH.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 7)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and,
if provided, probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{LRT() (in module cubmods.cush)@\spxentry{LRT()}\spxextra{in module cubmods.cush}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.LRT}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush.}}\sphinxbfcode{\sphinxupquote{LRT}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{fc}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Likelihood Ratio Test between the CUSH model and
the null model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{fc}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} relative frequency of the shelter category

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of observations

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the value of the LRT

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{draw() (in module cubmods.cush)@\spxentry{draw()}\spxextra{in module cubmods.cush}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUSH model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{gini() (in module cubmods.cush)@\spxentry{gini()}\spxextra{in module cubmods.cush}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.gini}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush.}}\sphinxbfcode{\sphinxupquote{gini}}}{\sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
The Gini index of a specified CUSH model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\sphinxlineitem{Returns}
\sphinxAtStartPar
the Gini index of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{laakso() (in module cubmods.cush)@\spxentry{laakso()}\spxextra{in module cubmods.cush}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.laakso}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush.}}\sphinxbfcode{\sphinxupquote{laakso}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
The Laakso index of a specified CUSH model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the Laakso index of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cush)@\spxentry{loglik()}\spxextra{in module cubmods.cush}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function for a CUSH model without covariates

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function for a CUSH model 
without covariate for the given ordinal responses.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likehood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mean() (in module cubmods.cush)@\spxentry{mean()}\spxextra{in module cubmods.cush}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.mean}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush.}}\sphinxbfcode{\sphinxupquote{mean}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Expected value of a specified CUSH model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the expected value of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cush)@\spxentry{mle()}\spxextra{in module cubmods.cush}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUSH model without covariates.

\sphinxAtStartPar
Estimate and validate a CUSH model for given ordinal responses, without covariates.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{None}}) \textendash{} default to None; ensure compatibility with \sphinxcode{\sphinxupquote{gem.from\_formula()}}

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{None}}) \textendash{} default to None; ensure compatibility with \sphinxcode{\sphinxupquote{gem.from\_formula()}}

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUSH}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cush)@\spxentry{pmf()}\spxextra{in module cubmods.cush}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a specified CUSH model.

\sphinxAtStartPar
\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{var() (in module cubmods.cush)@\spxentry{var()}\spxextra{in module cubmods.cush}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush.var}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush.}}\sphinxbfcode{\sphinxupquote{var}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance of a specified CUSH model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} shelter choice parameter \(\delta\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cush2 module}
\label{\detokenize{cubmods:module-cubmods.cush2}}\label{\detokenize{cubmods:cubmods-cush2-module}}\index{module@\spxentry{module}!cubmods.cush2@\spxentry{cubmods.cush2}}\index{cubmods.cush2@\spxentry{cubmods.cush2}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cush200-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUSH2 (Combination of Uniform
and 2 Shelter Choices).


\subsubsection{Description:}
\label{\detokenize{cubmods:id48}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUSH2 model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id49}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cush2-without-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id50}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id51}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id52}}\index{CUBresCUSH2 (class in cubmods.cush2)@\spxentry{CUBresCUSH2}\spxextra{class in cubmods.cush2}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2.CUBresCUSH2}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cush2.}}\sphinxbfcode{\sphinxupquote{CUBresCUSH2}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush2.CUBresCUSH2.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}ci, saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush2.CUBresCUSH2.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush2.CUBresCUSH2.plot_par_space}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_par\_space}}}}}({[}figsize, ax, ci, saveas{]})
&
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and the asymptotic standard error.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cush2.CUBresCUSH2 method)@\spxentry{plot()}\spxextra{cubmods.cush2.CUBresCUSH2 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2.CUBresCUSH2.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 11)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the standard error

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cush2.CUBresCUSH2 method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cush2.CUBresCUSH2 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2.CUBresCUSH2.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and,
if provided, probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_par\_space() (cubmods.cush2.CUBresCUSH2 method)@\spxentry{plot\_par\_space()}\spxextra{cubmods.cush2.CUBresCUSH2 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2.CUBresCUSH2.plot_par_space}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_par\_space}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and
the asymptotic standard error.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the confidence ellipse

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{draw() (in module cubmods.cush2)@\spxentry{draw()}\spxextra{in module cubmods.cush2}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUSH2 model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} 1st shelter choice parameter \(\delta_1\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} 2nd shelter choice parameter \(\delta_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cush2)@\spxentry{loglik()}\spxextra{in module cubmods.cush2}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{c1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{c2}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function for a CUSH2 model without covariates.

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function for a CUSH2 model 
without covariate for the given ordinal responses.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{c1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{c2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likehood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cush2)@\spxentry{mle()}\spxextra{in module cubmods.cush2}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{c1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{c2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUSH2 models without covariates.

\sphinxAtStartPar
Estimate and validate a CUSH2 model for ordinal responses, without covariates.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{c1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{c2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{None}}) \textendash{} default to None; ensure compatibility with \sphinxcode{\sphinxupquote{gem.from\_formula()}}

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{None}}) \textendash{} default to None; ensure compatibility with \sphinxcode{\sphinxupquote{gem.from\_formula()}}

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUSH2}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cush2)@\spxentry{pmf()}\spxextra{in module cubmods.cush2}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{c1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{c2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{d1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{d2}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a specified CUSH2 model.

\sphinxAtStartPar
\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{c1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{c2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{d1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} 1st shelter choice parameter \(\delta_1\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{d2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} 2nd shelter choice parameter \(\delta_2\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{varcov() (in module cubmods.cush2)@\spxentry{varcov()}\spxextra{in module cubmods.cush2}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2.varcov}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2.}}\sphinxbfcode{\sphinxupquote{varcov}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{d1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{d2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{fc1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{fc2}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Compute the variance\sphinxhyphen{}covariance matrix of parameter 
estimates of a CUSH2 model without covariates.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{d1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} 1st shelter choice parameter \(\delta_1\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{d2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} 2nd shelter choice parameter \(\delta_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{fc1}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} relative frequency of 1st shelter choice

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{fc2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} relative frequency of 2nd shelter choice

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance\sphinxhyphen{}covariance matrix

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cush2\_x0 module}
\label{\detokenize{cubmods:module-cubmods.cush2_x0}}\label{\detokenize{cubmods:cubmods-cush2-x0-module}}\index{module@\spxentry{module}!cubmods.cush2\_x0@\spxentry{cubmods.cush2\_x0}}\index{cubmods.cush2\_x0@\spxentry{cubmods.cush2\_x0}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cush2x0-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUSH2 (Combination of Uniform
and 2 Shelter Choices) with covariates
for the 1st shelter choice.


\subsubsection{Description:}
\label{\detokenize{cubmods:id53}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUSH2 model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id54}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cush2-with-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id55}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id56}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id57}}\index{CUBresCUSH2X0 (class in cubmods.cush2\_x0)@\spxentry{CUBresCUSH2X0}\spxextra{class in cubmods.cush2\_x0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_x0.CUBresCUSH2X0}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cush2\_x0.}}\sphinxbfcode{\sphinxupquote{CUBresCUSH2X0}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush2_x0.CUBresCUSH2X0.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush2_x0.CUBresCUSH2X0.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cush2\_x0.CUBresCUSH2X0 method)@\spxentry{plot()}\spxextra{cubmods.cush2\_x0.CUBresCUSH2X0 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_x0.CUBresCUSH2X0.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cush2\_x0.CUBresCUSH2X0 method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cush2\_x0.CUBresCUSH2X0 method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_x0.CUBresCUSH2X0.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and,
if provided, average probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{draw() (in module cubmods.cush2\_x0)@\spxentry{draw()}\spxextra{in module cubmods.cush2\_x0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_x0.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_x0.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUSH2 model,
with covariates for the 1st shelter choice only.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega1}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X1.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} 2nd shelter choice parameter \(\delta_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{effe() (in module cubmods.cush2\_x0)@\spxentry{effe()}\spxextra{in module cubmods.cush2\_x0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_x0.effe}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_x0.}}\sphinxbfcode{\sphinxupquote{effe}}}{\sphinxparam{\DUrole{n}{pars}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of CUSH2 models.

\sphinxAtStartPar
Compute the opposite of the scalar function that is maximized when running
the E\sphinxhyphen{}M algorithm for CUSH2 models with covariates for the 1st shelter choice.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cush2\_x0)@\spxentry{loglik()}\spxextra{in module cubmods.cush2\_x0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_x0.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_x0.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function for a CUSH2 model with covariates
for the 1st shelter choice only.

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function for a CUSH2 model 
with covariates for the 1st shelter choice only,
for the given ordinal responses.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega1}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X1.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} 2nd shelter choice parameter \(\delta_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likehood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cush2\_x0)@\spxentry{mle()}\spxextra{in module cubmods.cush2\_x0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_x0.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_x0.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUSH2 models with covariates for the 1st shelter choice only.

\sphinxAtStartPar
Estimate and validate a CUSH2 model for given ordinal responses, with covariates for the 1st shelter choice only.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUSH2X0}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cush2\_x0)@\spxentry{pmf()}\spxextra{in module cubmods.cush2\_x0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_x0.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_x0.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Average probability distribution of a specified CUSH2 model with covariates
for the 1st shelter choice.

\sphinxAtStartPar
\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega1}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X1.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} 2nd shelter choice parameter \(\delta_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the average probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmfi() (in module cubmods.cush2\_x0)@\spxentry{pmfi()}\spxextra{in module cubmods.cush2\_x0}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_x0.pmfi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_x0.}}\sphinxbfcode{\sphinxupquote{pmfi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{delta2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution for each subject of a specified CUSH2 model with covariates
for the first shelter choice only.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.draw()}}.

\sphinxAtStartPar
\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega1}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X1.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{delta2}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} 2nd shelter choice parameter \(\delta_2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the matrix of the probability distribution of dimension \(n \times r\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cush2\_xx module}
\label{\detokenize{cubmods:module-cubmods.cush2_xx}}\label{\detokenize{cubmods:cubmods-cush2-xx-module}}\index{module@\spxentry{module}!cubmods.cush2\_xx@\spxentry{cubmods.cush2\_xx}}\index{cubmods.cush2\_xx@\spxentry{cubmods.cush2\_xx}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cush2xx-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUSH2 (Combination of Uniform
and 2 Shelter Choices) with covariates.


\subsubsection{Description:}
\label{\detokenize{cubmods:id58}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUSH2 model family with covariates for
both shelter choices.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id59}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cush2-with-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id60}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id61}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id62}}\index{CUBresCUSH2XX (class in cubmods.cush2\_xx)@\spxentry{CUBresCUSH2XX}\spxextra{class in cubmods.cush2\_xx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_xx.CUBresCUSH2XX}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cush2\_xx.}}\sphinxbfcode{\sphinxupquote{CUBresCUSH2XX}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush2_xx.CUBresCUSH2XX.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush2_xx.CUBresCUSH2XX.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and, if provided, average probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cush2\_xx.CUBresCUSH2XX method)@\spxentry{plot()}\spxextra{cubmods.cush2\_xx.CUBresCUSH2XX method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_xx.CUBresCUSH2XX.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cush2\_xx.CUBresCUSH2XX method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cush2\_xx.CUBresCUSH2XX method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_xx.CUBresCUSH2XX.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative average frequencies of observed sample, estimated average probability distribution and,
if provided, average probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{draw() (in module cubmods.cush2\_xx)@\spxentry{draw()}\spxextra{in module cubmods.cush2\_xx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_xx.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_xx.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUSH2 model,
with covariates for both shelter choices.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega1}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X1.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega2}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_2\) of parameters for the 2nd shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X2.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X2}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 2nd shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{effe() (in module cubmods.cush2\_xx)@\spxentry{effe()}\spxextra{in module cubmods.cush2\_xx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_xx.effe}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_xx.}}\sphinxbfcode{\sphinxupquote{effe}}}{\sphinxparam{\DUrole{n}{pars}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X2}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of CUSH2 models.

\sphinxAtStartPar
Compute the opposite of the scalar function that is maximized when running
the E\sphinxhyphen{}M algorithm for CUSH2 models with covariates for both shelter choices.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X2}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 2nd shelter effect

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cush2\_xx)@\spxentry{loglik()}\spxextra{in module cubmods.cush2\_xx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_xx.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_xx.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X2}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function for a CUSH2 model with covariates
for both shelter choices.

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function for a CUSH2 model 
with covariates for both shelter choices,
for the given ordinal responses.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega1}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X1.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega2}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_2\) of parameters for the 2nd shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X2.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X2}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 2nd shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likehood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cush2\_xx)@\spxentry{mle()}\spxextra{in module cubmods.cush2\_xx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_xx.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_xx.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUSH2 models with covariates for both shelter choices.

\sphinxAtStartPar
Estimate and validate a CUSH2 model for given ordinal responses, with covariates for both shelter choices.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X2}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 2nd shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUSH2XX}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cush2\_xx)@\spxentry{pmf()}\spxextra{in module cubmods.cush2\_xx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_xx.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_xx.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X2}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Average probability distribution of a specified CUSH2 model with covariates
for both shelter choices.

\sphinxAtStartPar
\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega1}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X1.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega2}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_2\) of parameters for the 2nd shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X2.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X2}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 2nd shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the average probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmfi() (in module cubmods.cush2\_xx)@\spxentry{pmfi()}\spxextra{in module cubmods.cush2\_xx}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush2_xx.pmfi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush2\_xx.}}\sphinxbfcode{\sphinxupquote{pmfi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X1}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X2}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution for each subject of a specified CUSH2 model with covariates
for both shelter choices.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.draw()}}.

\sphinxAtStartPar
\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh1}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 1st shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh2}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the 2nd shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega1}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_1\) of parameters for the 1st shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X1.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega2}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega_2\) of parameters for the 2nd shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X2.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X1}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 1st shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X2}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} dataframe of covariates for explaining the 2nd shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the matrix of the probability distribution of dimension \(n \times r\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.cush\_x module}
\label{\detokenize{cubmods:module-cubmods.cush_x}}\label{\detokenize{cubmods:cubmods-cush-x-module}}\index{module@\spxentry{module}!cubmods.cush\_x@\spxentry{cubmods.cush\_x}}\index{cubmods.cush\_x@\spxentry{cubmods.cush\_x}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:cushx-module}}
\sphinxAtStartPar
CUB models in Python.
Module for CUSH (Combination of Uniform
and Shelter effect) with covariates.


\subsubsection{Description:}
\label{\detokenize{cubmods:id63}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for CUSH model family.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id64}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#cush-with-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id65}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id66}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id67}}\index{CUBresCUSHX (class in cubmods.cush\_x)@\spxentry{CUBresCUSHX}\spxextra{class in cubmods.cush\_x}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush_x.CUBresCUSHX}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.cush\_x.}}\sphinxbfcode{\sphinxupquote{CUBresCUSHX}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush_x.CUBresCUSHX.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.cush_x.CUBresCUSHX.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots avreage relative frequencies of observed sample, estimated  average probability distribution and, if provided, average probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.cush\_x.CUBresCUSHX method)@\spxentry{plot()}\spxextra{cubmods.cush\_x.CUBresCUSHX method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush_x.CUBresCUSHX.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.cush\_x.CUBresCUSHX method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.cush\_x.CUBresCUSHX method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush_x.CUBresCUSHX.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots avreage relative frequencies of observed sample, estimated 
average probability distribution and,
if provided, average probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{draw() (in module cubmods.cush\_x)@\spxentry{draw()}\spxextra{in module cubmods.cush\_x}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush_x.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush\_x.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified CUSH model with covariates
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{effe() (in module cubmods.cush\_x)@\spxentry{effe()}\spxextra{in module cubmods.cush\_x}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush_x.effe}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush\_x.}}\sphinxbfcode{\sphinxupquote{effe}}}{\sphinxparam{\DUrole{n}{pars}}\sphinxparamcomma \sphinxparam{\DUrole{n}{esterno}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of CUSH models with covariates

\sphinxAtStartPar
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 \sphinxcode{\sphinxupquote{.mle()}} function
as the function to minimize.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of the initial parameters estimates

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{esterno}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}) \textendash{} matrix binding together the vector of ordinal data and the matrix \sphinxcode{\sphinxupquote{XX}} of explanatory
variables whose first column is a column of ones needed to consider an intercept term

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.cush\_x)@\spxentry{loglik()}\spxextra{in module cubmods.cush\_x}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush_x.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush\_x.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function for CUSH models with covariates.

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function for CUSH models with covariates 
to explain the shelter effect.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.cush\_x)@\spxentry{mle()}\spxextra{in module cubmods.cush\_x}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush_x.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush\_x.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUSH models with covariates.

\sphinxAtStartPar
Estimate and validate a CUSH model for ordinal responses, with covariates
to explain the shelter effect.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} (\sphinxstyleliteralemphasis{\sphinxupquote{None}}) \textendash{} default to None; ensure compatibility with \sphinxcode{\sphinxupquote{gem.from\_formula()}}

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{None}}) \textendash{} default to None; ensure compatibility with \sphinxcode{\sphinxupquote{gem.from\_formula()}}

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresCUSHX}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.cush\_x)@\spxentry{pmf()}\spxextra{in module cubmods.cush\_x}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush_x.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush\_x.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Average probability distribution of a specified CUSH model with covariates.

\sphinxAtStartPar
\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmfi() (in module cubmods.cush\_x)@\spxentry{pmfi()}\spxextra{in module cubmods.cush\_x}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush_x.pmfi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush\_x.}}\sphinxbfcode{\sphinxupquote{pmfi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution for each subject of a specified CUSH model with covariates

\sphinxAtStartPar
\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the matrix of the probability distribution of dimension \(n \times r\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{prob() (in module cubmods.cush\_x)@\spxentry{prob()}\spxextra{in module cubmods.cush\_x}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.cush_x.prob}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.cush\_x.}}\sphinxbfcode{\sphinxupquote{prob}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{X}}\sphinxparamcomma \sphinxparam{\DUrole{n}{omega}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a specified CUSH model with covariates.

\sphinxAtStartPar
\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\;i = 1 \ldots n\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{omega}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \omega\) of parameters for the shelter effect, whose length equals 
\sphinxcode{\sphinxupquote{X.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{X}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the shelter effect

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability array \(\Pr(R = r | \pmb\theta)\) for observed responses

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.gem module}
\label{\detokenize{cubmods:module-cubmods.gem}}\label{\detokenize{cubmods:cubmods-gem-module}}\index{module@\spxentry{module}!cubmods.gem@\spxentry{cubmods.gem}}\index{cubmods.gem@\spxentry{cubmods.gem}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:gem-module}}
\sphinxAtStartPar
CUB models in Python.
Module for GEM (Generalized Mixtures).


\subsubsection{Description:}
\label{\detokenize{cubmods:id68}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for GEM maximum likelihood estimation
and sample drawing.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id69}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#gem-manual}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id70}}\begin{itemize}
\item {} 
\sphinxAtStartPar
TODO: implement best shelter search

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id71}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id72}}\index{draw() (in module cubmods.gem)@\spxentry{draw()}\spxextra{in module cubmods.gem}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.gem.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.gem.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}\DUrole{o}{=}\DUrole{default_value}{7}}\sphinxparamcomma \sphinxparam{\DUrole{n}{model}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}cub\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}\DUrole{o}{=}\DUrole{default_value}{500}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{o}{**}\DUrole{n}{params}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to draw a sample from GEneralized Mixture models.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} a formula used to draw the sample, see
Manual for details

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} the DataFrame with covariates (if any)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{model}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the model family; default to \sphinxcode{\sphinxupquote{"cub"}}; options \sphinxcode{\sphinxupquote{"cube"}} and \sphinxcode{\sphinxupquote{"cush"}}

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses; it is only effective if the model
is without covariates

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{options}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} a dictionary of extra options \sphinxcode{\sphinxupquote{maxiter}} and \sphinxcode{\sphinxupquote{tol}}; see the reference
guide for details

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\sphinxlineitem{Return type}
\sphinxAtStartPar
obj

\end{description}\end{quote}

\end{fulllineitems}

\index{estimate() (in module cubmods.gem)@\spxentry{estimate()}\spxextra{in module cubmods.gem}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.gem.estimate}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.gem.}}\sphinxbfcode{\sphinxupquote{estimate}}}{\sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{model}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}cub\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{options}\DUrole{o}{=}\DUrole{default_value}{\{\}}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to estimate and validate GEneralized Mixture models.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} a formula used to estimate the model’s parameters, see
Manual for details

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} the DataFrame with observed ordinal sample and covariates (if any)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{model}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the model family; default to \sphinxcode{\sphinxupquote{"cub"}}; options \sphinxcode{\sphinxupquote{"cube"}} and \sphinxcode{\sphinxupquote{"cush"}}

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} category corresponding to the shelter choice \([1,m]\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{options}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} a dictionary of extra options \sphinxcode{\sphinxupquote{maxiter}} and \sphinxcode{\sphinxupquote{tol}}; see the reference
guide for details

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of the Base Class \sphinxcode{\sphinxupquote{CUBres}} extended by the family module;
see each module for details

\sphinxlineitem{Return type}
\sphinxAtStartPar
obj

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.general module}
\label{\detokenize{cubmods:module-cubmods.general}}\label{\detokenize{cubmods:cubmods-general-module}}\index{module@\spxentry{module}!cubmods.general@\spxentry{cubmods.general}}\index{cubmods.general@\spxentry{cubmods.general}!module@\spxentry{module}}
\sphinxAtStartPar
CUB models in Python.
Module for General functions.


\subsubsection{Description:}
\label{\detokenize{cubmods:id73}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for general functions.
\end{quote}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id74}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id75}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id76}}\index{InvalidCategoriesError@\spxentry{InvalidCategoriesError}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.InvalidCategoriesError}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{exception\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{InvalidCategoriesError}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{model}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: \sphinxcode{\sphinxupquote{Exception}}

\sphinxAtStartPar
Exception: if m is not suitable for model.

\end{fulllineitems}

\index{InvalidSampleSizeError@\spxentry{InvalidSampleSizeError}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.InvalidSampleSizeError}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{exception\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{InvalidSampleSizeError}}}{\sphinxparam{\DUrole{n}{n}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: \sphinxcode{\sphinxupquote{Exception}}

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

\end{fulllineitems}

\index{NoShelterError@\spxentry{NoShelterError}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.NoShelterError}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{exception\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{NoShelterError}}}{\sphinxparam{\DUrole{n}{model}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: \sphinxcode{\sphinxupquote{Exception}}

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

\end{fulllineitems}

\index{NotImplementedModelError@\spxentry{NotImplementedModelError}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.NotImplementedModelError}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{exception\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{NotImplementedModelError}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: \sphinxcode{\sphinxupquote{Exception}}

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

\end{fulllineitems}

\index{ParameterOutOfBoundsError@\spxentry{ParameterOutOfBoundsError}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.ParameterOutOfBoundsError}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{exception\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{ParameterOutOfBoundsError}}}{\sphinxparam{\DUrole{n}{param}}\sphinxparamcomma \sphinxparam{\DUrole{n}{value}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: \sphinxcode{\sphinxupquote{Exception}}

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

\end{fulllineitems}

\index{ShelterGreaterThanM@\spxentry{ShelterGreaterThanM}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.ShelterGreaterThanM}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{exception\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{ShelterGreaterThanM}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: \sphinxcode{\sphinxupquote{Exception}}

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

\end{fulllineitems}

\index{UnknownModelError@\spxentry{UnknownModelError}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.UnknownModelError}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{exception\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{UnknownModelError}}}{\sphinxparam{\DUrole{n}{model}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: \sphinxcode{\sphinxupquote{Exception}}

\sphinxAtStartPar
Exception: if the requested family is unknown.

\end{fulllineitems}

\index{addones() (in module cubmods.general)@\spxentry{addones()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.addones}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{addones}}}{\sphinxparam{\DUrole{n}{A}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Expand with a unitary vector in the first column of the given matrix
to consider also an intercept term for CUB models with covariates.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{A}} \textendash{} a matrix to be expanded

\sphinxlineitem{Returns}
\sphinxAtStartPar
the expanded matrix

\sphinxlineitem{Return type}
\sphinxAtStartPar
same of \sphinxcode{\sphinxupquote{A}}

\end{description}\end{quote}

\end{fulllineitems}

\index{aic() (in module cubmods.general)@\spxentry{aic()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.aic}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{aic}}}{\sphinxparam{\DUrole{n}{l}}\sphinxparamcomma \sphinxparam{\DUrole{n}{p}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Akaike Information Criterion.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{l}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} log\sphinxhyphen{}likelihood

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{p}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of parameters

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the AIC value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{bic() (in module cubmods.general)@\spxentry{bic()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.bic}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{bic}}}{\sphinxparam{\DUrole{n}{l}}\sphinxparamcomma \sphinxparam{\DUrole{n}{p}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bayesian Information Criterion.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{l}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} log\sphinxhyphen{}likelihood

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{p}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of observations

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the BIC value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{bitgamma() (in module cubmods.general)@\spxentry{bitgamma()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.bitgamma}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{bitgamma}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{W}}\sphinxparamcomma \sphinxparam{\DUrole{n}{gamma}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Shifted Binomial distribution with covariates.

\sphinxAtStartPar
Return the shifted Binomial probabilities of ordinal responses where the feeling component 
is explained by covariates via a logistic link.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{W}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the feeling component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{gamma}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} array \(\pmb \gamma\) of parameters for the feeling component, whose length equals 
\sphinxcode{\sphinxupquote{W.columns.size+1}} to include an intercept term in the model (first entry)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an array of the same length as \sphinxcode{\sphinxupquote{sample}}, where each entry is the shifted Binomial probability for
the corresponding observation and feeling value.

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{bitxi() (in module cubmods.general)@\spxentry{bitxi()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.bitxi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{bitxi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Shifted Binomial probabilities of ordinal responses

\sphinxAtStartPar
Compute the shifted Binomial probabilities of ordinal responses.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
A vector of the same length as \sphinxcode{\sphinxupquote{sample}}, where each entry is the shifted Binomial probability 
of the corresponding observation.

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{choices() (in module cubmods.general)@\spxentry{choices()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.choices}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{choices}}}{\sphinxparam{\DUrole{n}{m}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Array of ordinal categories.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\sphinxlineitem{Returns}
\sphinxAtStartPar
array of int from 1 to m

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{colsof() (in module cubmods.general)@\spxentry{colsof()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.colsof}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{colsof}}}{\sphinxparam{\DUrole{n}{A}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Number of columns of the given
matrix or dataframe.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{A}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{dataframe}}) \textendash{} the matrix or dataframe

\sphinxlineitem{Returns}
\sphinxAtStartPar
number of columns

\sphinxlineitem{Return type}
\sphinxAtStartPar
int

\end{description}\end{quote}

\end{fulllineitems}

\index{conf\_border() (in module cubmods.general)@\spxentry{conf\_border()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.conf_border}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{conf\_border}}}{\sphinxparam{\DUrole{n}{Sigma}}\sphinxparamcomma \sphinxparam{\DUrole{n}{mx}}\sphinxparamcomma \sphinxparam{\DUrole{n}{my}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}}\sphinxparamcomma \sphinxparam{\DUrole{n}{conf}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{plane}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}z\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xyz0}\DUrole{o}{=}\DUrole{default_value}{(0, 0, 0)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot the bivariate projection of a trivariate confidence ellipse
on a plane.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{plot\_ellipsoid()}}.

\begin{sphinxadmonition}{note}{Note:}
\sphinxAtStartPar
Solution by \sphinxurl{https://gist.github.com/randolf-scholz}.
\end{sphinxadmonition}
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Sigma}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}) \textendash{} bivariate variance\sphinxhyphen{}covariance matrix

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{mx}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} center of the ellipse on the \(x\) axies

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{my}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} center of the ellipse on the \(y\) axies

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} \textendash{} matpplotlib axis

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{conf}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} confidence level of the trivariate ellipsoid.

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{plane}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} plane for the projection; could be \sphinxcode{\sphinxupquote{x}}, \sphinxcode{\sphinxupquote{y}} or \sphinxcode{\sphinxupquote{z}}

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xyz0}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}) \textendash{} tuple of the bivariate ellipse position

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{conf\_ell() (in module cubmods.general)@\spxentry{conf\_ell()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.conf_ell}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{conf\_ell}}}{\sphinxparam{\DUrole{n}{vcov}}\sphinxparamcomma \sphinxparam{\DUrole{n}{mux}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muy}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ci}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}}\sphinxparamcomma \sphinxparam{\DUrole{n}{color}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}b\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{label}\DUrole{o}{=}\DUrole{default_value}{True}}\sphinxparamcomma \sphinxparam{\DUrole{n}{alpha}\DUrole{o}{=}\DUrole{default_value}{0.25}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot bivariate confidence ellipse of estimated
parameters at level \sphinxcode{\sphinxupquote{ci}}\(=(1 - \alpha/2)\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{vcov}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}) \textendash{} Variance\sphinxhyphen{}covariance matrix \(2 \times 2\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{mux}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} estimate of first parameter

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{muy}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} estimate of second parameter

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} confidence level \(=(1 - \alpha/2)\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} \textendash{} matplotlib axis

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{color}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} color of confidence ellipse

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{label}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} whether to add a label of confidence level

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{alpha}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} transparency of confidence ellipse

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{dissimilarity() (in module cubmods.general)@\spxentry{dissimilarity()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.dissimilarity}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{dissimilarity}}}{\sphinxparam{\DUrole{n}{p\_obs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{p\_est}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Normalized dissimilarity measure.

\sphinxAtStartPar
Compute the normalized dissimilarity measure between observed
relative frequencies and estimated (theoretical) probabilities of a discrete distribution.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{p\_obs}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} Vector of observed relative frequencies

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{p\_est}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} Vector of estimated (theoretical) probabilities

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
Numeric value of the dissimilarity index, assessing the distance to a perfect fit.

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{dummies2() (in module cubmods.general)@\spxentry{dummies2()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.dummies2}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{dummies2}}}{\sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{DD}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Create dummy variables from polychotomous variables.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{cubmods.gem.from\_formula()}}.
A dummy variable is created for all polychotomous variables named
\sphinxcode{\sphinxupquote{C(\textless{}varname\textgreater{})}}.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} a DataFrame with all the covariates and the ordinal response

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{DD}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} the list of all covariates for each component

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
a tuple of the DataFrame with the dummy variables and the column names

\sphinxlineitem{Return type}
\sphinxAtStartPar
tuple

\end{description}\end{quote}

\end{fulllineitems}

\index{equal3d() (in module cubmods.general)@\spxentry{equal3d()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.equal3d}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{equal3d}}}{\sphinxparam{\DUrole{n}{ax}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Equalize 3d axes.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.plot\_ellipsoid()}}.

\end{fulllineitems}

\index{expit() (in module cubmods.general)@\spxentry{expit()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.expit}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{expit}}}{\sphinxparam{\DUrole{n}{x}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Expit function.

\sphinxAtStartPar
It is the inverse of logit. Aka
sigmoid or standard logistic.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{x}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} the argument

\sphinxlineitem{Returns}
\sphinxAtStartPar
the expit of x

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{formula\_parser() (in module cubmods.general)@\spxentry{formula\_parser()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.formula_parser}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{formula\_parser}}}{\sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{model}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}cub\textquotesingle{}}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Parse a CUB class formula.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{cubmods.gem}} functions.

\sphinxAtStartPar
TODO: add specific Exceptions for formula
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula to be parsed

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{model}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the model family

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
a tuple of the ordinal response column name and a list of all
covariates’ column names for each component

\sphinxlineitem{Return type}
\sphinxAtStartPar
tuple

\end{description}\end{quote}

\end{fulllineitems}

\index{freq() (in module cubmods.general)@\spxentry{freq()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.freq}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{freq}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dataframe}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Absolute frequecies of an
observed sample of ordinal
responses.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{dataframe}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if \sphinxcode{\sphinxupquote{True}} return
a DataFrame instead of an array,
defaults to \sphinxcode{\sphinxupquote{False}}

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the absolute frequencies of the observed sample

\sphinxlineitem{Return type}
\sphinxAtStartPar
array or dataframe

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_cov\_ellipsoid() (in module cubmods.general)@\spxentry{get\_cov\_ellipsoid()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.get_cov_ellipsoid}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{get\_cov\_ellipsoid}}}{\sphinxparam{\DUrole{n}{cov}}\sphinxparamcomma \sphinxparam{\DUrole{n}{mu}\DUrole{o}{=}\DUrole{default_value}{array({[}0., 0., 0.{]})}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Return the 3d points representing the covariance matrix
\sphinxcode{\sphinxupquote{cov}} centred at \sphinxcode{\sphinxupquote{mu}}, at confidence level \sphinxcode{\sphinxupquote{ci}}\(=(1 - \alpha/2)\).

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.plot\_ellipsoid()}}.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{cov}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}) \textendash{} Variance\sphinxhyphen{}covariance matrix \(3 \times 3\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{mu}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} ellispoid center \((x_0, y_0, z_0)\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} confidence level \(=(1 - \alpha/2)\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
a tuple of 3d points \sphinxcode{\sphinxupquote{(X, Y, Z)}}

\sphinxlineitem{Return type}
\sphinxAtStartPar
tuple

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_minor() (in module cubmods.general)@\spxentry{get\_minor()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.get_minor}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{get\_minor}}}{\sphinxparam{\DUrole{n}{A}}\sphinxparamcomma \sphinxparam{\DUrole{n}{i}}\sphinxparamcomma \sphinxparam{\DUrole{n}{j}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Get a minor of a matrix.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.plot\_ellipsoid()}}.

\begin{sphinxadmonition}{note}{Note:}
\sphinxAtStartPar
Solution by PaulDong
\end{sphinxadmonition}
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{A}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}) \textendash{} a generic matrix

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{i}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} row of the minor

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{j}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} column of the minor

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the minor of \sphinxcode{\sphinxupquote{A}}

\sphinxlineitem{Return type}
\sphinxAtStartPar
ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{hadprod() (in module cubmods.general)@\spxentry{hadprod()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.hadprod}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{hadprod}}}{\sphinxparam{\DUrole{n}{Amat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xvett}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Hadamard product of a matrix with a vector

\sphinxAtStartPar
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\sphinxhyphen{}covariance matrix of the estimated model 
with covariates.

\begin{sphinxadmonition}{note}{Note:}
\sphinxAtStartPar
if \sphinxcode{\sphinxupquote{xvett}} is a row vector, reshapes it to column vector
\end{sphinxadmonition}
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Amat}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}) \textendash{} A generic matrix

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xvett}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} A generic vector

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the Hadamard product \(\pmb A \odot \pmb x\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{kkk() (in module cubmods.general)@\spxentry{kkk()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.kkk}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{kkk}}}{\sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Sequence of combinatorial coefficients

\sphinxAtStartPar
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\sphinxhyphen{}th component is the corresponding binomial 
coefficient \(\binom{m-1}{r_i-1}\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\end{itemize}

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

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{load\_object() (in module cubmods.general)@\spxentry{load\_object()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.load_object}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{load\_object}}}{\sphinxparam{\DUrole{n}{fname}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Load a saved object from file.

\sphinxAtStartPar
It can used be used to load a \sphinxcode{\sphinxupquote{CUBsample}} or a
\sphinxcode{\sphinxupquote{CUBres}} object, previously saved on a file.

\begin{sphinxadmonition}{note}{Note:}
\sphinxAtStartPar
see the Classes for details about these objects
\end{sphinxadmonition}
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{fname}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} filename

\sphinxlineitem{Returns}
\sphinxAtStartPar
the loaded object, instance of \sphinxcode{\sphinxupquote{CUBsample}} or \sphinxcode{\sphinxupquote{CUBres}}

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{logis() (in module cubmods.general)@\spxentry{logis()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.logis}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{logis}}}{\sphinxparam{\DUrole{n}{Y}}\sphinxparamcomma \sphinxparam{\DUrole{n}{param}}}{}
\pysigstopsignatures
\sphinxAtStartPar
The logistic transform.

\sphinxAtStartPar
Create a matrix \sphinxcode{\sphinxupquote{YY}} binding array \sphinxcode{\sphinxupquote{Y}} with a vector of ones, placed as the first column of \sphinxcode{\sphinxupquote{YY}}. 
It applies the logistic transform componentwise to the standard matrix multiplication between \sphinxcode{\sphinxupquote{YY}} and \sphinxcode{\sphinxupquote{param}}.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{Y}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{dataframe}}) \textendash{} A generic matrix or a dataframe

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{param}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} Vector of coefficients, whose length is \sphinxcode{\sphinxupquote{Y.columns.size+1}} (to consider also an intercept term)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
a vector whose length is \sphinxcode{\sphinxupquote{Y.index.size}} and whose i\sphinxhyphen{}th component is the logistic function

\end{description}\end{quote}

\end{fulllineitems}

\index{logit() (in module cubmods.general)@\spxentry{logit()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.logit}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{logit}}}{\sphinxparam{\DUrole{n}{x}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Logit function.

\sphinxAtStartPar
It is the inverse of the
standard logistic function, aka
log\sphinxhyphen{}odds.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{x}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} the argument

\sphinxlineitem{Returns}
\sphinxAtStartPar
the logit of x

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{lsat() (in module cubmods.general)@\spxentry{lsat()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.lsat}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{lsat}}}{\sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood of saturated model.

\sphinxAtStartPar
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\sphinxhyphen{}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\sphinxhyphen{}likelihood quantities.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} absolute frequencies of observed ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of observations

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
log\sphinxhyphen{}likelihood of saturated model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{luni() (in module cubmods.general)@\spxentry{luni()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.luni}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{luni}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood of null model.

\sphinxAtStartPar
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.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of observations

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood of null model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ellipsoid() (in module cubmods.general)@\spxentry{plot\_ellipsoid()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.plot_ellipsoid}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{plot\_ellipsoid}}}{\sphinxparam{\DUrole{n}{V}}\sphinxparamcomma \sphinxparam{\DUrole{n}{E}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}}\sphinxparamcomma \sphinxparam{\DUrole{n}{zlabel}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{magnified}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plot a trivariate confidence ellipsoid.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{V}} (\sphinxstyleliteralemphasis{\sphinxupquote{ndarray}}) \textendash{} Variance\sphinxhyphen{}covariance matrix

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{E}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} Vector of estimated parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} \textendash{} matplotlib axis

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{zlabel}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} label for \(z\) axis

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} confidence level \((1 - \alpha/2)\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{magnified}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if \sphinxcode{\sphinxupquote{False}} plots in the full parameter space

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{probbit() (in module cubmods.general)@\spxentry{probbit()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.probbit}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{probbit}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xi}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of 
shifted binomial random variable.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xi}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} feeling parameter \(\xi\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the vector of the probability 
distribution of a shifted Binomial 
model.

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{unique() (in module cubmods.general)@\spxentry{unique()}\spxextra{in module cubmods.general}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.general.unique}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.general.}}\sphinxbfcode{\sphinxupquote{unique}}}{\sphinxparam{\DUrole{n}{l}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Unique elements in a 3\sphinxhyphen{}dimensional list.

\sphinxAtStartPar
Auxiliary function of \sphinxcode{\sphinxupquote{.dummies2()}}.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{l}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} the list to analyze

\sphinxlineitem{Returns}
\sphinxAtStartPar
the list of unique elements

\sphinxlineitem{Return type}
\sphinxAtStartPar
list

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.ihg module}
\label{\detokenize{cubmods:module-cubmods.ihg}}\label{\detokenize{cubmods:cubmods-ihg-module}}\index{module@\spxentry{module}!cubmods.ihg@\spxentry{cubmods.ihg}}\index{cubmods.ihg@\spxentry{cubmods.ihg}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:ihg0-module}}
\sphinxAtStartPar
CUB models in Python.
Module for IHG (Inverse HyperGeometric).


\subsubsection{Description:}
\label{\detokenize{cubmods:id77}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for IHG model family without covariates.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id78}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#ihg-without-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id79}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id80}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id81}}\index{CUBresIHG (class in cubmods.ihg)@\spxentry{CUBresIHG}\spxextra{class in cubmods.ihg}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.CUBresIHG}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.ihg.}}\sphinxbfcode{\sphinxupquote{CUBresIHG}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}

\sphinxAtStartPar
Object returned by \sphinxcode{\sphinxupquote{.mle()}} function.
See \sphinxhref{cubmods.html\#cubmods.smry.CUBres}{here} the Base for details.
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.ihg.CUBresIHG.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}ci, saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.ihg.CUBresIHG.plot_estim}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_estim}}}}}({[}ci, ax, magnified{]})
&
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and the asymptotic standard error.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.ihg.CUBresIHG.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and, if provided, probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.ihg.CUBresIHG method)@\spxentry{plot()}\spxextra{cubmods.ihg.CUBresIHG method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.CUBresIHG.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 8)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the standard error

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_estim() (cubmods.ihg.CUBresIHG method)@\spxentry{plot\_estim()}\spxextra{cubmods.ihg.CUBresIHG method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.CUBresIHG.plot_estim}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_estim}}}{\sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{magnified}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots the estimated parameter values in the parameter space and
the asymptotic standard error.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the confidence ellipse

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{magnified}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if False the limits will be the entire parameter space, otherwise let matplotlib choose the limits

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.ihg.CUBresIHG method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.ihg.CUBresIHG method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.CUBresIHG.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots relative frequencies of observed sample, estimated probability distribution and,
if provided, probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{draw() (in module cubmods.ihg)@\spxentry{draw()}\spxextra{in module cubmods.ihg}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified IHG model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{theta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} parameter \(\theta\) (probability of 1st shelter category)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal responses to be drawn

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{effe() (in module cubmods.ihg)@\spxentry{effe()}\spxextra{in module cubmods.ihg}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.effe}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg.}}\sphinxbfcode{\sphinxupquote{effe}}}{\sphinxparam{\DUrole{n}{theta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Compute the negative log\sphinxhyphen{}likelihood function of a IHG model without 
covariates for a given absolute frequency distribution.
Auxiliary function of \sphinxcode{\sphinxupquote{mle()}} for optimization algorithm.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{theta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} parameter \(\theta\) (probability of 1st shelter category)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of absolute frequency distribution

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{init\_theta() (in module cubmods.ihg)@\spxentry{init\_theta()}\spxextra{in module cubmods.ihg}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.init_theta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg.}}\sphinxbfcode{\sphinxupquote{init\_theta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Preliminary estimators for IHG models without covariates.

\sphinxAtStartPar
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\sphinxhyphen{}M algorithm.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of the absolute frequencies of given ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the value of \(\theta^{(0)}\)

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.ihg)@\spxentry{loglik()}\spxextra{in module cubmods.ihg}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theta}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function of a IHG model without 
covariates for a given absolute frequency distribution.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{theta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} parameter :math:\textasciigrave{}     heta\textasciigrave{} (probability of 1st shelter category)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of absolute frequency distribution

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.ihg)@\spxentry{mle()}\spxextra{in module cubmods.ihg}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for CUB models without covariates.

\sphinxAtStartPar
Function to estimate and validate a CUB model without covariates for given ordinal responses.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresIHG}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.ihg)@\spxentry{pmf()}\spxextra{in module cubmods.ihg}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a specified IHG model without covariates.

\sphinxAtStartPar
\(\Pr(R = r | \pmb\theta),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{theta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} parameter \(\theta\) (probability of 1st shelter category)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the vector of the probability distribution of a CUB model.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}

\index{var() (in module cubmods.ihg)@\spxentry{var()}\spxextra{in module cubmods.ihg}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg.var}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg.}}\sphinxbfcode{\sphinxupquote{var}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theta}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Variance of a specified IHG model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{theta}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} parameter \(\theta\) (probability of 1st shelter category)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the variance of the model

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.ihg\_v module}
\label{\detokenize{cubmods:module-cubmods.ihg_v}}\label{\detokenize{cubmods:cubmods-ihg-v-module}}\index{module@\spxentry{module}!cubmods.ihg\_v@\spxentry{cubmods.ihg\_v}}\index{cubmods.ihg\_v@\spxentry{cubmods.ihg\_v}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:ihgv-module}}
\sphinxAtStartPar
CUB models in Python.
Module for IHG (Inverse HyperGeometric) with covariates.


\subsubsection{Description:}
\label{\detokenize{cubmods:id82}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for IHG model family with covariates.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id83}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#ihg-with-covariates}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id84}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id85}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id86}}\index{CUBresIHGV (class in cubmods.ihg\_v)@\spxentry{CUBresIHGV}\spxextra{class in cubmods.ihg\_v}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.CUBresIHGV}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.ihg\_v.}}\sphinxbfcode{\sphinxupquote{CUBresIHGV}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: {\hyperref[\detokenize{cubmods:cubmods.smry.CUBres}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{CUBres}}}}}
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_dataframe}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{as\_txt}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.ihg_v.CUBresIHGV.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}saveas, figsize{]})
&
\sphinxAtStartPar
Main function to plot an object of the Class.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.ihg_v.CUBresIHGV.plot_ordinal}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot\_ordinal}}}}}({[}figsize, ax, kind, saveas{]})
&
\sphinxAtStartPar
Plots avreage relative frequencies of observed sample, estimated  average probability distribution and, if provided, average probability distribution of a known model.
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{save}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{summary}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{plot() (cubmods.ihg\_v.CUBresIHGV method)@\spxentry{plot()}\spxextra{cubmods.ihg\_v.CUBresIHGV method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.CUBresIHGV.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function to plot an object of the Class.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{plot\_ordinal() (cubmods.ihg\_v.CUBresIHGV method)@\spxentry{plot\_ordinal()}\spxextra{cubmods.ihg\_v.CUBresIHGV method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.CUBresIHGV.plot_ordinal}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot\_ordinal}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Plots avreage relative frequencies of observed sample, estimated 
average probability distribution and,
if provided, average probability distribution of a known model.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{draw() (in module cubmods.ihg\_v)@\spxentry{draw()}\spxextra{in module cubmods.ihg\_v}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.draw}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg\_v.}}\sphinxbfcode{\sphinxupquote{draw}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{nu}}\sphinxparamcomma \sphinxparam{\DUrole{n}{V}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Draw a random sample from a specified IHG model with covariates
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{nu}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \nu\) of parameters for \(\theta\), whose length equals 
\sphinxcode{\sphinxupquote{V.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{V}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the parameter \(\theta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} the \sphinxtitleref{seed} to ensure reproducibility, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBsample}} (see \sphinxhref{cubmods.html\#cubmods.smry.CUBsample}{here}) containing ordinal responses drawn from the specified model

\end{description}\end{quote}

\end{fulllineitems}

\index{effe() (in module cubmods.ihg\_v)@\spxentry{effe()}\spxextra{in module cubmods.ihg\_v}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.effe}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg\_v.}}\sphinxbfcode{\sphinxupquote{effe}}}{\sphinxparam{\DUrole{n}{nu}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{V}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Auxiliary function for the log\sphinxhyphen{}likelihood estimation of IHG models with covariates

\sphinxAtStartPar
Compute the opposite of the loglikelihood function for IHG models
with covariates.
It is called as an argument for “optim” within \sphinxcode{\sphinxupquote{.mle()}} function
as the function to minimize.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{nu}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} initial parameter estimate

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{V}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the parameter \(\theta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{init\_theta() (in module cubmods.ihg\_v)@\spxentry{init\_theta()}\spxextra{in module cubmods.ihg\_v}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.init_theta}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg\_v.}}\sphinxbfcode{\sphinxupquote{init\_theta}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Preliminary estimators for IHG models without covariates.

\sphinxAtStartPar
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\sphinxhyphen{}M algorithm.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of the absolute frequencies of given ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\end{itemize}

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

\end{description}\end{quote}

\end{fulllineitems}

\index{loglik() (in module cubmods.ihg\_v)@\spxentry{loglik()}\spxextra{in module cubmods.ihg\_v}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.loglik}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg\_v.}}\sphinxbfcode{\sphinxupquote{loglik}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{V}}\sphinxparamcomma \sphinxparam{\DUrole{n}{nu}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Log\sphinxhyphen{}likelihood function for IHG models with covariates.

\sphinxAtStartPar
Compute the log\sphinxhyphen{}likelihood function for CUSH models with covariates 
to explain the shelter effect.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{nu}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \nu\) of parameters for \(\theta\), whose length equals 
\sphinxcode{\sphinxupquote{V.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{V}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the parameter \(\theta\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the log\sphinxhyphen{}likelihood value

\sphinxlineitem{Return type}
\sphinxAtStartPar
float

\end{description}\end{quote}

\end{fulllineitems}

\index{mle() (in module cubmods.ihg\_v)@\spxentry{mle()}\spxextra{in module cubmods.ihg\_v}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.mle}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg\_v.}}\sphinxbfcode{\sphinxupquote{mle}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{V}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Main function for IHG models with covariates.

\sphinxAtStartPar
Estimate and validate a IHG model for ordinal responses, with covariates.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{V}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the parameter \(\theta\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} (\sphinxstyleliteralemphasis{\sphinxupquote{DataFrame}}) \textendash{} original DataFrame

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} the formula used

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} (\sphinxstyleliteralemphasis{\sphinxupquote{dictionary}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} dictionary of hypothesized parameters, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
an instance of \sphinxcode{\sphinxupquote{CUBresIHGV}} (see the Class for details)

\sphinxlineitem{Return type}
\sphinxAtStartPar
object

\end{description}\end{quote}

\end{fulllineitems}

\index{pmf() (in module cubmods.ihg\_v)@\spxentry{pmf()}\spxextra{in module cubmods.ihg\_v}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.pmf}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg\_v.}}\sphinxbfcode{\sphinxupquote{pmf}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{V}}\sphinxparamcomma \sphinxparam{\DUrole{n}{nu}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Average probability distribution of a specified IHG model with covariates.

\sphinxAtStartPar
\(\frac{1}{n} \sum_{i=1}^n \Pr(R_i=r|\pmb\theta; \pmb T_i),\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{nu}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \nu\) of parameters for \(\theta\), whose length equals 
\sphinxcode{\sphinxupquote{V.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{V}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the parameter \(\theta\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the probability distribution

\sphinxlineitem{Return type}
\sphinxAtStartPar
array

\end{description}\end{quote}

\end{fulllineitems}

\index{pmfi() (in module cubmods.ihg\_v)@\spxentry{pmfi()}\spxextra{in module cubmods.ihg\_v}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.pmfi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg\_v.}}\sphinxbfcode{\sphinxupquote{pmfi}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{V}}\sphinxparamcomma \sphinxparam{\DUrole{n}{nu}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution for each subject of a specified IHG model with covariates

\sphinxAtStartPar
\(\Pr(R_i=r|\pmb\theta; \pmb T_i),\; i=1 \ldots n ,\; r=1 \ldots m\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{nu}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \nu\) of parameters for \(\theta\), whose length equals 
\sphinxcode{\sphinxupquote{V.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{V}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the parameter \(\theta\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the matrix of the probability distribution of dimension \(n \times r\)

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy ndarray

\end{description}\end{quote}

\end{fulllineitems}

\index{prob() (in module cubmods.ihg\_v)@\spxentry{prob()}\spxextra{in module cubmods.ihg\_v}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.ihg_v.prob}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.ihg\_v.}}\sphinxbfcode{\sphinxupquote{prob}}}{\sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{V}}\sphinxparamcomma \sphinxparam{\DUrole{n}{nu}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Probability distribution of a IHG model with covariates
given an observed sample.

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

\sphinxAtStartPar
\(\Pr(R_i=r_i|\pmb\theta;\pmb T_i),\; i=1 \ldots n\)
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} array of ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{nu}} (\sphinxstyleliteralemphasis{\sphinxupquote{array}}) \textendash{} array \(\pmb \nu\) of parameters for \(\theta\), whose length equals 
\sphinxcode{\sphinxupquote{V.columns.size+1}} to include an intercept term in the model (first entry)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{V}} (\sphinxstyleliteralemphasis{\sphinxupquote{pandas dataframe}}) \textendash{} dataframe of covariates for explaining the parameter \(\theta\)

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
the array of the probability distribution.

\sphinxlineitem{Return type}
\sphinxAtStartPar
numpy array

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.multicub module}
\label{\detokenize{cubmods:module-cubmods.multicub}}\label{\detokenize{cubmods:cubmods-multicub-module}}\index{module@\spxentry{module}!cubmods.multicub@\spxentry{cubmods.multicub}}\index{cubmods.multicub@\spxentry{cubmods.multicub}!module@\spxentry{module}}\phantomsection\label{\detokenize{cubmods:multicub-module}}
\sphinxAtStartPar
CUB models in Python.
Module for MULTICUB and MULTICUBE.


\subsubsection{Description:}
\label{\detokenize{cubmods:id87}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for MULTICUB and MULTICUBE tool.
\end{quote}


\subsubsection{Manual, Examples and References:}
\label{\detokenize{cubmods:id88}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxhref{manual.html\#multicub-manual}{Models manual}

\end{itemize}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id89}}\begin{itemize}
\item {} 
\sphinxAtStartPar
…

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id90}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id91}}\index{multi() (in module cubmods.multicub)@\spxentry{multi()}\spxextra{in module cubmods.multicub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.multicub.multi}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.multicub.}}\sphinxbfcode{\sphinxupquote{multi}}}{\sphinxparam{\DUrole{n}{ords}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ms}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{model}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}cub\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{title}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{labels}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{shs}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{plot}\DUrole{o}{=}\DUrole{default_value}{True}}\sphinxparamcomma \sphinxparam{\DUrole{n}{print\_res}\DUrole{o}{=}\DUrole{default_value}{False}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pos}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{xlim}\DUrole{o}{=}\DUrole{default_value}{(0, 1)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ylim}\DUrole{o}{=}\DUrole{default_value}{(0, 1)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{equal}\DUrole{o}{=}\DUrole{default_value}{True}}\sphinxparamcomma \sphinxparam{\DUrole{n}{confell}\DUrole{o}{=}\DUrole{default_value}{True}}\sphinxparamcomma \sphinxparam{\DUrole{n}{alpha}\DUrole{o}{=}\DUrole{default_value}{0.2}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ci}\DUrole{o}{=}\DUrole{default_value}{0.95}}\sphinxparamcomma \sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 7)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Joint plot of estimated CUB models in the parameter space

\sphinxAtStartPar
Return a plot of estimated CUB models represented as points in the parameter space.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ords}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} list of arrays of observed ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{model}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} model; defaults to \sphinxcode{\sphinxupquote{cub}}; options \sphinxcode{\sphinxupquote{cube}}

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{title}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} title of the plot

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{labels}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} labels of the points

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{shs}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} shelter effect(s); can be an \sphinxstyleemphasis{int} if the same shelter
effect is valid for all samples or a \sphinxstyleemphasis{list} to specify different
shelter choices

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{plot}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if \sphinxcode{\sphinxupquote{True}} (default) plot the results;

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{print\_res}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if \sphinxcode{\sphinxupquote{True}} print the results; defaults to \sphinxcode{\sphinxupquote{False}}

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pos}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} position of the \(\delta\) or \(\phi\) estimated values

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{xlim}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}) \textendash{} x\sphinxhyphen{}axis limits

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ylim}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}) \textendash{} y\sphinxhyphen{}axis limits

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{equal}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if the plot must have equal aspect; defaults to \sphinxcode{\sphinxupquote{True}}

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{alpha}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} confidence ellipse transparency

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{confell}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}) \textendash{} if \sphinxcode{\sphinxupquote{True}} (default) plot confidence ellipse (for CUB model only)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ci}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} level \((1-\alpha/2)\) for the confidence ellipse

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}}

\end{description}\end{quote}

\end{fulllineitems}

\index{pos\_kwargs() (in module cubmods.multicub)@\spxentry{pos\_kwargs()}\spxextra{in module cubmods.multicub}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.multicub.pos_kwargs}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxcode{\sphinxupquote{cubmods.multicub.}}\sphinxbfcode{\sphinxupquote{pos\_kwargs}}}{\sphinxparam{\DUrole{n}{pos}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Position of the \(\delta\) or \(\phi\) estimated values

\begin{sphinxVerbatim}[commandchars=\\\{\}]
    1
  8   2
7   @   3
  6   4
    5
\end{sphinxVerbatim}
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pos}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} position (1..8)

\sphinxlineitem{Returns}
\sphinxAtStartPar
a dictionary for \sphinxcode{\sphinxupquote{matplotlib}}

\sphinxlineitem{Return type}
\sphinxAtStartPar
dict

\end{description}\end{quote}

\end{fulllineitems}



\subsection{cubmods.smry module}
\label{\detokenize{cubmods:module-cubmods.smry}}\label{\detokenize{cubmods:cubmods-smry-module}}\index{module@\spxentry{module}!cubmods.smry@\spxentry{cubmods.smry}}\index{cubmods.smry@\spxentry{cubmods.smry}!module@\spxentry{module}}
\sphinxAtStartPar
CUB models in Python.
Module for summary tools.


\subsubsection{Description:}
\label{\detokenize{cubmods:id92}}\begin{quote}

\sphinxAtStartPar
This module contains methods and classes
for summary tools.
\end{quote}


\subsubsection{List of TODOs:}
\label{\detokenize{cubmods:id93}}\begin{itemize}
\item {} 
\sphinxAtStartPar
TODO: risultati inferenziali come DataFrame nel Manuale e negli esempi

\item {} 
\sphinxAtStartPar
TODO: bounds opzionali in CUBE mle (anche CUBSH?)

\item {} 
\sphinxAtStartPar
TODO: 2 decimali nei 3d plot?

\item {} 
\sphinxAtStartPar
TODO: dissim in multicub plot (aggiungere opzione)

\item {} 
\sphinxAtStartPar
TODO: grandezza punti phi in multicube

\end{itemize}


\subsubsection{Credits}
\label{\detokenize{cubmods:id94}}\begin{quote}
\begin{quote}\begin{description}
\sphinxlineitem{Author}
\sphinxAtStartPar
Massimo Pierini

\sphinxlineitem{Date}
\sphinxAtStartPar
2023\sphinxhyphen{}24

\sphinxlineitem{Credits}
\sphinxAtStartPar
Domenico Piccolo, Rosaria Simone

\sphinxlineitem{Contacts}
\sphinxAtStartPar
\sphinxhref{mailto:cub@maxpierini.it}{cub@maxpierini.it}

\end{description}\end{quote}
\end{quote}


\subsubsection{Classes and Functions}
\label{\detokenize{cubmods:id95}}\index{CUBres (class in cubmods.smry)@\spxentry{CUBres}\spxextra{class in cubmods.smry}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.smry.CUBres}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.smry.}}\sphinxbfcode{\sphinxupquote{CUBres}}}{\sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{n}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sample}}\sphinxparamcomma \sphinxparam{\DUrole{n}{f}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{est\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{estimates}}\sphinxparamcomma \sphinxparam{\DUrole{n}{e\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{varmat}}\sphinxparamcomma \sphinxparam{\DUrole{n}{stderrs}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pval}}\sphinxparamcomma \sphinxparam{\DUrole{n}{wald}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglike}}\sphinxparamcomma \sphinxparam{\DUrole{n}{muloglik}}\sphinxparamcomma \sphinxparam{\DUrole{n}{loglikuni}}\sphinxparamcomma \sphinxparam{\DUrole{n}{AIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{BIC}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seconds}}\sphinxparamcomma \sphinxparam{\DUrole{n}{time\_exe}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksat}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{dev}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{logliksatcov}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{niter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{maxiter}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{rho}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ass\_pars}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: \sphinxcode{\sphinxupquote{object}}

\sphinxAtStartPar
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 \sphinxcode{\sphinxupquote{.mle()}}
functions of model modules.
\begin{quote}\begin{description}
\sphinxlineitem{Variables}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{model}} \textendash{} the model family

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} \textendash{} the original DataFrame with observed sample and covariates (if any)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} \textendash{} the formula used to fit the data

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} \textendash{} number of observed ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sample}} \textendash{} the observed sample of ordinal resposes

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{f}} \textendash{} absolute frequecies of the sample

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{theoric}} \textendash{} estimated probabilty distribution

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{diss}} \textendash{} dissimilarity index

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{est\_names}} \textendash{} name of estimated parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{estimates}} \textendash{} values of estimated parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{e\_types}} \textendash{} parameters’ component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{varmat}} \textendash{} variance\sphinxhyphen{}covariance matrix of estimated parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{srtderrs}} \textendash{} standard errors of estimated parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pval}} \textendash{} p\sphinxhyphen{}values of estimated parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{wald}} \textendash{} Wald test statistics of estimated parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{loglike}} \textendash{} log\sphinxhyphen{}likelihood value

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{muloglik}} \textendash{} average log\sphinxhyphen{}likelihood for each observation

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{loglikuni}} \textendash{} log\sphinxhyphen{}likelihood of null model

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{AIC}} \textendash{} Akaike Information Criterion

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{BIC}} \textendash{} Bayesian Information Criterino

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seconds}} \textendash{} execution time of the algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{time\_exe}} \textendash{} when the algorithm has been executed

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{logliksat}} \textendash{} log\sphinxhyphen{}likelihood of saturated model (for models without covariates only)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{logliksatcov}} \textendash{} \sphinxstylestrong{deprecated}

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{dev}} \textendash{} deviance

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{niter}} \textendash{} number of iterations of the EM algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{maxiter}} \textendash{} maximum number of iterations of the EM algorithm

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{tol}} \textendash{} fixed error tolerance

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} \textendash{} shelter choice(s), if any

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{rho}} \textendash{} coefficient of correlation between \(\pi\) and \(\xi\)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ass\_pars}} \textendash{} parameters of known model to be compared with the estimates

\end{itemize}

\end{description}\end{quote}
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.smry.CUBres.as_dataframe}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{as\_dataframe}}}}}()
&
\sphinxAtStartPar
DataFrame of estimated parameters
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.smry.CUBres.as_txt}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{as\_txt}}}}}()
&
\sphinxAtStartPar
Print the summary.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.smry.CUBres.save}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{save}}}}}(fname)
&
\sphinxAtStartPar
Save a CUBresult object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.smry.CUBres.summary}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{summary}}}}}()
&
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{as\_dataframe() (cubmods.smry.CUBres method)@\spxentry{as\_dataframe()}\spxextra{cubmods.smry.CUBres method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.smry.CUBres.as_dataframe}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{as\_dataframe}}}{}{}
\pysigstopsignatures
\sphinxAtStartPar
DataFrame of estimated parameters

\end{fulllineitems}

\index{as\_txt() (cubmods.smry.CUBres method)@\spxentry{as\_txt()}\spxextra{cubmods.smry.CUBres method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.smry.CUBres.as_txt}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{as\_txt}}}{}{}
\pysigstopsignatures
\sphinxAtStartPar
Print the summary. Auxiliary function of \sphinxcode{\sphinxupquote{summary()}}.

\end{fulllineitems}

\index{save() (cubmods.smry.CUBres method)@\spxentry{save()}\spxextra{cubmods.smry.CUBres method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.smry.CUBres.save}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{save}}}{\sphinxparam{\DUrole{n}{fname}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Save a CUBresult object to file
named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{.cub.fit}}

\end{fulllineitems}

\index{summary() (cubmods.smry.CUBres method)@\spxentry{summary()}\spxextra{cubmods.smry.CUBres method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.smry.CUBres.summary}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{summary}}}{}{}
\pysigstopsignatures
\sphinxAtStartPar
Call \sphinxcode{\sphinxupquote{as\_txt()}}

\end{fulllineitems}


\end{fulllineitems}

\index{CUBsample (class in cubmods.smry)@\spxentry{CUBsample}\spxextra{class in cubmods.smry}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.smry.CUBsample}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class\DUrole{w}{ }}}\sphinxcode{\sphinxupquote{cubmods.smry.}}\sphinxbfcode{\sphinxupquote{CUBsample}}}{\sphinxparam{\DUrole{n}{rv}}\sphinxparamcomma \sphinxparam{\DUrole{n}{m}}\sphinxparamcomma \sphinxparam{\DUrole{n}{pars}}\sphinxparamcomma \sphinxparam{\DUrole{n}{model}}\sphinxparamcomma \sphinxparam{\DUrole{n}{df}}\sphinxparamcomma \sphinxparam{\DUrole{n}{formula}}\sphinxparamcomma \sphinxparam{\DUrole{n}{diss}}\sphinxparamcomma \sphinxparam{\DUrole{n}{theoric}}\sphinxparamcomma \sphinxparam{\DUrole{n}{par\_names}}\sphinxparamcomma \sphinxparam{\DUrole{n}{p\_types}}\sphinxparamcomma \sphinxparam{\DUrole{n}{sh}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{seed}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Bases: \sphinxcode{\sphinxupquote{object}}

\sphinxAtStartPar
An instance of this Class is returned by \sphinxcode{\sphinxupquote{.draw()}} functions. 
See the corresponding model’s function for details.
\begin{quote}\begin{description}
\sphinxlineitem{Variables}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{rv}} \textendash{} array of drawn ordinal responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{m}} \textendash{} number of ordinal categories

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{n}} \textendash{} number of drawn responses

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{p}} \textendash{} number of model’s parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{pars}} \textendash{} parameters’ values array

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{model}} \textendash{} the model family

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{df}} \textendash{} original DataFrame (if provided) with a column of the drawn sample

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{formula}} \textendash{} the formula used to draw the sample

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{diss}} \textendash{} dissimilarity index between drawn and theoretical distribution

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{theoric}} \textendash{} theoretical distribution

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{par\_names}} \textendash{} names of the parameters

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{p\_types}} \textendash{} parameters’ component

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{sh}} \textendash{} shelter choice(s), if any

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{seed}} \textendash{} the \sphinxcode{\sphinxupquote{seed}} used to ensure reproducibility

\end{itemize}

\end{description}\end{quote}
\subsubsection*{Methods}


\begin{savenotes}\sphinxattablestart
\sphinxthistablewithglobalstyle
\sphinxthistablewithnovlinesstyle
\centering
\begin{tabulary}{\linewidth}[t]{\X{1}{2}\X{1}{2}}
\sphinxtoprule
\sphinxtableatstartofbodyhook
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.smry.CUBsample.as_dataframe}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{as\_dataframe}}}}}()
&
\sphinxAtStartPar
The parameters\textquotesingle{} values specified.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.smry.CUBsample.plot}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{plot}}}}}({[}figsize, kind, ax, saveas{]})
&
\sphinxAtStartPar
Basic plot function.
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.smry.CUBsample.save}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{save}}}}}(fname)
&
\sphinxAtStartPar
Save a CUBsample object to file named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{cub.sample}}
\\
\sphinxhline
\sphinxAtStartPar
{\hyperref[\detokenize{cubmods:cubmods.smry.CUBsample.summary}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{summary}}}}}()
&
\sphinxAtStartPar
Print the summary of the drawn sample.
\\
\sphinxbottomrule
\end{tabulary}
\sphinxtableafterendhook\par
\sphinxattableend\end{savenotes}
\index{as\_dataframe() (cubmods.smry.CUBsample method)@\spxentry{as\_dataframe()}\spxextra{cubmods.smry.CUBsample method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.smry.CUBsample.as_dataframe}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{as\_dataframe}}}{}{}
\pysigstopsignatures
\sphinxAtStartPar
The parameters’ values specified.
\begin{quote}\begin{description}
\sphinxlineitem{Returns}
\sphinxAtStartPar
a DataFrame with parameters’ names and values

\sphinxlineitem{Return type}
\sphinxAtStartPar
DataFrame

\end{description}\end{quote}

\end{fulllineitems}

\index{plot() (cubmods.smry.CUBsample method)@\spxentry{plot()}\spxextra{cubmods.smry.CUBsample method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.smry.CUBsample.plot}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{plot}}}{\sphinxparam{\DUrole{n}{figsize}\DUrole{o}{=}\DUrole{default_value}{(7, 5)}}\sphinxparamcomma \sphinxparam{\DUrole{n}{kind}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}bar\textquotesingle{}}}\sphinxparamcomma \sphinxparam{\DUrole{n}{ax}\DUrole{o}{=}\DUrole{default_value}{None}}\sphinxparamcomma \sphinxparam{\DUrole{n}{saveas}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Basic plot function.
\begin{quote}\begin{description}
\sphinxlineitem{Parameters}\begin{itemize}
\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{figsize}} (\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}\sphinxstyleliteralemphasis{\sphinxupquote{ of }}\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} tuple of \sphinxcode{\sphinxupquote{(length, height)}} for the figure (useful only if \sphinxcode{\sphinxupquote{ax}} is not None)

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{kind}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} choose a barplot (\sphinxcode{\sphinxupquote{\textquotesingle{}bar\textquotesingle{}}} default) of a scatterplot (\sphinxcode{\sphinxupquote{\textquotesingle{}scatter\textquotesingle{}}})

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{ax}} (\sphinxstyleliteralemphasis{\sphinxupquote{matplolib ax}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{optional}}) \textendash{} matplotlib axis, if None a new figure will be created, defaults to None

\item {} 
\sphinxAtStartPar
\sphinxstyleliteralstrong{\sphinxupquote{saveas}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} if provided, name of the file to save the plot

\end{itemize}

\sphinxlineitem{Returns}
\sphinxAtStartPar
\sphinxcode{\sphinxupquote{ax}} or a tuple \sphinxcode{\sphinxupquote{(fig, ax)}}

\end{description}\end{quote}

\end{fulllineitems}

\index{save() (cubmods.smry.CUBsample method)@\spxentry{save()}\spxextra{cubmods.smry.CUBsample method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.smry.CUBsample.save}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{save}}}{\sphinxparam{\DUrole{n}{fname}}}{}
\pysigstopsignatures
\sphinxAtStartPar
Save a CUBsample object to file
named \sphinxcode{\sphinxupquote{fname}} + \sphinxcode{\sphinxupquote{cub.sample}}

\end{fulllineitems}

\index{summary() (cubmods.smry.CUBsample method)@\spxentry{summary()}\spxextra{cubmods.smry.CUBsample method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{cubmods:cubmods.smry.CUBsample.summary}}
\pysigstartsignatures
\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{summary}}}{}{}
\pysigstopsignatures
\sphinxAtStartPar
Print the summary of the drawn sample.

\end{fulllineitems}


\end{fulllineitems}



\subsection{Module contents}
\label{\detokenize{cubmods:module-cubmods}}\label{\detokenize{cubmods:module-contents}}\index{module@\spxentry{module}!cubmods@\spxentry{cubmods}}\index{cubmods@\spxentry{cubmods}!module@\spxentry{module}}
\sphinxstepscope


\chapter{References}
\label{\detokenize{references:references}}\label{\detokenize{references::doc}}

\chapter{Indices and tables}
\label{\detokenize{index:indices-and-tables}}\begin{itemize}
\item {} 
\sphinxAtStartPar
\DUrole{xref,std,std-ref}{genindex}

\item {} 
\sphinxAtStartPar
\DUrole{xref,std,std-ref}{modindex}

\item {} 
\sphinxAtStartPar
\DUrole{xref,std,std-ref}{search}

\end{itemize}

\begin{sphinxthebibliography}{IPSMaint}
\bibitem[CP17]{references:id11}
\sphinxAtStartPar
Stefania Capecchi and Domenico Piccolo. Dealing with heterogeneity in ordinal responses. \sphinxstyleemphasis{Quality \& Quantity}, 51:2375\textendash{}2393, 2017.
\bibitem[CSDI+21]{references:id29}
\sphinxAtStartPar
Giovanni Cerulli, R Simone, Francesca Di Iorio, D Piccolo, CF Baum, and others. The Stata module for CUB models for rating data analysis. In \sphinxstyleemphasis{London Stata Conference 2021}, number 16. Stata Users Group, 2021.
\bibitem[CIP09]{references:id10}
\sphinxAtStartPar
Marcella Corduas, Maria Iannario, and Domenico Piccolo. A class of statistical models for evaluating services and performances. In \sphinxstyleemphasis{Statistical methods for the evaluation of educational services and quality of products}, pages 99\textendash{}117. Springer, 2009.
\bibitem[DEliaP+05]{references:id19}
\sphinxAtStartPar
A D\textquotesingle{}Elia, Domenico Piccolo, and others. The moment estimator for the IHG distribution. In \sphinxstyleemphasis{S. Co. Modelli complessi e metodi computazionali intensivi per la stima e la previsione}, pages 245\textendash{}250. CLEUP, 2005.
\bibitem[DEliaP05]{references:id5}
\sphinxAtStartPar
Angela D\textquotesingle{}Elia and Domenico Piccolo. A mixture model for preferences data analysis. \sphinxstyleemphasis{Computational Statistics \& Data Analysis}, 49(3):917\textendash{}934, 2005.
\bibitem[DElia03]{references:id18}
\sphinxAtStartPar
Angela D’Elia. Modelling ranks using the inverse hypergeometric distribution. \sphinxstyleemphasis{Statistical modelling}, 3(1):65\textendash{}78, 2003.
\bibitem[Ian12a]{references:id16}
\sphinxAtStartPar
Maria Iannario. Cube models for interpreting ordered categorical data with overdispersion. \sphinxstyleemphasis{Quaderni di statistica}, 14:137\textendash{}140, 2012.
\bibitem[Ian12b]{references:id9}
\sphinxAtStartPar
Maria Iannario. Modelling shelter choices in a class of mixture models for ordinal responses. \sphinxstyleemphasis{Statistical Methods \& Applications}, 21:1\textendash{}22, 2012.
\bibitem[Ian14]{references:id17}
\sphinxAtStartPar
Maria Iannario. Modelling uncertainty and overdispersion in ordinal data. \sphinxstyleemphasis{Communications in Statistics\sphinxhyphen{}Theory and Methods}, 43(4):771\textendash{}786, 2014.
\bibitem[IP09]{references:id21}
\sphinxAtStartPar
Maria Iannario and Domenico Piccolo. A program in R for CUB models inference. \sphinxstyleemphasis{Available via Internet, URL http://www. dipstat. unina. it/CUBmodels/, Version}, 2009.
\bibitem[IP10]{references:id8}
\sphinxAtStartPar
Maria Iannario and Domenico Piccolo. A new statistical model for the analysis of customer satisfaction. \sphinxstyleemphasis{Quality Technology \& Quantitative Management}, 7(2):149\textendash{}168, 2010.
\bibitem[IP+14]{references:id22}
\sphinxAtStartPar
Maria Iannario, Domenico Piccolo, and others. Inference for CUB models: a program in R. \sphinxstyleemphasis{Statistica \& Applicazioni}, 12(2):177\textendash{}204, 2014.
\bibitem[IPSMaintainer22]{references:id23}
\sphinxAtStartPar
Maria Iannario, Domenico Piccolo, and Rosaria Simone (Maintainer). Package ‘CUB’. \sphinxstyleemphasis{CRAN}, 2022.
\bibitem[Pic03]{references:id4}
\sphinxAtStartPar
Domenico Piccolo. On the moments of a mixture of uniform and shifted binomial random variables. \sphinxstyleemphasis{Quaderni di Statistica}, 5(1):85\textendash{}104, 2003.
\bibitem[Pic06]{references:id7}
\sphinxAtStartPar
Domenico Piccolo. Observed information matrix for MUB models. \sphinxstyleemphasis{Quaderni di Statistica}, 8(1):33\textendash{}78, 2006.
\bibitem[Pic15]{references:id15}
\sphinxAtStartPar
Domenico Piccolo. Inferential issues on cube models with covariates. \sphinxstyleemphasis{Communications in Statistics\sphinxhyphen{}Theory and Methods}, 44(23):5023\textendash{}5036, 2015.
\bibitem[PS19]{references:id3}
\sphinxAtStartPar
Domenico Piccolo and Rosaria Simone. The class of CUB models: statistical foundations, inferential issues and empirical evidence (with discussion and rejoinder). \sphinxstyleemphasis{Statistical Methods \& Applications}, 28:389\textendash{}493, 2019.
\bibitem[Pie24]{references:id42}
\sphinxAtStartPar
Massimo Pierini. Modelli della classe CUB in python. \sphinxstyleemphasis{Universitas Mercatorum, Rome, IT}, pages 1\textendash{}172, June 2024. (Bachelor\textquotesingle{}s thesis L\sphinxhyphen{}41).
\bibitem[PL20]{references:id28}
\sphinxAtStartPar
W Stephen Pittard and Shuzhao Li. The essential toolbox of data science: python, R, git, and docker. \sphinxstyleemphasis{Computational Methods and Data Analysis for Metabolomics}, pages 265\textendash{}311, 2020.
\bibitem[Sim22]{references:id12}
\sphinxAtStartPar
Rosaria Simone. On finite mixtures of Discretized Beta model for ordered responses. \sphinxstyleemphasis{TEST}, 31(3):828\textendash{}855, 2022.
\bibitem[SDIL19]{references:id30}
\sphinxAtStartPar
Rosaria Simone, Francesca Di Iorio, and Riccardo Lucchetti. CUB for gretl. \sphinxstyleemphasis{GNU Regression, Econometrics and Time Series Library}, pages 147, 2019.
\bibitem[ST18]{references:id13}
\sphinxAtStartPar
Rosaria Simone and Gerhard Tutz. Modelling uncertainty and response styles in ordinal data. \sphinxstyleemphasis{Statistica Neerlandica}, 72(3):224\textendash{}245, 2018.
\end{sphinxthebibliography}


\renewcommand{\indexname}{Python Module Index}
\begin{sphinxtheindex}
\let\bigletter\sphinxstyleindexlettergroup
\bigletter{c}
\item\relax\sphinxstyleindexentry{cubmods}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods}}
\item\relax\sphinxstyleindexentry{cubmods.cub}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cub}}
\item\relax\sphinxstyleindexentry{cubmods.cub\_0w}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cub_0w}}
\item\relax\sphinxstyleindexentry{cubmods.cub\_y0}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cub_y0}}
\item\relax\sphinxstyleindexentry{cubmods.cub\_yw}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cub_yw}}
\item\relax\sphinxstyleindexentry{cubmods.cube}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cube}}
\item\relax\sphinxstyleindexentry{cubmods.cube\_0w0}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cube_0w0}}
\item\relax\sphinxstyleindexentry{cubmods.cube\_ywz}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cube_ywz}}
\item\relax\sphinxstyleindexentry{cubmods.cubsh}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cubsh}}
\item\relax\sphinxstyleindexentry{cubmods.cubsh\_ywx}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cubsh_ywx}}
\item\relax\sphinxstyleindexentry{cubmods.cush}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cush}}
\item\relax\sphinxstyleindexentry{cubmods.cush2}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cush2}}
\item\relax\sphinxstyleindexentry{cubmods.cush2\_x0}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cush2_x0}}
\item\relax\sphinxstyleindexentry{cubmods.cush2\_xx}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cush2_xx}}
\item\relax\sphinxstyleindexentry{cubmods.cush\_x}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.cush_x}}
\item\relax\sphinxstyleindexentry{cubmods.gem}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.gem}}
\item\relax\sphinxstyleindexentry{cubmods.general}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.general}}
\item\relax\sphinxstyleindexentry{cubmods.ihg}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.ihg}}
\item\relax\sphinxstyleindexentry{cubmods.ihg\_v}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.ihg_v}}
\item\relax\sphinxstyleindexentry{cubmods.multicub}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.multicub}}
\item\relax\sphinxstyleindexentry{cubmods.smry}\sphinxstyleindexpageref{cubmods:\detokenize{module-cubmods.smry}}
\end{sphinxtheindex}

\renewcommand{\indexname}{Index}
\printindex
\end{document}