pibble_fit: Interface to fit pibble models

In fido: Bayesian Multinomial Logistic Normal Regression

Interface to fit pibble models

Description

This function is largely a more user friendly wrapper around optimPibbleCollapsed and uncollapsePibble. See details for model specification. Notation: N is number of samples, D is number of multinomial categories, Q is number of covariates, iter is the number of samples of eta (e.g., the parameter n_samples in the function optimPibbleCollapsed)

Usage

pibble(
  Y = NULL,
  X = NULL,
  upsilon = NULL,
  Theta = NULL,
  Gamma = NULL,
  Xi = NULL,
  init = NULL,
  pars = c("Eta", "Lambda", "Sigma"),
  newdata = NULL,
  ...
)

## S3 method for class 'pibblefit'
refit(m, pars = c("Eta", "Lambda", "Sigma"), ...)

Arguments

Y	D x N matrix of counts (if NULL uses priors only)
X	Q x N matrix of covariates (design matrix) (if NULL uses priors only, must be present to sample Eta)
upsilon	degrees of freedom for the inverse-Wishart prior on Sigma (numeric, must be > D-2; the prior mean of Sigma exists only if > D) Values <= D require an explicit positive-definite Xi. (default: D+3)
Theta	(D-1) x Q matrix of prior mean for regression parameters (default: matrix(0, D-1, Q))
Gamma	QxQ prior covariance matrix (default: diag(Q))
Xi	(D-1)x(D-1) prior covariance matrix (default: ALR transform of diag(1)*(upsilon-D)/2 - this is essentially iid on "base scale" using Aitchison terminology)
init	(D-1) x N initialization for Eta for optimization
pars	character vector of posterior parameters to return
newdata	Default is NULL. If non-null, newdata is used in the uncollapse sampler in place of X.
...	arguments passed to optimPibbleCollapsed and uncollapsePibble
m	object of class pibblefit

Details

upsilon is the usual inverse-Wishart degrees of freedom, so the prior mean of Sigma is Xi/(upsilon-D) (for upsilon > D). Larger values give a more concentrated prior on Sigma. Internally this is converted to the matrix-t degrees of freedom (upsilon-D+2) used by the collapsed model; you do not need to do this yourself. (If you call optimPibbleCollapsed directly, you do.)

Versions of fido before 1.1.5 skipped this conversion when D > 2, so the prior used to estimate Eta did not match the prior requested. Fits made with earlier versions should be refit from the original data and priors. Log marginal likelihoods from earlier versions were also mis-normalized (for any D) and should not be compared with new values.

The full model is given by:

Y_j \sim Multinomial(\pi_j)

\pi_j = \Phi^{-1}(\eta_j)

\eta \sim MN_{D-1 \times N}(\Lambda X, \Sigma, I_N)

\Lambda \sim MN_{D-1 \times Q}(\Theta, \Sigma, \Gamma)

\Sigma \sim InvWish(\upsilon, \Xi)

Where \Gamma is a Q x Q covariance matrix, and \Phi^{-1} is ALRInv_D transform.

Default behavior is to use MAP estimate for uncollaping the LTP model if laplace approximation is not preformed.

Value

an object of class pibblefit

References

JD Silverman K Roche, ZC Holmes, LA David, S Mukherjee. Bayesian Multinomial Logistic Normal Models through Marginally Latent Matrix-T Processes. 2019, arXiv e-prints, arXiv:1903.11695

See Also

fido_transforms provide convenience methods for transforming the representation of pibblefit objects (e.g., conversion to proportions, alr, clr, or ilr coordinates.)

access_dims provides convenience methods for accessing dimensions of pibblefit object

Generic functions including summary, print, coef, as.list, predict, name, and sample_prior name_dims

Plotting functions provided by plot and ppc (posterior predictive checks)

Examples

sim <- pibble_sim()
fit <- pibble(sim$Y, sim$X)

fido documentation built on Oct. 31, 2026, 1:07 a.m.