Source code for MDAnalysis.analysis.encore.confdistmatrix

# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*-
# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4
#
# MDAnalysis --- https://www.mdanalysis.org
# Copyright (c) 2006-2017 The MDAnalysis Development Team and contributors
# (see the file AUTHORS for the full list of names)
#
# Released under the GNU Public Licence, v2 or any higher version
#
# Please cite your use of MDAnalysis in published work:
#
# R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler,
# D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein.
# MDAnalysis: A Python package for the rapid analysis of molecular dynamics
# simulations. In S. Benthall and S. Rostrup editors, Proceedings of the 15th
# Python in Science Conference, pages 102-109, Austin, TX, 2016. SciPy.
# doi: 10.25080/majora-629e541a-00e
#
# N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein.
# MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
#
"""
Distance Matrix calculation --- :mod:`MDAnalysis.analysis.ensemble.confdistmatrix`
==================================================================================


The module contains a base class to easily compute, using
parallelization and shared memory, matrices of conformational
distance between the structures stored as frames in a Universe. A
class to compute an RMSD matrix in such a way is also available.

:Author: Matteo Tiberti, Wouter Boomsma, Tone Bengtsen

.. versionadded:: 0.16.0

"""
from __future__ import division, absolute_import

from joblib import Parallel, delayed
import numpy as np
from getpass import getuser
from socket import gethostname
from datetime import datetime
from time import sleep
import logging
import warnings

from ...core.universe import Universe

from ..align import rotation_matrix

from .cutils import PureRMSD
from .utils import TriangularMatrix, trm_indices


[docs]def conformational_distance_matrix(ensemble, conf_dist_function, selection="", superimposition_selection="", n_jobs=1, pairwise_align=True, weights='mass', metadata=True, verbose=False, max_nbytes=None): """ Run the conformational distance matrix calculation. args and kwargs are passed to conf_dist_function. Parameters ---------- ensemble : Universe object Universe object for which the conformational distance matrix will be computed. conf_dist_function : function object Function that fills the matrix with conformational distance values. See set_rmsd_matrix_elements for an example. selection : str, optional use this selection for the calculation of conformational distance superimposition_selection : str, optional use atoms from this selection for fitting instead of those of "selection" pairwise_align : bool, optional Whether to perform pairwise alignment between conformations. Default is True (do the superimposition) weights : str/array_like, optional weights to be used for fit. Can be either 'mass' or an array_like metadata : bool, optional Whether to build a metadata dataset for the calculated matrix. Default is True. n_jobs : int, optional Number of cores to be used for parallel calculation Default is 1. -1 uses all available cores max_nbytes : str, optional Threshold on the size of arrays passed to the workers that triggers automated memory mapping in temp_folder (default is None). See https://joblib.readthedocs.io/en/latest/generated/joblib.Parallel.html for detailed documentation. verbose : bool, optional enable verbose output Returns ------- conf_dist_matrix : encore.utils.TriangularMatrix object Conformational distance matrix in triangular representation. """ # framesn: number of frames framesn = len(ensemble.trajectory.timeseries( ensemble.select_atoms(selection), order='fac')) # Prepare metadata recarray if metadata: metadata = np.array([(gethostname(), getuser(), str(datetime.now()), ensemble.filename, framesn, pairwise_align, selection, weights=='mass')], dtype=[('host', object), ('user', object), ('date', object), ('topology file', object), ('number of frames', int), ('pairwise superimposition', bool), ('superimposition subset', object), ('mass-weighted', bool)]) # Prepare alignment subset coordinates as necessary rmsd_coordinates = ensemble.trajectory.timeseries( ensemble.select_atoms(selection), order='fac') if pairwise_align: if superimposition_selection: subset_selection = superimposition_selection else: subset_selection = selection fitting_coordinates = ensemble.trajectory.timeseries( ensemble.select_atoms(subset_selection), order='fac') else: fitting_coordinates = None if not isinstance(weights, (list, tuple, np.ndarray)) and weights == 'mass': weights = ensemble.select_atoms(selection).masses.astype(np.float64) if pairwise_align: subset_weights = ensemble.select_atoms(subset_selection).masses.astype(np.float64) else: subset_weights = None elif weights is None: weights = np.ones((ensemble.trajectory.timeseries( ensemble.select_atoms(selection))[0].shape[0])).astype(np.float64) if pairwise_align: subset_weights = np.ones((fit_coords[0].shape[0])).astype(np.float64) else: subset_weights = None else: if pairwise_align: if len(weights) != 2: raise RuntimeError("used pairwise alignment with custom " "weights. Please provide 2 tuple with " "weights for 'selection' and " "'superimposition_selection'") subset_weights = weights[1] weights = weights[0] else: subset_weights = None # Allocate for output matrix matsize = framesn * (framesn + 1) // 2 distmat = np.empty(matsize, np.float64) # Initialize workers. Simple worker doesn't perform fitting, # fitter worker does. indices = trm_indices((0, 0), (framesn - 1, framesn - 1)) Parallel(n_jobs=n_jobs, verbose=verbose, require='sharedmem', max_nbytes=max_nbytes)(delayed(conf_dist_function)( np.int64(element), rmsd_coordinates, distmat, weights, fitting_coordinates, subset_weights) for element in indices) # When the workers have finished, return a TriangularMatrix object return TriangularMatrix(distmat, metadata=metadata)
[docs]def set_rmsd_matrix_elements(tasks, coords, rmsdmat, weights, fit_coords=None, fit_weights=None, *args, **kwargs): ''' RMSD Matrix calculator Parameters ---------- tasks : iterator of int of length 2 Given a triangular matrix, this function will calculate RMSD values from element tasks[0] to tasks[1]. Since the matrix is triangular, the trm_indices matrix automatically calculates the corrisponding i,j matrix indices. The matrix is written as an array in a row-major order (see the TriangularMatrix class for details). If fit_coords and fit_weights are specified, the structures will be superimposed before calculating RMSD, and fit_coords and fit_weights will be used to place both structures at their center of mass and compute the rotation matrix. In this case, both fit_coords and fit_weights must be specified. coords : numpy.array Array of the ensemble coordinates weights : numpy.array Array of atomic weights, having the same order as the coordinates array rmsdmat : encore.utils.TriangularMatrix Memory-shared triangular matrix object fit_coords : numpy.array or None, optional Array of the coordinates used for fitting fit_weights : numpy.array. optional Array of atomic weights, having the same order as the fit_coords array ''' i, j = tasks if fit_coords is None and fit_weights is None: sumweights = np.sum(weights) rmsdmat[(i + 1) * i // 2 + j] = PureRMSD(coords[i].astype(np.float64), coords[j].astype(np.float64), coords[j].shape[0], weights, sumweights) elif fit_coords is not None and fit_weights is not None: sumweights = np.sum(weights) subset_weights = np.asarray(fit_weights) / np.mean(fit_weights) com_i = np.average(fit_coords[i], axis=0, weights=fit_weights) translated_i = coords[i] - com_i subset1_coords = fit_coords[i] - com_i com_j = np.average(fit_coords[j], axis=0, weights=fit_weights) translated_j = coords[j] - com_j subset2_coords = fit_coords[j] - com_j rotamat = rotation_matrix(subset1_coords, subset2_coords, subset_weights)[0] rotated_i = np.transpose(np.dot(rotamat, np.transpose(translated_i))) rmsdmat[(i + 1) * i // 2 + j] = PureRMSD( rotated_i.astype(np.float64), translated_j.astype(np.float64), coords[j].shape[0], weights, sumweights) else: raise TypeError("Both fit_coords and fit_weights must be specified \ if one of them is given")
[docs]def get_distance_matrix(ensemble, selection="name CA", load_matrix=None, save_matrix=None, superimpose=True, superimposition_subset="name CA", weights='mass', n_jobs=1, max_nbytes=None, verbose=False, *conf_dist_args, **conf_dist_kwargs): """ Retrieves or calculates the conformational distance (RMSD) matrix. The distance matrix is calculated between all the frames of all the :class:`~MDAnalysis.core.universe.Universe` objects given as input. The order of the matrix elements depends on the order of the coordinates of the ensembles and on the order of the input ensembles themselves, therefore the order of the input list is significant. The distance matrix can either be calculated from input ensembles or loaded from an input numpy binary file. Please notice that the .npz file does not contain a bidimensional array, but a flattened representation that is meant to represent the elements of an encore.utils.TriangularMatrix object. Parameters ---------- ensemble : Universe selection : str Atom selection string in the MDAnalysis format. Default is "name CA" load_matrix : str, optional Load similarity/dissimilarity matrix from numpy binary file instead of calculating it (default is None). A filename is required. save_matrix : bool, optional Save calculated matrix as numpy binary file (default is None). A filename is required. superimpose : bool, optional Whether to superimpose structures before calculating distance (default is True). superimposition_subset : str, optional Group for superimposition using MDAnalysis selection syntax (default is CA atoms: "name CA") weights : str/array_like, optional weights to be used for fit. Can be either 'mass' or an array_like n_jobs : int, optional Maximum number of cores to be used (default is 1). If -1 use all cores. max_nbytes : str, optional Threshold on the size of arrays passed to the workers that triggers automated memory mapping in temp_folder (default is None). See https://joblib.readthedocs.io/en/latest/generated/joblib.Parallel.html for detailed documentation. verbose : bool, optional print progress Returns ------- confdistmatrix : encore.utils.TriangularMatrix Conformational distance matrix. . """ # Load the matrix if required if load_matrix: logging.info( " Loading similarity matrix from: {0}".format(load_matrix)) confdistmatrix = \ TriangularMatrix( size=ensemble.trajectory.timeseries( ensemble.select_atoms(selection), order='fac').shape[0], loadfile=load_matrix) logging.info(" Done!") for key in confdistmatrix.metadata.dtype.names: logging.info(" {0} : {1}".format( key, str(confdistmatrix.metadata[key][0]))) # Check matrix size for consistency if not confdistmatrix.size == \ ensemble.trajectory.timeseries( ensemble.select_atoms(selection), order='fac').shape[0]: logging.error( "ERROR: The size of the loaded matrix and of the ensemble" " do not match") return None # Calculate the matrix else: # Transfer universe to memory to ensure timeseries() support ensemble.transfer_to_memory() if not isinstance(weights, (list, tuple, np.ndarray)) and weights == 'mass': weight_type = 'Mass' elif weights is None: weight_type = 'None' else: weight_type = 'Custom' logging.info( " Perform pairwise alignment: {0}".format(str(superimpose))) logging.info(" weighted alignment and RMSD: {0}".format(weight_type)) if superimpose: logging.info( " Atoms subset for alignment: {0}" .format(superimposition_subset)) logging.info(" Calculating similarity matrix . . .") # Use superimposition subset, if necessary. If the pairwise alignment # is not required, it will not be performed anyway. confdistmatrix = conformational_distance_matrix(ensemble, conf_dist_function=set_rmsd_matrix_elements, selection=selection, pairwise_align=superimpose, weights=weights, n_jobs=n_jobs, max_nbytes=max_nbytes, verbose=verbose) logging.info(" Done!") if save_matrix: confdistmatrix.savez(save_matrix) return confdistmatrix