API Patterns¶
Models in msmbuilder inherit from base classes in scikit-learn, and follow a similar API. Like sklearn, each type of model is a python class. Models are “fit” to data, and can then “transform” data into a different representation. Unlike sklearn, the data here is a list (or dataset) of time-series arrays or trajectories.
Hyperparameters¶
Hyperparameters are passed in via
the __init__
method and set as instance attributes.
from msmbuilder.decomposition import tICA
tica = tICA(gamma=0.05)
tica.fit(...)
Fit¶
The estimation of model parameters is done in fit()
. In msmbuilder, the
fit()
method always accepts a list
or
dataset()
of 2-dimensional arrays as input data,
where each array represents a single timeseries (trajectory) and has a
shape of (length_of_trajectory, n_features)
. Some models can also
accept a list of MD trajectories (Trajectory
) as opposed to a
list of arrays.
features = [np.load('traj-1-features.npy'), np.load('traj-2-featues.npy')]
assert features[0].ndim == 2 and features[1].ndim == 2
clusterer = KCenters(n_clusters=100)
clusterer.fit(dataset)
Note
This is different from sklearn. In sklearn, estimators take a single
2D array as input in fit()
. Here we use a list of arrays or
trajectories. However, for many models, it’s still quite easy to go
between sklearn-style input and msmbuilder-style input, as shown in
the following code block.
import msmbuilder.cluster
import sklearn.cluster
X_sklearn = np.random.normal(size=(100, 10)) # sklearn style input: (n_samples, n_features)
X_msmb = [X_sklearn] # MSMBuilder style input: list of (n_samples, n_features)
clusterer_sklearn = sklearn.cluster.KMeans(n_clusters=5)
clusterer_sklearn.fit(X_sklearn)
clusterer_msmb = msmbuilder.cluster.KMeans(n_clusters=5)
clusterer_msmb.fit(X_msmb)
Some models like tICA
only require a single pass over the
data. In this case, use the partial_fit
method, which can incrementally
learn the model one trajectory at a time and be more memory-efficient.
Attributes¶
Parameters of the model which are learned or estimated during fit()
are always set as instance attributes that are named with a trailing
underscore. This is merely a convention, and not a special Python syntax.
tica = tICA(gamma=0.05)
tica.fit(...)
# timescales is an estimated quantity, so it ends in an underscore
print(tica.timescales_)
Transform¶
Many models also implement a transform()
method, which converts an
input dataset to an alternative representation. For example, the
transform
method of featurizers takes as input a
list of trajectories and returns a list of 2D feature arrays.
Clustering takes a list of 2D feature arrays and returns
a list of 1D sequences.
Pipelines¶
The models in msmbuilder are designed to work together as part of a
sklearn.pipeline.Pipeline
from msmbuilder.cluster import KMeans
from msmbuilder.msm import MarkovStateModel
from sklearn.pipeline import Pipeline
pipeline = Pipeline([
('cluster', KMeans(n_clusters=100)),
('msm', MarkovStateModel())
])
pipeline.fit(dataset)