naginterfaces.library.contab.binary

naginterfaces.library.contab.binary(n, gprob, x, irl, a, c, cgetol, chisqr, iprint=1, maxit=1000, ishow=0, io_manager=None)

binary fits a latent variable model (with a single factor) to data consisting of a set of measurements on individuals in the form of binary-valued sequences (generally referred to as score patterns). Various measures of goodness-of-fit are calculated along with the factor (theta) scores.

For full information please refer to the NAG Library document for g11sa

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/g11/g11saf.html

Parameters

nint

$n$, the number of individuals in the sample.

gprobbool

Must be set equal to $True$ if $G\left(z\right)={\Phi }^{-1}\left(z\right)$ and $False$ if $G\left(z\right)=logit\left(z\right)$.

xbool, array-like, shape $(\text{ns},\text{ip})$

The first $s$ rows of $x$ must contain the $s$ different score patterns. The $l$th row of $x$ must contain the $l$th score pattern with $x[l-1,j-1]$ set equal to $True$ if $x_{lj}=1$ and $False$ if $x_{lj}=0$. All rows of $x$ must be distinct.

irlint, array-like, shape $\left(\text{ns}\right)$

The $i$th component of $irl$ must be set equal to the frequency with which the $i$th row of $x$ occurs.

afloat, array-like, shape $\left(\text{ip}\right)$

$a[j-1]$ must be set equal to an initial estimate of ${\alpha }_{j1}$. In order to avoid divergence problems with the E-M algorithm you are strongly advised to set all the $a[j-1]$ to $0.5$ .

cfloat, array-like, shape $\left(\text{ip}\right)$

$c[j-1]$ must be set equal to an initial estimate of ${\alpha }_{j0}$. In order to avoid divergence problems with the E-M algorithm you are strongly advised to set all the $c[j-1]$ to $0.0$ .

cgetolfloat

The accuracy to which the solution is required.

If $cgetol$ is set to ${10}^{-l}$ and on exit the function exits successfully or $errno$ = 7, then all elements of the gradient vector will be smaller than ${10}^{-l}$ in absolute value.

For most practical purposes the value ${10}^{-4}$ should suffice.

You should be wary of setting $cgetol$ too small since the convergence criterion may then have become too strict for the machine to handle.

If $cgetol$ has been set to a value which is less than the square root of the machine precision, $ϵ$, then binary will use the value $\sqrt{ϵ}$ instead.

chisqrbool

If $chisqr$ is set equal to $True$, a likelihood ratio statistic will be calculated (see $chi$).

If $chisqr$ is set equal to $False$, no such statistic will be calculated.

iprintint, optional

The frequency with which the maximum likelihood search function is to be monitored.

$iprint>0$

The search is monitored once every $iprint$ iterations, and when the number of quadrature points is increased, and again at the final solution point.

$iprint=0$

The search is monitored once at the final point.

$iprint<0$

The search is not monitored at all.

$iprint$ should normally be set to a small positive number.

maxitint, optional

The maximum number of iterations to be made in the maximum likelihood search. There will be an error exit (see Exceptions) if the search function has not converged in $maxit$ iterations.

ishowint, optional

Indicates which of the following three quantities are to be printed before exit from the function (given a valid parameter set):

1. Table of maximum likelihood estimates and standard errors (as returned in the output arrays $a$, $c$, $alpha$, $pigam$ and $cm$).

2. Table of observed and expected first - and second-order margins (as returned in the output arrays $expp$ and $obs$).

3. Table of observed and expected frequencies of score patterns along with theta scores (as returned in the output arrays $irl$, $exf$, $y$, $xl$ and $iob$) and the likelihood ratio statistic (if required).

$ishow=0$

None of the above are printed.

$ishow=1$

(a) only is printed.

$ishow=2$

(b) only is printed.

$ishow=3$

(c) only is printed.

$ishow=4$

(a) and (b) are printed.

$ishow=5$

(a) and (c) are printed.

$ishow=6$

(b) and (c) are printed.

$ishow=7$

(a), (b) and (c) are printed.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns

xbool, ndarray, shape $(\text{ns},\text{ip})$

Given a valid parameter set then the first $s$ rows of $x$ still contain the $s$ different score patterns. However, the following points should be noted:

1. If the estimated factor loading for the $j$th item is negative then that item is re-coded, i.e., $0$s and $1$s (or $True$ and $False$) in the $j$th column of $x$ are interchanged.

2. The rows of $x$ will be reordered so that the theta scores corresponding to rows of $x$ are in increasing order of magnitude.

irlint, ndarray, shape $\left(\text{ns}\right)$

Given a valid parameter set then the first $s$ components of $irl$ are reordered as are the rows of $x$.

afloat, ndarray, shape $\left(\text{ip}\right)$

$a[\text{j}-1]$ contains the latest estimate of ${\alpha }_{\text{j}1}$, for $\text{j}=1,2,\dots ,p$. (Because of possible recoding all elements of $a$ will be positive.)

cfloat, ndarray, shape $\left(\text{ip}\right)$

$c[\text{j}-1]$ contains the latest estimate of ${\alpha }_{\text{j}0}$, for $\text{j}=1,2,\dots ,p$.

niterint

Given a valid parameter set then $niter$ contains the number of iterations performed by the maximum likelihood search function.

alphafloat, ndarray, shape $\left(\text{ip}\right)$

Given a valid parameter set then $alpha[j-1]$ contains the latest estimate of ${\alpha }_j$. (Because of possible recoding all elements of $alpha$ will be positive.)

pigamfloat, ndarray, shape $\left(\text{ip}\right)$

Given a valid parameter set then $pigam[j-1]$ contains the latest estimate of either ${\pi }_j$ if $gprob=False$ (logit model) or ${\gamma }_j$ if $gprob=True$ (probit model).

cmfloat, ndarray, shape $(2\times \text{ip},2\times \text{ip})$

Given a valid parameter set then the strict lower triangle of $cm$ contains the correlation matrix of the parameter estimates held in $alpha$ and $pigam$ on exit. The diagonal elements of $cm$ contain the standard errors. Thus:

$cm[2\times i-2,2\times i-2]$	=	standard error $\left(alpha\right[i-1\left]\right)$
$cm[2\times i-1,2\times i-1]$	=	standard error $\left(pigam\right[i-1\left]\right)$
$cm[2\times i-1,2\times i-2]$	=	correlation $(pigam[i-1],alpha[i-1])$,

for $i=1,2,\dots ,p$;

$cm[2\times i-2,2\times j-2]$	=	correlation $(alpha[i-1],alpha[j-1])$
$cm[2\times i-1,2\times j-1]$	=	correlation $(pigam[i-1],pigam[j-1])$
$cm[2\times i-2,2\times j-1]$	=	correlation $(alpha[i-1],pigam[j-1])$
$cm[2\times i-1,2\times j-2]$	=	correlation $(alpha[j-1],pigam[i-1])$,

for $j=1,2,\dots ,i-1$.

If the second derivative matrix cannot be computed then all the elements of $cm$ are returned as zero.

gfloat, ndarray, shape $(2\times \text{ip})$

Given a valid parameter set then $g$ contains the estimated gradient vector corresponding to the final point held in the arrays $alpha$ and $pigam$. $g[2\times \text{j}-2]$ contains the derivative of the log-likelihood with respect to $alpha[\text{j}-1]$, for $\text{j}=1,2,\dots ,p$. $g[2\times \text{j}-1]$ contains the derivative of the log-likelihood with respect to $pigam[\text{j}-1]$, for $\text{j}=1,2,\dots ,p$.

exppfloat, ndarray, shape $(\text{ip},\text{ip})$

Given a valid parameter set then $expp[i-1,j-1]$ contains the expected percentage of individuals in the sample who respond positively to items $i$ and $j$ ($j\le i$), corresponding to the final point held in the arrays $alpha$ and $pigam$.

obsfloat, ndarray, shape $(\text{ip},\text{ip})$

Given a valid parameter set then $obs[i-1,j-1]$ contains the observed percentage of individuals in the sample who responded positively to items $i$ and $j$ ($j\le i$).

exffloat, ndarray, shape $\left(\text{ns}\right)$

Given a valid parameter set then $exf[l-1]$ contains the expected frequency of the $l$th score pattern ($l$th row of $x$), corresponding to the final point held in the arrays $alpha$ and $pigam$.

yfloat, ndarray, shape $\left(\text{ns}\right)$

Given a valid parameter set then $y[l-1]$ contains the estimated theta score corresponding to the $l$th row of $x$, for the final point held in the arrays $alpha$ and $pigam$.

xlfloat, ndarray, shape $(:)$

If $gprob$ has been set equal to $False$ (logit model) then, given a valid parameter set, $xl[l-1]$ contains the estimated component score corresponding to the $l$th row of $x$ for the final point held in the arrays $alpha$ and $pigam$.

If $gprob$ is set equal to $True$ (probit model), this array is not used.

iobint, ndarray, shape $\left(\text{ns}\right)$

Given a valid parameter set then $iob[l-1]$ contains the number of items in the $l$th row of $x$ for which the response was positive ($True$).

rloglfloat

Given a valid parameter set then $rlogl$ contains the value of the log-likelihood kernel corresponding to the final point held in the arrays $alpha$ and $pigam$, namely

$$\sum _{l=0}^{s-1}irl\left[l\right]\times \log \left(exf\right[l\left]/n\right)\text{.}$$

chifloat

If $chisqr$ was set equal to $True$ on entry, then given a valid parameter set, $chi$ will contain the value of the likelihood ratio statistic corresponding to the final parameter estimates held in the arrays $alpha$ and $pigam$, namely

$$2\times \sum _{l=0}^{s-1}irl\left[l\right]\times \log \left(exf\right[l\left]/irl\right[l\left]\right)\text{.}$$

The summation is over those elements of $irl$ which are positive. If $exf[l-1]$ is less than $5.0$, then adjacent score patterns are pooled (the score patterns in $x$ being first put in order of increasing theta score).

If $chisqr$ has been set equal to $False$, then $chi$ is not used.

idfint

If $chisqr$ was set equal to $True$ on entry, then given a valid parameter set, $idf$ will contain the degrees of freedom associated with the likelihood ratio statistic, $chi$.

$idf=s_0-2\times p$	if $s_0<2^p$;
$idf=s_0-2\times p-1$	if $s_0=2^p$,

where $s_0$ denotes the number of terms summed to calculate $chi$ ($s_0=s$ only if there is no pooling).

If $chisqr$ has been set equal to $False$, $idf$ is not used.

siglevfloat

If $chisqr$ was set equal to $True$ on entry, then given a valid parameter set, $siglev$ will contain the significance level of $chi$ based on $idf$ degrees of freedom. If $idf$ is zero or negative then $siglev$ is set to zero.

If $chisqr$ was set equal to $False$, $siglev$ is not used.

Raises

NagValueError

(errno $1$)

On entry, ${\sum }_i\left(irl\right[i\left]\right)=⟨value⟩$ and $n=⟨value⟩$.

Constraint: ${\sum }_i\left(irl\right[i\left]\right)=n$.

(errno $1$)

On entry, $i=⟨value⟩$ and $irl[i-1]=⟨value⟩$.

Constraint: $irl[i-1]\ge 0$.

(errno $1$)

On entry, $i=⟨value⟩$ and $j=⟨value⟩$.

Constraint: rows $i$ and $j$ of $x$ should not be identical.

(errno $1$)

On entry, $\text{ns}=⟨value⟩$ and $\text{ip}=⟨value⟩$.

Constraint: $\text{ns}>2\times \text{ip}$.

(errno $1$)

On entry, $\text{ip}=⟨value⟩$.

Constraint: $\text{ip}\ge 3$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 7$.

(errno $1$)

On entry, $ishow=⟨value⟩$.

Constraint: $ishow=0$, $1$, $2$, $3$, $4$, $5$, $6$ or $7$.

(errno $1$)

On entry, $\text{ns}=⟨value⟩$ and $\text{ip}=⟨value⟩$.

Constraint: $\text{ns}\le 2^{\text{ip}}$.

(errno $1$)

On entry, $\text{ns}=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $\text{ns}\le n$.

(errno $1$)

On entry, $maxit=⟨value⟩$.

Constraint: $maxit\ge 1$.

(errno $2$)

For at least one of the $\text{ip}$ items the responses are all at the same level.

(errno $3$)

$maxit$ iterations have been performed: $maxit=⟨value⟩$.

(errno $4$)

One of the elements of $a$ has exceeded $10$ in absolute.

(errno $5$)

Failure to invert Hessian matrix and $maxit$ iterations made: $maxit=⟨value⟩$.

(errno $6$)

Failure to invert Hessian matrix plus Heywood case encountered.

Warns

NagAlgorithmicWarning

(errno $7$)

${\chi }^2$ statistic has less than one degree of freedom.

Notes

Given a set of $p$ dichotomous variables $\tilde{x}={(x_1,x_2,\dots ,x_p)}^{\prime }$, where ${}^{\prime }$ denotes vector or matrix transpose, the objective is to investigate whether the association between them can be adequately explained by a latent variable model of the form (see Bartholomew (1980) and Bartholomew (1987))

$$G\left\{{\pi }_i\left(\theta \right)\right\}={\alpha }_{i0}+{\alpha }_{i1}\theta \text{.}$$

The $x_i$ are called item responses and take the value $0$ or $1$. $\theta$ denotes the latent variable assumed to have a standard Normal distribution over a population of individuals to be tested on $p$ items. Call ${\pi }_i\left(\theta \right)=P(x_i=1|\theta )$ the item response function: it represents the probability that an individual with latent ability $\theta$ will produce a positive response (1) to item $i$. ${\alpha }_{i0}$ and ${\alpha }_{i1}$ are item parameters which can assume any real values. The set of parameters, ${\alpha }_{\text{i}1}$, for $\text{i}=1,2,\dots ,p$, being coefficients of the unobserved variable $\theta$, can be interpreted as ‘factor loadings’.

$G$ is a function selected by you as either ${\Phi }^{-1}$ or logit, mapping the interval $(0,1)$ onto the whole real line. Data from a random sample of $n$ individuals takes the form of the matrices $X$ and $R$ defined below:

$$\begin{array}{c}{X}_{s\times p}=\left[\begin{array}{cccc}{x}_{11}& x_{12}& \dots & x_{1p}\\ x_{21}& x_{22}& \dots & x_{2p}\\ ⋮& ⋮& & ⋮\\ x_{s1}& x_{s2}& \dots & x_{sp}\end{array}\right]=\left[\begin{array}{c}{\tilde{x}}_1\\ {\tilde{x}}_2\\ ⋮\\ {\tilde{x}}_s\end{array}\right]\text{,}{R}_{s\times 1}=\left[\begin{array}{c}{r}_1\\ r_2\\ ⋮\\ r_s\end{array}\right]\end{array}$$

where ${\tilde{x}}_l=(x_{l1},x_{l2},\dots ,x_{lp})$ denotes the $l$th score pattern in the sample, $r_l$ the frequency with which ${\tilde{x}}_l$ occurs and $s$ the number of different score patterns observed. (Thus ${\sum }_{l=1}^s{r}_l=n$). It can be shown that the log-likelihood function is proportional to

$$\sum _{l=1}^s{r}_l\log \left(P_l\right)\text{,}$$

where

$$P_l=P(\tilde{x}={\tilde{x}}_l)={\int }_{-\infty }^{\infty }P(\tilde{x}={\tilde{x}}_l|\theta )\varphi \left(\theta \right)d\theta$$

($\varphi \left(\theta \right)$ being the probability density function of a standard Normal random variable).

$P_l$ denotes the unconditional probability of observing score pattern ${\tilde{x}}_l$. The integral in (2) is approximated using Gauss–Hermite quadrature. If we take $G\left(z\right)=logit\left(z\right)=\log \left(\frac{z}{1-z}\right)$ in (1) and reparameterise as follows,

$$\begin{array}{c}\begin{array}{ccc}{\alpha }_i& =& {\alpha }_{i1}\text{,}\\ {\pi }_i& =& {logit}^{-1}\left({\alpha }_{i0}\right)\text{,}\end{array}\end{array}$$

then (1) reduces to the logit model (see Bartholomew (1980))

$${\pi }_i\left(\theta \right)=\frac{{\pi }_i}{{\pi }_i+(1-{\pi }_i)exp(-{\alpha }_i\theta )}\text{.}$$

If we take $G\left(z\right)={\Phi }^{-1}\left(z\right)$ (where $\Phi$ is the cumulative distribution function of a standard Normal random variable) and reparameterise as follows,

$$\begin{array}{c}\begin{array}{ccc}{\alpha }_i& =& \frac{{\alpha }_{i1}}{\sqrt{(1+{\alpha }_{i1}^2)}}\\ & & \\ & & \\ {\gamma }_i& =& \frac{-{\alpha }_{i0}}{\sqrt{(1+{\alpha }_{i1}^2)}}\end{array}\text{,}\end{array}$$

then (1) reduces to the probit model (see Bock and Aitkin (1981))

$${\pi }_i\left(\theta \right)=\varphi \left(\frac{{\alpha }_i\theta -{\gamma }_i}{\sqrt{(1-{\alpha }_i^2)}}\right)\text{.}$$

An E-M algorithm (see Bock and Aitkin (1981)) is used to maximize the log-likelihood function. The number of quadrature points used is set initially to $10$ and once convergence is attained increased to $20$.

The theta score of an individual responding in score pattern ${\tilde{x}}_l$ is computed as the posterior mean, i.e., $E\left(\theta |{\tilde{x}}_l\right)$. For the logit model the component score $X_l={\sum }_{j=1}^p{\alpha }_j{x}_{lj}$ is also calculated. (Note that in calculating the theta scores and measures of goodness-of-fit binary automatically reverses the coding on item $j$ if ${\alpha }_j<0$; it is assumed in the model that a response at the one level is showing a higher measure of latent ability than a response at the zero level.)

The frequency distribution of score patterns is required as input data. If your data is in the form of individual score patterns (uncounted), then binary_service() may be used to calculate the frequency distribution.

References

Bartholomew, D J, 1980, Factor analysis for categorical data (with Discussion), J. Roy. Statist. Soc. Ser. B (42), 293–321

Bartholomew, D J, 1987, Latent Variable Models and Factor Analysis, Griffin

Bock, R D and Aitkin, M, 1981, Marginal maximum likelihood estimation of item parameters: Application of an E-M algorithm, Psychometrika (46), 443–459