Quantile regions#

Fit source points with transport = ot.fit(source), then request a central 90% region with transport.quantile_region(0.9). See the guide for the construction and a worked example.

Transport.quantile_region(coverage, *, randomized=True, rng=None)[source]#

Return a quantile region with the requested marginal coverage.

\[W_j\sim\nu(\,\cdot\mid L_j),\qquad \Omega=\bigcup_{j:\|W_j\|\leq 1-\alpha}V_j^\dagger.\]
Parameters:
  • coverage – Probability in [0, 1], equal to 1 - alpha.

  • randomized – Draw once per reference cell, then keep membership fixed. Defaults to True. False selects whole shells of target centres.

  • rng – Seed or NumPy Generator for reproducible randomization.

Under exchangeability and almost-sure uniqueness of the augmented assignment, coverage averages over observations and randomization, not one fitted sample. The selected-cell fraction can differ from the request. With randomized=False, return the smallest region {z: ||T(z)|| <= r} reaching coverage; equal-radius cells enter together and can overshoot. Requires reference cells. Return a QuantileRegion.

class yemale.ot.QuantileRegion[source]#

Source cells selected by reference radius.

Create with transport.quantile_region(coverage). Randomization is enabled by default.

radius#

Reference-ball radius; applied to cell draws when randomized, and to target centres otherwise.

Type:

float

randomized#

Whether reference-cell draws selected the cells.

Type:

bool

property coverage#

Marginal coverage, averaging over data and any region randomization.

For a randomized region, the realized fraction len(labels) / (n + 1) can differ from this probability.

contains(point)#

Return whether each point belongs to the region.

halfspaces()#

Return (A, b) for every closed source cell in the region.

property labels#

Zero-based labels of the included cells.

select(points)#

Return accepted observations in input order, preserving their shape.

points has shape (q, d), or (q,) for scalar observations.

Reference sets#

For a different shape, choose a reference set B through membership. The function receives reference points (q, d) and returns one Boolean per row. region.contains still receives source points: it tests B(transport(points)).

def B(u):
    return u[:, 0] >= 0

region = transport.region(B)
points = [[0.2, 0.4], [-0.5, -0.3]]
region.contains(points)  # Boolean mask
region.select(points)    # Accepted rows, in input order

region.coverage is the fraction of target centers in B, not generally its continuous reference probability \(\nu(B)\). For the marginal coverage guarantee, choose B independently of the fitted observations.

Reference coordinates versus probability levels#

For a continuous one-dimensional population with CDF \(F^\star\), the center-outward map and the conversion of probability levels \([a,b]\) are

\[T^\star(z)=2F^\star(z)-1,\qquad B=[2a-1,\,2b-1].\]

The reference uses coordinates in \([-1,1]\). The 5th-to-95th percentile range therefore gives \(B=[-0.9,0.9]\); use transport.quantile_region(0.9) for a central 90% region with the default randomization. In multiple dimensions, specify B through membership in reference space.

Transport.region(reference_set)[source]#

Return the source region mapped into a fixed target set B.

\[\mathcal Q_T(B)=\{z:T(z)\in B\}.\]

reference_set takes target points (q, d) and returns one Boolean per point. For the default 1-D reference, u = 2*p - 1 converts probability levels to reference coordinates: [0.05, 0.95] becomes [-0.9, 0.9]. Use quantile_region(0.9) for central 90% coverage. For a data-independent B, marginal coverage is the fraction of target centres in B, not generally its continuous reference probability.

class yemale.ot.Region[source]#

Source points whose assigned targets belong to a chosen reference set.

Create with transport.region(reference_set).

property labels#

Zero-based labels of the included cells.

property coverage#

Fraction of reference cells included in the region.

For a fixed reference set, this is marginal coverage under exchangeability and almost-sure uniqueness of the augmented assignment.

contains(point)[source]#

Return whether each point belongs to the region.

select(points)[source]#

Return accepted observations in input order, preserving their shape.

points has shape (q, d), or (q,) for scalar observations.

halfspaces()[source]#

Return (A, b) for every closed source cell in the region.

Density regions#

law.density_region(mass=0.9) selects a density superlevel set. threshold is its density cutoff; mass is the numerically integrated probability at or above that cutoff under the chosen law. Quantile-region coverage describes marginal future-data coverage under the exchangeability and assignment assumptions.

class yemale.ot.DensityRegion[source]#

Points whose density reaches a cutoff, including ties.

Create with law.density_region(mass) or reference.density_region(mass). mass estimates the included density integral, not the coverage of future observations.

mass#

Estimated density integral over the region, including cutoff ties.

Type:

float

property threshold#

Density cutoff; membership is compared in log space.

contains(points)[source]#

Return membership for one point or a batch, preserving batch axes.