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)

Bases: _Warping

Identity warping.

Leaves the data as they are: the model sees the variable in its own units. What a continuous likelihood uses when it is given no warping.

forward(x)

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)

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.Spline(size, knots_per_arm=5, backbone='cubic')

Bases: _Warping

Uses 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, backbone='cubic')

Initializer for Spline.

Parameters:

• knots_per_arm (int) – The number of knots used to build each side (positive and negative) of the spline.

• backbone (str) – The interpolant between the knots: “cubic” (the monotonic cubic, the default) or “rq” (the monotonic rational quadratic, whose inverse is a closed form rather than an iteration). Same knots and slopes either way.

forward(x)

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)

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, weights=None)

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].

• weights – One declustering weight per row: the empirical CDF the knots are placed on is then the weighted one, so the target distribution is the field’s rather than the sampling’s.

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

Rotation

the 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)

Bases: _Warping

A Warping that simply normalizes the values to z-scores.

__init__(size, mean=None, std=None, robust=False)

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)

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)

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, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

class geoml.warping.Softplus(size, shift=1e-06)

Bases: _Warping

Transforms the data using the inverse of the softplus function. All the data must be positive.

__init__(size, shift=1e-06)

Initializer for Softplus.

Parameters:

shift (float) – A positive value to add to the data. Use it if you have zeros.

forward(x)

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)

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.Log(size, shift=1e-06)

Bases: _Warping

Log-scale warping.

Forward function: log Backward function: exp

__init__(size, shift=1e-06)

Initializer for Log.

Parameters:

shift (float) – A positive value to add to the data. Use it if you have zeros.

forward(x)

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)

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.ChainedWarping(*warpings)

Bases: _Warping

Chains multiple Warping objects.

Applies the warpings in order on the way into the model and in reverse on the way out, the width each gives out being the width the next takes in. Each link is initialized on the data as the links before it leave them.

__init__(*warpings)

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.

refresh()

Recomputes whatever internal state forward and backward read.

A no-op for the closed-form warpings. The likelihood calls it once at each of its entry points, so a warping with real state (the flow) pays for it per call rather than per invocation – integrated_backward alone runs the backward once per noise node. Deliberately a per-call recomputation and never a stored-Variable cache, which would cut the training gradients to the state’s parameters.

forward(x)

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)

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, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

class geoml.warping.Scale(size, scale=1)

Bases: ZScore

Linear scaling, assuming a mean of zero.

Divides each column by a scale and subtracts nothing, so zero stays zero. Initialized from the data’s range.

initialize(x, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

backward(x)

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.Sigmoid(size, shift=1e-06)

Bases: _Warping

Sigmoid warping, for values constrained to the ]0, 1[ interval.

Forward function: inverse sigmoid Backward function: sigmoid

__init__(size, shift=1e-06)

Initializer for Sigmoid.

Parameters:

shift (float) – A positive value to ensure the data is constrained to the ]0, 1[ interval.

forward(x)

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)

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.Center(size, mean=None)

Bases: ZScore

A Warping that simply centers the data.

__init__(size, mean=None)

Initializer for Center.

The mean can be computed from the data (if omitted) or specified.

Parameters:

mean (double) – The desired mean of the data.

initialize(x, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

class geoml.warping.ContinuousNormalizingFlow(size, inducing_points=20, n_steps=10, step=0.01, rtol=1e-06)

Bases: _ContinuousFlow

A continuous-time flow on a fixed, separable space-time field.

The velocity field is a deterministic Gaussian-kernel interpolant over anchors that never move: Sobol points covering the [-5, 5] box (the chain leads with a ZScore, so the flow sees whitened units) crossed with regular time knots on [0, 1], the covariance factorizing as K_space (x) K_time. refresh settles the field with one Cholesky per factor; forward then integrates the augmented state (x, log_det) with an adaptive Dormand-Prince solver, and backward integrates the same field with time reversed, so the round trip is exact to the solver tolerance rather than to a scheme mismatch. The divergence driving the log-determinant is analytic – the derivative of the spatial kernel factor – and the map decays to the identity away from the box, so nothing steep ever reaches the tails.

__init__(size, inducing_points=20, n_steps=10, step=0.01, rtol=1e-06)

Initializer for ContinuousNormalizingFlow.

Parameters:

• size – Number of components. The flow exists to mix them; a single component is Spline’s job.

• inducing_points – Number of spatial anchors – Sobol points covering the [-5, 5] box, fixed by construction.

• n_steps – Number of time knots of the field over [0, 1].

• step – Accepted so saves from versions before 0.6.9 replay, and ignored: the integration interval is fixed at [0, 1] and the amplitude parameter carries the scale.

• rtol – Relative tolerance of the solver, shared by both directions and by the log-determinant.

alpha: Tensor | None

chol_space: Tensor | None

chol_time: Tensor | None

refresh()

Recomputes whatever internal state forward and backward read.

A no-op for the closed-form warpings. The likelihood calls it once at each of its entry points, so a warping with real state (the flow) pays for it per call rather than per invocation – integrated_backward alone runs the backward once per noise node. Deliberately a per-call recomputation and never a stored-Variable cache, which would cut the training gradients to the state’s parameters.

class geoml.warping.TensorProductFlow(size, grid=9, rank=5, n_steps=10, rtol=1e-06)

Bases: _ContinuousFlow

A continuous-time flow on a gridded field with CP-structured weights.

The field lives on the full (size + 1)-dimensional lattice – a regular grid on each [-5, 5] axis crossed with the time knots – and escapes the curse of dimensionality by never forming the lattice: the weight tensor is a rank-R canonical polyadic sum of per-axis vectors, sum_r lambda_r a_r^(1) (x) … (x) a_r^(size) (x) a_r^(t) (x) a_r^(c) with a component axis, and because the kernel is separable the field factorizes through it into one-dimensional kernel sums: O(R (size * grid + knots)) per evaluation, with the grid tensor’s grid^size * knots entries never materialized. Whitening survives the structure too – a Kronecker-factored operator acts axis-wise on CP factors – so the coefficients cost one small triangular solve per axis. The divergence is exact, the derivative landing on one axis’ factor at a time.

A zero factor would gate its whole rank’s gradients, so every factor initializes at unit scale and the per-rank amplitude weights alone holds the field near the identity at the start.

__init__(size, grid=9, rank=5, n_steps=10, rtol=1e-06)

Initializer for TensorProductFlow.

Parameters:

• size – Number of components. The flow exists to mix them.

• grid – Nodes per axis of the regular [-5, 5] grid.

• rank – Number of canonical-polyadic terms – the capacity knob.

• n_steps – Number of time knots of the field over [0, 1].

• rtol – Relative tolerance of the solver, shared by both directions and by the log-determinant.

refresh()

Recomputes whatever internal state forward and backward read.

A no-op for the closed-form warpings. The likelihood calls it once at each of its entry points, so a warping with real state (the flow) pays for it per call rather than per invocation – integrated_backward alone runs the backward once per noise node. Deliberately a per-call recomputation and never a stored-Variable cache, which would cut the training gradients to the state’s parameters.

class geoml.warping.CenteredLogRatio(n_dim)

Bases: _Warping

The 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.

forward(x)

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)

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.PCA(n_dim, n_components=None)

Bases: _Warping

Principal components: correlated columns turned into uncorrelated ones.

Centres the data, rotates them onto the eigenvectors of their covariance and scales each component to unit variance, all fixed when the warping is initialized on the data; nothing is trained. With fewer components than columns the data are projected onto the leading ones.

Parameters:

• n_dim – The number of columns taken in.

• n_components – The number given out; all of them if left out.

forward(x)

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)

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, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

class geoml.warping.RobustPCA(n_dim, n_components=None, support_fraction=0.75)

Bases: PCA

Principal components of a robust covariance.

PCA with the mean and covariance estimated by the minimum covariance determinant (FastMCD), from the most concentrated share of the data, so a few outlying samples cannot set the axes. Seeded from the package generator.

Parameters:

• n_dim – The number of columns taken in.

• n_components – The number given out; all of them if left out.

• support_fraction – The share of the samples the robust estimate is made from.

initialize(x, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

class geoml.warping.Rotation(n_dim, fixed=False)

Bases: Identity

An 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.

See also

PCA, RobustPCA, by

Spline

the per-component warping usually placed after this one.

forward(x)

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)

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, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

class geoml.warping.ScaledSimplex(size)

Bases: Identity

Compositional data transformation without log-ratios.

Accepts zeros.

forward(x)

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)

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, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

class geoml.warping.BoxCox(size, shift=1e-06, exponent=1.0)

Bases: _Warping

Box-Cox power transform with a trainable exponent.

Maps x to ((x + shift)**λ - 1) / λ, the logarithm at λ = 0, with one exponent per component. The exponent starts at the value that makes the column most Gaussian – the profile likelihood of Box and Cox – and trains with the model. For positive data it is the power link between the logarithm and the identity, and its inverse is a root rather than an exponential, which is what keeps a latent draw in the tail from blowing up the way Log.backward does.

Parameters:

• size – Number of components.

• shift – A positive value added to the data before the power, which gives a zero a logarithm. Where the data hold zeros it wants the order of their smallest positive value: a zero shifted by far less sits so far down the logarithm that the zeros alone pull the exponent toward it, and the inverse steepens with it.

• exponent – The starting exponent, one value or one per component; initialize replaces it.

Notes

The exponent is kept in [0, 2]. A zero maps to (shift**λ - 1) / λ, and a latent draw below that comes back as zero: its pre-image lies under zero, and past -1/λ there is none at all, so backward never returns a negative value whatever the shift. A negative exponent bounds the transformed values above, and the inverse then blows up toward that bound – measured on Jura at 826 times the data’s maximum on tail draws, with the mean prediction destroyed in one arm – so negative exponents are not offered.

References

Box, G. E. P., & Cox, D. R. (1964). An analysis of transformations. Journal of the Royal Statistical Society: Series B, 26(2), 211-252.

forward(x)

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)

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, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

class geoml.warping.YeoJohnson(size, exponent=1.0)

Bases: _Warping

Yeo-Johnson power transform with a trainable exponent.

Box-Cox extended to the whole real line: the power λ acts on 1 + x for x >= 0 and the power 2 - λ on 1 - x for x < 0, so the map is smooth through zero, the identity at λ = 1, and needs no shift. One exponent per component, started at the most Gaussian value by the profile likelihood and trained with the model. The link for a centred or residual column, where BoxCox cannot go.

Parameters:

• size – Number of components.

• exponent – The starting exponent, one value or one per component; initialize replaces it.

Notes

The exponent is kept in [0, 2], where both powers are non-negative and the inverse is defined for every real value. Outside it one side of the map is bounded and its inverse blows up toward the bound, the hazard BoxCox documents.

References

Yeo, I.-K., & Johnson, R. A. (2000). A new family of power transformations to improve normality or symmetry. Biometrika, 87(4), 954-959.

forward(x)

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)

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, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

class geoml.warping.Arcsinh(size, scale=1.0)

Bases: _Warping

Inverse hyperbolic sine warping, with a trainable scale.

Maps x to asinh(x / scale): the identity for values small against the scale, the logarithm of 2 |x| / scale far from it, on both sides of zero. Tolerates zeros and negatives with no shift, which is what recommends it over Log for a variable that is skewed but not strictly positive. The scale starts at the value that makes the column most Gaussian and trains with the model.

Parameters:

• size – Number of components.

• scale – The starting scale, one value or one per component; initialize replaces it.

References

Johnson, N. L. (1949). Systems of frequency curves generated by methods of translation. Biometrika, 36(1-2), 149-176.

Burbidge, J. B., Magee, L., & Robb, A. L. (1988). Alternative transformations to handle extreme values of the dependent variable. Journal of the American Statistical Association, 83(401), 123-127.

forward(x)

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)

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, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.

class geoml.warping.SinhArcsinh(size, skewness=0.0, tailweight=1.0)

Bases: _Warping

Sinh-arcsinh warping, with trainable skewness and tail weight.

Maps x to sinh(δ asinh(x) - ε): ε skews the distribution, δ sets its tail weight (below one heavier than the Gaussian, above one lighter), and ε = 0, δ = 1 is the identity. The inverse is closed form, sinh((asinh(z) + ε) / δ). Meant for a column already centred and scaled, as by ZScore: the curvature of the map sits at unit scale. The two parameters start at the values that make the column most Gaussian and train with the model. Between them they cover what Arcsinh and Johnson’s S_U system do.

Parameters:

• size – Number of components.

• skewness – The starting ε, one value or one per component; initialize replaces it.

• tailweight – The starting δ, likewise.

References

Jones, M. C., & Pewsey, A. (2009). Sinh-arcsinh distributions. Biometrika, 96(4), 761-780.

forward(x)

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)

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, weights=None)

Uses the provided values to initialize the object’s parameters.

A data-dependent start, not a fit — and weights is how a declustered start arrives: one weight per row, as container.decluster() stores them, so a crowded patch of drilling does not set the target distribution. A warping with nothing to weight accepts and ignores them; None reproduces the unweighted start exactly.

Parameters:

• x (array-like) – Vector with values to warp.

• weights (array-like, optional) – One declustering weight per row of x.

Returns:

x (array-like) – Vector with warped values.