% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Distance.R
\name{diagram_matching}
\alias{diagram_matching}
\title{Optimal point matching between two persistence diagrams}
\usage{
diagram_matching(
  df1,
  df2,
  dimension,
  distance = c("wasserstein", "bottleneck"),
  p = 2,
  ground = NULL
)
}
\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 compute,
\code{"wasserstein"} (default) or \code{"bottleneck"}.}

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

\item{ground}{Ground metric on the birth-death plane, \code{"L2"} or
\code{"Linf"}. Defaults to each distance's own default (\code{"L2"} for
Wasserstein, \code{"Linf"} for bottleneck) when left \code{NULL}.}
}
\value{
A list with \code{distance} (the matching's cost, equal to what
  \code{\link{wasserstein_distance}}/\code{\link{bottleneck_distance}}
  would return), \code{matches} (a data frame with columns
  \code{x_birth, x_death, x_essential, y_birth, y_death, y_essential,
  type}; a \code{NA} pair on one side means that row's point matched the
  diagonal), and \code{X}, \code{Y}, \code{essential_X}, \code{essential_Y}
  (the two diagrams' points after the same essential-pair capping
  \code{\link{wasserstein_distance}} uses - see its Details - and which of
  them were essential before capping).
}
\description{
Computes the same optimal matching that
\code{\link{wasserstein_distance}}/\code{\link{bottleneck_distance}}
reduce to internally, and returns it decoded into a readable table
instead of just the distance - what \code{\link{plot_matching}} draws.
Every point of both diagrams appears in exactly one row: matched to a
point of the other diagram (\code{type = "real-real"}), or matched to the
diagonal, i.e. effectively unmatched (\code{type = "x-diagonal"} for a
point of \code{df1}, \code{"y-diagonal"} for a point of \code{df2}).
}
\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))
diagram_matching(df1, df2, dimension = 0, distance = "wasserstein", p = 2)
}
