EspressoProblem#

class cofi_espresso.EspressoProblem(example_number=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 cofi_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)[source]#

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)[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.log_likelihood(data, pred)[source]#

Returns the log likelihood density value

Parameters
Returns

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

Return type

Number

EspressoProblem.log_prior(model)[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, pred)[source]#

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

Parameters
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)[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 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)[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 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