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:

PSFContainer.read()

PSFContainer.write()

Methods for updating atom types:

PSFContainer.update_atom_charge()

PSFContainer.update_atom_type()

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

PSFContainer.generate_bonds()

PSFContainer.generate_angles()

PSFContainer.generate_dihedrals()

PSFContainer.generate_impropers()

PSFContainer.generate_atoms()

Parameters:

filename (\(1\) numpy.ndarray [str]) – Optional: A 1D array-like object containing a single filename. See also PSFContainer.filename.
title (\(n\) numpy.ndarray [str]) – Optional: A 1D array of strings holding the title block. See also PSFContainer.title.
atoms (\(n*8\) pandas.DataFrame) – Optional: A Pandas DataFrame holding the atoms block. See also PSFContainer.atoms.
bonds (\(n*2\) numpy.ndarray [int]) – Optional: A 2D array-like object holding the indices of all atom-pairs defining bonds. See also PSFContainer.bonds.
angles (\(n*3\) numpy.ndarray [int]) – Optional: A 2D array-like object holding the indices of all atom-triplets defining angles. See also PSFContainer.angles.
dihedrals (\(n*4\) numpy.ndarray [int]) – Optional: A 2D array-like object holding the indices of all atom-quartets defining proper dihedral angles. See also PSFContainer.dihedrals.
impropers (\(n*4\) numpy.ndarray [int]) – Optional: A 2D array-like object holding the indices of all atom-quartets defining improper dihedral angles. See also PSFContainer.impropers.
donors (\(n*1\) numpy.ndarray [int]) – Optional: A 2D array-like object holding the atomic indices of all hydrogen-bond donors. See also PSFContainer.donors.
acceptors (\(n*1\) numpy.ndarray [int]) – Optional: A 2D array-like object holding the atomic indices of all hydrogen-bond acceptors. See also PSFContainer.acceptors.
no_nonbonded (\(n*2\) numpy.ndarray [int]) – Optional: A 2D array-like object holding the indices of all atom-pairs whose nonbonded interactions should be ignored. See also PSFContainer.no_nonbonded.

filename¶

A 1D array with a single string as filename.

Type:	\(1\) `numpy.ndarray` [`str`]

title¶

A 1D array of strings holding the title block.

Type:	\(n\) `numpy.ndarray` [`str`]

atoms¶

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"

Type:	\(n*8\) `pandas.DataFrame`

bonds¶

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

Type:	\(n*2\) `numpy.ndarray` [`int`]

angles¶

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

Type:	\(n*3\) `numpy.ndarray` [`int`]

dihedrals¶

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

Type:	\(n*4\) `numpy.ndarray` [`int`]

impropers¶

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

Type:	\(n*4\) `numpy.ndarray` [`int`]

donors¶

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

Type:	\(n*1\) `numpy.ndarray` [`int`]

acceptors¶

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

Type:	\(n*1\) `numpy.ndarray` [`int`]

no_nonbonded¶

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

Type:	\(n*2\) `numpy.ndarray` [`int`]

np_printoptions¶

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

Type:	`Mapping` [`str`, `object`]

pd_printoptions¶

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

Type:	`Mapping` [`str`, `object`]

_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.

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:	atom_type (`str`) – An atom type in `PSFContainer.atoms` `["atom type"]`. charge (`float`) – The new atomic charge to-be assigned to atom_type. See `PSFContainer.atoms` `["charge"]`.
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:	atom_type_old (`str`) – An atom type in `PSFContainer.atoms` `["atom type"]`. atom_type_new (`str`) – The new atom type to-be assigned to atom_type. See `PSFContainer.atoms` `["atom type"]`.
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`