MembraneCurvature

Author:

Estefania Barreto-Ojeda

Year:

2021

Copyright:

GNU Public License v3

MembraneCurvature is the main analysis class for calculating mean and Gaussian curvature from atom selections.

It derives a height surface from the selected reference atoms using either the "fourier" method (default) or the "binning" method, then evaluates curvature on the resulting surface. The specific operations used to derive the surface depend on the method selected by the user in the parameter surface_method.

The set of required parameters to run MembraneCurvature varies depending on the selected surface_method:

  • Fourier method:

    Required parameters are the maximum Fourier mode indices fourier_m and fourier_n (Default: 2). Optional parameters include a singular-value cutoff for the Fourier fit via truncated SVD with fourier_rcond.

  • Binning method:

    Required parameters are the number of bins in the x and y directions n_x_bins and n_y_bins. Optional wrap parameter to control whether to wrap the coordinates exceeding the simulation box dimensions.

Mean curvature is calculated in units of Å -1 and Gaussian curvature in units of Å -2.

class membrane_curvature.base.MembraneCurvature(universe, select='all', n_x_bins=100, n_y_bins=100, x_range=None, y_range=None, wrap=None, surface_method='fourier', fourier_m=2, fourier_n=2, fourier_rcond=None, fft_filter='auto', **kwargs)[source]
Parameters:

  • universe (Universe or AtomGroup) – An MDAnalysis Universe object.

  • select (str or iterable of str, optional.) – The selection string of an atom selection to use as a reference to derive a surface.

  • wrap (bool or None, optional) – Apply coordinate wrapping with wrap(). Defaults to True for surface_method='binning' and must be omitted or explicitly set to False for surface_method='fourier'.

  • n_x_bins (int, optional, default: 100) – Number of bins in grid in the x dimension.

  • n_y_bins (int, optional, default: 100) – Number of bins in grid in the y dimension.

  • x_range (tuple of (float, float), optional, default: (0, universe.dimensions[0])) – Range of coordinates (min, max) in the x dimension.

  • y_range (tuple of (float, float), optional, default: (0, universe.dimensions[1])) – Range of coordinates (min, max) in the y dimension.

  • surface_method ({‘binning’, ‘fourier’}, optional) – fourier (default) fits a periodic Fourier sum to atom positions at each frame and evaluates Monge-gauge curvature from analytic derivatives on the same bin grid (bin centers). binning derives the surface by creating a grid and assigning atoms to bins. It uses numpy.gradient() for derivatives.

  • fourier_m (int, optional) – Maximum Fourier mode index in x when surface_method='fourier'. Default 2.

  • fourier_n (int, optional) – Maximum Fourier mode index in y when surface_method='fourier'. Default 2.

  • fourier_rcond (float, optional) – Singular-value cutoff for the Fourier fit via truncated SVD with _solve_design_least_squares_svd() when surface_method='fourier'. The cutoff is interpreted as a relative threshold on singular values.

  • fft_filter (None, 'auto', or dict, optional) – Brick-wall filter on the binned height field when surface_method='binning'. Default 'auto' (low-pass (0, 0.5 * q_Nyq) from bin widths). Pass None to disable. Pass {'q': (q_low, q_high)} for custom bounds in rad/Å. For average maps: time-average of z_surface, filter once, then curvature on that filtered height. Per-frame arrays are not FFT-filtered. Ignored for surface_method='fourier'.

Variables:

  • results.z_surface (ndarray) – Per-frame height field from the atom selection (unfiltered when fft_filter is used with surface_method=’binning’). Shape (n_frames, n_x_bins, n_y_bins).

  • results.mean (ndarray) – Per-frame mean curvature associated with the surface. Array of shape (n_frames, n_x_bins, n_y_bins)

  • results.gaussian (ndarray) – Per-frame Gaussian curvature associated with the surface. Array of shape (n_frames, n_x_bins, n_y_bins)

  • results.average_z_surface (ndarray) – Average of the array elements in z_surface. With binning and fft_filter enabled, this is the FFT-filtered temporal mean of z_surface, not the mean of per-frame filtered surfaces. Each array has shape (n_x_bins, n_y_bins)

  • results.average_mean (ndarray) – Average of the array elements in mean_curvature. With binning and fft_filter enabled, curvature of the filtered time-averaged height (not the time average of per-frame results.mean). Each array has shape (n_x_bins, n_y_bins)

  • results.average_gaussian (ndarray) – Average of the array elements in gaussian_curvature. With binning and fft_filter enabled, curvature of the filtered time-averaged height (not the time average of per-frame results.gaussian). Each array has shape (n_x_bins, n_y_bins)

Raises:

ValueError – If n_x_bins or n_y_bins is not a positive integer (see validate_positive_bin_counts()), if the selection is empty, if surface_method is not one of 'binning' or 'fourier', or, when surface_method='fourier', if fourier_m / fourier_n are negative or the selection has fewer atoms than Fourier parameters, if wrap=True with surface_method='fourier', or if a manual fft_filter dict is passed with surface_method='fourier'.

See also

wrap

Wrap/unwrap the atoms of a given AtomGroup in the unit cell.

Notes

Fourier surface method (default)

surface_method='fourier' uses fourier_m = fourier_n = 2 as default. Do not modify the default values unless you need shorter wavelengths. Since the method performs periodic boundary conditions by itself, wrap defaults to False and is not required.

Binning mode

The binning routine does not apply periodic wrapping itself; MembraneCurvature calls AtomGroup.wrap() when surface_method='binning' and wrap=True. When using binning, wrap defaults to True if not provided. Omit wrap or pass wrap=True for raw trajectories so atoms are packed into the unit cell before binning. Run with wrap=False for preprocessed trajectories that have already applied periodic boundary conditions. For membrane-protein systems without position restraints, preprocessing should include rotational and translational fitting around the protein.

For more details on when to use wrap=True, check the Usage page.

For any method of choice, the derived surface and calculated curvatures are available in the results attributes.

The attribute average_z_surface contains the time-averaged derived surface. When fft_filter is set, the brick-wall filter is applied to that averaged surface.

The attributes average_mean and average_gaussian contain mean and Gaussian curvature maps for analysis and plotting; with fft_filter on binning surfaces they are curvatures of the filtered average height, not the time average of per-frame curvatures.

Example

You can pass a universe containing your selection of reference:

import MDAnalysis as mda
from membrane_curvature.base import MembraneCurvature

u = mda.Universe(coordinates, trajectory)
mc = MembraneCurvature(u).run()

surface =  mc.results.average_z_surface
mean_curvature =  mc.results.average_mean
gaussian_curvature = mc.results.average_gaussian

The respective 2D curvature plots can be obtained using the matplotlib package for data visualization via contourf() or imshow().

For specific examples visit the Usage page. Check the Visualization page for more examples to plot MembraneCurvature results using contourf() and imshow().