% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/PlotMatching.R
\name{plot_matching}
\alias{plot_matching}
\title{Plot the optimal matching between two persistence diagrams}
\usage{
plot_matching(
  df1,
  df2,
  dimension,
  distance = c("wasserstein", "bottleneck"),
  p = 2,
  ground = NULL,
  labels = c("Diagram 1", "Diagram 2")
)
}
\arguments{
\item{df1, df2}{Persistence diagram data frames with columns \code{dim},
\code{birth}, \code{death}.}

\item{dimension}{Homological dimension to compare.}

\item{distance}{Which distance's optimal matching to visualize,
\code{"wasserstein"} (default) or \code{"bottleneck"}.}

\item{p}{Wasserstein order, used only when \code{distance = "wasserstein"}.}

\item{ground}{Ground metric, \code{"L2"} or \code{"Linf"}. Defaults to
each distance's own default (\code{"L2"} for Wasserstein, \code{"Linf"}
for bottleneck) when left \code{NULL} - see
\code{\link{wasserstein_distance}}/\code{\link{bottleneck_distance}}.}

\item{labels}{Legend labels identifying \code{df1} and \code{df2},
e.g. \code{c("Clean", "Noisy")}.}
}
\value{
A ggplot2 object; the title reports the resulting distance.
}
\description{
Visualizes the point correspondence that realizes the Wasserstein or
bottleneck distance between two persistence diagrams in a given
homological dimension: both diagrams' points, overlaid on the same axes,
joined by dashed lines to their matched partner - either a point of the
other diagram, or (for a point left unmatched) its own projection onto
the diagonal \code{birth = death}.
}
\details{
Essential (death = \code{Inf}) points are capped exactly the way
\code{\link{wasserstein_distance}} does (see its Details) so they take
part in the matching instead of being dropped, and are drawn as triangles
at their capped height - marked "essential" in the legend - so they stay
visually distinguishable from genuine finite points that happen to reach
that height. Matches to the diagonal are always drawn to the point's
perpendicular projection \code{((birth+death)/2, (birth+death)/2)}
regardless of \code{ground}, since that is the standard, readable way to
depict an unmatched point whichever ground metric produced the matching.
}
\examples{
df1 <- data.frame(dim = c(0, 0), birth = c(0, 0), death = c(1, 2))
df2 <- data.frame(dim = c(0, 0), birth = c(0, 0), death = c(1, 3))
plot_matching(df1, df2, dimension = 0, distance = "wasserstein", p = 2)
}
