molpx.visualize

The core functionality is to link two interative figures, fig1 and fig2, inside an Ipython/Jupyter notebook, so that an action in fig1 (e.g.a click of the mouse or a slide of a slidebar) will trigger an event in fig2 (e.g. a frame update or point moved) and vice versa. Usually, these two figures contain representations from:

  • molecules: an nglviewer widget showing the molecular structure that a particular value of is associated with and
  • projected coordinates: a matplotlib figure showing the projected coordinates (e.g. TICs or PCs or any other), \({Y_0, ..., Y_N}\), either as a 2D histogram, \(PDF(Y_i, Y_j)\) or as trajectory views \({Y_0(t), ...Y_N(t)}\)

You are strongly encouraged to check nglview’ documentation, since its functionalities extend beyond the scope of this package and the molecular visualization universe is rich and complex (unlike this module).

The three methods offered by this module are:

molpx.visualize.FES(MD_trajectories, MD_top, ...) Return a molecular visualization widget connected with a free energy plot.
molpx.visualize.sample(positions, geom, ax) Visualize the geometries in geom according to the data in positions on an existing matplotlib axes ax
molpx.visualize.traj(MD_trajectories, ...[, ...]) Link one or many projected trajectories, [Y_0(t), Y_1(t)...], with the MD_trajectories that originated them.
molpx.visualize.FES(MD_trajectories, MD_top, projected_trajectory, proj_idxs=[0, 1], nbins=100, n_sample=100, axlabel='proj')

Return a molecular visualization widget connected with a free energy plot.

Parameters:
  • MD_trajectories (str, or list of strings with the filename(s) the the molecular dynamics (MD) trajectories.) –

    Any file extension that mdtraj (.xtc, .dcd etc) can read is accepted.

    Alternatively, a single mdtraj.Trajectory object or a list of them can be given as input.

  • MD_top (str to topology filename or directly an mdtraj.Topology object) –
  • projected_trajectory (str to a filename or numpy ndarray of shape (n_frames, n_dims)) – Time-series with the projection(s) that want to be explored. If these have been computed externally, you can provide .npy-filenames or readable asciis (.dat, .txt etc). NOTE: molpx assumes that there is no time column.
  • proj_idxs (list or ndarray of length 2) – Selection of projection idxs (zero-idxd) to visualize.
  • nbins (int, default 100) – The number of bins per axis to used in the histogram (FES)
  • n_sample (int, default is 100) – The number of geometries that will be used to represent the FES. The higher the number, the higher the spatial resolution of the “click”-action.
  • axlabel (str, default is 'proj') – Format of the labels in the FES plot
Returns:

  • ax – pylab.Axis object
  • iwd – nglview.NGLWidget
  • data_sample – numpy ndarray of shape (n, n_sample) with the position of the dots in the plot
  • geoms – mdtraj.Trajectory object with the geometries n_sample geometries shown by the nglwidget
molpx.visualize.sample(positions, geom, ax, plot_path=False, clear_lines=True, n_smooth=0, widget=None, **link_ax2wdg_kwargs)

Visualize the geometries in geom according to the data in positions on an existing matplotlib axes ax

Use this method when the array of positions, the geometries, the axes (and the widget, optionally) have already been generated elsewhere.

Parameters:
  • positions (numpy nd.array of shape (n_frames, 2)) – Contains the position associated with each frame in geom in that order
  • geom (mdtraj.Trajectory object) – Contains n_frames, each frame
  • ax (matplotlib.pyplot.Axes object) – The axes to be linked with the nglviewer widget
  • plot_path (bool, default is False) – whether to draw a line connecting the positions in positions
  • clear_lines (bool, default is True) – whether to clear all the lines that were previously drawn in ax
  • n_smooth (int, default is 0,) – if n_smooth > 0, the shown geometries and paths will be smoothed out by 2*n frames. See bmutils.smooth_geom for more information
  • widget (None or existing nglview widget) – you can provide an already instantiated nglviewer widget here (avanced use)
  • link_ax2wdg_kwargs (dictionary of named arguments, optional) – named arguments for the function _link_ax_w_pos_2_nglwidget, which is the one that internally provides the interactivity. Non-expert users can safely ignore this option.
Returns:

iwd
Return type:

nglview.NGLWidget
molpx.visualize.traj(MD_trajectories, MD_top, projected_trajectories, active_traj=0, max_frames=2000, stride=1, proj_stride=1, proj_idxs=[0, 1], plot_FES=False, panel_height=1, sharey_traj=True, dt=1.0, tunits='ns', traj_selection=None)

Link one or many projected trajectories, [Y_0(t), Y_1(t)...], with the MD_trajectories that originated them.

Optionally plot also the resulting FES.

Parameters:
  • MD_trajectories (str, or list of strings with the filename(s) the the molecular dynamics (MD) trajectories.) –

    Any file extension that mdtraj (.xtc, .dcd etc) can read is accepted.

    Alternatively, a single mdtraj.Trajectory object or a list of them can be given as input.

  • MD_top (str to topology filename or directly mdtraj.Topology object) –
  • projected_trajectories (str to a filename or numpy ndarray of shape (n_frames, n_dims)) – Time-series with the projection(s) that want to be explored. If these have been computed externally, you can provide .npy-filenames or readable asciis (.dat, .txt etc). NOTE: molpx assumes that there is no time column.
  • active_traj (int, default 0) – Index of the trajectory that will be responsive. (zero-indexing)
  • max_frames (int, default is 1000) – If the trajectoy is longer than this, stride to this length (in frames)
  • stride (int, default is 1) – Stride value in case of large datasets. In case of having MD_trajectories and projected_trajectories in memory (and not on disk) the stride can take place also before calling this method.
  • proj_stride (int, default is 1) – Stride value that was used in the projected_trajectories relative to the MD_trajectories If the original MD_trajectories were stored every 5 ps but the projected trajectories were stored every 50 ps, proj_stride = 10 has to be provided, otherwise an exception will be thrown informing the user that the MD_trajectories and the projected_trajectories have different number of frames.
  • proj_idxs (iterable of ints, default is [0,1]) – Indices of the projected coordinates to use in the various representations
  • plot_FES (bool, default is False) – Plot (and interactively link) the FES as well
  • panel_height (int, default 1) – Height, in inches, of each panel of each trajectory subplots
  • sharey_traj (bool, default is True) – Force the panels of each projection to have the same yaxes across trajectories (Note: Not across coordinates)
  • dt (float, default is 1.0) – Physical time-unit equivalent to one frame of the projected_trajectories
  • tunits (str, default is 'ns') – Name of the physical time unit provided in dt
  • traj_selection (None, int, iterable of ints, default is None) – Don’t plot all trajectories but only few of them. The default None implies that all trajs will be plotted. Note: the data used for the FES will always include all trajectories, regardless of this value
Returns:

  • ax, iwd, data_sample, geoms – return _plt.gca(), _plt.gcf(), widget, geoms
  • ax – pylab.Axis object
  • fig – pylab.Figure object
  • iwd – nglview.NGLWidget
  • geoms – mdtraj.Trajectory object with the geometries n_sample geometries shown by the nglwidget