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.
pointshas 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
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_settakes target points(q, d)and returns one Boolean per point. For the default 1-D reference,u = 2*p - 1converts probability levels to reference coordinates: [0.05, 0.95] becomes [-0.9, 0.9]. Usequantile_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.
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)orreference.density_region(mass).massestimates 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.