MLGLUE package#

Submodules#

MLGLUE.Likelihoods module#

class MLGLUE.Likelihoods.InverseErrorVarianceLikelihood(threshold=0.1, T=2.0, weights=None)[source]#

Bases: object

likelihood(obs=None, sim=None, bias=None)[source]#

Compute the Inverse Variance Likelihood

Compute the Inverse Variance Likelihood:

\[L_{\ell}(\theta | Y') = \left( \frac{\sum_{j=1}^m (y_j - y'_j + \mu_{B,\ell,j} )^2}{m - 2} \right)^{-T}\]

where \(L(\cdot)\) is the likelihood function, \(\theta\) are model parameters, \(Y\) are observations, \(\mu_{B,\ell}\) is the bias up to level \(\ell\), \(m\) is the number of observations, and \(T\) is the shape parameter.

Parameters:

  • obs (1D array-like of float) – The observations of the system.

  • sim (1D array-like of float) – The simulated observation equivalents, simulated by the model.

  • bias (1D array-like of float) – The bias on the level to which the current call to the likelihood belongs. Has the same length as obs and sim.

Returns:

likelihood – The likelihood computed from observations, simulated observation equivalents, and the bias term.

Return type:

float

class MLGLUE.Likelihoods.RelativeVarianceLikelihood(threshold=0.1, weights=None)[source]#

Bases: object

likelihood(obs=None, sim=None, bias=None)[source]#

Compute the Relative Variance Likelihood

Compute the Relative Variance Likelihood:

\[L(\theta | Y') = 1 - \frac{\sigma_e^2}{\sigma_{obs}^2}\]

where \(L(\cdot)\) is the likelihood function, \(\theta\) are model parameters, \(Y'\) are observations, \(\sigma_e^2\) is the variance of errors or residuals, and \(\sigma_{obs}^2\) is the variance of observed values. Note that bias is included when computing residuals as: residuals = sim - obs + bias.

Parameters:

  • obs (1D array-like of float) – The observations of the system.

  • sim (1D array-like of float) – The simulated observation equivalents, simulated by the model.

  • bias (1D array-like of float) – The bias on the level to which the current call to the likelihood belongs. Has the same length as obs and sim.

Returns:

likelihood – The likelihood computed from observations and simulated observation equivalents.

Return type:

float

class MLGLUE.Likelihoods.GaussianLogLikelihood(var, threshold=0.1, weights=None)[source]#

Bases: object

likelihood(obs=None, sim=None, bias=None)[source]#

Compute the Gaussian log-likelihood

Compute the Gaussian log-likelihood:

\[L(\theta | Y) = - \frac{n}{2}\ln(2\pi) - \frac{n}{2}\ln(\sigma^2) - \frac{1}{2}\sigma^{-2} \times \sum_{i=1}^n (y'_i(\theta) - y_i)^2\]

where \(L(\cdot)\) is the log-likelihood function, \(\theta\) are model parameters, \(y_i\) are observations, \(\sigma^2\) is the (theoretical) variance of errors or residuals, \(y'_i(\cdot)\) is the \(i\)-th model output corresponding to the \(i\)-th observation.

Parameters:

  • obs (1D array-like of float) – The observations of the system.

  • sim (1D array-like of float) – The simulated observation equivalents, simulated by the model.

  • bias – Not implemented for this likelihood.

Returns:

likelihood – The likelihood computed from observations and simulated observation equivalents.

Return type:

float

MLGLUE.MLGLUE module#

class MLGLUE.MLGLUE.MLGLUE(model, likelihood=None, lower_bounds=None, upper_bounds=None, n_samples=1000, samples=None, tuning=0.2, n_levels=1, coarsening_factor=2, obs=None, thresholds=None, multiprocessing=False, n_processors=None, hierarchy_analysis=True, savefigs='my_model', include_bias=False)[source]#

Bases: object

The MLGLUE class.

This is the basic class of the MLGLUE implementation. It is used to define all general settings of MLGLUE sampling for a given case such as the model function, the likelihood function, parameter samples (or settings for internal sample generation if no samples are given by the user directly), etc.

Parameters:

  • model (Callable) – The callable representing the model to which MLGLUE should be applied. See the Notes section below for further details.

  • likelihood – An instance of an MLGLUE likelihood object. See the Notes section below for further details.

  • lower_bounds (1D array-like of float) – The lower bounds of the uniform distribution over the model parameters. This attribute is ignored if samples are directly supplied. lower_bounds has to have shape (n_parameters,).

  • upper_bounds (1D array-like of float) – The upper bounds of the uniform distribution over the model parameters. This attribute is ignored if samples are directly supplied. upper_bounds has to have shape (n_parameters,).

  • n_samples (int) – The total number of parameter samples to draw from the uniform prior distribution. Note that this includes the samples used for tuning! This attribute is ignored if samples are directly supplied.

  • samples ((tuple of) 2D array-like of float, optional) – The prior parameter samples, which can optionally be supplied. If samples are given, lower_bounds, upper_bounds, and n_samples are ignored. Default is None. If a 2D array-like, it is considered the full set of parameter samples, including the samples used for tuning. If a tuple of 2D array-like, the first element of the tuple is considered as tuning samples and the second element as the regular samples. Every 2D array-like has to have shape (n_samples, n_parameters).

  • tuning (float) – The tuning fraction (0. < tuning < 1.). The rounded result (int(n_samples * tuning) is used to split the samples into the two parts.

  • n_levels (int) – The number of levels in the hierarchy.

  • coarsening_factor (float) – For the case of a geometric series of resolutions in the hierarchy, coarsening_factor represents the coarsening of the resolution when going from level (l) to level (l-1).

  • obs (1D array-like of float) – The observations for which the model simulates values.

  • thresholds (1D array-like of float, optional) – The level-dependent likelihood thresholds to use. Has to have shape (n_levels,). If thresholds is given, the tuning phase is skipped. Note that this has an effect on the definition of the parameter samples! Default is None.

  • multiprocessing (bool) – Whether to use multiprocessing using the Ray package or not.

  • n_processors (int, optional) – The number of CPUs to use if multiprocessing is enabled. By default, all processors are used (`n_processors`=None).

  • savefigs – Whether to save variance analysis figures or not. If None, figures will not be saved. If str, figures will be saved as png with the str as identifier.

  • hiearchy_analysis (bool) – Whether hiararchy analysis is strict or not. If not strict (False), results of variance and mean analysis are printed to the screen but MLGLUE continues independently of the result. If strict (True), results are also printed to the screen but MLGLUE is stopped if the variances and mean values between levels (l-1, l) is larger than on level (l) and / or if the variances or mean values between levels do not decay monotonically.

  • include_bias (bool) – Whether to include the computation of bias vectors or not. If included (True), a likelihood must be used which accepts a bias vector (e.g., InverseErrorVarianceLikelihood_bias). Bias is computed for lower-level models w.r.t. the highest-level model.

model#

The callable representing the model to which MLGLUE should be applied. See the Notes section below for further details.

Type:

Callable

likelihood#

An instance of an MLGLUE likelihood object. See the Notes section below for further details.

lower_bounds#

The lower bounds of the uniform distribution over the model parameters. This attribute is ignored if samples are directly supplied. lower_bounds has to have shape (n_parameters,).

Type:

1D array-like of float

upper_bounds#

The upper bounds of the uniform distribution over the model parameters. This attribute is ignored if samples are directly supplied. upper_bounds has to have shape (n_parameters,).

Type:

1D array-like of float

n_samples#

The total number of parameter samples to draw from the uniform prior distribution. Note that this includes the samples used for tuning! This attribute is ignored if samples are directly supplied.

Type:

int

samples#

The prior parameter samples, which can optionally be supplied. Note that this includes the samples used for tuning! If samples are given, lower_bounds, upper_bounds, and n_samples are ignored. Has to have shape (n_samples, n_parameters).

Type:

2D array-like of float

samples_tuning#

The (prior) parameter samples used for tuning. If samples_tuning are given, lower_bounds, upper_bounds, and n_samples are ignored. Has to have shape (n_samples, n_parameters).

Type:

2D array-like of float

samples_tuning#

The (prior) parameter samples used for sampling. If samples_sampling are given, lower_bounds, upper_bounds, and n_samples are ignored. Has to have shape (n_samples, n_parameters).

Type:

2D array-like of float

tuning#

The tuning fraction (0. < tuning < 1.). The rounded result (int(n_samples * tuning) is used to split the samples into the two parts.

Type:

float

n_levels#

The number of levels in the hierarchy.

Type:

int

coarsening_factor#

For the case of a geometric series of resolutions in the hierarchy, coarsening_factor represents the coarsening of the resolution when going from level (l) to level (l-1).

Type:

float

obs#

The observations for which the model simulates values.

Type:

1D array-like of float

thresholds#

The level-dependent likelihood thresholds to use. Has to have shape (n_levels,). If thresholds is given, the tuning phase is skipped. Note that this has an effect on the definition of the parameter samples! Default is None.

Type:

1D array-like of float

multiprocessing#

Whether to use multiprocessing using the Ray package or not.

Type:

bool

n_processors#

The number of CPUs to use if multiprocessing is enabled. By default, all processors are used (`n_processors`=None).

Type:

int

savefigs#

Whether to save variance analysis figures or not. If None, figures will not be saved. If str, figures will be saved as png with the str as identifier.

hiearchy_analysis#

Whether hiararchy analysis is strict or not. If not strict (False), results of variance and mean analysis are printed to the screen but MLGLUE continues independently of the result. If strict (True), results are also printed to the screen but MLGLUE is stopped if the variances and mean values between levels (l-1, l) is larger than on level (l) and / or if the variances or mean values between levels do not decay monotonically.

Type:

bool

selected_samples#

The array of selected samples that are accepted on the highest level; has shape (n_selected_samples, n_model_parameters)

Type:

2D array-like of float

results#

Holds simulated observation equivalents corresponding to all posterior samples; has shape (len(selected_samples), len(obs)).

Type:

2D array-like of float

results_analysis#

Holds simulated observation equivalents corresponding to all posterior samples on all levels; has shape (n_levels, len(selected_samples), len(obs)).

Type:

3D array-like of float

results_analysis_tuning#

Holds simulated observation equivalents corresponding to all tuning samples (except for tuning samples that result in an error or NaN returned by the model callable) on all levels; has shape (n_levels, len(selected_samples_tuning), len(obs))

Type:

3D array-like of float

likelihoods#

The likelihood values correpsonding to the selected samples.

Type:

1D array-like of float

normalized_likelihoods#

Normalized likelihood values used for the computation of uncertainty estimates.

Type:

1D array-like of float

likelihoods_tuning#

The likelihood values on all levels for all tuning samples (except for tuning samples that result in an error or NaN returned by the model callable) on all levels; has shape (n_levels, len(selected_samples_tuning))

Type:

2D array-like of float

highest_level_calls#

A list with the number of ones equal to the number of calls made to the model on the highest level. This is implemented like that currently as a list can be shared across processes / workers. A single variable (e.g., an int) could not be shared this way. This will be improved in the future.

Type:

1D array-like of int

include_bias#

Whether to include the computation of bias vectors or not. If included (True), a likelihood must be used which accepts a bias vector (e.g., InverseErrorVarianceLikelihood_bias). Bias is computed for lower-level models w.r.t. the highest-level model.

Type:

bool

bias#

Holds the bias vectors for all levels. Has shape (n_levels, len(obs)).

Type:

2D array-like of float

Notes

The callable for the model attribute has to accept the following arguments: parameters (1D list-like of floats representing model parameters), level (0-based integer representing the level index), n_levels (integer representing the total number of levels), obs (1D list-like of floats representing observations), likelihood (the MLGLUE likelihood function). The callable has to return a float corresponding to the likelihood of the given parameter sample and return simulation results (these results can either be only simulated observation equivalents or other simulation results; if other simulation results are given as well, the corresponding weight in the likelihood function should be set to zero). The likelihood value should be computed using a likelihood function implemented in this package; user-defined likelihood functions can be used as well but are not tested. The simulated values have to be of a type that can be appended to a list but do not have to have a certain structure otherwise. The object instance for the likelihood attribute should then have a likelihood method (see the Examples section for further details). The likelihood method has to accept the following arguments: obs (1D list-like of floats representing observations), sim (1D list-like of floats representing simulated observation equivalents). Using a likelihood included in the present package already ensures this structure. If the model function only has one level, it should be the finest / target level.

MLGLUE_tuning(samples)[source]#

Single-core MLGLUE tuning phase.

Perform the tuning phase of MLGLUE without using multiprocessing / Ray.

Parameters:

samples (2D list-like of float) – The parameter samples with which to perform tuning. Has to have the individual samples as rows and variables / model parameters as columns.

Return type:

None

Notes

This is implemented as an instance method; it cannot be used independently of an MLGLUE instance. Therefore, results are not returned by this function but are rather stored in the class / instance attributes.

analyze_variances_likelihoods(raise_error=True)[source]#

Analyze likelihood variances.

Analyze the relationships between levels in terms of variances: (1) variances of likelihood values on each individual level (2) covariances of likelihoods across levels (3) variances of the difference between likelihood values on subsequent levels.

Specifically, the following expression is evaluated for all levels:

\[\mathbb{V}[L_{\ell} - L_{\ell-1}] = \mathbb{V}[L_{\ell}] + \mathbb{V}[L_{\ell-1}] - 2 \cdot Cov[L_{\ell}-L_{\ell-1}]\]

where \(L_{\ell}\) is the random variable representing likelihood values on level \(\ell\) form the tuning phase. Then, for \(\mathbb{V}[L_{\ell}-L_{\ell-1}]\) to decay monotonically, \(2 \cdot Cov[L_{\ell}-L_{\ell-1}]\) has to be larger than \(\mathbb{V}[L_{\ell-1}]\), which implies that two subsequent levels need to be sufficiently correlated.

Parameters:

raise_error (bool) – Whether variance analysis is strict or not. If not strict (False), results of variance analysis are printed to the screen but MLGLUE continues independently of the result. If strict (True), results are also printed to the screen but MLGLUE is stopped if the variances between levels (l-1, l) is larger than on level (l) and / or if the variances between levels do not decay monotonically.

Return type:

None

analyze_means_likelihoods(raise_error=True)[source]#

Analyze likelihood mean values.

Analyze the relationships between levels in terms of mean values: (1) mean values of likelihood values on each individual level (2) mean values of the difference between likelihood values on subsequent levels.

Specifically, the following expression is evaluated for all levels:

\[\mathbb{E}[L_{\ell} - L_{\ell-1}] = \mathbb{E}[L_{\ell}] - \mathbb{E}[L_{\ell-1}]\]

where \(L_{\ell}\) is the random variable representing likelihood values on level \(\ell\) form the tuning phase. Then, for \(E[L_{\ell}-L_{\ell-1}]\) to decay monotonically, the difference in the mean values of the likelihoods on different levels has to decay.

Parameters:

raise_error (bool) – Whether mean value analysis is strict or not. If not strict (False), results of mean value analysis are printed to the screen but MLGLUE continues independently of the result. If strict (True), results are also printed to the screen but MLGLUE is stopped if the mean values of the difference between likelihood values on levels (l-1, l) are larger than on level (l) and / or if the mean values of the difference between likelihood values do not decay monotonically.

Return type:

None

calculate_thresholds(including_bias=False)[source]#

Calculate likelihood thresholds

Calculate the thresholds according to the threshold fraction given by the user as a class attribute.

Parameters:

None –

Return type:

None

calculate_initial_bias_estimate()[source]#

Calculate an intial estimate of the bias.

Calculate the intial estimate of the bias from tuning samples. This results in a bias vector for each model level except for the highest-level model. I.e., the bias is estimated w.r.t. the highest-level model. Note that only results are considered for which the likelihood is above the level-dependent threshold on all levels. If there is strong bias or if the number of tuning samples is small or if the threshold fraction is small, possibly only a small number of samples can be included for bias estimation (or sometimes even no samples at all).

Parameters:

None –

Return type:

None

recalculate_likelihoods()[source]#

Re-calculate likelihoods, accounting for bias.

Re-calculate likelihoods while accounting for the bias from the initial estimate after tuning. During tuning, likelihoods are computed without accounting for bias. In order to include the bias- adapted likelihoods for hierarchy analysis and threshold computation, they need to be re-calculated.

Parameters:

None –

Return type:

None

MLGLUE_sampling(samples)[source]#

Single-core MLGLUE sampling phase.

Perform the sampling phase of MLGLUE without using multiprocessing / Ray.

Parameters:

samples (2D list-like of float) – The parameter samples with which to perform sampling. Has to have the individual samples as rows and variables / model parameters as columns.

Return type:

None

Notes

This is implemented as an instance method; it cannot be used independently of an MLGLUE instance. Therefore, results are not returned by this function but are rather stored in the class / instance attributes.

evaluate_sample(sample, run_id)[source]#

Multiprocessing MLGLUE sampling utility.

Evaluate a single parameter sample with the MLGLUE hierarchy. This design allows for multiprocessing (using Ray).

Parameters:

  • sample (1D list-like of float) – The parameter sample which is evaluated. Each element has to represent an individual model parameter. Note that the order of the elements has to correspond to the order of model parameters in the model callable.

  • run_id (int or str) – A run identifier in the form of an integer or string (the value of run_id is converted to a str later in any case). The value of run_id is also passed to the model callable, which is especially relevant if each model run is associated with a corresponding individual working directory. Then this directory can be named including the run_id value. This resolves problems for multiprocessing when multiple such individual directories are present in the same parent directory.

Returns:

  • sample (1D list-like of float) – The parameter sample which was evaluated.

  • likelihood_ (float) – The likelihood value on the highest level corresponding to the parameter sample which was evaluated.

  • results (1D list-like of float) – The simulation results (at least all simulated observation equivalents) on the highest level corresponding to the sample which was evaluated.

  • results_analysis_sample (2D list-like of float) – The simulation results (at least all simulated observation equivalents) on all levels corresponding to the sample which was evaluated. Has the levels in rows and the individual results in columns.

  • highest_level_call (int) – An identifier if the highest level model has been called (1) or not (0) using the evaluated parameter sample. It may happen that a parameter sample reaches the highest level model but is not accepted after running the model with that sample. Such cases should be minimized for MLGLUE to have optimal efficiency.

Notes

All returns are returned together as a tuple.

evaluate_sample_tuning(sample, run_id)[source]#

Multiprocessing MLGLUE tuning utility.

Evaluate a single parameter sample for tuning with the MLGLUE hierarchy. This design allows for multiprocessing (using Ray). Although similar to the evaluate_sample method, this method is slightly different: independently of the actual likelihood value, the sample is passed through all levels in the model hierarchy.

Parameters:

  • sample (1D list-like of float) – The parameter sample which is evaluated. Each element has to represent an individual model parameter. Note that the order of the elements has to correspond to the order of model parameters in the model callable.

  • run_id (int or str) – A run identifier in the form of an integer or string (the value of run_id is converted to a str later in any case). The value of run_id is also passed to the model callable, which is especially relevant if each model run is associated with a corresponding individual working directory. Then this directory can be named including the run_id value. This resolves problems for multiprocessing when multiple such individual directories are present in the same parent directory.

Returns:

  • likelihoods_sample (1D list-like of float) – The likelihood values on all levels corresponding to the parameter sample (except for tuning samples that result in an error or NaN returned by the model callable). The order is from the lowest to the highest level.

  • results_analysis_tuning_sample (2D list-like of float) – Holds simulated observation equivalents (ans possibly other quantities returned by the model) corresponding to the tuning sample (except for tuning samples that result in an error or NaN returned by the model callable) on all levels; has the tuning samples in the first dimension, the levels in the second dimension, and the simulated values in the third dimension.

check_samples()[source]#

Check user-specified parameter samples.

Check the user-specified parameter samples. If a tuple is given, assign the elements to the respective attributes. If a single 2D array-like is given, split it into tuning and sampling parts.

Parameters:

None –

Return type:

None

get_uniform_samples()[source]#

Get uniform parameter samples.

Get uniform parameter samples in case no user-defined samples are provided. The user-defined upper and lower bounds of the parameter vector are used.

Parameters:

None –

Return type:

None

perform_MLGLUE_multiprocessing_tuning(restart_ray=True, **kwargs)[source]#

MLGLUE tuning using Ray actors.

Perform MLGLUE tuning using Ray actors for parallelization.

Parameters:

  • restart_ray (bool) – Whether to restart Ray. This is useful if the user wants to prevent Ray from restarting if it is already running (e.g., when a model is put in the object store).

  • **kwargs – Keyword arguments passed to Ray.init

Return type:

None

perform_MLGLUE_multiprocessing_sampling(restart_ray=True, **kwargs)[source]#

MLGLUE sampling using Ray actors.

Perform MLGLUE sampling using Ray actors for parallelization.

Parameters:

  • restart_ray (bool) – Whether to restart Ray. This is useful if the user wants to prevent Ray from restarting if it is already running (e.g., when a model is put in the object store).

  • **kwargs – Keyword arguments passed to Ray.init

Return type:

None

perform_MLGLUE_singlecore_tuning()[source]#

MLGLUE tuning using a single CPU.

Perform the MLGLUE tuning using a single CPU. This only includes actual computations and not the preparation of samples etc.

Parameters:

None –

Return type:

None

perform_MLGLUE_singlecore_sampling()[source]#

MLGLUE sampling using a single CPU.

Perform the MLGLUE sampling using a single CPU. This only includes actual computations and not the preparation of samples etc.

Parameters:

None –

Return type:

None

perform_MLGLUE(restart_ray=True, **kwargs)[source]#

Perform the full MLGLUE algorithm.

Perform the full MLGLUE algorithm using single-core or parallelized computation. Settings for performing all computations are obtained from instance attributes.

Parameters:

  • restart_ray (bool) – Whether to restart Ray. This is useful if the user wants to prevent Ray from restarting if it is already running (e.g., when a model is put in the object store).

  • **kwargs (dict) – Additional keyword arguments passed to Ray.init.

Returns:

  • selected_samples (2D array-like of float) – The array of selected samples that are accepted on the highest level; has individual samples as rows and variables / model parameters as columns.

  • likelihoods (1D array-like of float) – The likelihood values correpsonding to the selected samples.

  • results (2D array-like of float) – Holds simulated observation equivalents corresponding to all posterior samples; has shape (len(selected_samples), len(obs)).

Notes

The returns of this function can always be accessed by referring to the correpsonding instance attributes. This function only returns those instance attributes for convenience.

estimate_uncertainty(quantiles=[0.01, 0.5, 0.99])[source]#

Estimate simulation uncertainty.

Estimate the simulation uncertainty, i.e., normalize likelihoods, and create probability densities for the model output. From that, uncertainty estimates given by user-defined quantiles are computed. The estimates are obtained by (1) normalizing likelihood values for individual values to always be in the range [0, 1], (2) ordering model outputs according to their associated normalized likelihood value, (3) estimating CDFs for the model outputs, and (4) computing quantile estimates.

Parameters:

quantiles (1D list-like of float) – The quantiles with which to estimate the uncertainty of model outputs. Quantiles have to be given as floats in the range (0, 1). Default is [0.01, 0.50, 0.99].

Returns:

uncertainty – The uncertainty estimates where individual model outputs are in rows and quantiles are in columns (in the order corresponding to the given quantiles).

Return type:

2D list-like of float

class MLGLUE.MLGLUE.MLGLUELocalWorker(model, likelihood, obs, bias, n_levels, thresholds=None, *, _ray_trace_ctx=None)[source]#

Bases: object

The MLGLUELocalWorker class.

This is a utility class used to parallelize MLGLUE. It enables using Ray actors for parallelization (previously MLGLUE used Ray’s multiprocessing API). The class for the remote worker is defined by just inheriting from this class and using the @ray.remote decorator. The remote class is not separately documented.

Parameters:

  • model (Callable) – The callable representing the model to which MLGLUE should be applied. See the Notes section of the MLGLUE class for further details.

  • likelihood – An instance of an MLGLUE likelihood object. See the Notes section of the MLGLUE class for further details.

  • obs (1D array-like of float) – The observations for which the model simulates values.

  • bias (1D array-like of float) – The bias array with the same length as obs.

  • n_levels (int) – The number of levels in the hierarchy.

  • thresholds (1D array-like of float) – The level-dependent likelihood thresholds to use. Can be None if only tuning is considered, has to have shape (n_levels,) if sampling is considered.

model#

The callable representing the model to which MLGLUE should be applied. See the Notes section of the MLGLUE class for further details.

Type:

Callable

likelihood#

An instance of an MLGLUE likelihood object. See the Notes section of the MLGLUE class for further details.

obs#

The observations for which the model simulates values.

Type:

1D array-like of float

bias#

The bias array with the same length as obs.

Type:

1D array-like of float

n_levels#

The number of levels in the hierarchy.

Type:

int

thresholds#

The level-dependent likelihood thresholds to use. Can be None if only tuning is considered, has to have shape (n_levels,) if sampling is considered.

Type:

1D array-like of float

evaluate_sample_tuning(sample, run_id, *, _ray_trace_ctx=None)[source]#

Multiprocessing MLGLUE tuning utility.

Evaluate a single parameter sample for tuning with the MLGLUE hierarchy. This design allows for multiprocessing (using Ray). Although similar to the evaluate_sample method, this method is slightly different: independently of the actual likelihood value, the sample is passed through all levels in the model hierarchy.

Parameters:

  • sample (1D list-like of float) – The parameter sample which is evaluated. Each element has to represent an individual model parameter. Note that the order of the elements has to correspond to the order of model parameters in the model callable.

  • run_id (int or str) – A run identifier in the form of an integer or string (the value of run_id is converted to a str later in any case). The value of run_id is also passed to the model callable, which is especially relevant if each model run is associated with a corresponding individual working directory. Then this directory can be named including the run_id value. This resolves problems for multiprocessing when multiple such individual directories are present in the same parent directory.

Returns:

  • likelihoods_sample (1D list-like of float) – The likelihood values on all levels corresponding to the parameter sample (except for tuning samples that result in an error or NaN returned by the model callable). The order is from the lowest to the highest level.

  • results_analysis_tuning_sample (2D list-like of float) – Holds simulated observation equivalents (ans possibly other quantities returned by the model) corresponding to the tuning sample (except for tuning samples that result in an error or NaN returned by the model callable) on all levels; has the tuning samples in the first dimension, the levels in the second dimension, and the simulated values in the third dimension.

evaluate_sample(sample, run_id, *, _ray_trace_ctx=None)[source]#

Multiprocessing MLGLUE sampling utility.

Evaluate a single parameter sample with the MLGLUE hierarchy. This design allows for multiprocessing (using Ray).

Parameters:

  • sample (1D list-like of float) – The parameter sample which is evaluated. Each element has to represent an individual model parameter. Note that the order of the elements has to correspond to the order of model parameters in the model callable.

  • run_id (int or str) – A run identifier in the form of an integer or string (the value of run_id is converted to a str later in any case). The value of run_id is also passed to the model callable, which is especially relevant if each model run is associated with a corresponding individual working directory. Then this directory can be named including the run_id value. This resolves problems for multiprocessing when multiple such individual directories are present in the same parent directory.

Returns:

  • sample (1D list-like of float) – The parameter sample which was evaluated.

  • likelihood_ (float) – The likelihood value on the highest level corresponding to the parameter sample which was evaluated.

  • results (1D list-like of float) – The simulation results (at least all simulated observation equivalents) on the highest level corresponding to the sample which was evaluated.

  • results_analysis_sample (2D list-like of float) – The simulation results (at least all simulated observation equivalents) on all levels corresponding to the sample which was evaluated. Has the levels in rows and the individual results in columns.

  • highest_level_call (int) – An identifier if the highest level model has been called (1) or not (0) using the evaluated parameter sample. It may happen that a parameter sample reaches the highest level model but is not accepted after running the model with that sample. Such cases should be minimized for MLGLUE to have optimal efficiency.

Notes

All returns are returned together as a tuple.

MLGLUE.version module#

Module contents#