molsysmt.basic.extract#

molsysmt.basic.extract(molecular_system, selection='all', structure_indices='all', to_form=None, output_filename=None, copy_if_all=True, syntax='MolSysMT', skip_digestion=False)[source]#

Extracting a subset of atoms and/or structures from a molecular system.

This function creates a new molecular system containing only the elements and structures specified by selection and structure_indices. Composite inputs are materialized as a native molsysmt.MolSys before extraction so topology and structural data remain aligned. Optionally, the result can be returned in another form using to_form.

Parameters:

  • molecular_system (molecular system) – Molecular system in any supported MolSysMT format.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or boolean/integer array specifying elements.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) to include or process.

  • to_form (str, list of str, or None, default=None) – Target molecular-system form; None preserves or infers the input form.

  • output_filename (str or pathlib.Path, default=None) – Output file path for serialization.

  • copy_if_all (bool, default=True) – Whether an unrestricted extraction returns a copy instead of the original object.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

Returns:

A new molecular system containing only the selected atoms and structures, in to_form if provided. Otherwise, the result uses the singular input form or molsysmt.MolSys for a composite input.

Return type:

molecular system

Raises:

  • NotSupportedFormError – If the input or requested output form is not supported.

  • ArgumentError – If input arguments are invalid or inconsistent, including an out-of-range structure index.

Notes

  • Supported molecular-system forms are summarized in Items and Forms.

  • Selection strings must follow one of the syntaxes described in Selection syntaxes.

  • When the input is an H5MSM file, extracting a subset to the same file form requires a distinct output_filename. Use to_form='molsysmt.MolSys' for an in-memory subset.

See also

molsysmt.basic.select()

Select elements from a molecular system without extracting them.

molsysmt.basic.copy()

Create an independent copy of a molecular system.

molsysmt.basic.convert()

Convert a molecular system into a different form.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys_A = msm.convert(systems['T4 lysozyme L99A']['181l.h5msm'])
>>> molsys_B = msm.extract(molsys_A, selection='molecule_type=="protein"')
>>> msm.contains(molsys_A, waters=True)
True
>>> msm.contains(molsys_B, waters=True)
False

Tutorial with more examples

See the following tutorial for a practical demonstration of how to use this function, along with additional examples: Extract.

Added in version 1.0.0.

On this page