lba: Latent Budget Analysis (LBA) for Compositional Data

In ivanalaman/lba: Latent Budget Analysis for Compositional Data

Latent Budget Analysis (LBA) for Compositional Data

Description

Latent budget analysis (LBA) is a method for the analysis of contingency tables, from where the compositional data is derived. It is used to understand the relationship between the table rows and columns, where the rows denote the categories of the explanatory variable and the columns denote the categories of the response variable.

Usage

lba(obj, ...)

## S3 method for class 'matrix'
lba(obj,
    A           = NULL,
    B           = NULL,
    K           = 1L,
    cA          = NULL,
    cB          = NULL,
    logitA      = NULL,
    logitB      = NULL,
    omsk        = NULL,
    psitk       = NULL,
    S           = NULL,
    T           = NULL,
    row.weights = NULL,
    col.weights = NULL,
    tolG        = 1e-10,
    tolA        = 1e-05,
    tolB        = 1e-05,
    itmax.unide = 1e3,
    itmax.ide   = 1e3,
    trace.lba   = TRUE,
    toltype     = "all",
    method      = c("ls", "mle"),
    what        = c("inner","outer"), ...)

## S3 method for class 'table'
lba(obj,
    A           = NULL,
    B           = NULL,
    K           = 1L,
    cA          = NULL,
    cB          = NULL,
    logitA      = NULL,
    logitB      = NULL,
    omsk        = NULL,
    psitk       = NULL,
    S           = NULL,
    T           = NULL,
    row.weights = NULL,
    col.weights = NULL,
    tolG        = 1e-10,
    tolA        = 1e-05,
    tolB        = 1e-05,
    itmax.unide = 1e3,
    itmax.ide   = 1e3,
    trace.lba   = TRUE,
    toltype     = "all",
    method      = c("ls", "mle"),
    what        = c("inner","outer"), ...)

## S3 method for class 'formula'
lba(formula, data,
    A           = NULL,
    B           = NULL,
    K           = 1L,
    cA          = NULL,
    cB          = NULL,
    logitA      = NULL,
    logitB      = NULL,
    omsk        = NULL,
    psitk       = NULL,
    S           = NULL,
    T           = NULL,
    row.weights = NULL,
    col.weights = NULL,
    tolG        = 1e-10,
    tolA        = 1e-05,
    tolB        = 1e-05,
    itmax.unide = 1e3,
    itmax.ide   = 1e3,
    trace.lba   = TRUE,
    toltype     = "all",
    method      = c("ls", "mle"),
    what        = c("inner","outer"), ...)

## S3 method for class 'ls'
lba(obj,
    A           ,
    B           ,
    K           ,
    row.weights ,
    col.weights ,
    tolA        ,
    tolB        ,
    itmax.unide ,
    itmax.ide   ,
    trace.lba   ,
    what        , ...)

## S3 method for class 'mle'
lba(obj,
    A           ,
    B           ,
    K           ,
    tolG        ,
    tolA        ,
    tolB        ,
    itmax.unide ,
    itmax.ide   ,
    trace.lba   ,
    toltype     ,
    what        , ...)

## S3 method for class 'ls.fe'
lba(obj,
    A           ,
    B           ,
    K           ,
    cA          ,
    cB          ,
    row.weights ,
    col.weights ,
    itmax.ide   ,
    trace.lba   , ...)

## S3 method for class 'mle.fe'
lba(obj,
    A          ,
    B          ,
    K          ,
    cA         ,
    cB         ,
    tolG       ,
    tolA       ,
    tolB       ,
    itmax.ide  ,
    trace.lba  ,
    toltype    , ...)

## S3 method for class 'ls.logit'
lba(obj,
    A           ,
    B           ,
    K           ,
    cA          ,
    cB          ,
    logitA      ,
    logitB      ,
    omsk        ,
    psitk       ,
    S           ,
    T           ,
    row.weights ,
    col.weights ,
    itmax.ide   ,
    trace.lba   , ...)

## S3 method for class 'mle.logit'
lba(obj,
    A          ,
    B          ,
    K          ,
    cA         ,
    cB         ,
    logitA     ,
    logitB     ,
    omsk       ,
    psitk      ,
    S          ,
    T          ,
    itmax.ide  ,
    trace.lba  , ...)

Arguments

obj,formula	The function is generic, accepting some forms of the principal argument for specifying a two-way frequency table. Currently accepted forms are matrix, data frame (coerced to frequency tables), objects of class "xtabs" or "table" and one-sided formulae of the form Col1 + Col2 + ... + Coln ~ Row1 + Row2 + ... + Rown, where Rown and Coln are nth row (the mixing parameters) and column variable (the latent components).
data	A data frame containing variables in formula.
A	The starting value of a (I x K) matrix containing the mixing parameters, if given. The default is NULL, producing random starting values.
B	The starting value of a (J x K) matrix containing the latent components, if given. The default is NULL, producing random starting values.
K	Integer giving the number of latent budgets chosen by the user. The default is 1.
cA	The value of a (I x K) matrix containing the constraints on the mixing parameters. Fixed constraints are the values themselves which are numbers in the [0,1] interval. The optional equality constraints are indicated by an integer starting from 2, such that parameters that must be equal have the same integer. The default is NULL, indicating no constraints.
cB	The value of a (J x K) matrix containing the constraints on the latent components. Fixed constraints are the values themselves which are numbers in the [0,1] interval. The optional equality constraints are indicated by an integer starting from 2, such that parameters that must be equal have the same integer. The default is NULL, indicating no constraints.
logitA	Design (IxS) matrix for row-covariates. The first column contains the one number, indicating a constant covariate. The entries may be continuous or dummy coded values.
logitB	Design (JxT) matrix for column-covariates. The entries may be continuous or dummy coded values.
omsk	A (SxK) matrix giving the starting values for the multinomial logit parameters of the row covariates. The default is NULL, producing random starting values.
psitk	A (TxK) matrix giving the starting values for the multinomial logit parameters of the column covariates. The default is NULL, producing random starting values.
S	Number of row-covariates. The default is NULL.
T	Number of column-covariates. The default is NULL.
row.weights	A vector with the same number of rows of the matrix of the weighted least squares method. If is NULL (default), the weights are \sqrt{n_{i+}/n_{++}} .
col.weights	A vector with the same number of columns of the matrix of the weighted least squares method. If is NULL (default), the weights are 1/\sqrt{n_{+j}/n_{++}} .
tolG	A tolerance value for judging when convergence has been reached. It is based on the estimated likelihood ratio statistics G2. The default is 1e-10.
tolA	A tolerance value for judging when convergence has been reached. When the one-iteration change in the maximum of the absolute value of the element wise difference of the estimated matrices A is less than tolA. The default is 1e-05.
tolB	A tolerance value for judging when convergence has been reached. When the one-iteration change in the maximum of the absolute value of the element wise difference of the estimated matrices B is less than tolB. The default is 1e-05.
itmax.unide	Maximum number of iterations performed by the mle or ls method, if convergence is not achieved, before identification parameters. The default is 1e3.
itmax.ide	Maximum number of iterations performed by the mle or ls method in the identification process. Is used too when the constrained fixed, equality and logit are required. The default is 1e3.
trace.lba	Logical, indicating whether the base function optim and constrOptim.nl from package alabama, will trace their results. The default is TRUE.
toltype	String indicating which kind of tolerance to be used. That is, the EM algorithm stops updating and considers the maximum log-likelihood to have been found. Their types are: "all" when the one-iteration change in the estimated likelihood ratio statistics G2 is less than tolG, and the one-iteration change in the maximum of the absolute value of the element wise difference of the estimated matrices A is less than tolA and the same for estimated matrices B with respect to tolB; "G2" when the only one-iteration change in the estimated likelihood ratio statistics G2 is less than tolG; "ab" when only the one-iteration change in the maximum of the absolute value of the element wise difference of the estimated matrices A is less than tolA and the same for estimated matrices B with respect to tolB. toltype works only for method = "mle". The default is "all". The ls method uses only "ab" as tolerance limit.
method	String indicating which kind of estimating method. They are: "ls" when least squares, either weighted or ordinary, method is used; "mle" when maximum likelihood method is used. The default is "ls".
what	String indicating which kind identified solutions for mixing parameters and latent budgets matrices. They are: the "inner" extreme solution and the "outer" extreme solution. The default is "inner".
...	Further arguments (required by generic).

Value

The method lba.ls and lba.mle returns a list of class lba.ls and lba.mle respectively with the slots:

P	The compositional data matrix which is formed by dividing the raw data matrix by their corresponding total, its rows are called observed budgets.
pij	Matrix whose rows are the expected budgets.
residual	Residual matrix P - pij.
A	(I x K) matrix of the unidentified the mixing parameters.
B	(J x K) matrix of the unidentified the latent components.
Aoi	(I x K) matrix of the identified mixing parameters, they may be either the inner extreme values or the outer extreme values.
Boi	(J x K) matrix of the identified latent componentes, they may be either the inner extreme values or the outer extreme values.
rescB	(J x K) matrix of the rescaled latent components.
pk	Budget proportions.
val_func	Value of least squared or likelihood function achieved.
iter_unide	Number of unidentified iterations.
iter_ide	Number of identified iterations.

The method lba.ls.fe and lba.mle.fe returns a list of class lba.ls.fe and lba.mle.fe respectively with the slots:

P	The compositional data matrix which is formed by dividing the raw data matrix by their corresponding row total, its rows are called observed budgets.
pij	Matrix whose rows are the expected budgets.
residual	Residual matrix P - pij.
A	(I x K) matrix of the unidentified the mixing parameters.
B	(J x K) matrix of the unidentified the latent components.
rescB	(J x K) matrix of the rescaled latent components.
pk	Budget proportions.
val_func	Value of least squared or likelihood function achieved.
iter_ide	Number of identified iteractions.

The method lba.ls.logit and lba.mle.logit returns a list of class lba.ls.logit and lba.mle.logit respectively with the slots:

P	The compositional data matrix which is formed by dividing the raw data matrix by their corresponding total, its rows are called observed budgets.
pij	Matrix whose rows are the expected budgets.
residual	Residual matrix P - pij.
A	(I x K) matrix of the unidentified the mixing parameters.
B	(J x K) matrix of the unidentified the latent componentes.
rescB	(J x K) matrix of the rescaled latent components.
pk	Budget proportions.
val_func	Value of least squared or likelihood function achieved.
iter_ide	Number of identified iterations.
omsk	A (SxK) matrix giving estimated values of the multinomial logit parameters of the row covariates.
psitk	A (TxK) matrix giving the estimated values for the multinomial logit parameters of the column covariates.

Note

The user has two options to entry the data: the raw data and the tabulated data. If the raw data is imported, he may indicate which, among the variables, comprises the row and which the column variable and let the lba.formula function make the tabulation. The user may also tabulate the data with the available functions in R. Recalling that if this second option is used, the object must be of the class xtabs, table or matrix. If the user imports the tabulated data, the class is, in general, data.frame and so, it is necessary to transform the object data into a matrix.

The function lba uses EM algorithm to maximise the latent budget model log-likelihood function; the Active Constraints Methods (ACM) to minimise either the weighted least squares (wls), or ordinary least squares (ols) functions; and "BFGS" variable metric method in constrOptim.nl function of alabama package and in optim function of stats package used in identification for K >= 3, in constraint algorithm for ls method, in multinomial logit constraints and in some parts of constraining for mle method. Depending on the starting parameters, those algorithms may only locate a local, rather than global, maximum. This becomes more and more of a problem as K, the number of latent budgets, increases. It is therefore highly advisable to run lba multiple times until you are relatively certain that you have located the global maximum log-likelihood or the global minimum least squares.

References

Agresti, Alan. 2002. Categorical Data Analysis, second edition. Hoboken: John Wiley and Sons.

de Leeuw, J., and van der Heijden, P.G.M. 1988. "The analysis of time-budgets with a latent time-budget model". In E. Diday (Ed.), Data Analysis and Informatics V. pp. 159-166. Amsterdam: North-Holland.

de Leeuw, J., van der Heijden, P.G.M., and Verboon, P. 1990. "A latent time budget model". Statistica Neerlandica. 44, 1, 1-21.

Dempster, A.P., Laird, N.M., and Rubin, D.B. 1977. "Maximum likelihood from incomplete data via the EM algorithm". Journal of the Royal Statistical Society, Series. 39, 1-38.

van der Ark, A.L. 1999. Contributions to Latent Budget Analysis, a tool for the analysis of comositional data. Ph.D. Thesis University of Utrecht.

van der Heijden, P.G.M., Mooijaart, A., and de Leeuw, J. 1992. "Constrained latent budget analysis". In P.V. Marsden (Ed.), Sociological Methodology pp. 279-320. Cambridge: Blackwell Publishers.

See Also

goodnessfit, summary.lba.ls,summary.lba.mle,plotlba,plotcorr

Examples

data('votB')

# Using LS method (default) without constraint
# K = 2
ex1 <- lba(parties ~ city,
           votB,
           K = 2)
ex1 

# Already tabulated data? Ok!
data('PerfMark') 

## Not run: 
ex2 <- lba(as.matrix(PerfMark),
           K = 2,
           what='outer')
ex2

## End(Not run)
# Using LS method (default) with constraint
# Fixed constraint to mixing parameters
cakiF1 <- matrix(c(0.2, NA, NA,
                   NA , NA,0.2,
                   NA , NA,0.2,
                   0.3, NA, NA,
                   0.2, NA, NA,
                   NA , NA, NA),
                 byrow = TRUE,
                 ncol  = 3)  

# K = 3
## Not run: 
exf1 <- lba(parties ~ city,
            votB,
            cA = cakiF1,
            K = 3)
exf1 

## End(Not run)
# Using LS method (default) with LOGIT constrain
data('housing')

# Make cross-table to matrix design.
tbh <- xtabs(value ~ Influence + Housing, housing)

Xis <- model.matrix(~ Housing*Influence,
                    tbh,
                    contrasts=list(Housing='contr.sum',
                                   Influence='contr.sum'))

tby <- xtabs(value ~ Satisfaction + Contact, housing)

Yis <- model.matrix(~ Satisfaction*Contact,
                    tby,
                    contrasts=list(Satisfaction='contr.sum',
                                   Contact='contr.sum'))[,-1]

S <- 12
T <- 5

tabs <- xtabs(value ~ interaction(Housing,
                                  Influence) + interaction(Satisfaction,
                                  Contact),
              housing)
## Not run: 
exlogit2 <- lba(tabs,
           K = 2,
           logitA = Xis,
           logitB = Yis,
           S = S,
           T = T,
           trace.lba=FALSE) 
exlogit2

## End(Not run)

ivanalaman/lba documentation built on Sept. 9, 2023, 11:31 a.m.