PSFContainer

FOX.io.read_psf

A class for reading protein structure (.psf) files.

Index

PSFContainer([filename, title, atoms, …]) A container for managing protein structure files.

API

class FOX.io.read_psf.PSFContainer(filename=None, title=None, atoms=None, bonds=None, angles=None, dihedrals=None, impropers=None, donors=None, acceptors=None, no_nonbonded=None)[source]

A container for managing protein structure files.

The PSFContainer class has access to three general sets of methods.

Methods for reading & constructing .psf files:

Methods for updating atom types:

Methods for extracting bond, angle and dihedral-pairs from plams.Molecule instances:

Parameters:
filename: :math:`1` :class:`numpy.ndarray` [:class:`str`]

A 1D array with a single string as filename.

title: :math:`n` :class:`numpy.ndarray` [:class:`str`]

A 1D array of strings holding the title block.

atoms: :math:`n*8` :class:`pandas.DataFrame`

A Pandas DataFrame holding the atoms block. The DataFrame should possess the following collumn keys:

  • "segment name"
  • "residue ID"
  • "residue name"
  • "atom name"
  • "atom type"
  • "charge"
  • "mass"
  • "0"
bonds: :math:`n*2` :class:`numpy.ndarray` [:class:`int`]

A 2D array holding the indices of all atom-pairs defining bonds. Indices are expected to be 1-based.

angles: :math:`n*3` :class:`numpy.ndarray` [:class:`int`]

A 2D array holding the indices of all atom-triplets defining angles. Indices are expected to be 1-based.

dihedrals: :math:`n*4` :class:`numpy.ndarray` [:class:`int`]

A 2D array holding the indices of all atom-quartets defining proper dihedral angles. Indices are expected to be 1-based.

impropers: :math:`n*4` :class:`numpy.ndarray` [:class:`int`]

A 2D array holding the indices of all atom-quartets defining improper dihedral angles. Indices are expected to be 1-based.

donors: :math:`n*1` :class:`numpy.ndarray` [:class:`int`]

A 2D array holding the atomic indices of all hydrogen-bond donors. Indices are expected to be 1-based.

acceptors: :math:`n*1` :class:`numpy.ndarray` [:class:`int`]

A 2D array holding the atomic indices of all hydrogen-bond acceptors. Indices are expected to be 1-based.

no_nonbonded: :math:`n*2` :class:`numpy.ndarray` [:class:`int`]

A 2D array holding the indices of all atom-pairs whose nonbonded interactions should be ignored. Indices are expected to be 1-based.

np_printoptions: :class:`Mapping<collections.abc.Mapping>` [:class:`str`, :class:`object`]

A mapping with Numpy print options. See np.set_printoptions.

pd_printoptions: :class:`Mapping<collections.abc.Mapping>` [:class:`str`, :class:`object`]

A mapping with Pandas print options. See Options and settings.

_PRIVATE_ATTR: Set[str] = frozenset({'_np_printoptions', '_pd_printoptions'})

A from with the names of private instance attributes. These attributes will be excluded whenever calling PSF.as_dict().

_SHAPE_DICT = mappingproxy({'filename': {'shape': 1}, 'title': {'shape': 1}, 'atoms': {'shape': 8}, 'bonds': {'shape': 2, 'row_len': 4, 'header': '{:>10d} !NBOND: bonds'}, 'angles': {'shape': 3, 'row_len': 3, 'header': '{:>10d} !NTHETA: angles'}, 'dihedrals': {'shape': 4, 'row_len': 2, 'header': '{:>10d} !NPHI: dihedrals'}, 'impropers': {'shape': 4, 'row_len': 2, 'header': '{:>10d} !NIMPHI: impropers'}, 'donors': {'shape': 1, 'row_len': 8, 'header': '{:>10d} !NDON: donors'}, 'acceptors': {'shape': 1, 'row_len': 8, 'header': '{:>10d} !NACC: acceptors'}, 'no_nonbonded': {'shape': 2, 'row_len': 4, 'header': '{:>10d} !NNB'}})

A dictionary containg array shapes among other things

_HEADER_DICT: Mapping[str, str] = mappingproxy({'!NTITLE': 'title', '!NATOM': 'atoms', '!NBOND': 'bonds', '!NTHETA': 'angles', '!NPHI': 'dihedrals', '!NIMPHI': 'impropers', '!NDON': 'donors', '!NACC': 'acceptors', '!NNB': 'no_nonbonded'})

A dictionary mapping .psf headers to PSFContainer attribute names

__init__(filename=None, title=None, atoms=None, bonds=None, angles=None, dihedrals=None, impropers=None, donors=None, acceptors=None, no_nonbonded=None)[source]

Initialize a PSFContainer instance.

Return type:None
static _is_dict(value)[source]

Check if value is a dict instance; raise a TypeError if not.

Return type:dict
__repr__()[source]

Return a (machine readable) string representation of this instance.

The string representation consists of this instances’ class name in addition to all (non-private) instance variables.

Returns:A string representation of this instance.
Return type:str

See also

PSFContainer._PRIVATE_ATTR
A set with the names of private instance variables.
PSFContainer._repr_fallback
Fallback function for PSFContainer.__repr__() incase of recursive calls.
PSFContainer._str_iterator()
Return an iterable for the iterating over this instances’ attributes.
PSFContainer._str()
Returns a string representation of a single key/value pair.
_str_iterator()[source]

Return an iterable for the PSFContainer.__repr__() method.

Return type:Iterable[Tuple[str, Any]]
__eq__(value)[source]

Check if this instance is equivalent to value.

The comparison checks if the class type of this instance and value are identical and if all (non-private) instance variables are equivalent.

Returns:Whether or not this instance and value are equivalent.
Return type:bool

See also

PSFContainer._PRIVATE_ATTR
A set with the names of private instance variables.
PSFContainer._eq
Return if v1 and v2 are equivalent.
PSFContainer._eq_fallback
Fallback function for PSFContainer.__eq__() incase of recursive calls.
as_dict(return_private=False)[source]

Construct a dictionary from this instance with all non-private instance variables.

The returned dictionary values are shallow copies.

Parameters:return_private (bool) – If True, return both public and private instance variables. Private instance variables are defined in PSFContainer._PRIVATE_ATTR.
Returns:A dictionary with keyword arguments for initializing a new instance of this class.
Return type:dict [str, Any]

See also

PSFContainer.from_dict()
Construct a instance of this objects’ class from a dictionary with keyword arguments.
PSFContainer._PRIVATE_ATTR
A set with the names of private instance variables.
copy(deep=True)[source]

Return a shallow or deep copy of this instance.

Parameters:deep (bool) – Whether or not to return a deep or shallow copy.
Returns:A new instance constructed from this instance.
Return type:PSFContainer
__copy__()[source]

Return a shallow copy of this instance; see PSFContainer.copy().

Return type:~AT
property filename

Get PSFContainer.filename as string or assign an array-like object as a 1D array.

Return type:str
property title

Get PSFContainer.title or assign an array-like object as a 1D array.

Return type:ndarray
property atoms

Get PSFContainer.atoms or assign an a DataFrame.

Return type:DataFrame
property bonds

Get PSFContainer.bonds or assign an array-like object as a 2D array.

Return type:ndarray
property angles

Get PSFContainer.angles or assign an array-like object as a 2D array.

Return type:ndarray
property dihedrals

Get PSFContainer.dihedrals or assign an array-like object as a 2D array.

Return type:ndarray
property impropers

Get PSFPSFContainerimpropers or assign an array-like object as a 2D array.

Return type:ndarray
property donors

Get PSFContainer.donors or assign an array-like object as a 2D array.

Return type:ndarray
property acceptors

Get PSFContainer.acceptors or assign an array-like object as a 2D array.

Return type:ndarray
property no_nonbonded

Get PSFContainer.no_nonbonded or assign an array-like object as a 2D array.

Return type:ndarray
_set_nd_array(name, value, ndmin, dtype)[source]

Assign an array-like object (value) to the name attribute as ndarray.

Performs an inplace update of this instance.

Parameters:
  • name (str) – The name of the to-be set attribute.
  • value (array-like) – The array-like object to-be assigned to name. The supplied object is converted into into an array beforehand.
  • ndmin (int) – The minimum number of dimensions of the to-be assigned array.
  • dtype (type or numpy.dtype) – The desired datatype of the to-be assigned array.
  • Exceptions
  • ----------
  • ValueError – Raised if value array construction was unsuccessful.
Return type:

None

property segment_name

Get or set the "segment name" column in PSFContainer.atoms.

Return type:Series
property residue_id

Get or set the "residue ID" column in PSFContainer.atoms.

Return type:Series
__hash__(self)

Return the hash of this instance.

The returned hash is constructed from two components: * The hash of this instances’ class type. * The hashes of all key/value pairs in this instances’ (non-private) attributes.

If an unhashable instance variable is encountered, e.g. a list, then its id() is used for hashing.

This method will raise a TypeError if the class attribute AbstractDataClass._HASHABLE is False.

See also

AbstractDataClass._PRIVATE_ATTR
A set with the names of private instance variables.
AbstractDataClass._HASHABLE
Whether or not this class is hashable.
AbstractDataClass._hash_fallback
Fallback function for AbstractDataClass.__hash__() incase of recursive calls.
AbstractDataClass._hash
An instance variable for caching the hash() of this instance.
Return type:int
__weakref__

list of weak references to the object (if defined)

property residue_name

Get or set the "residue name" column in PSFContainer.atoms.

Return type:Series
property atom_name

Get or set the "atom name" column in PSFContainer.atoms.

Return type:Series
property atom_type

Get or set the "atom type" column in PSFContainer.atoms.

Return type:Series
property charge

Get or set the "charge" column in PSFContainer.atoms.

Return type:Series
property mass

Get or set the "mass" column in PSFContainer.atoms.

Return type:Series
classmethod read(filename, encoding=None, **kwargs)[source]

Construct a new instance from this object’s class by reading the content of filename.

Parameters:
  • filename (str, bytes, os.PathLike or a file object) – The path+filename or a file object of the to-be read .psf file. In practice, any iterable can substitute the role of file object as long iteration returns either strings or bytes (see encoding).
  • encoding (str, optional) – Encoding used to decode the input (e.g. "utf-8"). Only relevant when a file object is supplied to filename and the datastream is not in text mode.
  • **kwargs (Any) – Optional keyword arguments that will be passed to both PSFContainer._read_iterate() and PSFContainer._read_postprocess().

See also

PSFContainer._read_iterate()
An abstract method for parsing the opened file in PSFContainer.read().
PSFContainer._read_postprocess()
Post processing the class instance created by PSFContainer.read().
Return type:PSFContainer
classmethod _read_iterate(iterator)[source]

An abstract method for parsing the opened file in read.

Parameters:iterator (Iterator [str]) – An iterator that returns str instances upon iteration.
Return type:Dict[str, Any]
Returns:
  • dict [str, Any] – A dictionary with keyword arguments for a new instance of this objects’ class.
  • **kwargs (Any) – Optional keyword arguments.

See also

read()
The main method for reading files.
_read_postprocess(filename, encoding=None, **kwargs)[source]

Post processing the class instance created by read().

Parameters:
  • filename (str, bytes, os.PathLike or a file object) – The path+filename or a file object of the to-be read .psf file. In practice, any iterable can substitute the role of file object as long iteration returns either strings or bytes (see encoding).
  • encoding (str, optional) – Encoding used to decode the input (e.g. "utf-8"). Only relevant when a file object is supplied to filename and the datastream is not in text mode.
  • **kwargs (Any) – Optional keyword arguments that will be passed to both PSFContainer._read_iterate() and PSFContainer._read_postprocess().

See also

PSFContainer.read()
The main method for reading files.
Return type:None
classmethod _post_process_psf(psf_dict)[source]

Post-process the output of PSF.read(), casting the values into appropiat objects.

  • The title block is converted into a 1D array of strings.
  • The atoms block is converted into a Pandas DataFrame.
  • All other blocks are converted into 2D arrays of integers.
Parameters:psf_dict (dict [str, numpy.ndarray]) – A dictionary holding the content of a .psf file (see PSFContainer.read_psf()).
Returns:The .psf output, psf_dict, with properly formatted values.
Return type:dict [str, numpy.ndarray]
write(filename, encoding=None, **kwargs)[source]

Write the content of this instance to filename.

Parameters:
  • filename (str, bytes, os.PathLike or a file object) – The path+filename or a file object of the to-be read .psf file. Contrary to _read_postprocess(), file objects can not be substituted for generic iterables.
  • encoding (str, optional) – Encoding used to decode the input (e.g. "utf-8"). Only relevant when a file object is supplied to filename and the datastream is not in text mode.
  • **kwargs (Any) – Optional keyword arguments that will be passed to _write_iterate().

See also

PSFContainer._write_iterate()
Write the content of this instance to an opened datastream.
PSFContainer._get_writer()
Take a write() method and ensure its first argument is properly encoded.
Return type:None
_write_iterate(write, **kwargs)[source]

Write the content of this instance to an opened datastream.

The to-be written content of this instance should be passed as str. Any (potential) encoding is handled by the write parameter.

Example

Basic example of a potential _write_iterate() implementation.

>>> iterator = self.as_dict().items()
>>> for key, value in iterator:
...     value: str = f'{key} = {value}'
...     write(value)
>>> return None
Parameters:
  • writer (Callable) – A callable for writing the content of this instance to a file object. An example would be the io.TextIOWrapper.write() method.
  • **kwargs (optional) – Optional keyword arguments.

See also

PSFContainer.write()
The main method for writing files.
Return type:None
_write_top(write)[source]

Write the top-most section of the to-be create .psf file.

The following blocks are seralized:

  • PSF.title
  • PSF.atoms
Parameters:write (Callable [[AnyStr], None]) – A callable for writing the content of this instance to a file object. An example would be the io.TextIOWrapper.write() method.
Returns:A string constructed from the above-mentioned psf blocks.
Return type:str

See also

PSFContainer.write()
The main method for writing .psf files.
_write_bottom(write)[source]

Write the bottom-most section of the to-be create .psf file.

The following blocks are seralized:

  • PSF.bonds
  • PSF.angles
  • PSF.dihedrals
  • PSF.impropers
  • PSF.donors
  • PSF.acceptors
  • PSF.no_nonbonded
Parameters:write (Callable [[AnyStr], None]) – A callable for writing the content of this instance to a file object. An example would be the io.TextIOWrapper.write() method.

See also

PSFContainer.write()
The main method for writing .psf files.
Return type:None
static _serialize_array(array, items_per_row=4)[source]

Serialize an array into a single string; used for creating .psf files.

Newlines are placed for every items_per_row rows in array.

Parameters:
  • array (numpy.ndarray) – A 2D array.
  • items_per_row (int) – The number of values per row before switching to a new line.
Returns:

A serialized array.

Return type:

str

See also

PSFContainer.write()
The main method for writing .psf files.
update_atom_charge(atom_type, charge)[source]

Change the charge of atom_type to charge.

Parameters:
Raises:

ValueError – Raised if charge cannot be converted into a float.

Return type:

None

update_atom_type(atom_type_old, atom_type_new)[source]

Change the atom type of a atom_type_old to atom_type_new.

Parameters:
Return type:

None

generate_bonds(mol)[source]

Update PSFContainer.bonds with the indices of all bond-forming atoms from mol.

Parameters:mol (plams.Molecule) – A PLAMS Molecule.
Return type:None
generate_angles(mol)[source]

Update PSFContainer.angles with the indices of all angle-defining atoms from mol.

Parameters:mol (plams.Molecule) – A PLAMS Molecule.
Return type:None
generate_dihedrals(mol)[source]

Update PSFContainer.dihedrals with the indices of all proper dihedral angle-defining atoms from mol.

Parameters:mol (plams.Molecule) – A PLAMS Molecule.
Return type:None
generate_impropers(mol)[source]

Update PSFContainer.impropers with the indices of all improper dihedral angle-defining atoms from mol.

Parameters:mol (plams.Molecule) – A PLAMS Molecule.
Return type:None
generate_atoms(mol, id_map=None)[source]

Update PSFContainer.atoms with the all properties from mol.

DataFrame keys in PSFContainer.atoms are set based on the following values in mol:

DataFrame column Value Backup value(s)
"segment name" "MOL{:d}"; See "atom type" and "residue name"  
"residue ID" Atom.properties ["pdb_info"]["ResidueNumber"] 1
"residue name" Atom.properties ["pdb_info"]["ResidueName"] "COR"
"atom name" Atom.symbol  
"atom type" Atom.properties ["symbol"] Atom.symbol
"charge" Atom.properties ["charge_float"] Atom.properties ["charge"] & 0.0
"mass" Atom.mass  
"0" 0  

If a value is not available in a particular Atom.properties instance then a backup value will be set.

Parameters:
  • mol (plams.Molecule) – A PLAMS Molecule.
  • id_map (Mapping [int, Hashable], optional) – A mapping of ligand residue ID’s to a custom (Hashable) descriptor. Can be used for generating residue names for quantum dots with multiple different ligands.
Return type:

None

_construct_segment_name(id_map=None)[source]

Generate a list for the PSF.atoms ["segment name"] column.

Return type:List[str]
to_atom_dict()[source]

Create a dictionary of atom types and lists with their respective indices.

Returns:A dictionary with atom types as keys and lists of matching atomic indices as values. The indices are 0-based.
Return type:dict [str, list [int]]
write_pdb(mol, pdb_file=<_io.StringIO object>, copy_mol=True)[source]

Construct a .pdb file from this instance and mol.

Parameters:
  • mol (plams.Molecule) – A PLAMS Molecule.
  • copy_mol (bool) – If True, create a copy of mol instead of modifying it inplace.
  • pdb_file (str ot TextIOBase) – A filename or a file-like object.
Return type:

None