Save your models in PyEMMA

Most of the Estimators and Models in PyEMMA are serializable. If a given Estimator or Model can be saved to disk, it provides a save method. In this notebook we will explain the basic concepts of file handling.

We try our best to provide future compatiblity of already saved data. This means it should always be possible to load data with a newer version of the software, but you can not do reverse, eg. load a model saved by a new version with an old version of PyEMMA.

If you are interested in the technical background, go ahead and read the source code (it is not that much actually).

import pyemma
import numpy as np
import os
import pprint
pyemma.config.mute = True

# delete all saved data
def rm_models():
    import glob
    for f in glob.glob('*.h5'):
        os.unlink(f)
rm_models()

# generate some artificial data with 10 states
dtrajs = [np.random.randint(0, 10, size=10000) for _ in range(5)]

# estimate a Bayesian Markov state model
bmsm = pyemma.msm.bayesian_markov_model(dtrajs, lag=10)
print(bmsm)

We can now save the estimator (which contains the model) to disk.

# now save our model
bmsm.save('my_models.h5')

We can now restore the model, by simply invoking pyemma.load function with our file name.

pyemma.load('my_models.h5')

BayesianMSM(conf=0.95, connectivity='largest', count_mode='effective',
      dt_traj='1 step', lag=10, mincount_connectivity='1/n', nsamples=100,
      nsteps=3, reversible=True, show_progress=False, sparse=False,
      statdist_constraint=None)

Note that we can save multiple models in one file. Because HDF5 acts like a file system, we have each model in a separate “folder”, which is completely independent of the other models. We now change a parameter during estimation and save the estimator again in the same file, but in a different “folder”.

bmsm.estimate(dtrajs, lag=100)
print(bmsm)
bmsm.save('my_models.h5', model_name='lag100')

Likewise when we want to restore the model with the new name, we have to pass it to the load function accordingly.

pyemma.load('my_models.h5', model_name='lag100')

BayesianMSM(conf=0.95, connectivity='largest', count_mode='effective',
      dt_traj='1 step', lag=100, mincount_connectivity='1/n', nsamples=100,
      nsteps=3, reversible=True, show_progress=False, sparse=False,
      statdist_constraint=None)

As you may have noted, there is no need to pass a model name. For convenience we always save under model_name “latest”, if the argument is not provided. To check which models are contained in a file, we provide a command line tool named “pyemma_list_models”.

! pyemma_list_models

! pyemma_list_models my_models.h5

You can also check the list of already stored models directly in PyEMMA.

content = pyemma.list_models('my_models.h5')
print("available models:", content.keys())
print("-" * 80)
print("detailed:")
pprint.pprint(content)

Overwriting existing models is also possible, but we have to tell the save method, that we want to overwrite.

# we now expect that we get a failure, because the model already exists in the file.
try:
    bmsm.save('my_models.h5')
except RuntimeError as e:
    print("can not save:", e)

bmsm.save('my_models.h5', overwrite=True)

Save Pipelines

In PyEMMA coordinates one often has chains of Estimators, eg. a reader followed by some transformations and finally a clustering. If you want to preserve this definition of data flow, you can set this during save.

# create some data, note that this in principle could also be a FeatureReader used to process MD data.
data = np.random.random((1000, 2))
from pyemma.coordinates import source, tica, cluster_kmeans

reader = source(data)
tica = tica(reader, lag=10)
clust = cluster_kmeans(tica)

print('clustering:', clust)
print('tica:', tica)
print('source:', reader)

The setting “save_streaming_chain” controls, if we want to save the input chain of the object being saved.

clust.save('pipeline.h5', save_streaming_chain=True)

The list models tools will also show the saved chain in a human readable fashion.

! pyemma_list_models pipeline.h5

restored = pyemma.load('pipeline.h5')

print('clustering:', restored)
print('tica:', restored.data_producer)
print('source:', restored.data_producer.data_producer)

As you see, we can access all elements of the pipeline by the data_producer attribute. In principle we can just assign these to variables again and change estimation parameters and re-estimate parts of the pipeline.

This concludes the storage tutorial of PyEMMA. Happy saving!