Transport

With the default target, T.reference is the Reference distribution used by the fit. An array supplied through target= instead gives arbitrary-target transport without reference-law or quantile-region features.

yemale.ot.fit(source, *, target=None)

Fit a reusable Transport from n observations to n + 1 targets.

Each later query appends one candidate: zeta(z) = (Z_1, …, Z_n, z). With target centres m_j, its assignment minimizes squared Euclidean cost:

\[\sigma_z\in\arg\min_{\sigma\in\mathfrak S_{n+1}} \sum_{i=1}^{n+1}\|\zeta_i(z)-m_{\sigma(i)}\|^2.\]

A query uses original source coordinates and does not solve a new assignment.

Parameters:

• source – Finite observations of shape (n, d). Use (n, 1) for scalar data.

• target – Matching Reference or finite target array of shape (n + 1, d). Defaults to reference(n, d). Target coordinates are used as supplied; they need not match the source’s centre or scale. Array targets support assignment and smoothing, but do not provide reference-cell laws.

Notes

For d > 1, fitting allocates a temporary cost matrix of 8 * (n + 1)**2 bytes. The one-dimensional solver avoids this matrix. Sources are centred and divided by their root-mean-square distance from the mean, using one scale for all coordinates (1 for identical sources). Coordinates are not standardized separately; if needed, choose feature scales independently of calibration and apply them to sources and queries. Assignment labels are invariant to a common target translation or positive scalar rescaling, up to floating-point precision. Returned targets retain the supplied values.

class yemale.ot.Transport

Assign each candidate to a target after appending it to the fitted source.

Build with fit. Each query is a separate n + 1 assignment. Queries use original source coordinates: (d,) or (..., d). Map and sign outputs keep the coordinate axis; label, rank and potential outputs do not. In one dimension, scalar and flat-vector queries also work.

reference

Reference used to construct the targets, or None for array targets.

Type:

yemale.ot.reference.Reference | None

property phi

Branch offsets in potential, with shape (n + 1,).

Use original source coordinates. A common additive constant is fixed by the fit; it does not affect assignments or derivatives.

label(point)

Return the assigned target index, from 0 to n, for each candidate.

__call__(point)

Map source points to their assigned centres in target coordinates.

\[T(z)=m_{k(z)},\qquad k(z)=\sigma_z(n+1).\]

Accept a point (d,) or batch (..., d) and keep its shape. Here sigma_z is the augmented assignment from fit, and m_j are the target centres. With the default reference, outputs lie in the unit ball.

rank(point)

Return the center-outward rank: the radius of the assigned target.

\[\mathrm{Rank}(z)=\|T(z)\|.\]

Smaller radii indicate more central reference cells. Default-reference ranks take discrete values in [0, 1); the minimum need not be zero. Custom targets retain their own radii. Return one value per candidate.

sign(point)

Return the assigned target’s unit direction; a zero target gives zero.

\[\mathrm{Sign}(z)=T(z)/\|T(z)\|\qquad\text{when }T(z)\ne0.\]

This direction is in target space, not from the source mean to the point. Return one vector per candidate, keeping the coordinate axis.

evaluate(point)

Return label, target, rank, sign and potential in one dictionary.

Use this when several outputs are needed; their target lookup is shared. Values match the corresponding methods, with target from self(point).

potential(point)

Return the convex potential whose gradient is this map away from ties.

\[\Phi(z)=\max_{1\leq j\leq n+1}\{\langle z,m_j\rangle-\phi_j\}.\]

Here m_j are the targets and phi_j are the offsets in phi. Accept (d,) or (..., d) in original source coordinates; return one scalar per candidate.

halfspaces(label)

Return A, b describing the closed source cell: A @ z <= b.

\[V_j=\bigcap_{k\ne j}\{z:\langle z,m_k-m_j\rangle \leq\phi_k-\phi_j\}.\]

For a label in 0, ..., n, return shapes (n, d) and (n,). Closed cells share boundaries; label(point) assigns boundary points.

assignment(point)

Return target indices for all source points followed by the candidate.

A point (d,) returns (n + 1,). Batches (..., d) return (..., n + 1) independent assignments, keeping singleton batch axes. The output uses 8 * q * (n + 1) bytes for q candidates; use label if only each candidate’s target index is needed.

For regions and distributions, see Quantile regions and Distributions. For the candidate-augmented construction, see the guide.