htmd.metricdata module#

Bases: object

Class used for storing projected trajectories, their clustering and state assignments. Objects of this class are constructed by the project methods of the other projection classes. Only construct this class if you want to load saved data.

Parameters:

dat (list or numpy.ndarray) – The projected metrics
ref (list or numpy.ndarray) – Reference indices to the simulations and frames that generated the metrics
description (pandas.DataFrame) – A description of the metrics
simlist (numpy.ndarray of Sim objects) – A simulation list generated by the simlist function
fstep (float) – Size of simulation step in ns
parent (MetricData object) – The MetricData object that was used to generate this object
file (str) – Path to a saved MetricData object
trajectories (list of Trajectory objects) – A list of Trajectory objects
cluster (numpy.ndarray) – A list of cluster indexes for each frame in the data

trajectories#

A list of Trajectory objects

Type:: list of Trajectory objects

fstep#

Size of simulation step in ns

Type:: float

description#

A description of the metrics

Type:: pandas.DataFrame

K#

Number of clusters

Type:: int

N#

Number of frames in each cluster

Type:: numpy.ndarray

Centers#

Cluster centers (if available)

Type:: numpy.ndarray

property St#: List of the cluster assignments (state trajectory) of each trajectory.

abs2rel(absFrames: int | list | ndarray) → ndarray#

Convert absolute frame indexes into trajectory index-frame pairs

Useful when doing calculations on a concatenated data array of all trajectories. When you find a frame of interest you can deconcatenate the frame index to the corresponding trajectory index-frame pair.

Parameters:: absFrames (int or list or np.ndarray) – An absolute frame index or a list of absolute frame indexes
Returns:: pairs – A array where each row is a trajectory index-frame pair
Return type:: np.ndarray

Examples

>>> relidx = data.abs2rel(536)

abs2sim(absFrames: int | list | ndarray) → ndarray#

Converts absolute frame indexes into Sim-frame pairs

Parameters:: absFrames (int or list or np.ndarray) – An absolute frame index or a list of absolute frame indexes
Returns:: frames – An array of Frame objects containing the simulation object, the trajectory piece ID and the frame index.
Return type:: np.ndarray

Examples

>>> simframes = data.abs2sim(563)  # 563rd frame to simulation/frame pairs

property aggregateTime#

The total aggregate simulation time

Examples

>>> data.aggTime

append(other: MetricData) → MetricData#

Append the trajectories of another MetricData object to this one

The simulation ids of all trajectories are renumbered after appending, and any existing clustering is reset.

Parameters:: other (MetricData object) – The MetricData object whose trajectories will be appended to this one
Returns:: data – This object, with the trajectories of other appended
Return type:: MetricData object

bootstrap(ratio: float, replacement: bool = False) → MetricData#

Randomly sample a set of trajectories

Parameters:

ratio (float) – What ratio of trajectories to keep. e.g. 0.8
replacement (bool) – If we should sample with replacement

Returns:

bootdata – A new MetricData object containing only the sampled trajectories

Return type:

MetricData object

Examples

>>> data = MetricSelfDistance.project(sims, 'protein and name CA')
>>> databoot = data.bootstrap(0.8)

cluster(clusterobj, mergesmall: int | None = None, batchsize: int = 0)#

Cluster the metrics

Parameters:

clusterobj (ClusterMixin object) – The object of a clustering class from sklearn or with the same interface
mergesmall (int, optional) – Clusters containing less than mergesmall conformations will be joined into their closest well-populated neighbour.
batchsize (int) – Batch sizes bigger than 0 will enable batching.

Examples

>>> from sklearn.cluster import MiniBatchKMeans
>>> data = MetricDistance.project(sims, 'protein and name CA', 'resname MOL')
>>> data.cluster(MiniBatchKMeans(n_clusters=1000), mergesmall=5)

combine(otherdata: MetricData)#

Combines two different metrics into one by concatenating them.

Parameters:: otherdata (MetricData object) – Concatenates the metrics of otherdata to the current objects metrics

Examples

>>> dataRMSD = MetricRmsd.project(sims)
>>> dataDist = MetricSelfDistance.project(sims, 'protein and name CA')
>>> dataRMSD.combine(dataDist)

copy() → MetricData#

Produces a deep copy of the object

Returns:: data – A copy of the current object
Return type:: MetricData object

Examples

>>> data = MetricSelfDistance.project(sims, 'protein and name CA')
>>> data2 = data.copy()

property dat#: List of the projected metrics of each trajectory.

deconcatenate(array: ndarray) → list#

Split a concatenated data array back into per-trajectory pieces

Parameters:: array (np.ndarray) – A concatenated array spanning all trajectories, with as many rows as the total number of frames in the data.
Returns:: pieces – One array per trajectory, split at the trajectory boundaries.
Return type:: list of np.ndarray

Drop some dimensions of the data given their indexes

Parameters:

drop (list or range or np.ndarray, optional) – A list of integer indexes of the dimensions to drop
keep (list or range or np.ndarray, optional) – A list of integer indexes of the dimensions to keep

Examples

>>> data.dropDimensions([1, 24, 3])
>>> data.dropDimensions(keep=[2, 10])

dropFrames(idx: int, frames: list | range | ndarray)#

Drop frames from a single trajectory of the data

Parameters:

idx (int) – The index of the trajectory from which to drop frames
frames (list or range or np.ndarray) – A list of frame indexes to drop

Drops trajectories based on their lengths

By default, drops all trajectories which are not of statistical mode (most common) length.

Parameters:

limits (list or tuple or np.ndarray, optional) – Lower and upper limits of trajectory lengths we want to keep. e.g. [100, 500]
multiple (list or range or np.ndarray, optional) – Drops trajectories whose length is not a multiple of lengths in the list. e.g. [50, 80]
partial (bool, optional) – Not implemented yet
idx (list or range or np.ndarray, optional) – A list of trajectory indexes to drop
keepsims (list of Sim objects, optional) – A list of sims which we want to keep

Returns:

dropidx – The indexes of the trajectories that were dropped

Return type:

np.ndarray

Examples

>>> data = MetricSelfDistance.project(sims, 'protein and name CA')
>>> data.dropTraj()
>>> data.dropTraj(multiple=[100])

static fromHDF5(filename: str | None = None, h5group: Group | None = None) → MetricData#

Load a MetricData object from an HDF5 file or group

Parameters:

filename (str, optional) – Path of the HDF5 file from which to load the object. Either filename or h5group must be given.
h5group (h5py.Group object, optional) – An open HDF5 group from which to read the object. Either filename or h5group must be given.

Returns:

data – The loaded MetricData object

Return type:

MetricData object

load(filename: str | dict | MetricData)#

Load a MetricData object from disk

Parameters:: filename (str or dict or MetricData) – Path to the saved MetricData object. A dict of attributes or a legacy MetricData object is also accepted for backward compatibility.

Examples

>>> data = MetricData()
>>> data.load('./data.dat')

property map#: The description of the projected dimensions (alias for description).

property numDimensions#

The number of dimensions

Examples

>>> data.numDimensions

property numFrames#

Get the total number of frames in all trajectories

Returns:: nframes – Total number of frames in all trajectories
Return type:: int

Examples

>>> data.numFrames

property numTrajectories#

The number of trajectories

Examples

>>> data.numTrajectories

plotClusters(dimX: int, dimY: int, resolution: int = 100, s: float = 4, c=None, cmap='Greys', logplot: bool = False, plot: bool = True, save: str | None = None, data: MetricData | None = None, levels: int = 7)#

Plot a scatter-plot of the locations of the clusters on top of the count histogram.

Parameters:

dimX (int) – Index of projected dimension to use for the X axis.
dimY (int) – Index of projected dimension to use for the Y axis.
resolution (int) – Resolution of bincount grid.
s (float) – Marker size for clusters.
c (list) – Colors or indexes for each cluster.
cmap (matplotlib.colors.Colormap) – Matplotlib colormap for the scatter plot.
logplot (bool) – Set True to plot the logarithm of counts.
plot (bool) – If the method should display the plot
save (str, optional) – Path of the file in which to save the figure
data (MetricData object, optional) – Optionally you can pass a different MetricData object than the one used for clustering. For example if the user wants to cluster on distances but wants to plot the centers on top of RMSD values. The new MetricData object needs to have the same simlist as this object.
levels (int) – Number of contour levels to draw.

plotCounts(dimX: int, dimY: int, resolution: int = 100, logplot: bool = False, plot: bool = True, save: str | None = None, levels: int = 7, cmap: str = 'viridis')#

Plots a histogram of counts on any two given dimensions.

Parameters:

dimX (int) – Index of projected dimension to use for the X axis.
dimY (int) – Index of projected dimension to use for the Y axis.
resolution (int) – Resolution of bincount grid.
logplot (bool) – Set True to plot the logarithm of counts.
plot (bool) – If the method should display the plot
save (str, optional) – Path of the file in which to save the figure
levels (int) – Number of contour levels to draw.
cmap (str) – Name of the matplotlib colormap to use.

plotTrajSizes()#

Plot the lengths of all trajectories in a sorted bar plot

Examples

>>> data = MetricSelfDistance.project(sims, 'protein and name CA')
>>> data.plotTrajSizes()

property ref#: List of the reference simulation and frame indexes of each trajectory.

rel2sim(relFrames: list | ndarray, simlist: ndarray | None = None) → ndarray#

Converts trajectory index-frame pairs into Sim-frame pairs

Parameters:

relFrames (list or np.ndarray) – An array containing in each row trajectory index and frame pairs
simlist (numpy.ndarray of Sim objects, optional) – Optionally pass a different (but matching, i.e. filtered) simlist for creating the Frames.

Returns:

frames – An array of Frame objects containing the simulation object, the trajectory piece ID and the frame index.

Return type:

np.ndarray

Examples

>>> simframes = data.rel2sim([100, 56])  # 100th simulation frame 56

Samples frames from a set of clusters

Parameters:

clusters (int or list or range or np.ndarray, optional) – A list of cluster indexes from which we want to sample. If None is given it will sample from all clusters.
frames (int or list or np.ndarray, optional) – An integer with the number of frames we want to sample from each state or a list of same length as clusters which contains the number of frames we want from each of the clusters. If None is given it will return all frames.
replacement (bool) – If we want to sample with or without replacement.
allframes (bool) – Deprecated. Use frames=None instead.

Returns:

absframes (numpy.ndarray) – An array which contains for each state an array containing absolute trajectory frames
relframes (numpy.ndarray) – An array which contains for each state a 2D array containing the trajectory ID and frame number for each of the sampled frames

Examples

>>> data.sampleClusters(range(5), [10, 3, 2, 50, 1])  # Sample from first 5 clusters, 10, 3, etc frames respectively

Samples conformations from a region in the projected space.

Parameters:

point (list or tuple or np.ndarray, optional) – A point in the projected space. Undefined dimensions should have None value.
radius (float, optional) – The radius in around the point in which to sample conformations.
limits (np.ndarray, optional) – A (2, ndim) dimensional array containing the min (1st row) and max (2nd row) limits for each dimension. None values will be interpreted as no limit in that dimension, or min/max value.
nsamples (int) – The number of conformations to sample.
singlemol (bool) – If True it will return all samples within a single Molecule instead of a list of Molecules.

Returns:

absFrames (list) – A list of the absolute frame indexes sampled
relFrames (list of tuples) – A list of (trajNum, frameNum) tuples sampled
mols (Molecule or list of Molecules) – The conformations stored in a Molecule or a list of Molecules

Examples

>>> # Working with 4 dimensional data for example
>>> abs, rel, mols = data.sampleRegion(point=(0.5, 3, None, None), radius=0.1)  # Point undefined in dim 3, 4
>>> minlims = [-1, None, None, 4]  # No min limit for 2, 3 dim
>>> maxlims = [2,     3, None, 7]  # No max limit for 3 dim
>>> abs, rel, mols = data.sampleRegion(limits=np.array([minlims, maxlims]))

save(filename: str)#

Save a MetricData object to disk

Parameters:: filename (str) – Path of the file in which to save the object

Examples

>>> data = MetricSelfDistance.project(sims, 'protein and name CA')
>>> data.save('./data.dat')

property simlist#: List of the Sim object of each trajectory.

splitCols()#

toHDF5(filename: str | None = None, h5group: Group | None = None)#

Save a MetricData object to an HDF5 file or group

Parameters:

filename (str, optional) – Path of the HDF5 file in which to save the object. Either filename or h5group must be given.
h5group (h5py.Group object, optional) – An open HDF5 group into which to write the object. Either filename or h5group must be given.

property trajLengths#

Get the lengths of all trajectories

Returns:: lens – The lengths of all trajectories in the object
Return type:: list

Examples

>>> data.trajLengths

class htmd.metricdata.Trajectory(projection: ndarray | None = None, reference: ndarray | None = None, sim: Sim | None = None, cluster: ndarray | None = None)#

Bases: object

Class used for storing trajectory projections, their clustering and state assignments.

Parameters:

projection (numpy.ndarray) – The projected metrics
reference (numpy.ndarray) – Reference indices to the simulations and frames that generated the metrics
sim (Sim object) – A simulation object
cluster (numpy.ndarray) – A list of cluster indexes for each frame in the simulation

property cluster#: The cluster indexes for each frame in the simulation

copy() → Trajectory#

Produce a deep copy of the object.

Returns:: traj – A copy of the current object.
Return type:: Trajectory object

dropFrames(frames: list | range | ndarray)#

Drop frames from the trajectory

Parameters:: frames (list or range or np.ndarray) – A list of frame indexes to drop

static fromHDF5(h5group: Group) → Trajectory#: Reconstruct a Trajectory from an open HDF5 group.

property numDimensions#: The number of dimensions in the projection of this trajectory

property numFrames#: The number of frames in this trajectory

property projection#: The projected metrics of this simulation trajectory

property reference#: The reference indices to the simulations and frames that generated the projections

toHDF5(h5group: Group)#: Write this trajectory’s data into an open HDF5 group.