EspressoProblem

EspressoProblem#

class espresso.EspressoProblem(example_number: int = 1)[source]#

Base class for all Espresso problems. All Espresso problems shoud be a subclass of this class.

Parameters:: example_number (int, optional) – The index of example you want to access. A typical Espresso problem will have several examples that have indices starting from 1. By default 1.
Raises:: InvalidExampleError – when you’ve passed in an example number that isn’t included in current problem

Metadata

Problem-sepecific metadata include the following keys:

problem_title
problem_short_description
author_names
contact_name
contact_email
citations
linked_sites

And they can be accessed through the metadata dictionary:

>>> from espresso import <ProblemClass>
>>> <ProblemClass>.metadata["problem_title"]
This is a problem about...
>>> <ProblemClass>.metadata.keys()
dict_keys(['problem_title', 'problem_short_description', 'author_names', 'contact_name', 'contact_email', 'citations', 'linked_sites'])

Required attributes

Required methods and properties are guaranteed to be written by problem contributors and available for user to access.

`EspressoProblem.model_size`	Returns the number of model parameters
`EspressoProblem.data_size`	Returns the number of data points
`EspressoProblem.good_model`	Returns a model vector that the contributor regards as a sensible explanation of the dataset
`EspressoProblem.starting_model`	Returns a model vector representing a typical starting point for inversion
`EspressoProblem.data`	Returns a data vector in the same format as output by `forward`
`EspressoProblem.forward`(model[, return_jacobian])	Perform forward simulation with a model to produce synthetic data

Optional attributes

Optional methods and properties have standards but are not always implemented for each Espresso problem. Try using them or check the documentation page for each problem to figure out whether they are available.

`EspressoProblem.description`	Returns a brief description of current example
`EspressoProblem.covariance_matrix`	Returns the covariance matrix for the data
`EspressoProblem.inverse_covariance_matrix`	Returns the inverse data covariance matrix for the data
`EspressoProblem.jacobian`(model)	Returns the Jacobian matrix
`EspressoProblem.plot_model`(model)	Returns a figure containing a basic visualisation of the model
`EspressoProblem.plot_data`(data1[, data2])	Returns a figure containing a basic visualisation of a dataset and (optionally) comparing it to a second dataset
`EspressoProblem.misfit`(data, pred)	Returns a measure of the extent to which a predicted data vector agrees with observed data
`EspressoProblem.log_likelihood`(data, pred)	Returns the log likelihood density value
`EspressoProblem.log_prior`(model)	Returns the log prior density value

Reference Details

abstract EspressoProblem.forward(model: ndarray, return_jacobian: bool = False) → ndarray[source]#

Perform forward simulation with a model to produce synthetic data

If return_jacobian == True, returns (d, G); else, returns d, where:

d : numpy.ndarray, shape(data_size,), a simulated data vector corresponding to the given model
G : numpy.ndarray, shape(data_size, model_size), the Jacobian such that \(G[i,j] = \partial d[i]/\partial model[j]\)

If an example does not permit calculation of the Jacobian then calling with return_jacobian=True should result in a NotImplementedError being raised.

Parameters:

model (numpy.ndarray) – a model vector, in the same shape of model_size
return_jacobian (bool) – a switch governing the output required

Returns:

(d, G) or d, depending on the value of return_jacobian. Details above.

Return type:

(numpy.ndarray, numpy.ndarray) | numpy.ndarray

EspressoProblem.jacobian(model: ndarray) → ndarray[source]#

Returns the Jacobian matrix

Parameters:: model (numpy.ndarray) – a model vector, in the same shape of model_size
Returns:: the Jacobian such that \(G[i,j] = \partial d[i]/\partial model[j]\), in the shape of (data_size, model_size)
Return type:: numpy.ndarray

EspressoProblem.list_capabilities() → list[source]#

Returns a dictionary describing the capabilities of the current example

Examples

>>> import espresso
>>> r = espresso.ReceiverFunctionInversionShibutani()
>>> r.list_capabilities()
['model_size', 'data_size', 'good_model', 'starting_model', 'data', 'description', 'covariance_matrix', 'plot_model', 'plot_data', 'log_likelihood', 'log_prior', 'rf', 'capability_report']

EspressoProblem.log_likelihood(data: ndarray, pred: ndarray) → Number[source]#

Returns the log likelihood density value

Parameters:

data (numpy.ndarray) – An observed data vector to base on
pred (numpy.ndarray) – A predicted data vector to evaluate

Returns:

The log likelihood that data is an imperfect observation of a system generating data pred.

Return type:

Number

EspressoProblem.log_prior(model: ndarray) → Number[source]#

Returns the log prior density value

Parameters:: model (numpy.ndarray) – A model vector to evaluate, shape(model_size)
Returns:: The log probability that a system is described by model prior to seeing any data.
Return type:: Number

EspressoProblem.misfit(data: ndarray, pred: ndarray) → Number[source]#

Returns a measure of the extent to which a predicted data vector agrees with observed data

Parameters:

data (numpy.ndarray) – An observed data vector to base on
pred (numpy.ndarray) – A predicted data vector to evaluate

Returns:

A measure of the extent to which a predicted data vector, pred, agrees with observed data, data. Smaller numbers imply better agreement; 0 -> perfect match.

Return type:

Number

EspressoProblem.plot_data(data1: ndarray, data2: ndarray | None = None) → Axes[source]#

Returns a figure containing a basic visualisation of a dataset and (optionally) comparing it to a second dataset

Parameters:

data (numpy.ndarray) – A data vector for visualisation
data2 (numpy.ndarray, optional) – A second data vector, for comparison with the first, by default None

Returns:

A matplotlib Axes handle containing a basic visualisation of a dataset and (optionally) comparing it to a second dataset.

Return type:

matplotlib.axes.Axes

EspressoProblem.plot_model(model: ndarray) → Axes[source]#

Returns a figure containing a basic visualisation of the model

Parameters:: model (numpy.ndarray) – a model vector for visualisatioin, in the same shape of model_size
Returns:: A matplotlib Axes handle containing a basic visualisation of the model.
Return type:: matplotlib.axes.Axes

EspressoProblem.author_names = NotImplemented#

EspressoProblem.citations = NotImplemented#

EspressoProblem.contact_email = NotImplemented#

EspressoProblem.contact_name = NotImplemented#

EspressoProblem.covariance_matrix#

Returns the covariance matrix for the data

Returns:: The covariance matrix describing any uncertainty and correlations in the data vector. The output has shape (data_size, data_size)
Return type:: numpy.ndarray

EspressoProblem.data#

Returns a data vector in the same format as output by forward

Returns:: A data vector in the same shape as data_size and the output from forward
Return type:: numpy.ndarray

EspressoProblem.data_size#

Returns the number of data points

Returns:: The number of data points (i.e. the dimension of a data vector).
Return type:: int

EspressoProblem.description#

Returns a brief description of current example

Returns:: A string containing a brief (1-3 sentence) description of the example.
Return type:: str

EspressoProblem.good_model#

Returns a model vector that the contributor regards as a sensible explanation of the dataset

Returns:: A model vector that the contributor regards as being a ‘correct’ or ‘sensible’ explanation of the dataset. (In some problems it may be the case that there are many ‘equally good’ models. The contributor should select just one of these.) It has the same shape as model_size.
Return type:: numpy.ndarray

EspressoProblem.inverse_covariance_matrix#

Returns the inverse data covariance matrix for the data

Returns:: The inverse data covariance matrix, in the shape (data_size, data_size)
Return type:: numpy.ndarray

EspressoProblem.linked_sites = NotImplemented#

EspressoProblem.model_size#

Returns the number of model parameters

Returns:: The number of model parameters (i.e. the dimension of a model vector).
Return type:: int

EspressoProblem.problem_short_description = NotImplemented#

EspressoProblem.problem_title = NotImplemented#

EspressoProblem.starting_model#

Returns a model vector representing a typical starting point for inversion

Returns:: A model vector, possibly just np.zeros(model_size), representing a typical starting point or ‘null model’ for an inversion. It has the same shape as model_size.
Return type:: numpy.ndarray

EspressoProblem

Contents

EspressoProblem#