duncanwp / esem

Easy emulating of geophysical models including (but not limited to!) Earth System Models.

Earth System Emulator (ESEm)

A tool for emulating geophysical datasets including (but not limited to!) Earth System Models.

Why ESEm?

While excellent tools exist for regression and emulation, and similarly for efficient calibration, there isn't a single package that makes it easy for Earth scientists to emulate and calibrate their models. ESEm provides a simple interface to do so, with a thin wrapper around familiar emulation engines and efficient sampling tools.

ESEm can use Iris Cubes or xarray DataArrays to retain useful geophysical information about the data being emulated and also streamlines the typical task of co-locating models and observations for comparison using e.g. CIS.

These tasks aren't just restricted to emulating and calibrating models though and can be used in any situation where regression of Earth system data is needed.

Documentation

Detailed instructions and example notebooks can be found in our official documentation at https://esem.readthedocs.io/en/latest/

Installation

ESEm can be easily installed using pip, including tensorflow (with GPU support):

$ pip install esem

Optionally also install GPFlow, keras or scikit-learn e.g.,:

$ pip install esem[gpflow]

For more detailed instructions, including using conda to install alongside iris or xarray see https://esem.readthedocs.io/en/latest/installation.html

Citation

If you use ESEm in your research please be sure to cite our paper:

@Article{gmd-2021-267,
AUTHOR = {Watson-Parris, D. and Williams, A. and Deaconu, L. and Stier, P.},
TITLE = {Model calibration using ESEm v1.0.0 -- an open, scalable Earth System Emulator},
JOURNAL = {Geoscientific Model Development Discussions},
VOLUME = {2021},
YEAR = {2021},
PAGES = {1--24},
URL = {https://gmd.copernicus.org/preprints/gmd-2021-267/},
DOI = {10.5194/gmd-2021-267}
}

Contributing

Contributions to ESEm of any size are very welcome, please see our Contributing page for more details.

Get in touch

• Ask general installation and usage questions ("How do I?") in our Discussions tab.
• Report bugs and suggest features in the Issues tab

License

Copyright 2019-2021 Duncan Watson-Parris

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

esem's Issues

Update README to reflect new license

I think the README needs to be updated now as well? Should have thought of this during #11 but nevermind ...

Add model parameter inputs

Need to be able to specify the kernel(s) and noise variance (or nugget) for GPs. Maybe the NN structure?

It's not clear exactly how far to abstract this. In principle the model class should just be a constructor for the model anyway... Maybe the NN and GP classes are just examples of a model which needs spatial structure and one that doesn't.

Add an option for a probabilistic threshold for ABC

Real ABC (as opposed to history matching) treats the standardized distance probabilistically and just samples compares it with samples from a normal distribution similarly to MCMC.

It would be great to add an option to enable this, perhaps by setting threshold=None.

MultiNest inference technique

I recently came across this inference technique used in astrophysics that might be useful in our setting: https://academic.oup.com/mnras/article/398/4/1601/981502.

Installation is Broken

Hi

I'm not able to install ESEm via pip and because it cannot find compatible version of tensorflow. I believe that requirement are to loosely specified. However it is essentially impossible for me to guess which version of tensorflow, numpy, and python that is supported.

Quickstart page

Create a very simple toy-model (ideally using the existing testing routines), plot it, emulate it and then calibrate some parameters.

Save a trained model for future use?

Wow! Great project - thanks for your hard work.

Is there a way to save a trained model, load it into a new notebook, and run inference? Apologies if this is documented somewhere.

e.g.

rf_model = rf_model(X_train, Y_train)
rf_model.train()
rf_model.save("rf_model.pb") # <---- Is there anything like this?

and then in a new notebook

rf_model = esem.open("rf_model.pb") # <---- Is there anything like this?

Add Random Forest model

Basically a wrapper around the scikit-learn implementation.

Notes:

• Random Forests have relatively few hyperparameters, but it should be possible to pass these as keywords to the model.
• The predict method will just return a mean, with variance=None, similar to the neural net.

Add support for masked data

This should be easy for GPs where we can just ignore masked values when flattening (although reshaping at the end will need to be done with care). I'm not sure what support keras has for masked values (or NaNs)