pyemma.coordinates.cluster_regspace

pyemma.coordinates.cluster_regspace(data=None, dmin=-1, max_centers=1000, stride=1, metric='euclidean')

Regular space clustering

If given data, it performs a regular space clustering [1] and returns a RegularSpaceClustering object that can be used to extract the discretized data sequences, or to assign other data points to the same partition. If data is not given, an empty RegularSpaceClustering will be created that still needs to be parametrized, e.g. in a pipeline().

Regular space clustering is very similar to Hartigan’s leader algorithm [2]. It consists of two passes through the data. Initially, the first data point is added to the list of centers. For every subsequent data point, if it has a greater distance than dmin from every center, it also becomes a center. In the second pass, a Voronoi discretization with the computed centers is used to partition the data.

Parameters:
  • data (ndarray (T, d) or list of ndarray (T_i, d) or a reader created by :func:`source) – input data, if available in memory
  • dmin (float) – the minimal distance between cluster centers
  • max_centers (int (optional), default=1000) – If max_centers is reached, the algorithm will stop to find more centers, but it is possible that parts of the state space are not properly ` discretized. This will generate a warning. If that happens, it is suggested to increase dmin such that the number of centers stays below max_centers.
  • stride (int, optional, default = 1) – If set to 1, all input data will be used for estimation. Note that this could cause this calculation to be very slow for large data sets. Since molecular dynamics data is usually correlated at short timescales, it is often sufficient to estimate transformations at a longer stride. Note that the stride option in the get_output() function of the returned object is independent, so you can parametrize at a long stride, and still map all frames through the transformer.
  • metric (str) – metric to use during clustering (‘euclidean’, ‘minRMSD’)
Returns:

regSpace – Object for regular space clustering. It holds discrete trajectories and cluster center information.

Return type:

a RegularSpaceClustering clustering object

class pyemma.coordinates.clustering.regspace.RegularSpaceClustering(dmin, max_centers=1000, metric='euclidean')

Regular space clustering

Methods

assign([X, stride]) Assigns the given trajectory or list of trajectories to cluster centers by using the discretization defined by this clustering method (usually a Voronoi tesselation).
describe(*args, **kwargs) Get a descriptive string representation of this class.
dimension() output dimension of clustering algorithm (always 1).
fit(X, **kwargs) For compatibility with sklearn
fit_transform(X, **kwargs) For compatibility with sklearn
get_output([dimensions, stride]) Maps all input data of this transformer and returns it as an array or list of arrays.
iterator([stride, lag]) Returns an iterator that allows to access the transformed data.
map(X) Deprecated: use transform(X)
n_frames_total([stride]) Returns total number of frames.
number_of_trajectories() Returns the number of trajectories.
output_type()
parametrize([stride]) Parametrize this Transformer
register_progress_callback(call_back[, stage]) Registers the progress reporter.
sample_indexes_by_cluster(clusters, nsample) Samples trajectory/time indexes according to the given sequence of states.
save_dtrajs([trajfiles, prefix, output_dir, ...]) saves calculated discrete trajectories. Filenames are taken from
trajectory_length(itraj[, stride]) Returns the length of trajectory of the requested index.
trajectory_lengths([stride]) Returns the length of each trajectory.
transform(X) Maps the input data through the transformer to correspondingly shaped output data array/list.

Attributes

chunksize chunksize defines how much data is being processed at once.
clustercenters Array containing the coordinates of the calculated cluster centers.
data_producer where the transformer obtains its data.
dmin Minimum distance between cluster centers.
dtrajs Discrete trajectories (assigned data to cluster centers).
in_memory are results stored in memory?
index_clusters Returns trajectory/time indexes for all the clusters
logger The logger for this class instance
max_centers Cutoff during clustering.
name The name of this instance
ntraj
overwrite_dtrajs Should existing dtraj files be overwritten.
assign(X=None, stride=1)

Assigns the given trajectory or list of trajectories to cluster centers by using the discretization defined by this clustering method (usually a Voronoi tesselation).

You can assign multiple times with different strides. The last result of assign will be saved and is available as the attribute dtrajs().

Parameters:
  • X (ndarray(T, n) or list of ndarray(T_i, n), optional, default = None) – Optional input data to map, where T is the number of time steps and n is the number of dimensions. When a list is provided they can have differently many time steps, but the number of dimensions need to be consistent. When X is not provided, the result of assign is identical to get_output(), i.e. the data used for clustering will be assigned. If X is given, the stride argument is not accepted.
  • stride (int, optional, default = 1) – If set to 1, all frames of the input data will be assigned. Note that this could cause this calculation to be very slow for large data sets. Since molecular dynamics data is usually correlated at short timescales, it is often sufficient to obtain the discretization at a longer stride. Note that the stride option used to conduct the clustering is independent of the assign stride. This argument is only accepted if X is not given.
Returns:

Y – The discretized trajectory: int-array with the indexes of the assigned clusters, or list of such int-arrays. If called with a list of trajectories, Y will also be a corresponding list of discrete trajectories

Return type:

ndarray(T, dtype=int) or list of ndarray(T_i, dtype=int)

chunksize

chunksize defines how much data is being processed at once.

clustercenters

Array containing the coordinates of the calculated cluster centers.

data_producer

where the transformer obtains its data.

describe(*args, **kwargs)

Get a descriptive string representation of this class.

dimension()

output dimension of clustering algorithm (always 1).

dmin

Minimum distance between cluster centers.

dtrajs

Discrete trajectories (assigned data to cluster centers).

fit(X, **kwargs)

For compatibility with sklearn

fit_transform(X, **kwargs)

For compatibility with sklearn

get_output(dimensions=slice(0, None, None), stride=1)

Maps all input data of this transformer and returns it as an array or list of arrays.

Parameters:
  • dimensions (list-like of indexes or slice) – indices of dimensions you like to keep, default = all
  • stride (int) – only take every n’th frame, default = 1
Returns:

output – the mapped data, where T is the number of time steps of the input data, or if stride > 1, floor(T_in / stride). d is the output dimension of this transformer. If the input consists of a list of trajectories, Y will also be a corresponding list of trajectories

Return type:

ndarray(T, d) or list of ndarray(T_i, d)

Notes

  • This function may be RAM intensive if stride is too large or too many dimensions are selected.
  • if in_memory attribute is True, then results of this methods are cached.

Example

plotting trajectories

>>> import pyemma.coordinates as coor 
>>> import matplotlib.pyplot as plt 

Fill with some actual data!

>>> tica = coor.tica() 
>>> trajs = tica.get_output(dimensions=(0,), stride=100) 
>>> for traj in trajs: 
...     plt.figure() 
...     plt.plot(traj[:, 0]) 
in_memory

are results stored in memory?

index_clusters

Returns trajectory/time indexes for all the clusters

Returns:indexes – For each state, all trajectory and time indexes where this cluster occurs. Each matrix has a number of rows equal to the number of occurrences of the corresponding state, with rows consisting of a tuple (i, t), where i is the index of the trajectory and t is the time index within the trajectory.
Return type:list of ndarray( (N_i, 2) )
iterator(stride=1, lag=0)

Returns an iterator that allows to access the transformed data.

Parameters:
  • stride (int) – Only transform every N’th frame, default = 1
  • lag (int) – Configure the iterator such that it will return time-lagged data with a lag time of lag. If lag is used together with stride the operation will work as if the striding operation is applied before the time-lagged trajectory is shifted by lag steps. Therefore the effective lag time will be stride*lag.
Returns:

iterator – If lag = 0, a call to the .next() method of this iterator will return the pair (itraj, X) : (int, ndarray(n, m)), where itraj corresponds to input sequence number (eg. trajectory index) and X is the transformed data, n = chunksize or n < chunksize at end of input.

If lag > 0, a call to the .next() method of this iterator will return the tuple (itraj, X, Y) : (int, ndarray(n, m), ndarray(p, m)) where itraj and X are the same as above and Y contain the time-lagged data.

Return type:

a TransformerIterator

logger

The logger for this class instance

map(X)

Deprecated: use transform(X)

Maps the input data through the transformer to correspondingly shaped output data array/list.

max_centers

Cutoff during clustering. If reached no more data is taken into account. You might then consider a larger value or a larger dmin value.

n_frames_total(stride=1)

Returns total number of frames.

Parameters:stride (int) – return value is the number of frames in trajectories when running through them with a step size of stride.
Returns:int
Return type:n_frames_total
name

The name of this instance

ntraj
number_of_trajectories()

Returns the number of trajectories.

Returns:int
Return type:number of trajectories
output_type()
overwrite_dtrajs

Should existing dtraj files be overwritten. Set this property to True to overwrite.

parametrize(stride=1)

Parametrize this Transformer

register_progress_callback(call_back, stage=0)

Registers the progress reporter.

Parameters:
  • call_back (function) –

    This function will be called with the following arguments:

    1. stage (int)
    2. instance of pyemma.utils.progressbar.ProgressBar
    3. optional *args and named keywords (**kw), for future changes
  • stage (int, optional, default=0) – The stage you want the given call back function to be fired.
sample_indexes_by_cluster(clusters, nsample, replace=True)

Samples trajectory/time indexes according to the given sequence of states.

Parameters:
  • clusters (iterable of integers) – It contains the cluster indexes to be sampled
  • nsample (int) – Number of samples per cluster. If replace = False, the number of returned samples per cluster could be smaller if less than nsample indexes are available for a cluster.
  • replace (boolean, optional) – Whether the sample is with or without replacement
Returns:

indexes – List of the sampled indices by cluster. Each element is an index array with a number of rows equal to N=len(sequence), with rows consisting of a tuple (i, t), where i is the index of the trajectory and t is the time index within the trajectory.

Return type:

list of ndarray( (N, 2) )

save_dtrajs(trajfiles=None, prefix='', output_dir='.', output_format='ascii', extension='.dtraj')

saves calculated discrete trajectories. Filenames are taken from given reader. If data comes from memory dtrajs are written to a default filename.

Parameters:
  • trajfiles (list of str (optional)) – names of input trajectory files, will be used generate output files.
  • prefix (str) – prepend prefix to filenames.
  • output_dir (str) – save files to this directory.
  • output_format (str) – if format is ‘ascii’ dtrajs will be written as csv files, otherwise they will be written as NumPy .npy files.
  • extension (str) – file extension to append (eg. ‘.itraj’)
trajectory_length(itraj, stride=1)

Returns the length of trajectory of the requested index.

Parameters:
  • itraj (int) – trajectory index
  • stride (int) – return value is the number of frames in the trajectory when running through it with a step size of stride.
Returns:

int

Return type:

length of trajectory

trajectory_lengths(stride=1)

Returns the length of each trajectory.

Parameters:stride (int) – return value is the number of frames of the trajectories when running through them with a step size of stride.
Returns:array(dtype=int)
Return type:containing length of each trajectory
transform(X)

Maps the input data through the transformer to correspondingly shaped output data array/list.

Parameters:X (ndarray(T, n) or list of ndarray(T_i, n)) – The input data, where T is the number of time steps and n is the number of dimensions. If a list is provided, the number of time steps is allowed to vary, but the number of dimensions are required to be to be consistent.
Returns:Y – The mapped data, where T is the number of time steps of the input data and d is the output dimension of this transformer. If called with a list of trajectories, Y will also be a corresponding list of trajectories
Return type:ndarray(T, d) or list of ndarray(T_i, d)

References

[1]Prinz J-H, Wu H, Sarich M, Keller B, Senne M, Held M, Chodera JD, Schuette Ch and Noe F. 2011. Markov models of molecular kinetics: Generation and Validation. J. Chem. Phys. 134, 174105.
[2]Hartigan J. Clustering algorithms. New York: Wiley; 1975.