LocScalePTM#

class liesel_ptm.LocScalePTM(response, knots, intercepts='pseudo_sample', loc_intercept_inference=None, scale_intercept_inference=None, centered=False, scaled=False, trafo_lambda=0.1, trafo_target_slope='identity', bspline='ptm', to_float32=True)[source]#

Bases: object

A Penalized Transformation Model for Location and Scale.

Parameters:

response (Any | Series) – Array of response values.
knots (Any) – Array of equidistant knots. Should correspond to the chosen bspline variant. See PTMKnots and OnionKnots.
intercepts (Literal['compute', 'pseudo_sample', 'sample', 'constant', 'sample_mh']) –
How to handle intercepts in the location and scale model parts. The options are:
- ”compute”: Intercepts are assumed constant and re-computed any time a value in the location or scale model part changes.
- ”pseudo_sample”: Intercepts are assumed constant and re-computed once in every MCMC iteration given the current values of the location and scale model parts.
- ”sample”: Intercepts are treated as ordinary parameters and sampled according to their inference specification in the arguments loc_intercept_inference and scale_intercept_inference. This can lead to identification issues.
- ”constant”: Intercepts are kept constant.
- ”sample_mh”: Intercepts are sampled with bespoke Metropolis-Hastings proposals. Experimental, undocumented. (default: 'pseudo_sample')
loc_intercept_inference (Any) – liesel.goose.MCMCSpec objects that define MCMC inference for intercepts, if intercepts="sample". (default: None)
scale_intercept_inference (Any) – liesel.goose.MCMCSpec objects that define MCMC inference for intercepts, if intercepts="sample". (default: None)
centered (bool) – Whether the transformation distribution should be centered and scaled to negate any side-effects the transformation might have on the location and scale of the response distribution. Can be used with intercepts="sample". See also TransformationDist. (default: False)
scaled (bool) – Whether the transformation distribution should be centered and scaled to negate any side-effects the transformation might have on the location and scale of the response distribution. Can be used with intercepts="sample". See also TransformationDist. (default: False)
trafo_lambda (float) – Parameter controlling the sharpness of transition to tail extrapolation. Is used to compute transition_width = eps * (knots[3] - knots[-4]), where transition_width indicates the width of the transition interval. Relevant only for bspline="ptm". (default: 0.1)
trafo_target_slope (Literal['identity', 'continue_linearly']) – If “continue_linearly”, there is no transition to the identity function. Instead, the spline will continue linearly in the tails with the slope fixed to the slopes at the boundaries of the core interval for left and right extrapolation, respectively. Relevant only for bspline="ptm". (default: 'identity')
bspline (Literal['ptm', 'onion', 'identity']) – Which B-spline formulation to use. The option "onion" is experimental. (default: 'ptm')
to_float32 (bool) – Whether to convert appropriate values in the model to 32-bit floats. (default: True)

intercepts#: How to handle intercepts in the location and scale model parts.

knots#: Array of knots.

response#: Response variable, an instance of liesel.model.Var.

graph#: The model graph, an instance of liesel.model.Model. Only available after build() has been called.

to_float32#: Whether to convert appropriate values in the model to 32-bit floats.

interface#: An instance of liesel.goose.LieselInterface representing graph. Only available after build() has been called.

is_initialized#: Boolean, indicating whether the model as been initialized with posterior modes.

Examples

A basic unconditional model:

import liesel_ptm as ptm
import jax

y = jax.random.normal(jax.random.key(0), (50,))

model = ptm.LocScalePTM.new_ptm(y, a=-4.0, b=4.0, nparam=20)
results = model.run_mcmc(seed=1, warmup=300, posterior=500)
samples = results.get_posterior_samples()

model.plot(samples)

dist = model.init_dist(samples) # initialize a distribution object

A basic linear location-scale model:

import jax
import liesel_ptm as ptm
from liesel_ptm import lin, term

y = jax.random.normal(jax.random.key(0), (50,))
x = jax.random.uniform(jax.random.key(1), (50,))

model = ptm.LocScalePTM.new_ptm(y, a=-4.0, b=4.0, nparam=20)

# location and scale predictors can be filled by adding terms.
xlin = lin(x, xname="x")
model.loc += term.f(xlin, fname="s")

# when adding terms to the scale model part, they are applied additively
# to the log-level automatically
model.scale += term.f(xlin, fname="g")

results = model.run_mcmc(seed=1, warmup=300, posterior=500)
samples = results.get_posterior_samples()

model.plot(samples)

A basic model with one P-spline:

import jax
import liesel_ptm as ptm
from liesel_ptm import term, ps

y = jax.random.normal(jax.random.key(0), (50,))
x = jax.random.uniform(jax.random.key(1), (50,))

model = ptm.LocScalePTM.new_ptm(y, a=-4.0, b=4.0, nparam=20)

xps = ps(x, nbases=20, xname="x")
model.loc += term.f_ig(xps, fname="s")

results = model.run_mcmc(seed=1, warmup=300, posterior=500)
samples = results.get_posterior_samples()

model.plot(samples)

Methods

`build`	Build the model graph.
`init_dist`	Construct a batched distribution from posterior samples.
`initialize`	Two-stage initialization that fits loc-scale, then transformation.
`new_gaussian`	Shortcut for initializing a Gaussian model.
`new_ptm`	Shortcut for convenient model setup.
`optim`	Optimize model parameters using the selected optimizer.
`plot`	Produce a set of diagnostic plots (qq, trafo, pdf, cdf).
`plot_qq`	Produce a QQ-plot comparing transformed r and its Gaussian reference.
`plot_r_cdf`	Plot the posterior CDF of the transformed variable r.
`plot_r_density`	Plot the posterior density of the transformed variable r.
`plot_trafo`	Plot the posterior mean and credible bands of the transformation h(r).
`run_mcmc`	Run MCMC sampling and return sampling results.
`setup_default_mcmc_kernels`	Configure default MCMC kernels for model parts.
`show_mcmc`	Logs the current MCMC configuration. If you do not see any output, you need to set up logging::.
`summarise_dist`	Return summary arrays (z, prob, log_prob, cdf) for a grid of values.
`summarise_trafo_by_samples`	Summarise transformation samples on a grid.

Attributes

`is_gaussian`	Whether the model is Gaussian.
`loc`	Location predictor
`sample_intercepts_under_constant_trafo`	If True (default), intercepts are sampled under the assumption of an identity transformation.
`scale`	Location predictor
`trafo`	Predictor for the transformation function.

LocScalePTM

Contents

LocScalePTM#