General helper functions

Small helper and utilities functions that don’t fit anywhere else.

maicos.lib.util.DOC_DICT

Dictionary containing the keys and the actual docstring used by maicos.lib.util.render_docs().

maicos.lib.util.DOI_LIST

References associated with MAICoS

class maicos.lib.util.Unit_vector(*args, **kwargs)

Bases: Protocol

Protocol class for unit vector methods type hints.

maicos.lib.util.atomgroup_header(AtomGroup: AtomGroup) → str

Return a string containing infos about the AtomGroup.

Infos include the total number of atoms, the including residues and the number of residues. Useful for writing output file headers.

Parameters:

AtomGroup (MDAnalysis.core.groups.AtomGroup) – The AtomGroup object containing the atoms.

Returns:

A string containing the AtomGroup information.

Return type:

str

maicos.lib.util.bin(a: ndarray, bins: ndarray) → ndarray

Average array values in bins for easier plotting.

Parameters:

• a (numpy.ndarray) – The input array to be averaged.

• bins (numpy.ndarray) – The array containing the indices where each bin begins.

Returns:

The averaged array values.

Return type:

numpy.ndarray

Notes

The “bins” array should contain the INDEX (integer) where each bin begins.

maicos.lib.util.charge_neutral(filter: str) → Callable

Raise a Warning when AtomGroup is not charge neutral.

Class Decorator to raise an Error/Warning when AtomGroup in an AnalysisBase class is not charge neutral. The behaviour of the warning can be controlled with the filter attribute. If the AtomGroup’s corresponding universe is non-neutral an ValueError is raised.

Parameters:

filter (str) – Filter type to control warning filter. Common values are: “error” or “default” See warnings.simplefilter for more options.

maicos.lib.util.citation_reminder(*dois: str) → str

Prints citations in order to remind users to give due credit.

Parameters:

dois (list) – dois associated with the method which calls this. Possible dois are registered in maicos.lib.util.DOI_LIST.

Returns:

cite – formatted citation reminders

Return type:

str

maicos.lib.util.correlation_analysis(timeseries: ndarray) → float

Timeseries correlation analysis.

Analyses a timeseries for correlation and prints a warning if the correlation time is larger than the step size.

Parameters:

timeseries (numpy.ndarray) – Array of (possibly) correlated data.

Returns:

corrtime – Estimated correlation time of timeseries.

Return type:

float

maicos.lib.util.get_center(atomgroup: AtomGroup, bin_method: str, compound: str) → ndarray

Center attribute for an MDAnalysis.core.groups.AtomGroup.

This function acts as a wrapper for the MDAnalysis.core.groups.AtomGroup.center() method, providing a more user-friendly interface by automatically determining the appropriate weights based on the chosen binning method.

Parameters:

• atomgroup (MDAnalysis.core.groups.AtomGroup) – A AtomGroup for which the calculations are performed.

• bin_method ({"com", "cog", "coc"}) –

  Method for the position binning.

  The possible options are center of mass ("com"), center of geometry ("cog"), and center of charge ("coc").

• compound ({"group", "segments", "residues", "molecules", "fragments"}) – The compound to be used in the center calculation. For example, "residue", "segment", etc.

Returns:

The coordinates of the calculated center.

Return type:

np.ndarray

Raises:

ValueError – If the provided bin_method is not one of {"com", "cog", "coc"}.

maicos.lib.util.get_cli_input() → str

Return a proper formatted string of the command line input.

Returns:

A string representing the command line input in a proper format.

Return type:

str

maicos.lib.util.get_compound(atomgroup: AtomGroup) → str

Returns the highest order topology attribute.

The order is “molecules”, “fragments”, “residues”. If the topology contains none of those attributes, an AttributeError is raised.

Parameters:

atomgroup (MDAnalysis.core.groups.AtomGroup) – A AtomGroup for which the calculations are performed.

Returns:

Name of the topology attribute.

Return type:

str

Raises:

AttributeError – atomgroup is missing any connection information”

maicos.lib.util.maicos_banner(version: str = '', frame_char: str = '-') → str

Prints ASCII banner resembling the MAICoS Logo with 80 chars width.

Parameters:

• version (str) – Version string to add to the banner.

• frame_char (str) – Character used to as framing around the banner.

Returns:

banner – formatted banner

Return type:

str

maicos.lib.util.render_docs(func: Callable) → Callable

Replace all template phrases in the functions docstring.

Keys for the replacement are taken from in maicos.lib.util.DOC_DICT.

Parameters:

func (callable) – The callable (function, class) where the phrase old should be replaced.

Returns:

callable with replaced phrase

Return type:

Callable

maicos.lib.util.trajectory_precision(trajectory: ReaderBase, dim: int = 2) → ndarray

Detect the precision of a trajectory.

Parameters:

• trajectory (MDAnalysis.coordinates.base.ReaderBase) – Trajectory from which the precision is detected.

• dim ({2, 0, 1}) – Dimension along which the precision is detected.

Returns:

precision – Precision of each frame of the trajectory.

If the trajectory has a high precision, its resolution will not be detected, and a value of 1e-4 is returned.

Return type:

numpy.ndarray

maicos.lib.util.unit_vectors_cylinder(atomgroup: AtomGroup, grouping: str, bin_method: str, dim: int, pdim: str) → ndarray

Calculate cylindrical unit vectors in cartesian coordinates.

Parameters:

• atomgroup (MDAnalysis.core.groups.AtomGroup) – A AtomGroup for which the calculations are performed.

• grouping ({"atoms", "residues", "segments", "molecules", "fragments"}) –

  Atom grouping for the calculations.

  The possible grouping options are the atom positions (in the case where grouping="atoms") or the center of mass of the specified grouping unit (in the case where grouping="residues", "segments", "molecules" or "fragments").

• bin_method ({"com", "cog", "coc"}) –

  Method for the position binning.

  The possible options are center of mass ("com"), center of geometry ("cog"), and center of charge ("coc").

• dim ({0, 1, 2}) – Dimension for binning (x=0, y=1, z=1).

• pdim ({"r", "z"}) – direction of the projection

Returns:

Array of the calculated unit vectors with shape (3,) for pdim=’z’ and shape (3,n) for pdim=’r’. The length of n depends on the grouping.

Return type:

numpy.ndarray

maicos.lib.util.unit_vectors_planar(atomgroup: AtomGroup, grouping: str, pdim: int) → ndarray

Calculate unit vectors in planar geometry.

Parameters:

• atomgroup (MDAnalysis.core.groups.AtomGroup) – A AtomGroup for which the calculations are performed.

• grouping ({"atoms", "residues", "segments", "molecules", "fragments"}) –

  Atom grouping for the calculations.

  The possible grouping options are the atom positions (in the case where grouping="atoms") or the center of mass of the specified grouping unit (in the case where grouping="residues", "segments", "molecules" or "fragments").

• pdim ({0, 1, 2}) – direction of the projection

Returns:

the unit vector

Return type:

numpy.ndarray

maicos.lib.util.unit_vectors_sphere(atomgroup: AtomGroup, grouping: str, bin_method: str) → ndarray

Calculate spherical unit vectors in cartesian coordinates.

Parameters:

• ATOMGROUP_PARAMETER

• grouping ({"atoms", "residues", "segments", "molecules", "fragments"}) –

  Atom grouping for the calculations.

  The possible grouping options are the atom positions (in the case where grouping="atoms") or the center of mass of the specified grouping unit (in the case where grouping="residues", "segments", "molecules" or "fragments").

• bin_method ({"com", "cog", "coc"}) –

  Method for the position binning.

  The possible options are center of mass ("com"), center of geometry ("cog"), and center of charge ("coc").

Returns:

Array of the calculated unit vectors with shape (3,n). The length of n depends on the grouping.

Return type:

numpy.ndarray

maicos.lib.util.unwrap_refgroup(original_class)

Class decorator error if unwrap = False and refgroup != None.