genX2X: Fitting fixed-effects coefficients shared between submodels

In spaMM: Mixed-Effect Models, with or without Spatial Random Effects

Fitting fixed-effects coefficients shared between submodels

Description

X2X is an argument of the fitmv function, whose use is illustrated in the Examples below. By providing an X2X matrix M, the default fixed-effect design matrix X of the model is replaced by XM. The fixed-effect term X\beta of the linear predictor is then modified to XM\beta^* for a new vector \beta^* of fixed-effect coefficients, distinct from the vector \beta of coefficients of the default fit.

In the examples, the vector \beta of fixed-effect coefficients of the default fit, without X2X argument, has four distinct elements, including one Intercept for each of the two sub-models. The M matrix is used to declare that the Intercept coefficient is identical in the two sub-models, so M has three columns and four rows.

M must have column names, labeling the \beta^* coefficients.

Because specifying the M matrix can be laborious and error-prone, the helper function genX2X is provided. The typical way of using it, illustrated below, is X2X=genX2X(matches=list), with the second argument of the function missing. This argument will be provided internally, so the user does not have to find its correct form. Without this argument, the function returns its own call, which is not of any immediate interest for the user.

The matches list is a named list: the names will become some of the column names of the matrix product (the new regressor variables) and each element should be a vector of column names of the original X matrix.

A common source of error in specifying X2X is not correctly predicting the latter column names (for example, forgetting the appended submodel indices). Under the (not otherwise necessary, but practically useful) premise that vector elements not matching original column names are wrongly predicted column names, genX2X checks that all vector elements match original column names.

The names of regressors for interaction terms, in particular, may be wrongly predicted because even if the user-level model formula contains x:y, a base R function may relabel it as y:x (this happens if y appears before x in the formula), and thus the matches vector elements should be of the form y:x_s for submodels s that are thus affected. Running attr(terms(submodel formula),"term.labels") will show whether such reversals of variables occur for some interaction terms.

Usage

genX2X(matches, names_ori)

Arguments

matches	A named list, whose elements are vectors of names (character strings). The list names are those of some of the coefficients to be fitted (notably, the names to be given to the new, shared coefficients); and the vector elements are some names of coefficients of the original model (the one without an X2X argument) that should be constrained to be identical to the corresponding shared coefficient.
names_ori	Either missing, or the names of all coefficients of the default model (the one without X2X argument).

Value

genX2X returns a matrix if names_ori is provided, and returns the call to the genX2X function is this argument is missing.

See Also

vignette("Multinomial-logit", package = "spaMM") for more examples.

Examples

### Data preparation
data(clinics)
climv <- clinics
(fitClinics <- HLfit(cbind(npos,nneg)~treatment+(1|clinic),
                     family=binomial(),data=clinics))
set.seed(123)
climv$np2 <- simulate(fitClinics, type="residual")

### fits

## Default fit without 'X2X' argument
(mvfit <- fitmv(
   submodels=list(mod1=list(formula=cbind(npos,nneg)~treatment+(1|clinic),family=binomial()),
                  mod2=list(formula=np2~treatment+(1|clinic),
                            family=poisson(), fixed=list(lambda=c("1"=1)))), 
   data=climv))
   
## Fits with 'X2X' argument
   
# Suppose we want to fit the same intercept for the two submodels 
# (there may be cases where this is meaningful, even if not here).
# The original fit has four coefficients corresponding to four columns 
# of fixed-effect design matrix:

head(design_X <- model.matrix(mvfit))
#      (Intercept)_1 treatment_1 (Intercept)_2 treatment_2
# [1,]             1           1             0           0
#      ...
# where '_1' or '_2' identifies the submodel to which each coefficient belongs.

# The three coefficients of the intended model are (say) 
# "(Intercept)" "treatment_1" "treatment_2"
# We build a matrix that relates the original 4 coefficients to these 3 ones:

X_4to3 <- 
  matrix(c(1,0,0,
           0,1,0,
           1,0,0,
           0,0,1), nrow=4, ncol=3, byrow=TRUE,
         dimnames=list(NULL, c("(Intercept)","treatment_1","treatment_2")))
                   
# defined such that design_X %*% X_4to3 will be the design matrix 
# for the intended model, and the single "(Intercept)" coefficient 
# of the three-parameter model will operate as a shared estimate 
# of the "(Intercept)_1" and "(Intercept)_2" coefficients
# of the original 4-coefficients model, as intended. 

# To define such matrices, it is *strongly advised* to either fit 
# the unconstrained model first, and to examine the structure 
# of its model matrix (as shown above), or to use genX2X(). 

# The 'X2X' argument provides the matrix:

(mvfit3m <- fitmv(
    submodels=list(mod1=list(formula=cbind(npos,nneg)~treatment+(1|clinic),family=binomial()),
                   mod2=list(formula=np2~treatment+(1|clinic),
                             family=poisson(), fixed=list(lambda=c("1"=1)))), 
    X2X = X_4to3,
    data=climv))

# => the column names of 'X_4to3' are the fixed-effect names in all output.

# Alternatively, the 'X2X' argument provides a genX2X() call:

(mvfit3g <- fitmv(
    submodels=list(mod1=list(formula=cbind(npos,nneg)~treatment+(1|clinic),family=binomial()),
                   mod2=list(formula=np2~treatment+(1|clinic),
                             family=poisson(), fixed=list(lambda=c("1"=1)))), 
    X2X = genX2X(list("(Intercept)"=c("(Intercept)_1","(Intercept)_2"))),
    data=climv))

# => the last two fits are equivalent (although the order of the coefficients may differ).
# The internally produced 'X2X' matrix is that provided by 
genX2X(list("(Intercept)"=c("(Intercept)_1","(Intercept)_2")),
       names_ori=colnames(design_X) )

spaMM documentation built on Sept. 10, 2026, 1:07 a.m.