Summaries of Gaussian parameter objects

Compute a Wasserstein-2 barycenter or a median within the Gaussian family using the existing parameter-based algorithms. The barycenter minimizes the weighted sum of squared distances; the median minimizes weighted distances. No finite sampling, covariance ridge, or covariance projection is performed.

Usage

ot_gaussian_summary(
  measures,
  target = c("barycenter", "median"),
  weights = NULL,
  control = list()
)

Arguments

measures

A nonempty list of [ot_gaussian()] objects of the same dimension. One-dimensional variances may be zero; covariance matrices in higher dimensions must be strictly positive definite.

target

Either `"barycenter"` or `"median"`.

weights

Nonnegative weights across Gaussian distributions, normalized separately. NULL assigns equal weights. Zero-weight inputs are validated but do not enter the optimization.

control

A named list. Outer controls are `maxiter = 496`, `atol = 1e-8`, and `rtol = 1e-8`. Only multidimensional medians also accept `inner_maxiter = 496`, `inner_atol = 1e-10`, and `inner_rtol = 1e-10`. These map to the legacy solvers' iteration and absolute/relative tolerance controls. Controls not used by an analytic branch are recorded in `settings$controls_unused`; unknown or inapplicable controls are errors.

Value

A `t4transport_gaussian_fit` containing `estimate` (a Gaussian parameter object), legacy `mean` and `var` fields, the objective, accepted history, status, stopping reason, iteration count, and diagnostics. `weights` records normalized outer weights; `control` records public controls and `backend_control` records their legacy names. `settings` describes the selected algorithm branch and unused controls. Non-success preserves the underlying solver's warning and available estimate.

Details

One-dimensional barycenters average means and standard deviations exactly. One-dimensional medians use the joint mean/standard-deviation geometric median. Multivariate calls use [gaussbarypd()] or [gaussmedpd()], including their diagonal and common-covariance reductions. General multivariate median termination is a numerical stopping result, not a global-optimality claim.

See also

[ot_inspect()], [ot_gaussian_distance()], [gaussbary1d()], [gaussmed1d()], [gaussbarypd()], [gaussmedpd()]

Examples

measures <- list(ot_gaussian(0, 1), ot_gaussian(4, 9))
fit <- ot_gaussian_summary(measures, weights = c(1, 3))
fit$estimate
#> Gaussian probability measure in 1 dimension(s)
#> Covariance domain: nonnegative variance 
#> Mean: 3 
ot_gaussian_distance(measures[[1]], fit$estimate)
#> Transport comparison | gaussian_formula | euclidean | order 2 
#> Status: SUCCESS ( gaussian_parameter_formula )
#> Transport cost: 11.25 
#> Wasserstein distance: 3.354102