Package {gipsDA}

Title:	Discriminant Analysis with Permutation-Invariant Covariance Models
Version:	1.0.0
URL:	https://antonikingston.github.io/gipsDA/, https://github.com/AntoniKingston/gipsDA
BugReports:	https://github.com/AntoniKingston/gipsDA/issues
Description:	Extends classical linear and quadratic discriminant analysis by incorporating permutation-group symmetries into covariance matrix estimation. Methods based on the 'gips' framework identify and impose permutation structures that regularize covariance estimates and improve stability and interpretability for symmetric or exchangeable features. The package provides pooled and class-specific covariance models, including multi-class variants with shared or independently estimated symmetry structures. The underlying methodology is described by Graczyk et al. (2022) <doi:10.1214/22-AOS2174> and Chojecki, Morgen, and Kołodziejek (2025) <doi:10.18637/jss.v112.i07>.
License:	GPL (≥ 3)
Imports:	gips (≥ 1.3.0), jsonlite, lattice, MASS, stats, stringi
Suggests:	knitr, mockery, rmarkdown, testthat (≥ 3.0.0), roxygen2, withr
Depends:	R (≥ 4.1.0)
Encoding:	UTF-8
RoxygenNote:	8.0.0
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/Needs/website:	pkgdown
NeedsCompilation:	no
Packaged:	2026-10-01 22:18:13 UTC; fantasy2fry
Author:	Antoni Zbigniew Kingston [aut], Norbert Maksymilian Frydrysiak [aut, cre], Adam Przemysław Chojecki [ctb]
Maintainer:	Norbert Maksymilian Frydrysiak <norbert.frydrysiak@proton.me>
Repository:	CRAN
Date/Publication:	2026-10-01 22:50:02 UTC

Extract gips LDA discriminant coefficients

Description

Extract gips LDA discriminant coefficients

Usage

## S3 method for class 'gipslda'
coef(object, ...)

Arguments

Value

The linear discriminant transformation matrix.

See Also

gipslda

Linear Discriminant Analysis with gips Covariance Projection

Description

Linear discriminant analysis (LDA) using covariance matrices projected via the gips framework to enforce permutation symmetry and improve numerical stability.

Usage

gipslda(x, ...)

## S3 method for class 'formula'
gipslda(formula, data, ..., subset, na.action)

## Default S3 method:
gipslda(x, grouping, prior = proportions,
  tol = 1e-4, weighted_avg = FALSE,
  MAP = TRUE, optimizer = NULL, max_iter = NULL,
  show_progress_bar = FALSE, store_probabilities = TRUE, ...)

## S3 method for class 'data.frame'
gipslda(x, ...)

## S3 method for class 'matrix'
gipslda(x, grouping, ..., subset, na.action)

Arguments

Details

This function is a minor modification of lda, replacing the classical sample covariance estimators by projected covariance matrices obtained using the gips framework.

Unlike classical LDA, the within-class covariance matrix is first projected onto a permutation-invariant structure using the gips framework. This can stabilize covariance estimation in high dimensions or when symmetry assumptions are justified.

The choice of optimizer and MAP estimation affects both the covariance estimate and the resulting discriminant directions.

See Chojecki et al. (2025) for theoretical background.

Value

An object of class "gipslda" containing:

• prior: prior class probabilities

• counts: number of observations per class

• means: group means

• scaling: transformation matrix of linear discriminants

• lev: class labels

• svd: singular values of the between-class scatter

• N: number of observations

• optimization_info: estimated posterior probabilities of retained permutations if stored; otherwise NULL

• selected_map_permutation: MAP permutation selected by the gips optimization and used for MAP covariance projection

• call: matched call

• Formula fits additionally contain terms, contrasts, xlevels, and any recorded na.action.

Note

This function is inspired by lda but is not a drop-in replacement. The covariance estimator, optimization procedure, and returned object differ substantially.

References

Chojecki, A., et al. (2025). Learning Permutation Symmetry of a Gaussian Vector with gips in R. Journal of Statistical Software, 112(7), 1–38. doi:10.18637/jss.v112.i07

See Also

lda, gips

Examples

Iris <- data.frame(rbind(iris3[, , 1], iris3[, , 2], iris3[, , 3]),
  Sp = rep(c("s", "c", "v"), rep(50, 3))
)
train <- sample(1:150, 75)
z <- gipslda(Sp ~ ., Iris, prior = c(1, 1, 1) / 3, subset = train)
predict(z, Iris[-train, ])$class
(z1 <- update(z, . ~ . - Petal.W.))

Quadratic Discriminant Analysis with multiple gips-projected covariances

Description

Quadratic Discriminant Analysis (QDA) in which each class covariance matrix participates in one joint gips projection, allowing the covariance matrices to share an estimated permutation symmetry.

Usage

gipsmultqda(x, ...)

## S3 method for class 'formula'
gipsmultqda(formula, data, ..., subset, na.action)

## Default S3 method:
gipsmultqda(x, grouping, prior = proportions,
  nu = 5, MAP = TRUE, optimizer = NULL, max_iter = NULL,
  show_progress_bar = FALSE, store_probabilities = TRUE, ...)

## S3 method for class 'data.frame'
gipsmultqda(x, ...)

## S3 method for class 'matrix'
gipsmultqda(x, grouping, ..., subset, na.action)

Arguments

Details

This function is a modification of qda in which the class-specific covariance matrices are jointly projected to improve numerical stability and exploit shared symmetry assumptions.

In contrast to classical QDA, which estimates each class covariance matrix independently, gipsmultqda performs a joint projection of all class covariance matrices using gips. This allows the incorporation of shared permutation symmetries and can improve classification performance in high-dimensional or small-sample regimes.

Several classification rules are available via predict.gipsmultqda, including plug-in, predictive, debiased, and leave-one-out cross-validation.

Value

An object of class "gipsmultqda" containing:

• prior: prior probabilities of the groups

• counts: number of observations per group

• means: group means

• scaling: array of group-specific scaling matrices derived from the projected covariance matrices

• ldet: log-determinants of the projected covariance matrices

• lev: class labels

• N: total number of observations

• optimization_info: estimated posterior probabilities of retained permutations from the joint gips optimization if stored; otherwise NULL

• selected_map_permutation: MAP permutation selected by the joint gips optimization and used for MAP covariance projection

• call: the matched call

• Formula fits additionally contain terms, contrasts, xlevels, and any recorded na.action.

Note

This function is not a drop-in replacement for qda. The covariance estimation, returned object, and classification rules differ substantially.

The theoretical background and details of covariance projection are documented by gips and Chojecki et al. (2025).

See Also

qda, predict.gipsmultqda, gipsqda, gipslda

Examples

tr <- sample(1:50, 25)
train <- rbind(iris3[tr, , 1], iris3[tr, , 2], iris3[tr, , 3])
test <- rbind(iris3[-tr, , 1], iris3[-tr, , 2], iris3[-tr, , 3])
cl <- factor(c(rep("s", 25), rep("c", 25), rep("v", 25)))
z <- gipsmultqda(train, cl)
predict(z, test)$class

Quadratic Discriminant Analysis with gips covariance projection

Description

Quadratic discriminant analysis (QDA) using covariance matrices projected via the gips framework to enforce permutation symmetry and improve numerical stability.

Usage

gipsqda(x, ...)

## S3 method for class 'formula'
gipsqda(formula, data, ..., subset, na.action)

## Default S3 method:
gipsqda(x, grouping, prior = proportions,
  nu = 5, MAP = TRUE, optimizer = NULL, max_iter = NULL,
  show_progress_bar = FALSE, store_probabilities = TRUE, ...)

## S3 method for class 'data.frame'
gipsqda(x, ...)

## S3 method for class 'matrix'
gipsqda(x, grouping, ..., subset, na.action)

Arguments

Details

This function is a minor modification of qda, replacing the classical sample covariance estimators by projected covariance matrices obtained using the gips framework.

Quadratic discriminant analysis models each class with its own covariance matrix. In gipsqda, these covariance matrices are projected using the gips framework, which enforces permutation symmetry and mitigates singularity and overfitting in high-dimensional or small-sample settings.

Classification can be performed using plug-in, predictive, debiased, or leave-one-out cross-validation rules via predict.gipsqda.

Value

An object of class "gipsqda" containing the following components:

• prior: prior probabilities of the groups

• counts: number of observations in each group

• means: group means

• scaling: group-specific scaling matrices derived from the projected covariance matrices

• ldet: log-determinants of the projected covariance matrices

• lev: class labels

• N: total number of observations

• optimization_info: named list of estimated posterior probabilities of retained permutations, one element per class, if stored; otherwise a named list of NULL values

• selected_map_permutation: named list of MAP permutations selected independently for each class

• call: the matched call

• Formula fits additionally contain terms, contrasts, xlevels, and any recorded na.action.

Note

The function may be called with either a formula interface or with a matrix and grouping factor. Arguments subset and na.action, if used, must be named.

References

Chojecki, A., et al. (2025). Learning Permutation Symmetry of a Gaussian Vector with gips in R. Journal of Statistical Software, 112(7), 1–38. doi:10.18637/jss.v112.i07

Venables, W. N. and Ripley, B. D. (2002). Modern Applied Statistics with S. Fourth edition. Springer.

See Also

qda, predict.gipsqda, gipslda, lda

Examples

tr <- sample(1:50, 25)
train <- rbind(iris3[tr, , 1], iris3[tr, , 2], iris3[tr, , 3])
test <- rbind(iris3[-tr, , 1], iris3[-tr, , 2], iris3[-tr, , 3])
cl <- factor(c(rep("s", 25), rep("c", 25), rep("v", 25)))
z <- gipsqda(train, cl)
predict(z, test)$class

Pairs plot for a fitted gips LDA model

Description

Displays discriminant coordinates using either base graphics or a lattice scatterplot matrix.

Usage

## S3 method for class 'gipslda'
pairs(
  x,
  labels = colnames(x),
  panel = panel.gipslda,
  dimen,
  abbrev = FALSE,
  ...,
  cex = 0.7,
  type = c("std", "trellis")
)

Arguments

Value

Invisibly returns NULL.

See Also

gipslda, plot.gipslda

Plot a fitted gips LDA model

Description

Displays training observations in discriminant space. One discriminant dimension is shown as class-wise histograms or densities, two dimensions as an equal-scale scatter plot, and higher dimensions as a pairs plot.

Usage

## S3 method for class 'gipslda'
plot(
  x,
  panel = panel.gipslda,
  ...,
  cex = 0.7,
  dimen,
  abbrev = FALSE,
  xlab = "LD1",
  ylab = "LD2"
)

Arguments

Value

Invisibly returns NULL.

See Also

gipslda, pairs.gipslda

Predict from a gips LDA model

Description

Computes class assignments, posterior probabilities, and linear discriminant coordinates for new observations.

Usage

## S3 method for class 'gipslda'
predict(
  object,
  newdata,
  prior = object$prior,
  dimen,
  method = c("plug-in", "predictive", "debiased"),
  ...
)

Arguments

Value

A list with class (predicted classes), posterior (posterior class probabilities), and x (linear discriminant coordinates).

See Also

gipslda, predict.lda

Predict from a joint-projection gips QDA model

Description

Computes class assignments and posterior probabilities from a fitted "gipsmultqda" model. Prediction rules match those of predict.gipsqda; the fitted covariance estimates differ because they were projected jointly.

Usage

## S3 method for class 'gipsmultqda'
predict(
  object,
  newdata,
  prior = object$prior,
  method = c("plug-in", "predictive", "debiased", "looCV"),
  ...
)

Arguments

Value

A list with class (predicted classes) and posterior (posterior class probabilities).

See Also

gipsmultqda, predict.gipsqda

Predict from a gips QDA model

Description

Computes class assignments and posterior probabilities from a fitted "gipsqda" model.

Usage

## S3 method for class 'gipsqda'
predict(
  object,
  newdata,
  prior = object$prior,
  method = c("plug-in", "predictive", "debiased", "looCV"),
  ...
)

Arguments

Value

A list with class (predicted classes) and posterior (posterior class probabilities).

See Also

gipsqda, predict.qda

Print a fitted gipsDA model

Description

Prints the main components of a fitted gipsDA model, including the model call, fitting options, group means, class counts, selected MAP permutation, and posterior probabilities of retained permutations when stored.

Usage

## S3 method for class 'gipslda'
print(x, ...)

## S3 method for class 'gipsqda'
print(x, ...)

## S3 method for class 'gipsmultqda'
print(x, ...)

Arguments

Value

Invisibly returns x.

Examples

fit <- gipslda(Species ~ ., data = iris, optimizer = "BF")
print(fit)

Print a gipsDA model summary

Description

Print a gipsDA model summary

Usage

## S3 method for class 'summary.gipsda'
print(x, ...)

Arguments

Value

Invisibly returns x.

Summarize a fitted gipsDA model

Description

Creates a compact summary object for a fitted gipsDA model. The summary contains the most important fitted quantities and can be printed using the corresponding print() method.

Usage

## S3 method for class 'gipslda'
summary(object, ...)

## S3 method for class 'gipsqda'
summary(object, ...)

## S3 method for class 'gipsmultqda'
summary(object, ...)

Arguments

Value

An object of class "summary.gipsda". Common components include:

• model: model type.

• call: original model call.

• n: number of observations used for fitting.

• p: number of predictors.

• groups: fitted class labels.

• counts: class counts.

• prior: prior class probabilities.

• means: group means.

• fit_info: fitting options, including MAP, optimizer, max_iter, store_probabilities, and for LDA also weighted_avg.

• optimization_info: stored posterior probabilities of retained permutations, if available.

• selected_map_permutation: selected MAP permutation or permutations.

LDA summaries additionally contain scaling, svd, and proportion_trace. QDA summaries additionally contain scaling_dim and ldet.

Examples

fit <- gipslda(Species ~ ., data = iris, optimizer = "BF")
summary(fit)

summary_object <- summary(fit)
names(summary_object)