---
title: "Choosing a transport geometry and inspecting results"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Choosing a transport geometry and inspecting results}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", cache = FALSE)
library(T4transport)
```

## Represent observations and choose their geometry

Rows of support are atoms, and mass belongs to one distribution. Weights
across distributions instead determine their importance in a collection.
Constructors normalize these two kinds of weights separately.

```{r inputs}
x <- ot_measure(rbind(c(0, 0), c(1, 0), c(0, 2)), c(1, 2, 1))
y <- ot_measure(rbind(c(0, 0), c(0, 1), c(-2, 0)), c(1, 2, 1))
exact <- ot_distance(x, y, method = "exact", return_plan = TRUE)
ot_inspect(exact)
```

Exact coordinate transport uses the supplied locations. Entropic transport
optimizes a different objective, consisting of a transport component and an
entropy term. The full value can be negative and is not a metric.

```{r entropy}
entropic <- ot_distance(x, y, method = "sinkhorn", epsilon = .1)
ot_inspect(entropic)
```

For an approximation based on projections, save the actual directions.
Directions supplied as rows are normalized by the function. Reusing them
makes numerical comparisons meaningful; a matching seed alone need not
produce the same directions in another language. A finite direction set can
define only a pseudometric: distinct measures may have zero sliced value.

```{r sliced}
directions <- rbind(c(1, 0), c(0, 1), c(1, 1))
sliced <- swdist(x, y, directions = directions)
ot_inspect(sliced)
```

## Alignment and relational geometry

Procrustes-Wasserstein comparison optimizes orthogonal alignment, including
reflections. It does not automatically center, translate, or rescale inputs.
Gromov-Wasserstein comparison instead uses within-object dissimilarities.
Use Euclidean distances here: the GW squared loss supplies its own square.

```{r align}
aligned <- pwdist(x, y)
relational <- gwdist(as.matrix(dist(x$support)),
                     as.matrix(dist(y$support)),
                     wx = x$mass, wy = y$mass, maxiter = 100)
ot_inspect(aligned)
ot_inspect(relational)
```

A local stopping condition is not a global optimization certificate. Raw
magnitudes from distinct objectives should not be used as a scoreboard for
choosing a geometry. In the accompanying shape application, centering and
RMS-radius scaling are explicit choices that remove position and size.

## Gaussian parameters and distribution summaries

Gaussian objects avoid artificial sampling. In one dimension, W2 geometry
is Euclidean in mean and standard deviation; a barycenter averages those
coordinates separately. A Gaussian-family median minimizes a different
objective within the declared family.

```{r gaussian}
inputs <- list(ot_gaussian(0, 1), ot_gaussian(2, 4), ot_gaussian(8, 1))
bary <- ot_gaussian_summary(inputs, weights = c(2, 2, 1))
med <- ot_gaussian_summary(inputs, target = "median", weights = c(2, 2, 1))
bary$estimate
med$estimate
ot_inspect(med)
```

Multivariate covariance matrices must be strictly positive definite. The
package does not add a ridge or silently project invalid covariances. General
multivariate medians retain local-optimization qualifications.

Finite summaries use `ot_summary()` with an explicit feasible set. Scalar
finite distributions support exact quantile representations. Fixed-support
summaries optimize masses; free-support fixed-mass summaries optimize locations.
These are distinct restrictions, not interchangeable solver settings.

```{r scalar}
collection <- ot_collection(lapply(c(0, 0, 0, 2, 8), ot_measure))
fit <- ot_summary(collection, target = "median")
ot_inspect(fit)
```

## Read the available evidence

`ot_inspect()` extracts available metadata without recomputing a result. Its
components identify the problem, numerical values, termination scope,
checks, approximation, history and settings. Missing information stays
missing. Inner failures, iteration limits and rejected steps remain visible.
The original result still supplies the family-specific estimate or plan.

```{r replay}
report <- ot_inspect(aligned)
stopifnot(identical(report, unserialize(serialize(report, NULL))))
names(report)
```

Constructors, plotting helpers, `fiedler()` and the descriptive resampling
helper `wassboot()` are outside this accessor. Inspect individual elements
of a multi-time interpolation result rather than the enclosing list.