Smoothing

Smoothing is optional. It is not needed for assignments or quantile regions.

Transport.smooth(temperature=None)

Return a SmoothMap that blends target centres instead of choosing one.

temperature must be positive, in the units of potential. Larger values give a smoother map. None uses 0.05 times the source scale described in fit.

class yemale.ot.smoothing.SmoothMap

A smooth transport that blends target centres instead of choosing one.

Build with Transport.smooth. Source queries follow Transport’s shape conventions. inverse maps target points back to source coordinates.

__call__(point)

Map each source point to a softmax average of target centres.

\[T_\tau(z)=\sum_{j=1}^{n+1}p_{\tau,j}(z)m_j,\qquad p_{\tau,j}(z)= \frac{e^{(\langle z,m_j\rangle-\phi_j)/\tau}} {\sum_k e^{(\langle z,m_k\rangle-\phi_k)/\tau}}.\]

Here m_j are the targets, phi_j are the fitted offsets, and tau is temperature. Accept (d,) or (..., d); keep the input shape.

potential(point)

Return the smooth potential; its gradient is this map.

\[\Phi_\tau(z)=\tau\log\sum_{j=1}^{n+1} e^{(\langle z,m_j\rangle-\phi_j)/\tau}.\]

Here tau is temperature, m_j are the targets, and phi_j the fitted offsets. Use original source coordinates; return one value per point.

jacobian(point)

Differentiate the map with respect to original source coordinates.

\[DT_\tau(z)=\frac1\tau\mathrm{Cov}_{p_\tau(z)}(m_j).\]

The covariance uses the target centres and their softmax weights; tau is temperature. Return (d, d) for one point or (..., d, d) for a batch.

map_jacobian(point)

Return (self(point), self.jacobian(point)) with shared computation.

log_density(points)

Return the log of density for one point or a batch.

density(points)

Evaluate the smooth density in source coordinates.

\[p_\tau^Z(z)=p_\nu(T_\tau(z))|\det DT_\tau(z)|.\]

Its integral is nu(K), not one, where K is the convex hull of the target centres. No normalization is applied. Requires a Reference target whose centres affinely span the space. Accept (d,) or (..., d) and return one value per point.

density_region(mass, *, n_integration_points=256)

Select a smooth-density superlevel set by absolute integrated mass.

\[A_t=\{z:p_\tau^Z(z)\ge t\},\qquad \int_{A_t}p_\tau^Z(z)\,dz\approx\mathrm{mass}.\]

mass is positive and cannot exceed nu(K), the density’s total mass. The returned mass is approximate, not a coverage guarantee. n_integration_points sets the reference points per cell; inverse evaluations are reused for subsequent mass requests at that resolution. A request for the full known mass returns all source space.

reference_distribution(point)

Return the reference-cell mixture weighted by the smooth map at one point.

Requires a Reference target; samples stay in reference coordinates.

inverse(target)

Map target points back to source coordinates using Newton iterations.

\[Q_\tau(u)=\arg\min_z\{\Phi_\tau(z)-\langle u,z\rangle\}.\]

Phi_tau is self.potential. Targets must lie strictly inside the convex hull of the target centres. The centres must affinely span all d dimensions. Accept (d,) or (..., d) and keep the input shape.

pullback(target_law)

Return the distribution obtained by mapping target_law through inverse.

This is a Dempster-Hill predictive distribution only when reference cells have equal probability and the inverse preserves their labels.