geoml.warping
How a variable’s own units are turned into the scale the latent Gaussian
lives on, and back. A warping is given to a likelihood, and chains compose
left to right — Log then ZScore then Spline is the usual shape for a
positive, skewed grade.
A warping’s second return value is the log of its Jacobian determinant, which is what makes the objective a density in the data’s own units rather than the latent one; chains add theirs. Each also declares whether one component of its input can reach another of its output, which decides how the likelihood integrates the noise.
- class geoml.warping.Identity(size)[source]
Bases:
_WarpingIdentity warping.
- class geoml.warping.Spline(size, knots_per_arm=5)[source]
Bases:
_WarpingUses a monotonic spline to convert from original to warped space and back.
The spline is assumed to work with normalized (z-score) values. It is centered at the origin and the arms span up to +/- 5 units. Its main use is to transform an asymmetric distribution to one closer to a Gaussian.
- n_knots
Total number of knots.
- Type:
int
- __init__(size, knots_per_arm=5)[source]
Initializer for Spline.
- Parameters:
knots_per_arm (int) – The number of knots used to build each side (positive and negative) of the spline.
- forward(x)[source]
Passes values through the class’s warping function.
- Parameters:
x (array-like) – Vector with values to warp.
- Returns:
x (array-like) – Vector with warped values.
log_det (array-like) – Log-derivative of warping function.
- backward(x)[source]
Transforms values back to the original units.
- Parameters:
x (array-like) – Vector with values to warp back to the original units.
- Returns:
x (array-like) – Vector with warped back values.
- initialize(x)[source]
Places the knots on the data’s own normal-score transform.
The spline’s input knots are fixed on a regular grid; what moves is where each one lands. Setting them to the marginal Gaussian anamorphosis – the empirical CDF at each knot, read through the normal quantile – starts the warping at the transform a geostatistician would apply by hand, and training refines it from there.
- Parameters:
x – Values reaching this link of the chain, one column per dimension. Expected to be roughly standardized, as the class docstring says: the knots span [-5, 5].
- Returns:
The warped values, so that a chain’s next link initializes on them.
Notes
Two compositional parameters carry each arm, so the map is monotone by construction and pinned at (-5, -5), (0, 0) and (5, 5) – a compositional vector sums to one, and those three points are what the sum buys. The fit therefore keeps the shape of the normal score transform on each arm while rescaling it to reach the anchors, which is the one approximation involved.
The knots span [-5, 5] and data rarely fills that, so the outermost knots of each arm read the same empirical quantile and ask to sit on top of one another. _arm_shares keeps the last segment of each arm at _OUTERMOST_SHARE of a uniform share instead, since that segment is the slope backward extrapolates along and a flat one inverts into an answer that leaves the scale entirely.
Without this the knots keep their uniform partition, which reads out as exactly the input grid – the identity – so a chain of Rotation and Spline pairs would rotate repeatedly with nothing gaussianizing in between, and every rotation after the first sees data the previous one already made as independent as it knows how.
An initialized spline is curved from the first iteration rather than after training, which used to matter: backward interpolated the swapped knots, an approximation good only where the map is straight, and the round trip was off by a tenth of a standard deviation. It solves the forward polynomial now (MonotonicCubicSpline.invert), so what is left is set by the transform’s own conditioning rather than by the inverse.
See also
Rotationthe usual partner before this one, likewise initialized from the data and likewise only as a starting point.
- class geoml.warping.ZScore(size, mean=None, std=None, robust=False)[source]
Bases:
_WarpingA Warping that simply normalizes the values to z-scores.
- __init__(size, mean=None, std=None, robust=False)[source]
Initializer for ZScore.
- Parameters:
mean (double) – The desired mean of the data.
std (double) – The desired standard deviation of the data.
robust (bool) – Whether to initialize from a winsorized copy of the data, so a handful of gross outliers cannot set the scale everything else is normalized by – one was measured squashing the genuine values into a sliver of a trainable warp’s working window. The clipped points still count, at the fence, so clean data fits the same moments. Meant for the warping under a Mixture likelihood, whose contamination component expects such values.
data (The mean and standard deviation can be computed from the)
specified. ((if omitted) or)
- forward(x)[source]
Passes values through the class’s warping function.
- Parameters:
x (array-like) – Vector with values to warp.
- Returns:
x (array-like) – Vector with warped values.
log_det (array-like) – Log-derivative of warping function.
- class geoml.warping.Softplus(size, shift=1e-06)[source]
Bases:
_WarpingTransforms the data using the inverse of the softplus function. All the data must be positive.
- __init__(size, shift=1e-06)[source]
Initializer for Softplus.
- Parameters:
shift (float) – A positive value to add to the data. Use it if you have zeros.
- class geoml.warping.Log(size, shift=1e-06)[source]
Bases:
_WarpingLog-scale warping.
Forward function: log Backward function: exp
- __init__(size, shift=1e-06)[source]
Initializer for Log.
- Parameters:
shift (float) – A positive value to add to the data. Use it if you have zeros.
- class geoml.warping.ChainedWarping(*warpings)[source]
Bases:
_WarpingChains multiple Warping objects.
- __init__(*warpings)[source]
- Parameters:
warpings (list) – List with Warping objects to apply in sequence.
- property elementwise
A chain is elementwise only if every link is.
One mixing link is enough to spread a component over the others, and everything applied after it sees the mixture.
- forward(x)[source]
Passes values through the class’s warping function.
- Parameters:
x (array-like) – Vector with values to warp.
- Returns:
x (array-like) – Vector with warped values.
log_det (array-like) – Log-derivative of warping function.
- class geoml.warping.Scale(size, scale=1)[source]
Bases:
ZScoreLinear scaling, assuming a mean of zero.
- class geoml.warping.Sigmoid(size, shift=1e-06)[source]
Bases:
_WarpingSigmoid warping, for values constrained to the ]0, 1[ interval.
Forward function: inverse sigmoid Backward function: sigmoid
- __init__(size, shift=1e-06)[source]
Initializer for Sigmoid.
- Parameters:
shift (float) – A positive value to ensure the data is constrained to the ]0, 1[ interval.
- class geoml.warping.Center(size, mean=None)[source]
Bases:
ZScoreA Warping that simply centers the data.
- class geoml.warping.ContinuousNormalizingFlow(size, inducing_points=20, n_steps=10, step=0.01)[source]
Bases:
_Warping- base_ip: Tensor | None
- inducing_points: Tensor
- alpha: Tensor
- chol_space: Tensor | None
- chol_time: Tensor | None
- backward(x)[source]
Transforms values back to the original units.
- Parameters:
x (array-like) – Vector with values to warp back to the original units.
- Returns:
x (array-like) – Vector with warped back values.
- class geoml.warping.CenteredLogRatio(n_dim)[source]
Bases:
_WarpingThe centered log-ratio transformation of compositional data.
Takes the logarithm of each part and subtracts the row’s mean log, which frees the composition from the constraint that its parts sum to one. The inverse is the softmax.
Notes
The transformation maps the simplex onto the hyperplane where the components sum to zero, and both are one dimension smaller than the number of parts. The log-determinant reported is the volume factor of that map, so the objective is a density on the hyperplane: values are comparable between compositional models and only loosely against a warping that transforms a variable one to one.
- class geoml.warping.PCA(n_dim, n_components=None)[source]
Bases:
_Warping- forward(x)[source]
Passes values through the class’s warping function.
- Parameters:
x (array-like) – Vector with values to warp.
- Returns:
x (array-like) – Vector with warped values.
log_det (array-like) – Log-derivative of warping function.
- class geoml.warping.Rotation(n_dim, fixed=False)[source]
Bases:
IdentityAn orthogonal rotation of the variables.
Multiplies the data by a square orthonormal matrix, which is a trainable parameter. The transformation is volume preserving, so the log-determinant it contributes is zero and the rotation neither stretches nor compresses the density.
The matrix is initialized by independent component analysis (sklearn.decomposition.FastICA), which positions the axes along the directions of maximum non-Gaussianity in the data. This makes it the natural partner of a per-component transformation placed after it: the rotation finds the directions along which the marginals depart most from a Gaussian, and the following warping is then applied where that departure lives. Rotation followed by Spline is the usual pairing.
- Parameters:
n_dim (int) – Number of variables, and the size of the rotation matrix.
fixed (bool) – Whether to keep the matrix at its initial value instead of training it. The ICA initialization is used either way.
Notes
This warping mixes its inputs, so elementwise is False for any chain containing it, and the likelihood integrates its noise over Sobol points rather than per-column Gauss-Hermite nodes.
The ICA fit is a starting point rather than a result: training moves the matrix from wherever ICA stopped, so a fit that reaches the iteration limit is not an error and its convergence warning is suppressed.
References
Hyvärinen, A., & Oja, E. (2000). Independent component analysis: algorithms and applications. Neural Networks, 13(4-5), 411-430.
- forward(x)[source]
Passes values through the class’s warping function.
- Parameters:
x (array-like) – Vector with values to warp.
- Returns:
x (array-like) – Vector with warped values.
log_det (array-like) – Log-derivative of warping function.
- class geoml.warping.ScaledSimplex(size)[source]
Bases:
IdentityCompositional data transformation without log-ratios.
Accepts zeros.
- forward(x)[source]
Passes values through the class’s warping function.
- Parameters:
x (array-like) – Vector with values to warp.
- Returns:
x (array-like) – Vector with warped values.
log_det (array-like) – Log-derivative of warping function.