schrodinger.application.matsci.species module¶

Module to group structure object in to subgroup of species

This module provides a flexible framework for grouping atoms, molecules, and residues in chemical structures into distinct species. The design is based on two main components:

Signature Classes: Define how to split species (e.g., by formula, SMILES)
Finder Classes: Define what to split (e.g., molecules, residues)

SpeciesCollectionTypes combines these components, providing predefined grouping methods.

Once species are identified, SpeciesData objects store information about each species.

The main user-facing class is SpeciesCollection, which allows users to: - Select a SpeciesCollectionType - Apply it to one or more structures - Interact with the resulting species groupings

Example usage: s_c = SpeciesCollection(‘mol’) s_c.loadSpecies([structure1, structure2]) for species in s_c: print(species.name, species.count)

To extend the module, add new Signature or Finder classes and add them to SpeciesCollectionTypes.

class schrodinger.application.matsci.species.SUB_STRUCT_INFO(main_st, sub_st, aids)¶

Bases: tuple

aids¶: Alias for field number 2

main_st¶: Alias for field number 0

sub_st¶: Alias for field number 1

class schrodinger.application.matsci.species.SC_TYPE_DATA(menus, finder, signature, split_unique)¶

Bases: tuple

finder¶: Alias for field number 1

menus¶: Alias for field number 0

signature¶: Alias for field number 2

split_unique¶: Alias for field number 3

schrodinger.application.matsci.species.set_component_name(struct, component_name)¶

Set the component name for all atoms in the structure. If an atom already has a component name, it will not be overwritten.

Parameters:

struct (Structure) – Structure to update
component_name (str) – The component name

schrodinger.application.matsci.species.format_species_display_name(name, count, is_cg=False, typo_type=None)¶

Gets the formatted species display name for the name of the atom/particle with the count

Parameters:

name (str) – The element/particle name
count (int) – The number of element/particle names in the structure
is_cg (bool) – Whether the structure is coarse-grained.
typo_type (TYPO_TYPE or None) – The typography type style used for formatting text. If None no formatting will be done.

Returns:

The formatted name

Return type:

str

schrodinger.application.matsci.species.sanitize_species_name(name)¶

Sanitize the species name to ensure it’s a valid identifier.

Parameters:: name (str) – The original species name
Returns:: The sanitized species name
Return type:: str

schrodinger.application.matsci.species.get_molecular_formula(struct, is_cg=None, typo_type=None)¶

Gets the molecular formula for the passed structure.

Parameters:

struct (schrodinger.structure.Structure) – the structure to get formula from
is_cg (bool or None) – Whether the structure is coarse-grained. Will check if None is passed.
typo_type (TYPO_TYPE or None) – The typography type style used for formatting text. If None no formatting will be done.

Return type:

str

Returns:

‘molecular formula’ based for the passed molecule

schrodinger.application.matsci.species.group_objects_by_hash(grp_list, hash_func)¶

Group a list of objects by their hashes, where their hashes are calculated by the given hashing function

Parameters:

grp_list (list) – The list of objects to group
hash_func (callable) – The function to generate hash for the passed object

Returns:

Dictionary where the key is the hash generated for the object and value is the list of object which generated the given hash

Return type:

dict

schrodinger.application.matsci.species.split_using_composition(atom_collections)¶

Splits list of atom collections to unique atom collections and non-unique atom collections using their elemental composition.

Parameters:: atom_collections (list(structure._AtomCollection)) – A list of atom collections
Returns:: The first element is the list of atom collections with unique elemental composition and second element is the list of atom collections that have non-unique elemental composition
Return type:: tuple(list, list)

schrodinger.application.matsci.species.get_unique_molecule_nums(struct)¶

Get the molecule number of unique representative molecules in the structure

Parameters:: struct (structure.Structure) – The structure to unique molecule number in
Return type:: list
Returns:: list of molecule numbers that are unique

schrodinger.application.matsci.species.get_unique_molecule_struct(struct, store_original_index=False)¶

Gets the structure comprising only unique representative molecules.

Parameters:

struct (structure.Structure) – The structure to find unique molecules from
store_original_index (bool) – Whether to store the original atom index before extraction on the structure.

Returns:

The structure with only unique molecules

Return type:

structure.Structure

class schrodinger.application.matsci.species.BaseSignature¶

Bases: object

Base signature class to calculate key and name for a passed structure

abstract getKeyName(struct, is_cg=None, unique=False, typo_type=None)¶

Signature function to calculate key and name for passed structure

Parameters:

struct (structure.Structure) – The structure to find signature
is_cg (bool) – Whether the structure is CG. If None then structure is tested for CG.
unique (bool) – Whether the structure is unique substructure
typo_type (TYPO_TYPE or None) – The typography type style used for formatting text. If None no formatting will be done.

Returns:

Tuple of two items where first item is the key and second the name

Return type:

tuple(str, str)

class schrodinger.application.matsci.species.MolecularFormulaSignature¶

Bases: BaseSignature

Signature class to calculate signature using molecular formula

getKeyName(struct, is_cg=None, unique=False, typo_type=None)¶

Calculate key and name the molecular formula. See parent for more information.

Returns:: Tuple of two items. Both items here are the generated molecular formula
Return type:: tuple(str, str)

class schrodinger.application.matsci.species.ComponentNameSignature¶

Bases: BaseSignature

Signature class that uses the atom component-name property.

getKeyName(struct, is_cg=None, unique=False, typo_type=None)¶

Return the atom component name as the key and name. Note that this signature assumes that all atoms in the structure have the same component name and finder classes has the responsibility to ensure that the structure is consistent with this assumption.

See the parent class for parameter documentation.

Return type:: tuple(str, str)
Returns:: Component name as both the key and name

class schrodinger.application.matsci.species.SmilesSignature(stereo_allowed=True)¶

Bases: BaseSignature

Signature class to calculate signature using smiles structure

__init__(stereo_allowed=True)¶

Constructs a new SmilesSignature

Parameters:: stereo_allowed (bool) – Whether the SMILES pattern should be stereo aware

getKeyName(struct, is_cg=None, unique=False, typo_type=None)¶

Calculate key as smiles and name as molecular formula. See parent for more information.

Returns:: Tuple of two items. Both items here are the generated molecular formula
Return type:: tuple(str, str)

class schrodinger.application.matsci.species.PolymerSmilesSignature(stereo_allowed=True)¶

Bases: SmilesSignature

Signature class to calculate signature using polymer name. Revert to SMILES if the structure is not a polymer.

getKeyName(struct, is_cg=None, unique=False, typo_type=None)¶

Calculate key and name as polymer name. It will revert to calculating key as smiles and name as molecular formula if the structure is not a polymer. See parent for more information.

Returns:: Tuple of two items. Both items here are the generated molecular formula
Return type:: tuple(str, str)

class schrodinger.application.matsci.species.SpeciesData(key, name)¶

Bases: object

Tracks information about each chemically distinct group of atoms in a system

__init__(key, name)¶

Constructs a new instance.

Parameters:

key (str) – The key unique to the group of atoms
name (str) – The name of the group of atoms

property count¶: Get the number of groups in the species

addAtomGroup(struct, atom_group)¶

Add a new group of atoms to the species

Parameters:

struct (structure.Structure) – structure to which the atoms belong to
atom_group (iterable) – Atom indices of atoms belonging to the group

getStructures()¶

Get all structures to which the group of atoms in this species belong to

Returns:: All structures to which the group of atoms in this species belong to
Return type:: list(Structure)

getAtomGroups(struct)¶

Gets the groups of atoms belonging to passed structure for the current species.

Parameters:: struct (structure.Structure) – structure to which the group of atoms need to be searched.
Returns:: All the groups of atoms belonging to passed structure
Return type:: set(frozenset)

getAllAtomIds(struct)¶

Gets all atom indices belonging to the species for the passed structure. If all atom groups belong to same structure then structure is optional.

Parameters:: struct (structure.Structure) – structure to which the group of atoms need to be searched.
Returns:: all atom indices belonging to the species for the passed structure
Return type:: list(int)

isAtomMember(atom_id, struct)¶

Check if atom is a part of the species. If all atom groups belong to same structure then structure is optional.

Parameters:

atom_id (int) – Index of the atom to check
struct (structure.Structure) – structure to which the group of atoms need to be searched.

Return type:

bool

Returns:

Whether the atom is part of the species

Raises:

RuntimeError – If struct is None and the species contains atom indices from different structures.

getExampleAtomGroup(struct)¶

Get a group of atoms for the species with the lowest atom index

Parameters:: struct (structure.Structure) – structure to which the group of atoms sample should belong to.
Return type:: frozenset(int)
Returns:: The first of group of atoms of the species

getSampleAtomId(struct)¶

Gets the sample atom index that belongs to the species.

Parameters:: struct (structure.Structure) – structure to which the sample atom should belong to.
Return type:: Int
Returns:: Index of an atom that belongs to the species

class schrodinger.application.matsci.species.SpeciesFinder(signature, split_unique=True)¶

Bases: object

Base class to find unique species in structures.

__init__(signature, split_unique=True)¶

Construct a species finder.

Parameters:

signature (BaseSignature) – The signature class to generate name and key for the species
split_unique (bool) – Whether to split using composition before splitting using signature key. Note this is skipped when finding species in multiple structures.

getKeyNamePrefix(struct)¶

Gets the prefix for the key and name generated from the signature

Parameters:: struct (structure.Structure) – The sub structure used to generate key and name
Returns:: The prefix for key and name generated by the signature
Return type:: str

iterAtomCollections(struct)¶

Generate atom collections for the passed structure.

Parameters:: struct (schrodinger.Structure) – The structure to divide into atom collections
Returns:: Atom collections that divide the structure
Return type:: iterable(structure.Structure._AtomCollection)

getSubStAndAids(struct)¶

Gets the extracted sub structures and their associated atom indices

Parameters:: struct (structure.Structure) – The structure

getAtomGroupKeyName(sub_st, is_cg, unique, typo_type)¶

Gets the substructure key and name from the signature

Parameters:

sub_st (structure.Structure) – The sub structure for current group of atoms
is_cg (bool) – Whether the substructure is cg
unique (bool) – Whether the substructure is unique in composition
typo_type (TYPO_TYPE or None) – The typography type style used for formatting text. If None no formatting will be done.

Return type:

typle(str, str)

Returns:

Tuple with two items. First item is the signature key associated with the substructure and the second item is the signature name for the substructure

addAtomGroup(sub_st_info, is_cg, unique=False, typo_type=None)¶

Add group of atom to species

Parameters:

sub_st_info (SUB_STRUCT_INFO) – Namedtuple containing information regarding the group of atoms to be added
is_cg (bool) – Whether the substructure is cg
unique (bool) – Whether the substructure is unique in composition
typo_type (TYPO_TYPE or None) – The typography type style used for formatting text. If None no formatting will be done.

getSampleAtomAndStructTag(species)¶

Gets the sample atom and structure tag for the passed species

Parameters:: species (SpeciesData) – The species to get the structure tag and sample atom from
Returns:: Tuple containing two items. First is the sample atom and second is the structure tag for the sample structure.
Return type:: tuple(structure.Structure._StructureAtom, str)

getExampleTag(species)¶

Get the example tag for the passed species

Parameters:: species (SpeciesData) – The species to get the example tag from
Returns:: The example tag for the passed species
Return type:: str

setDisplayNames(all_species)¶

Sets the display names for the list of species such that they are unique

Parameters:: all_species (list(SpeciesData)) – All species

findSpeciesInStruct(struct, split_unique, typo_type)¶

Finds a species in passed structure

Parameters:

struct (structure.Structure) – The structure to find species in
split_unique (bool) – Whether structure split first based on it composition
typo_type (TYPO_TYPE or None) – The typography type style used for formatting text. If None no formatting will be done.

getSpecies(structs, typo_type=None)¶

Gets the species for the passed structure

Parameters:

structs (list(structure.Structure)) – The list of structures to find species in
typo_type (TYPO_TYPE or None) – The typography type style used for formatting text. If None no display name is not set for the species.

Returns:

The list of species

Return type:

list(SpeciesData)

sanitizeName(name)¶

Sanitize the property name to ensure it’s a valid identifier.

Parameters:: name (str) – The original property name
Return str:: The sanitized property name

addSpeciesAsProps(all_species)¶

Add Species name as an atom property in its structure

Parameters:: all_species (list(SpeciesData)) – List of species

class schrodinger.application.matsci.species.MoleculeSpeciesFinder(signature, split_unique=True)¶

Bases: SpeciesFinder

Find unique molecule species in structures.

iterAtomCollections(struct)¶

Generate molecules from the passed structure.

Parameters:: struct (Structure) – Structure containing the molecules
Return type:: iterable(structure.Structure._AtomCollection)
Returns:: Molecules in the structure

getExampleTag(species)¶

Get an example molecule tag for the passed species.

Parameters:: species (SpeciesData) – Species for which to get the example tag
Return type:: str
Returns:: Example molecule tag

class schrodinger.application.matsci.species.ComponentSpeciesFinder(signature, split_unique=True)¶

Bases: SpeciesFinder

Find connected atom groups whose atoms have the same component name.

getSubStAndAids(struct)¶

Get connected component-name groups and their atom indices.

Parameters:: struct (Structure) – Structure containing the components
Return type:: dict
Returns:: Extracted component structures mapped to their atom indices

getConnectedAtomIds(struct, starting_atom_id, remaining_atom_ids, component_names_by_atom_id)¶

Get atoms connected to the starting atom with the same component name.

Parameters:

struct (Structure) – Structure containing the atoms
starting_atom_id (int) – Atom index at which to start traversal
remaining_atom_ids (set(int)) – Atom indices not yet assigned to a component
component_names_by_atom_id (dict) – Component names keyed by atom index

Return type:

set(int)

Returns:

Connected atom indices with the same component name

class schrodinger.application.matsci.species.ResidueSpeciesFinder(signature, split_unique=True)¶

Bases: MoleculeSpeciesFinder

Class to find unique residue species in structures.

getKeyNamePrefix(struct)¶

Gets the prefix for the key and name generated from the signature

Parameters:: struct (structure.Structure) – The sub structure used to generate key and name
Returns:: The prefix for key and name generated by the signature
Return type:: str

iterAtomCollections(struct)¶

Generate atom collections of residues for the passed structure

Parameters:: struct (schrodinger.Structure) – The structure to be divided into residues
Returns:: Atom collections for the passed structure that divides the structure into list of residues
Return type:: iterable(structure.Structure._AtomCollection)

getExampleTag(species)¶

Get the example tag for the passed species

Parameters:: species (SpeciesData) – The species to get the example tag from
Returns:: The example tag for the passed species
Return type:: str

class schrodinger.application.matsci.species.SpeciesCollectionTypes¶

Bases: Enum

Enumeration for various species collection types

Variables:

formula (SC_TYPE_DATA) – Molecules grouped using their molecular formula
component (SC_TYPE_DATA) – Connected atom groups grouped using their component name
mol (SC_TYPE_DATA) – Molecules grouped using their stereochemically unaware SMILES
chiral_mol (SC_TYPE_DATA) – Molecules grouped using their stereochemically aware SMILES
poly_mol (SC_TYPE_DATA) – Molecules grouped using their polymer name. If polymer name is not available then stereochemically unaware SMILES is used.
poly_chiral_mol (SC_TYPE_DATA) – Molecules grouped using their polymer name. If polymer name is not available then stereochemically unaware SMILES is used.
formula_res (SC_TYPE_DATA) – Residues grouped using their molecular formula
res (SC_TYPE_DATA) – Residues grouped using their stereochemically unaware SMILES
chiral_res (SC_TYPE_DATA) – Residues grouped using their stereochemically aware SMILES

formula = SC_TYPE_DATA(menus=['Molecule', 'Formula'], finder=<class 'schrodinger.application.matsci.species.MoleculeSpeciesFinder'>, signature=<class 'schrodinger.application.matsci.species.MolecularFormulaSignature'>, split_unique=False)¶

component = SC_TYPE_DATA(menus=['Component'], finder=<class 'schrodinger.application.matsci.species.ComponentSpeciesFinder'>, signature=<class 'schrodinger.application.matsci.species.ComponentNameSignature'>, split_unique=False)¶

mol = SC_TYPE_DATA(menus=['Molecule', 'SMILES'], finder=<class 'schrodinger.application.matsci.species.MoleculeSpeciesFinder'>, signature=functools.partial(<class 'schrodinger.application.matsci.species.SmilesSignature'>, False), split_unique=True)¶

chiral_mol = SC_TYPE_DATA(menus=['Molecule', 'Chiral SMILES'], finder=<class 'schrodinger.application.matsci.species.MoleculeSpeciesFinder'>, signature=functools.partial(<class 'schrodinger.application.matsci.species.SmilesSignature'>, True), split_unique=True)¶

poly_mol = SC_TYPE_DATA(menus=['Polymer', 'Name and SMILES'], finder=<class 'schrodinger.application.matsci.species.MoleculeSpeciesFinder'>, signature=functools.partial(<class 'schrodinger.application.matsci.species.PolymerSmilesSignature'>, False), split_unique=True)¶

poly_chiral_mol = SC_TYPE_DATA(menus=['Polymer', 'Name and Chiral SMILES'], finder=<class 'schrodinger.application.matsci.species.MoleculeSpeciesFinder'>, signature=functools.partial(<class 'schrodinger.application.matsci.species.PolymerSmilesSignature'>, True), split_unique=True)¶

formula_res = SC_TYPE_DATA(menus=['Residue', 'Formula'], finder=<class 'schrodinger.application.matsci.species.ResidueSpeciesFinder'>, signature=<class 'schrodinger.application.matsci.species.MolecularFormulaSignature'>, split_unique=False)¶

res = SC_TYPE_DATA(menus=['Residue', 'SMILES'], finder=<class 'schrodinger.application.matsci.species.ResidueSpeciesFinder'>, signature=functools.partial(<class 'schrodinger.application.matsci.species.SmilesSignature'>, False), split_unique=False)¶

chiral_res = SC_TYPE_DATA(menus=['Residue', 'Chiral SMILES'], finder=<class 'schrodinger.application.matsci.species.ResidueSpeciesFinder'>, signature=functools.partial(<class 'schrodinger.application.matsci.species.SmilesSignature'>, True), split_unique=False)¶

class schrodinger.application.matsci.species.SpeciesCollection(sc_type, typo_type=None)¶

Bases: object

Class to find and interact with species in a structure.

__init__(sc_type, typo_type=None)¶

Constructs a new instance SpeciesCollection

Parameters:

sc_type (str) – Name of the SpeciesCollectionTypes
typo_type (TYPO_TYPE or None) – The typography type style used for formatting text. If None no display name is not set for the species.

__len__()¶

Get the number species in current species collection

Return type:: int
Returns:: The number species in the collection

loadSpecies(structs)¶

Load species in the current species collection

Parameters:: structs – The structure to find species in

getSpeciesFromAtomIndex(atom_idx, struct)¶

Select the species data in which the atom index belongs to

Parameters:

atom_idx (int) – The atom index
structs – The structure to find species belong to

Returns:

SpeciesData

Return type:

The species data in which the atom index belongs to.

Raises:

KeyError – If the atom index is not found in any of the species.

getSpeciesCount()¶

Get the species count for each species

Return type:: dict
Returns:: Dictionary containing the species name and count