mlreg: Fitting Multivariate Logistic Regression Models

In LocaTT: Geographically-Conscious Taxonomic Assignment for Metabarcoding

Fitting Multivariate Logistic Regression Models

Description

Fit a multivariate logistic regression model. Installation of the rstan package is required to use this function.

Usage

mlreg(
  Y,
  X,
  multivariate = TRUE,
  priors = c(B.mu = 0, B.sd = 1, lkj = 1),
  iter = 20000,
  thin = 20,
  control = list(adapt_delta = 0.99, max_treedepth = 20, stepsize = 0.01),
  ...
)

Arguments

Y	Numeric response matrix. Each record represents an observation, and each field represents a response dimension. Matrix cells contain binary values (i.e., 0 or 1).
X	Numeric predictor matrix. Each record represents an observation, and each field represents a predictor variable. Matrix cells contain predictor values.
multivariate	Logical scalar. If TRUE (the default), then fits a multivariate logistic regression. If FALSE, then fits stacked univariate logistic regressions.
priors	Named numeric vector. Elements represent the prior values of their respective named parameters. When predictors are centered and scaled, the defaults generally represent weakly informative priors. Regression coefficients (B) receive normal priors (with standard normal as the default). The residual correlation matrix (R) receives an LKJ prior (with default shape parameter of 1).
iter	Numeric scalar. Integer value specifying the number of iterations for each chain (including warmup). The default is 20000. Passed to the iter argument of the rstan::sampling function.
thin	Numeric scalar. Integer value specifying the thinning interval. The default is 20. Passed to the thin argument of the rstan::sampling function.
control	Named list of parameters which control the behavior of the Stan sampler. Passed to the control argument of the rstan::sampling function.
...	Additional arguments passed to the rstan::sampling function.

Details

Fits a multivariate logistic regression model using the rstan interface to Stan (Carpenter et al. 2017). The multivariate logistic regression follows that of Ovaskainen et al. 2010, where the Bernoulli marginals are reparameterized as truncated continuous latent variables (Albert & Chib 1993). The latent variables z receive a positive constraint when y = 1 and a negative constraint when y = 0, where z is a linear combination of predictors with correlated standard logistic errors. Equivalently, the latent variables follow a multivariate logistic distribution with scale parameters fixed at one (O'Brien & Dunson 2004), constructed in Stan as a Gaussian copula with logistic marginals (Song 2000). A stanfit object of the fitted model is returned, which can be used with standard rstan functions to evaluate model convergence (e.g., posterior trace plots, R-hat convergence diagnostics, and effective sample sizes). By default, weakly informative priors are used on the regression coefficients (B) and residual correlation matrix (R).

Value

Returns a stanfit object of the fitted multivariate logistic regression model.

References

Albert JH, and Chib S. 1993. Bayesian analysis of binary and polychotomous response data. Journal of the American Statistical Association, 88(422): 669-679.

Carpenter B, Gelman A, Hoffman MD, Lee D, Goodrich B, Betancourt M, Brubaker M, Guo J, Li P, and Riddell A. 2017. Stan: A probabilistic programming language. Journal of Statistical Software, 76: 1-32. DOI: 10.18637/jss.v076.i01

O'Brien SM, and Dunson DB. 2004. Bayesian multivariate logistic regression. Biometrics, 60: 739-746. DOI: 10.1111/j.0006-341X.2004.00224.x

Ovaskainen O, Hottola J, and Siitonen J. 2010. Modeling species co-occurrence by multivariate logistic regression generates new hypotheses on fungal interactions. Ecology, 91(9): 2514-2521. DOI: 10.1890/10-0173.1

Song P. 2000. Multivariate dispersion models generated from Gaussian copula. Scandinavian Journal of Statistics, 27(2): 305-320. DOI: 10.1111/1467-9469.00191

See Also

mlformat for formatting output of multivariate logistic regression models.

mlpredict for generating predictions from multivariate logistic regression models.

mlWAIC for computing widely applicable information criteria for multivariate logistic regression models.

Examples

# Define example data file path.
path<-system.file("extdata",
                  "example_mvlogistic_data.rds",
                  package="LocaTT",
                  mustWork=TRUE)

# Read in example regression data.
data<-readRDS(file=path)

# Fit multivariate logistic regression.
out<-mlreg(Y=data$Y,X=data$X)

LocaTT documentation built on June 14, 2026, 1:06 a.m.