Barycenters and medians of finite probability measures

The unregularized barycenter minimizes the weighted sum of squared W2 distances; the median minimizes the weighted sum of W2 distances. The feasible set is explicit. Fixed-location entropy barycenters minimize the full regularized objectives; regularized medians are not substituted for unregularized medians. Free-support fits keep candidate masses fixed.

Usage

ot_summary(
  measures,
  target = c("barycenter", "median"),
  weights = NULL,
  feasible = c("auto", "unrestricted_1d", "free_support_fixed_mass", "fixed_support"),
  method = c("auto", "quantile", "relocation", "subgradient"),
  support = NULL,
  mass = NULL,
  epsilon = NULL,
  control = list(),
  nstart = 1L,
  seed = NULL
)

Arguments

measures: A collection or list of convertible finite measures.
target: `barycenter` or `median`, both using inner Wasserstein order two.
weights: Outer weights, overriding a collection's weights if supplied.
feasible: `unrestricted_1d`, `free_support_fixed_mass`, or `fixed_support`. `auto` selects unrestricted quantiles in one dimension, free support otherwise; an explicit support requires an explicit feasible set.
method: `quantile`, `relocation`, `subgradient`, or automatic selection consistent with the feasible set. Unsupported combinations are errors.
support: Candidate locations: fixed grid for fixed support, or initial locations for free support. NULL lets the free-support initializer choose.
mass: Fixed candidate masses for free support. Initial variable masses on a fixed grid are instead supplied as `control$init_mass`.
epsilon: Optional positive entropy coefficient, only for a fixed-support barycenter. NULL means unregularized transport.
control: Named, method-specific numerical controls. Quantile methods use `maxiter`, `atol`, `rtol`. Relocation adds `stationarity_tol`, `alpha`, `smoothing`, `inner_maxiter`, `surrogate_steps`, `num_support`, `max_backtrack`, `print.progress`. Fixed support adds `step0`, `max_backtrack`, `init_mass`, `inner_maxiter`, `inner_tol`.
nstart: Number of free-support starts. When support is supplied it is used for the first start; later starts sample pooled atoms with outer and within-measure probabilities. All initial supports and failed outcomes are recorded.
seed: Optional local RNG seed; the previous RNG state is restored.

Value

A `t4transport_fit` identifying the estimate, objective, feasible set, method, accepted history, numerical status, per-measure diagnostics and initialization. Multiple starts retain all outcomes and choose among successful runs using the same objective. If none succeeds the best finite failed run is returned with a non-success status.

Details

Fixed-support median stationarity alone is not an optimality certificate: all vertices are probed for descent, and an uncertified stationary point is returned with non-success status. Free-support relocation uses a residual from the selected optimal transport plans, which is not a certificate of a local minimum when optimal plans tie. A positive-cost stop with coincident active candidate atoms and nondegenerate input measures is marked `unresolved_degeneracy` unless an independent certificate applies. Separate initial locations or multiple starts can help diagnose this case. Quantile summaries preserve an input measure when its quantile is selected; objectives and residuals describe the final stored finite measure, including any rounding introduced when quantile cells are converted to atom masses.

Examples

measures <- lapply(c(0, 0, 0, 2, 8), ot_measure)
ot_summary(measures, target = "barycenter")
#> Wasserstein barycenter | unrestricted_1d | quantile 
#> Status: SUCCESS ( quantile_average )
#> Objective: 9.6 | estimated atoms: 1 
fit <- ot_summary(measures, target = "median")
summary(fit)
#> $target
#> [1] "median"
#> 
#> $feasible
#> [1] "unrestricted_1d"
#> 
#> $method
#> [1] "quantile"
#> 
#> $status
#> [1] "success"
#> 
#> $stop_reason
#> [1] "collision_optimality"
#> 
#> $objective
#> [1] 2
#> 
#> $diagnostics
#> $diagnostics$stationarity_residual
#> [1] 0
#> 
#> $diagnostics$stationarity_tolerance
#> [1] 2e-08
#> 
#> $diagnostics$collision_weight
#> [1] 0.6
#> 
#> $diagnostics$step_norm
#> [1] 0
#> 
#> $diagnostics$objective_change
#> [1] 0
#> 
#> $diagnostics$step_norm_scope
#> [1] "last accepted quantile iterate before finite-measure conversion"
#> 
#> $diagnostics$optimization_objective_change
#> [1] 0
#> 
#> $diagnostics$distances
#> [1] 0 0 0 2 8
#> 
#> $diagnostics$contributions
#> [1] 0.0 0.0 0.0 0.4 1.6
#> 
#> $diagnostics$active_measure_indices
#> [1] 1 2 3 4 5
#> 
#> $diagnostics$refinement_cells
#> [1] 1
#> 
#> $diagnostics$returned_refinement_cells
#> [1] 1
#> 
#> $diagnostics$selected_input_index
#> [1] 1
#> 
#> $diagnostics$mass_grid_input_index
#> [1] NA
#> 
#> $diagnostics$optimization_objective
#> [1] 2
#> 
#> $diagnostics$representation_objective_change
#> [1] 0
#> 
#> $diagnostics$diagnostic_scope
#> [1] "returned finite measure"
#> 
#> $diagnostics$stationarity_definition
#> [1] "minimum Hilbert subgradient norm on the returned measure refinement"
#> 
#> 
#> $multistart
#> $multistart$nstart
#> [1] 1
#> 
#> $multistart$chosen
#> [1] 1
#> 
#> $multistart$successful
#> [1] TRUE
#> 
#> $multistart$objectives
#> [1] 2
#> 
#> $multistart$statuses
#> [1] "success"
#> 
#> $multistart$stop_reasons
#> [1] "collision_optimality"
#> 
#> $multistart$diagnostics
#> $multistart$diagnostics[[1]]
#> $multistart$diagnostics[[1]]$stationarity_residual
#> [1] 0
#> 
#> $multistart$diagnostics[[1]]$stationarity_tolerance
#> [1] 2e-08
#> 
#> $multistart$diagnostics[[1]]$collision_weight
#> [1] 0.6
#> 
#> $multistart$diagnostics[[1]]$step_norm
#> [1] 0
#> 
#> $multistart$diagnostics[[1]]$objective_change
#> [1] 0
#> 
#> $multistart$diagnostics[[1]]$step_norm_scope
#> [1] "last accepted quantile iterate before finite-measure conversion"
#> 
#> $multistart$diagnostics[[1]]$optimization_objective_change
#> [1] 0
#> 
#> $multistart$diagnostics[[1]]$distances
#> [1] 0 0 0 2 8
#> 
#> $multistart$diagnostics[[1]]$contributions
#> [1] 0.0 0.0 0.0 0.4 1.6
#> 
#> $multistart$diagnostics[[1]]$active_measure_indices
#> [1] 1 2 3 4 5
#> 
#> $multistart$diagnostics[[1]]$refinement_cells
#> [1] 1
#> 
#> $multistart$diagnostics[[1]]$returned_refinement_cells
#> [1] 1
#> 
#> $multistart$diagnostics[[1]]$selected_input_index
#> [1] 1
#> 
#> $multistart$diagnostics[[1]]$mass_grid_input_index
#> [1] NA
#> 
#> $multistart$diagnostics[[1]]$optimization_objective
#> [1] 2
#> 
#> $multistart$diagnostics[[1]]$representation_objective_change
#> [1] 0
#> 
#> $multistart$diagnostics[[1]]$diagnostic_scope
#> [1] "returned finite measure"
#> 
#> $multistart$diagnostics[[1]]$stationarity_definition
#> [1] "minimum Hilbert subgradient norm on the returned measure refinement"
#> 
#> 
#> 
#> $multistart$initializations
#> $multistart$initializations[[1]]
#> NULL
#> 
#> 
#> 
#> $per_measure
#>      label weight distance contribution
#> 1 measure1    0.2        0          0.0
#> 2 measure2    0.2        0          0.0
#> 3 measure3    0.2        0          0.0
#> 4 measure4    0.2        2          0.4
#> 5 measure5    0.2        8          1.6
#>