API reference

This page documents the modules, classes, and functions provided by the probeye package.

Problem definition

class ForwardModelBase(prms_def_, input_sensors, output_sensors)

Bases: object

This class serves as a base class for any forward model. When you want to define a specific forward model, you need to derive your own class from this one, and then define the ‘__call__’ method. The latter essentially describes the model function mapping the model input to the output.

property input_channel_names

Provides input_channel_names attribute.

property input_sensor_names

Provides input_sensor_names attribute.

jacobian(inp)

Numerically computes the Jacobian matrix of the forward model and returns it in form of a dictionary. Note that this method should be overwritten, if there is a more efficient way to compute the jacobian, for example, when one can compute the Jacobian analytically.

Parameters

inp (dict) – Contains both the exp. input data and the model’s parameters. The keys are the names, and the values are their numeric values.

Returns

jac_dict – The Jacobian matrix in dict-form: The keys are the names of the forward model’s output sensors. The values are dictionaries with the forward model’s input channel’s names as keys and the derivatives or Nones as values. Derivatives are only provided for the model’s parameters, see self.prms_def. For all other input channels (e.g., measurements from an experiment) None is written to the dictionary’s values, since they are not required by sampling routines. To give an example: the element jac[‘y’][‘a’] would give the derivative dy/da, and jac[‘y’] would give the gradient of the forward model’s y-computation with respect to the input channels in a dictionary-format.

Return type

dict or numpy.ndarray

jacobian_dict_to_array(inp, jac_dict, n_inp_dim)

Converts the Jacobian in dict-format (computed by the above ‘jacobian’ method) into a numpy array. This method is external to the above ‘jacobian’ method, so that it is easier for a user to overwrite the it (i.e., the ‘jacobian’ method) without also having to define the conversion into an array.

Parameters

• inp (dict) – See docstring of the ‘jacobian’-method above.

• jac_dict (dict) – See docstring of the ‘jacobian’-method above.

• n_inp_dim (int) – The added-up dimensions of the forward model’s input channels, i.e., of all model parameters and other input variables.

Returns

jac – Similar structure as the conventional Jacobi matrix with respect to the columns and rows (i.e. the rows are the different gradients and the columns are derivatives with respect to one fixed parameter).

Return type

numpy.ndarray

property output_sensor_names

Provides input_sensor_names attribute.

response(inp)

Evaluates the model response and provides computed results for all of the model’s output sensors. This method must be overwritten by the user.

Parameters

inp (dict) – Contains both the exp. input data and the model’s parameters. The keys are the names, and the values are their numeric values.

Returns

Contains the model response (value) for each output sensor, referenced by the output sensor’s name (key).

Return type

dict

class InferenceProblem(name, use_default_logger=True, log_file=None)

Bases: object

This class provides a general framework for defining an inference problem. Capabilities for solving the set up problem are intentionally not included.

add_experiment(exp_name, sensor_values, fwd_model_name)

Adds a single experiment to the inference problem. Here, an experiment is defined as one or more sensors (note that the experiment does not distinguish between input and output sensors) which provide some measured data. Additionally, a reference to one of the problem’s forward models is associated with an experiment.

Parameters

• exp_name (str) – The name of the experiment, e.g. “Exp_20May.12”. If an experiment with a similar name has already been added, it will be overwritten and a warning will be thrown.

• sensor_values (dict) – The keys are the sensor’s names, the values are the measured values.

• fwd_model_name (str) – Name of the forward model this experiment refers to.

add_forward_model(name, forward_model)

Adds a forward model to the inference problem. Note that multiple forward models can be added to one problem.

Parameters

• name (str) – The name of the forward model to be added.

• forward_model (obj[ForwardModelBase]) – Defines the forward model. Check out forward_model.py to see a template for the forward model definition. The user will then have to derive his own forward model from that base class.

add_noise_model(noise_model)

Adds a noise model to the inference problem.

Parameters

noise_model (obj[NoiseModelBase]) – The noise model object, e.g. from NormalNoise. Check out noise.py to see some noise model classes.

add_parameter(prm_name, prm_type, dim=1, const=None, prior=None, info='No explanation provided', tex=None)

Adds a parameter (‘const’ or ‘latent’) to the inference problem. For more information, check out the Parameters.add_parameter method.

assign_experiments_to_noise_models()

Assigns each noise model the corresponding experiment names, based on the sensor names, that are defined for each noise model. This function is intended to be called after the problem was fully defined. Alternatively, you can assign the experiments ‘by hand’, by using the NoiseModelBase’s ‘add_experiments’ method.

change_constant(prm_name, new_value)

Changes the value of a ‘const’-parameter, i.e. a constant parameter of the inference problem.

Parameters

• prm_name (str) – The name of the ‘const’-parameter whose value should be changed.

• new_value (float) – The new value that prm_name should assume.

change_parameter_info(prm_name, new_info=None, new_tex=None)

Changes the info-string and/or the tex-string of a given parameter.

Parameters

• prm_name (str) – The name of the parameter whose info-string should be changed.

• new_info (str, None, optional) – The new string for the explanation of parameter prm_name.

• new_tex (str, None, optional) – The new string for the parameter’s tex-representation.

change_parameter_role(prm_name, const=None, prior=None)

Performs the necessary tasks to change a parameter’s role in the problem definition. A parameter’s role can either be changed from ‘const’ to ‘latent’ or from ‘latent’ to ‘const’.

Parameters

• prm_name (str) – The name of the parameter whose role should be changed.

• const (float or None, optional) – If the new role is ‘const’, the corresponding value has to be specified by this argument.

• prior (tuple of two elements or None, optional) – If the added parameter is a ‘latent’-parameter, this argument has to be given as a 2-tuple. The first element (a string) defines the prior-type (will be referenced in inference routines). The 2nd element must be a dictionary stating the prior’s parameters as keys and their numeric values as values or the name of a pre-defined parameter within the problem scope. An example for a normal prior: (‘normal’, {‘loc’: 0.0, ‘scale’: 1.0}). In order to define the prior’s parameters, check out the prior definitions in priors.py.

check_problem_consistency()

Conducts various checks to make sure the problem definition does not contain any inconsistencies.

property constant_prms

Provides constant_prms attribute.

property constant_prms_dict

Provides constant_prms_dict attribute.

property experiments

Access self._experiments from outside via self.experiments.

property forward_models

Access self._forward_models from outside via self.forward_models.

get_experiment_names(forward_model_names=None, sensor_names=None, experiment_names=None)

Extracts the names of all experiments which refer to a given list of forward models and/or to a given list of sensor names from a given list of experiment names.

Parameters

• forward_model_names (str, list[str] or None, optional) – The names of the forward model the experiments should refer to.

• sensor_names (list or None, optional) – The names of the sensors the experiments should should contain.

• experiment_names (str, list[str] or None, optional) – The names of the experiments to sub-select from. If None is given, then all experiments of the problem will be used.

Returns

relevant_experiment_names – The names of the sub-selected experiments.

Return type

list

get_parameters(theta, prm_def)

Extracts the numeric values for given parameters from the parameter vector theta and the constant parameters of the problem.

Parameters

• theta (array_like) – A numeric parameter vector passed to the loglike and logprior method. Which parameters these numbers refer to can be checked by calling self.theta_explanation() once the problem is set up.

• prm_def (dict) – Defines which parameters to extract. The keys of this dictionary are the global parameter names, while the values are the local parameter names. In most cases global and local names will be identical, but sometimes it is convenient to define a local parameter name, for example in the forward model.

Returns

prms – Contains <local parameter name> : <(global) parameter value> pairs.

Return type

dict

get_theta_names(tex=False, components=False)

Returns the parameter names of the parameter vector theta in the corresponding order.

Parameters

• tex (bool, optional) – If True, the TeX-names of the parameters will be returned, otherwise the names as they are used in the code will be returned.

• components (bool, optional) – If True, parameters with dimension > 1 are returned component-wise; e.g., if ‘alpha’ is a 2D parameter, it will be returned as ‘alpha_1’ and ‘alpha_2’. If False, only ‘alpha’ would be returned.

Returns

theta_names – List of strings with the parameter names appearing in theta.

Return type

list

info(include_experiments=False, tablefmt='presto', check_consistency=True)

Either prints the problem definition to the console (print_it=True) or just returns the generated string without printing it (print_it=False).

Parameters

• include_experiments (bool, optional) – If True, information on the experiments defined within the model will be included in the printout. Depending on the number of defined experiments, this might result in a long additional printout, which is why this is set to False (no experiment printout) by default.

• tablefmt (str, optional) – An argument for the tabulate function defining the style of the generated table. Check out tabulate’s documentation for more info.

• check_consistency (bool, optional) – When True, a consistency check is performed before printing the explanations on theta. When False, this check is skipped.

Returns

The constructed string when ‘print_it’ was set to False.

Return type

string or None

property latent_prms

Provides latent_prms attribute.

property latent_prms_dims

Provides latent_prms_dims attribute.

property model_prms

Provides model_prms attribute.

property n_constant_prms

Provides n_constant_prms attribute.

property n_latent_prms

Provides n_latent_prms attribute.

property n_latent_prms_dim

Provides n_latent_prms_dim attribute.

property n_model_prms

Provides n_model_prms attribute.

property n_noise_prms

Provides n_noise_prms attribute.

property n_prior_prms

Provides n_prior_prms attribute.

property n_prms

Provides n_prms attribute.

property noise_models

Access self._noise_models from outside via self.noise_models.

property noise_prms

Provides noise_prms attribute.

property parameters

Access self._parameters from outside via self.parameters.

property prior_prms

Provides prior_prms attribute.

property priors

Provides the problem’s prior-dictionary which is derived from the latent parameters in the self.parameters dictionary. The keys are the priors names, while the values are the prior-objects.

property prms

Provides prms attribute.

remove_parameter(prm_name)

Removes a parameter (‘const’ or ‘latent’) from inference problem.

Parameters

prm_name (str) – The name of the parameter to be removed.

theta_explanation(check_consistency=True)

Logs and returns a string on how the theta-vector, which is the numeric parameter vector that is given to the self.loglike and self.logprior methods, is interpreted with respect to the problem’s parameters. The printout will tell you which parameter is connected to which index of theta.

Parameters

check_consistency (bool, optional) – When True, a consistency check is performed before printing the explanations on theta. When False, this check is skipped.

Returns

s – The constructed string when ‘log’ was set to False.

Return type

str or None

transform_experimental_data(f, args=(), **kwargs)

Creates a full copy of the problem the experimental data of which is transformed in some way. This might be a necessary pre-processing step for an inference engine in order to be able to solve the problem. Note that the original problem remains unchanged.

Parameters

• f (callable) – The function that is applied on each of the experiment’s sensor values.

• args (tuple) – Additional positional arguments to be passed to f.

• kwargs – Keyword arguments to be passed to f.

Returns

self_copy – A full copy of self where the experimental data has been transformed in the specified fashion.

Return type

obj[InferenceProblem]

Post-processing

create_pair_plot(inference_data, problem, plot_with='arviz', plot_priors=True, focus_on_posterior=False, kind='kde', figsize=(9, 9), textsize=10, true_values=None, show_legends=True, show=True, **kwargs)

Creates a pair-plot for the given inference data using arviz.

Parameters

• inference_data (obj[arviz.data.inference_data.InferenceData]) – Contains the results of the sampling procedure.

• problem (obj[InferenceProblem]) – The inference problem the inference data refers to.

• plot_with ({'arviz', 'seaborn', 'matplotlib'}, optional) – Defines the python package the plot will be generated with.

• plot_priors (bool, optional) – If True, the prior-distributions are included in the marginal subplots. Otherwise the priors are not shown.

• focus_on_posterior (bool, optional) – If True, the marginal plots will focus on the posteriors, i.e., the range of the horizontal axis will adapt to the posterior. This might result in just seeing a fraction of the prior distribution (if they are included). If False, the marginal plots will focus on the priors, which will have a broader x-range. If plot_priors=False, this argument has no effect on the generated plot.

• kind (str, optional) – Type of plot to display (‘scatter’, ‘kde’ and/or ‘hexbin’).

• figsize (tuple, None, optional) – Defines the size of the generated plot in the default unit. If None is chose, the figsize will be derived automatically.

• textsize (float, optional) – Defines the font size in the default unit.

• true_values (None, dict, optional) – Used for plotting ‘true’ parameter values. Keys are the parameter names and values are the values that are supposed to be shown in the marginal plots.

• show_legends (bool, optional) – If True, legends are shown in the marginal plots. Otherwise no legends are included in the plot.

• show (boolean, optional) – When True, the show-method is called after creating the plot. Otherwise, the show-method is not called. The latter is useful, when the plot should be further processed.

• kwargs – Additional keyword arguments passed to arviz’ pairplot function.

Returns

The subplots of the created plot.

Return type

array[matplotlib.axes._subplots.AxesSubplot]

create_posterior_plot(inference_data, problem, plot_with='arviz', kind='hist', figsize=(10, 3), textsize=10, hdi_prob=0.95, true_values=None, show=True, **kwargs)

Creates a posterior-plot for the given inference data using arviz.

Parameters

• inference_data (obj[arviz.data.inference_data.InferenceData]) – Contains the results of the sampling procedure.

• problem (obj[InferenceProblem]) – The inference problem the inference data refers to.

• plot_with ({'arviz', 'seaborn', 'matplotlib'}, optional) – Defines the python package the plot will be generated with.

• kind (str, optional) – Type of plot to display (‘kde’ or ‘hist’).

• figsize (tuple, None, optional) – Defines the size of the generated plot in the default unit. If None is chose, the figsize will be derived automatically.

• textsize (float, optional) – Defines the font size in the default unit.

• hdi_prob (float, optional) – Defines the highest density interval. Must be a number between 0 and 1.

• true_values (None, dict, optional) – Used for plotting ‘true’ parameter values. Keys are the parameter names and values are the values that are supposed to be shown in the marginal plots.

• show (boolean, optional) – When True, the show-method is called after creating the plot. Otherwise, the show-method is not called. The latter is useful, when the plot should be further processed.

• kwargs – Additional keyword arguments passed to arviz’ plot_posterior function.

Returns

The subplots of the created plot.

Return type

array[matplotlib.axes._subplots.AxesSubplot]

create_trace_plot(inference_data, problem, plot_with='arviz', kind='trace', figsize=(10, 6), textsize=10, show=True, **kwargs)

Creates a trace-plot for the given inference data using arviz.

Parameters

• inference_data (obj[arviz.data.inference_data.InferenceData]) – Contains the results of the sampling procedure.

• problem (obj[InferenceProblem]) – The inference problem the inference data refers to.

• plot_with ({'arviz', 'seaborn', 'matplotlib'}, optional) – Defines the python package the plot will be generated with.

• kind (str, optional) – Allows to choose between plotting sampled values per iteration (“trace”) and rank plots (“rank_bar”, “rank_vlines”).

• figsize (tuple, None, optional) – Defines the size of the generated plot in the default unit. If None is chose, the figsize will be derived automatically.

• textsize (float, optional) – Defines the font size in the default unit.

• show (boolean, optional) – When True, the show-method is called after creating the plot. Otherwise, the show-method is not called. The latter is useful, when the plot should be further processed.

• kwargs – Additional keyword arguments passed to arviz’ plot_posterior function.

Returns

The subplots of the created plot.

Return type

array[matplotlib.axes._subplots.AxesSubplot]