EspressoProblem

class espresso.EspressoProblem(example_number=1)

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[, with_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(data[, 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, with_jacobian=False)

Perform forward simulation with a model to produce synthetic data

If with_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 with_jacobian=True should result in a NotImplementedError being raised.

Parameters:

• model (numpy.ndarray) – a model vector, in the same shape of model_size

• with_jacobian (bool) – a switch governing the output required

Returns:

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

Return type:

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

EspressoProblem.jacobian(model)

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

Returns a dictionary describing the capabilities of the current example

Examples

>>> import espresso
>>> r = espresso.ReceiverFunction()
>>> 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, pred)

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)

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, pred)

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(data, data2=None)

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 figure handle containing a basic visualisation of a dataset and (optionally) comparing it to a second dataset.

Return type:

matplotlib.figure.Figure

EspressoProblem.plot_model(model)

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 figure handle containing a basic visualisation of the model.

Return type:

matplotlib.figure.Figure

---

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

back to top