Interpolation between Histograms

Compute exact finite displacement interpolation between midpoint-discrete histograms with identical breaks, then project each result onto the original histogram bins. The unprojected finite measures follow the 2-Wasserstein geodesic; the projected histogram displays generally do not.

Usage

histinterp(hist1, hist2, t = 0.5, L = 2000L)

Arguments

hist1

a histogram ("histogram" object).

hist2

another histogram with the same breaks as hist1.

t

a scalar or numeric vector in \([0,1]\) specifying interpolation times. Endpoints preserve the corresponding input probability measure.

L

retained for compatibility and validated as a positive integer. The finite quantile backend uses exact mass intervals, so this argument no longer controls an approximation grid.

Value

If length(t) == 1, a single "histogram" object representing the projected interpolation at time t, including the unprojected measure. If length(t) > 1, a length-length(t) list of "histogram" objects.

Details

Inputs are discrete measures at bin midpoints, using normalized counts (or the canonical mass field of an estimated histogram). The unprojected finite result is saved in unprojected_measure. For the legacy histogram display it is binned onto the original breaks, using right-closed bins with the lowest endpoint included, and represented at bin midpoints. This projection generally changes the measure; it is not an exact unrestricted Wasserstein summary or geodesic. Downstream histogram functions consistently use the displayed midpoint measure, not the separate unprojected result. Break values must agree exactly across inputs; no grid snapping is done. When an estimated histogram is reused, its previous computational metadata is discarded. Returned diagnostics describe the current calculation. Returned mass and counts are the same probabilities; density equals mass divided by bin width. Counts are not rounded observations, and effective_sample_size is NA because an estimated measure has no implied sample size. The objective/history and solver status refer to the unprojected summary.

Examples

# \donttest{
#----------------------------------------------------------------------
#                      Interpolating Two Gaussians
#
# The source histogram is created from N(-5,1/4).
# The target histogram is created from N(+5,4)
#----------------------------------------------------------------------
# SETTING
set.seed(123)
x_source = rnorm(1000, mean=-5, sd=1/2)
x_target = rnorm(1000, mean=+5, sd=2)

# BUILD HISTOGRAMS WITH COMMON BREAKS
bk = seq(from=-8, to=12, by=2)
h1 = hist(x_source, breaks=bk, plot=FALSE)
h2 = hist(x_target, breaks=bk, plot=FALSE)

# INTERPOLATE WITH 5 GRID POINTS
h_path <- histinterp(h1, h2, t = seq(0, 1, length.out = 8))

# VISUALIZE
y_slim <- c(0, max(h1$density, h2$density)) # shared y-limit
xt     <- round(h1$mids, 1) # x-ticks

opar <- par(no.readonly = TRUE)
par(mfrow = c(2,4), pty = "s")
for (i in 1:8){
  if (i < 2){
    barplot(h_path[[i]]$density,  names.arg=xt, ylim=y_slim,
            main="Source", col=rgb(0,0,1,1/4))
  } else if (i > 7){
    barplot(h_path[[i]]$density,  names.arg=xt, ylim=y_slim,
            main="Target", col=rgb(1,0,0,1/4))
  } else {
    barplot(h_path[[i]]$density,  names.arg=xt, ylim=y_slim, 
            col="gray90", main=sprintf("t = %.3f", (i-1)/7))
  }
}

par(opar)
# }