Plotting utilities — lipyphilic.lib.plotting

Author

Paul Smith

Year

2021

Copyright

GNU Public License v2

Generally, lipyphilic is not a plotting library — everyone has their favourite plotting tool and aesthetics and so plotting is generally left up to the user. However, some plots are complex to make, requiring further processing of results or lots of boilerplate code to get the end result.

This module provides methods for plotting joint probability densities and lateral distribution maps of lipid properties projected onto the membrane plane.

The class lipyphilic.lib.plotting.ProjectionPlot can be used, for example, to plot the area per lipid projected onto the membrane plane, i.e. plot the area per lipid as a function of \(xy\). See Gu et al. (2020) for examples of these projection plots.

The class lipyphilic.lib.plotting.JointDensity can be used, for example, to plot a 2D PMF of cholesterol orientation and height in a lipid membrane. See Gu et al. (2019) for an example of the this 2D PMF.

The classes and their methods

class lipyphilic.lib.plotting.ProjectionPlot(x_pos, y_pos, values)[source]

Plot membrane properties as a function of xy. See

This class can be used for plotting membrane properties projected onto the \(xy\) plane. This is useful, for example, for detecting phase separation in lipid membranes.

The plotted data are stored in the .statistic attribute. This means, if you plot separately the projection of a membrane property of lipids in the upper and lower leaflets, you can easily calculate the correlation coefficient of this property across the leaflets.

interpolate(tile=True, method='linear', fill_value=numpy.NaN)[source]

Interpolate NaN values in the projection array.

Uses scipy.interpolate.griddata to interpolate missing values and optionally remove NaN values.

Parameters

  • tile (bool, optional) – If True, the xy values will be tiled on a (3, 3) grid to reproduce the effect of periodic boundary conditions. If False, no periodic boundary conditions are taken into account when interpolating.

  • method ({‘linear’, ‘nearest’, ‘cubic’}, optional) – Method of interpolation. One of:

    nearest return the value at the data point closest to the point of interpolation. See SciPy’s NearestNDInterpolator for more details.

    linear tessellate the input point set to N-D simplices, and interpolate linearly on each simplex. See SciPy’s LinearNDInterpolator for more details.

    cubic return the value determined from a piecewise cubic, continuously differentiable (C1), and approximately curvature-minimizing polynomial surface. See SciPy’s CloughTocher2DInterpolator for more details.

  • fill_value (float, optional) – Value used to fill in for requested points outside of the convex hull of the input points. This option has no effect for the ‘nearest’ method. If not provided, then the these points will have NaN values.

  • rescale (bool, optional) – Rescale points to unit cube before performing interpolation. This is useful if some of the input dimensions have incommensurable units and differ by many orders of magnitude.

plot_projection(ax=None, title=None, xlabel=None, ylabel=None, cmap=None, vmin=None, vmax=None, cbar=True, cbar_kws=None, imshow_kws=None)[source]

Plot the 2D projection of a membrane property.

Use matplotlib.pyplot.imshow to plot a heatmap of the values.

Parameters

  • ax (Axes, optional) – Matplotlib Axes on which to plot the projection. The default is None, in which case a new figure and axes will be created.

  • title (str, optional) – Title for the plot. By default, there is no title.

  • xlabel (str, optional) – Label for the x-axis. By default, there is no label on the x-axis.

  • ylabel (str, optional) – Label for the y-axis. By default, there is no label on the y-axis.

  • cmap (str or ~matplotlib.colors.Colormap, optional) – The Colormap instance or registered colormap name used to map scalar data to colors.

  • vmin, vmax (float, optional) – Define the data range that the colormap covers. By default, the colormap covers the complete value range of the supplied data.

  • cbar (bool, optional) – Whether or not to add a colorbar to the plot.

  • cbar_kws (dict, optional) – A dictionary of keyword options to pass to matplotlib.pyplot.colorbar.

  • imshow_kws (dict, optional) – A dictionary of keyword options to pass to matplotlib.pyplot.imshow, which is used to plot the 2D density map.

Returns

  • ProjectionPlot.fig – Matplotlib Figure on which the plot was drawn.

  • ProjectionPlot.ax – Matplotlib Axes on which the plot was drawn.

  • ProjectionPlot.cbar – If a colorbar was added to the plot, this is the Matplotlib colorbar instance for ProjectionPlot.ax. Otherwise it is None.

project_values(bins, statistic='mean')[source]

Discretise the membrane and project values onto the xy-plane

Parameters

  • bins (int or array_like or [int, int] or [array, array]) – The bin specification:

    int

    If int, the number of bins for the two dimensions (nx=ny=bins).

    array-like

    If array_like, the bin edges for the two dimensions (x_edges=y_edges=bins).

    [int, int]

    If [int, int], the number of bins in each dimension (nx, ny = bins).

    [array, array]

    If [array, array], the bin edges in each dimension (x_edges, y_edges = bins).

    combination

    A combination [int, array] or [array, int], where int is the number of bins and array is the bin edges.

  • statistic (string or callable, optional) – The statistic to project onto the membrae plane (the default is ‘mean’). The following statistics are available:

    mean

    compute the mean of values for points within each bin. Empty bins will be represented by NaN.

    std`

    compute the standard deviation within each bin.

    median

    compute the median of values for points within each bin. Empty bins will be represented by NaN.

    count

    compute the count of points within each bin. This is identical to an unweighted histogram. The value of the membrane property is not referenced.

    sum

    compute the sum of values for points within each bin. This is identical to a weighted histogram.

    min

    compute the minimum of values for points within each bin. Empty bins will be represented by NaN.

    max

    compute the maximum of values for point within each bin. Empty bins will be represented by NaN.

    function

    a user-defined function which takes a 1D array of values, and outputs a single numerical statistic. This function will be called on the values in each bin. Empty bins will be represented by function([]), or NaN if this returns an error.

class lipyphilic.lib.plotting.JointDensity(ob1, ob2)[source]

Calculate and plot the joint probability density of two observables.

Set up parameters for calculating joint densities.

Parameters

  • ob1 (array_like) – An array containing values of the first observable.

  • ob2 (array_like) – An array containing values of the second observable. It must have the same shape as ob1

calc_density_2D(bins, filter_by=None, temperature=None)[source]

Calculate the joint probability density of two observables.

If a tempearutre is provided, the PMF is calculated directly from the probability distribution.

Parameters

  • bins (int or array_like or [int, int] or [array, array]) – The bin specification:

    int

    If int, the number of bins for the two dimensions (nx=ny=bins).

    array-like

    If array_like, the bin edges for the two dimensions (x_edges=y_edges=bins).

    [int, int]

    If [int, int], the number of bins in each dimension (nx, ny = bins).

    [array, array]

    If [array, array], the bin edges in each dimension (x_edges, y_edges = bins).

    combination

    A combination [int, array] or [array, int], where int is the number of bins and array is the bin edges.

  • filter_by (2D numpy array of shape (n_residues, n_frames), optional) – A boolean mask for filtering lipids or frames. The default is None, in which case no filtering is performed.

  • temperature (float, optional) – Temperature of the system, which will be used to convert the 2D density into a PMF. The default is None, in which case the density is returned rather than the PMF.

interpolate(method='linear', fill_value=None, rescale=True)[source]

Interpolate NaN values in the joint probability density or PMF.

Uses scipy.interpolate.griddata to interpolate the joint density and optionally remove NaN values.

Parameters

  • method ({‘linear’, ‘nearest’, ‘cubic’}, optional) – Method of interpolation. One of:

    nearest

    return the value at the data point closest to the point of interpolation. See SciPy’s NearestNDInterpolator for more details.

    linear

    tessellate the input point set to N-D simplices, and interpolate linearly on each simplex. See SciPy’s LinearNDInterpolator for more details.

    cubic

    return the value determined from a piecewise cubic, continuously differentiable (C1), and approximately curvature-minimizing polynomial surface. See SciPy’s CloughTocher2DInterpolator for more details.

  • fill_value (float, optional) – Value used to fill in for requested points outside of the convex hull of the input points. This option has no effect for the ‘nearest’ method. If not provided, then the default is to use the maximum free energy value if a PMF was calculated, or 0 otherwise.

  • rescale (bool, optional) – Rescale points to unit cube before performing interpolation. This is useful if some of the input dimensions have incommensurable units and differ by many orders of magnitude.

plot_density(difference=None, ax=None, title=None, xlabel=None, ylabel=None, cmap=None, vmin=None, vmax=None, n_contours=4, contour_labels=None, cbar=True, cbar_kws=None, imshow_kws=None, contour_kws=None, clabel_kws=None)[source]

Plot the 2D density or PMF.

Use matplotlib.pyplot.imshow to plot a heatmap of the density.

Optionally, add contour lines using matplotlib.pyplot.contour and label the contours with their values.

Parameters

  • difference (JointDensity, optional) – A JointDensity object for which the probability density or PMF has been calculated. Before ploting, the density or PMF of difference will be subtracted from the density of PMF of this object. This is useful for plotting difference in PMFs due to e.g a change in membrane lipid composition.

  • ax (Axes, optional) – Matplotlib Axes on which to plot the 2D denstiy. The default is None, in which case a new figure and axes will be created.

  • title (str, optional) – Title for the plot. By default, there is no title.

  • xlabel (str, optional) – Label for the x-axis. By default, there is no label on the x-axis.

  • ylabel (str, optional) – Label for the y-axis. By default, there is no label on the y-axis.

  • cmap (str or ~matplotlib.colors.Colormap, optional) – The Colormap instance or registered colormap name used to map scalar data to colors.

  • vmin, vmax (float, optional) – Define the data range that the colormap covers. By default, the colormap covers the complete value range of the supplied data.

  • n_contours (int or array-like, optional) – Determines the number and positions of the contour lines / regions plotted with matplotlib.pyplot.contour:

    int

    If an int n, use ~matplotlib.ticker.MaxNLocator, which tries to automatically choose no more than n+1 “nice” contour levels between vmin and vmax.

    array-like

    If array-like, draw contour lines at the specified levels. The values must be in increasing order.

    0

    If 0, no contour lines are drawn.

  • contour_labels (array-like, optional) – A list of contour level indices specifyig which levles should be labeled. The default is None, in which case no contours are labeled.

  • cbar (bool, optional) – Whether or not to add a colorbar to the plot.

  • cbar_kws (dict, optional) – A dictionary of keyword options to pass to matplotlib.pyplot.colorbar.

  • imshow_kws (dict, optional) – A dictionary of keyword options to pass to matplotlib.pyplot.imshow, which is used to plot the 2D density map.

  • contour_kws (dict, optional) – A dictionary of keyword options to pass to matplotlib.pyplot.contour, which is used to plot the contour lines.

  • clabel_kws (dict, optional) – A dictionary of keyword options to pass to matplotlib.pyplot.contour, which is used to add labels to the contour lines.

Returns

  • JointDensity.fig – Matplotlib Figure on which the plot was drawn.

  • JointDensity.ax – Matplotlib Axes on which the plot was drawn.

  • JointDensity.cbar – If a colorbar was added to the plot, this is the Matplotlib colorbar instance for JointDensity.ax. Otherwise it is None.