PDBModel

class biskit.PDBModel(source=None, pdbCode=None, noxyz=0, skipRes=None, headPatterns=[])

Bases: object

Store and manipulate coordinates and atom infos stemming from a PDB file. Coordinates are stored in the numpy array ‘xyz’; the additional atom infos from the PDB (name, residue_name, and many more) are efficiently stored in a PDBProfiles instance ‘atoms’ which can be used to also associate arbitrary other data to the atoms. Moreover, a similar collection ‘residues’ can hold data associated to residues (but is initially empty). A normal dictionary ‘info’ accepts any information about the whole model.

For detailed documentation, see http://biskit.pasteur.fr/doc/handling_structures/PDBModel

@todo:

• outsource validSource into PDBParserFactory
• prevent repeated loading of test PDB for each test

Methods Overview

__init__	Examples:
addChainFromSegid	Takes the last letter of the segment ID and adds it as chain ID.
addChainId	Assign consecutive chain identifiers A - Z to all atoms.
argsort	Prepare sorting atoms within residues according to comparison function.
atom2chainIndices	Convert atom indices to chain indices.
atom2chainMask	Mask (set to 0) chains for which all atoms are masked (0) in atomMask.
atom2resIndices	Get list of indices of residues for which any atom is in indices.
atom2resMask	Mask (set 0) residues for which all atoms are masked (0) in atomMask.
atom2resProfile	Get a residue profile where each residue has the value that its first atom has in the atom profile.
atomNames	Return a list of atom names from start to stop RESIDUE index
atomRange	>>> m.atomRange() == range( m.lenAtoms() )
atomkey	Create a string key encoding the atom content of this model independent of the order in which atoms appear within residues.
biomodel	Return the ‘biologically relevant assembly’ of this model according to the information in the PDB’s BIOMT record (captured in info[‘BIOMT’]).
center	Geometric centar of model.
centerOfMass	Center of mass of PDBModel.
centered	Get model with centered coordinates.
chain2atomIndices	Convert chain indices into atom indices.
chain2atomMask	Convert chain mask to atom mask.
chainBreaks	Identify discontinuities in the molecule’s backbone.
chainEndIndex	Get the position of the each residue’s last atom.
chainIndex	Get indices of first atom of each chain.
chainMap	Get chain index of each atom.
clone	Clone PDBModel.
compareAtoms	Get list of atom indices for this and reference model that converts both into 2 models with identical residue and atom content.
compareChains	Get list of corresponding chain indices for this and reference model.
compress	Compress PDBmodel using mask.
concat	Concatenate atoms, coordinates and profiles.
disconnect	Disconnect this model from its source (if any).
equals	Compares the residue and atom sequence in the given range.
extendIndex	Translate a list of positions that is defined, e.g., on residues (/chains) to a list of atom positions AND also return the starting position of each residue (/chain) in the new sub-list of atoms.
extendMask	Translate a mask that is defined,e.g., on residues(/chains) to a mask that is defined on atoms.
filter	Extract atoms that match a combination of key=values.
filterIndex	Get atom positions that match a combination of key=values.
fit	Least-square fit this model onto refMode
getAtoms	Get atom CrossViews that can be used like dictionaries.
getPdbCode	Return pdb code of model.
getXyz	Get coordinates, fetch from source PDB or pickled PDBModel, if necessary.
index2map	Create a map of len_i length, giving the residue(/chain) numer of each atom, from list of residue(/chain) starting positions.
indices	Get atom indices conforming condition.
indicesFrom	Get atom indices conforming condition applied to an atom profile.
keep	Replace atoms,coordinates,profiles of this(!) model with sub-set.
lenAtoms	Number of atoms in model.
lenBiounits	Number of biological assemblies defined in PDB BIOMT record, if any.
lenChains	Number of chains in model.
lenResidues	Number of residues in model.
magicFit	Superimpose this model onto a ref.
map2index	Identify the starting positions of each residue(/chain) from a map giving the residue(/chain) number of each atom.
mask	Get atom mask.
maskBB	Short cut for mask of all backbone atoms.
maskCA	Short cut for mask of all CA atoms.
maskCB	Short cut for mask of all CB I{and} CA of GLY.
maskDNA	Short cut for mask of all atoms in DNA (based on residue name).
maskF	Create list whith result of atomFunction( atom ) for each atom.
maskFrom	Create an atom mask from the values of a specific profile.
maskH	Short cut for mask of hydrogens.
maskH2O	Short cut for mask of all atoms in residues named TIP3, HOH and WAT
maskHeavy	Short cut for mask of all heavy atoms.
maskHetatm	Short cut for mask of all HETATM
maskNA	Short cut for mask of all atoms in DNA or RNA (based on residue name).
maskProtein	Short cut for mask containing all atoms of amino acids.
maskRNA	Short cut for mask of all atoms in RNA (based on residue name).
maskSolvent	Short cut for mask of all atoms in residues named TIP3, HOH, WAT, Na+, Cl-, CA, ZN
mass	Molecular weight of PDBModel.
masses	Collect the molecular weight of all atoms in PDBModel.
mergeChains	Merge two adjacent chains.
mergeResidues	Merge two adjacent residues.
plot	Get a quick & dirty overview over the content of a PDBModel.
profile	Use:: profile( name, updateMissing=0) -> atom or residue profile
profile2atomMask	Same as profile2mask, but converts residue mask to atom mask.
profile2mask	param cutoff_min:  low value cutoff (all values >= cutoff_min) :type cutoff_min: float :param cutoff_max: high value cutoff (all values < cutoff_max) :type cutoff_max: float
profile2resList	Group the profile values of each residue’s atoms into a separate list.
profileChangedFromDisc	Check if profile has changed compared to source.
profileInfo	Use:
remove	Convenience access to the 3 different remove methods.
removeProfile	Remove residue or atom profile(s)
removeRes	Remove all atoms with a certain residue name.
renameAmberRes	Rename special residue names from Amber back into standard names (i.e CYX S{->} CYS )
renumberResidues	Make all residue numbers consecutive and remove any insertion code letters.
report	Print (or return) a brief description of this model.
reportAtoms	param i:optional list of atom positions to report (default: all) :type i: [ int ] :return: formatted string with atom and residue names similar to PDB :rtype: str
res2atomIndices	Convert residue indices to atom indices.
res2atomMask	Convert residue mask to atom mask.
res2atomProfile	Get an atom profile where each atom has the value its residue has in the residue profile.
resEndIndex	Get the position of the each residue’s last atom.
resIndex	Get the position of the each residue’s first atom.
resList	Return list of lists of atom pseudo dictionaries per residue, which allows to iterate over residues and atoms of residues.
resMap	Get list to map from any atom to a continuous residue numbering (starting with 0).
resMapOriginal	Generate list to map from any atom to its ORIGINAL(!) PDB residue number.
resModels	Creates one new PDBModel for each residue in the parent PDBModel.
residusMaximus	Take list of value per atom, return list where all atoms of any residue are set to the highest value of any atom in that residue.
rms	Rmsd between two PDBModels.
saveAs	Pickle this PDBModel to a file, set the ‘source’ field to this file name and mark atoms, xyz, and profiles as unchanged.
sequence	Amino acid sequence in one letter code.
setPdbCode	Set model pdb code.
setSource	param source:LocalPath OR PDBModel OR str
setXyz	Replace coordinates.
slim	Remove xyz array and profiles if they haven’t been changed and could hence be loaded from the source file (only if there is a source file…).
sort	Apply a given sort list to the atoms of this model.
sourceFile	Name of pickled source or PDB file.
structureFit	Structure-align this model onto a reference model using the external TM-Align program (which needs to be installed).
take	Extract a PDBModel with a subset of atoms:
takeChains	Get copy of this model with only the given chains.
takeResidues	Copy the given residues into a new model.
transform	Transform coordinates of PDBModel.
transformation	Get the transformation matrix which least-square fits this model onto the other model.
unequalAtoms	Identify atoms that are not matching between two models.
unsort	Undo a previous sorting on the model itself (no copy).
update	Read coordinates, atoms, fileName, etc.
validSource	Check for a valid source on disk.
version
writePdb	Save model as PDB file.
xplor2amber	Rename atoms so that tleap from Amber can read the PDB.
xyzChangedFromDisc	Tell whether xyz can currently be reconstructed from a source on disc.
xyzIsChanged	Tell if xyz or atoms have been changed compared to source file or source object (which can be still in memory).

Attributes Overview

PDB_KEYS

keys of all atom profiles that are read directly from the PDB file

---

PDBModel Method & Attribute Details

PDB_KEYS = ['name', 'residue_number', 'insertion_code', 'alternate', 'name_original', 'chain_id', 'occupancy', 'element', 'segment_id', 'charge', 'residue_name', 'after_ter', 'serial_number', 'type', 'temperature_factor']

keys of all atom profiles that are read directly from the PDB file

__init__(source=None, pdbCode=None, noxyz=0, skipRes=None, headPatterns=[])

Examples:

• PDBModel() creates an empty Model to which coordinates (field xyz) and PDB records (atom profiles) have still to be added.
• PDBModel( file_name ) creates a complete model with coordinates and PDB records from file_name (pdb, pdb.gz, or pickled PDBModel)
• PDBModel( PDBModel ) creates a copy of the given model
• PDBModel( PDBModel, noxyz=1 ) creates a copy without coordinates

Parameters:

• source (str or PDBModel) – str, file name of pdb/pdb.gz file OR pickled PDBModel OR PDBModel, template structure to copy atoms/xyz field from
• pdbCode (str or None) – PDB code, is extracted from file name otherwise
• noxyz (0||1) – 0 (default) || 1, create without coordinates
• headPatterns ([(str, str)]) – [(putIntoKey, regex)] extract given REMARK values

Raises:

PDBError – if file exists but can’t be read

residues = None

save atom-/residue-based values

xyzChanged = None

monitor changes of coordinates

initVersion = None

version as of creation of this object

info = None

to collect further informations

report(prnt=True, plot=False, clipseq=60)

Print (or return) a brief description of this model.

Parameters:

• prnt (bool) – directly print report to STDOUT (default True)
• plot (bool) – show simple 2-D line plot using gnuplot [False]
• clipseq (int) – clip chain sequences at this number of letters [60]

Returns:

if prnt==True: None, else: formatted description of this model

Return type:

None or str

plot(hetatm=False)

Get a quick & dirty overview over the content of a PDBModel. plot simply creates a 2-D plot of all x-coordinates versus all y coordinates, colored by chain. This is obviously not publication-quality ;-). Use the Biskit.Pymoler class for real visalization.

Parameters:hetatm (bool) – include hetero & solvent atoms (default False)

update(skipRes=None, updateMissing=0, force=0, headPatterns=[])

Read coordinates, atoms, fileName, etc. from PDB or pickled PDBModel - but only if they are currently empty. The atomsChanged and xyzChanged flags are not changed.

Parameters:

• skipRes (list of str) – names of residues to skip if updating from PDB
• updateMissing (0|1) – 0(default): update only existing profiles
• force (0|1) – ignore invalid source (0) or report error (1)
• headPatterns ([(str, str)]) – [(putIntoKey, regex)] extract given REMARKS

Raises:

PDBError – if file can’t be unpickled or read:

setXyz(xyz)

Replace coordinates.

Parameters:xyz (array) – Numpy array ( 3 x N_atoms ) of float Returns:array( 3 x N_atoms ) or None, old coordinates Return type:array

setSource(source)

Parameters:source – LocalPath OR PDBModel OR str

getXyz(mask=None)

Get coordinates, fetch from source PDB or pickled PDBModel, if necessary.

Parameters:mask (list of int OR array of 1||0) – atom mask Returns:xyz-coordinates, array( 3 x N_atoms, Float32 ) Return type:array

getAtoms(mask=None)

Get atom CrossViews that can be used like dictionaries. Note that the direct manipulation of individual profiles is more efficient than the manipulation of CrossViews (on profiles)!

Parameters:mask (list of int OR array of 1||0) – atom mask Returns:list of CrossView dictionaries Return type:[ ProfileCollection.CrossView ]

profile(name, default=None, update=True, updateMissing=False)

Use::

profile( name, updateMissing=0) -> atom or residue profile

Parameters:

• name (str) – name to access profile
• default – default result if no profile is found, if None,

try to update from source and raise error [None] :type default: any :param update: update from source before returning empty profile [True] :type update: bool :param updateMissing: update from source before reporting missing

profile [False]

Raises:ProfileError – if neither atom- nor rProfiles contains |name|

profileInfo(name, updateMissing=0)

Use:

profileInfo( name ) -> dict with infos about profile

Parameters:

• name (str) – name to access profile
• updateMissing (0|1) –

  update from source before reporting missing profile. Guaranteed infos are:

  • ’version’ (str)
  • ’comment’ (str)
  • ’changed’ (1||0)

Raises:

ProfileError – if neither atom - nor rProfiles contains |name|

removeProfile(*names)

Remove residue or atom profile(s)

Use:

removeProfile( str_name [,name2, name3] ) -> 1|0,

Parameters:names (str OR list of str) – name or list of residue or atom profiles Returns:1 if at least 1 profile has been deleted, 0 if none has been found Return type:int

xyzIsChanged()

Tell if xyz or atoms have been changed compared to source file or source object (which can be still in memory).

Returns:xyz field has been changed with respect to source Return type:(1||0, 1||0)

xyzChangedFromDisc()

Tell whether xyz can currently be reconstructed from a source on disc. Same as xyzChanged() unless source is another not yet saved PDBModel instance that made changes relative to its own source.

Returns:xyz has been changed Return type:bool

profileChangedFromDisc(pname)

Check if profile has changed compared to source.

Returns:1, if profile |pname| can currently not be reconstructed from a source on disc. Return type:int Raises:ProfileError – if there is no atom or res profile with pname

slim()

Remove xyz array and profiles if they haven’t been changed and could hence be loaded from the source file (only if there is a source file…). AUTOMATICALLY CALLED BEFORE PICKLING Currently also called by deepcopy via getstate

validSource()

Check for a valid source on disk.

Returns:str or PDBModel, None if this model has no valid source Return type:str or PDBModel or None

sourceFile()

Name of pickled source or PDB file. If this model has another PDBModel as source, the request is passed on to this one.

Returns:file name of pickled source or PDB file Return type:str Raises:PDBError – if there is no valid source

disconnect()

Disconnect this model from its source (if any).

Note

If this model has an (in-memory) PDBModel instance as source, the entries of ‘atoms’ could still reference the same dictionaries.

getPdbCode()

Return pdb code of model.

Returns:pdb code Return type:str

setPdbCode(code)

Set model pdb code.

Parameters:code (str) – new pdb code

sequence(mask=None, xtable={'ca': '+', 'cl-': '-', 'hoh': '~', 'na+': '+', 'nap': 'X', 'ndp': 'X', 'tip3': '~', 'wat': '~'})

Amino acid sequence in one letter code.

Parameters:

• mask (list or array) – atom mask, to apply before (default None)
• xtable (dict) – dict {str:str}, additional residue:single_letter mapping for non-standard residues (default molUtils.xxDic) [currently not used]

Returns:

1-letter-code AA sequence (based on first atom of each res).

Return type:

str

xplor2amber(aatm=True, parm10=False)

Rename atoms so that tleap from Amber can read the PDB. If HIS residues contain atoms named HE2 or/and HD2, the residue name is changed to HIE or HID or HIP, respectively. Disulfide bonds are not yet identified - CYS -> CYX renaming must be done manually (see AmberParmBuilder for an example). Internally amber uses H atom names ala HD21 while (old) standard pdb files use 1HD2. By default, ambpdb produces ‘standard’ pdb atom names but it can output the less ambiguous amber names with switch -aatm.

Parameters:

• change (1|0) – change this model’s atoms directly (default:1)
• aatm (1|0) – use, for example, HG23 instead of 3HG2 (default:1)
• parm10 (1|0) – adapt nucleic acid atom names to 2010 Amber forcefield

Returns:

[ {..} ], list of atom dictionaries

Return type:

list of atom dictionaries

renameAmberRes()

Rename special residue names from Amber back into standard names (i.e CYX S{->} CYS )

writePdb(fname, ter=1, amber=0, original=0, left=0, wrap=0, headlines=None, taillines=None)

Save model as PDB file.

Parameters:

• fname (str) – name of new file
• ter (int) –

  Option of how to treat the terminal record:

  • 0 - don’t write any TER statements
  • 1 - restore original TER statements (doesn’t work, if preceeding atom has been deleted) [default]
  • 2 - put TER between all detected chains
  • 3 - as 2 but also detect and split discontinuous chains
• amber (1||0) – amber formatted atom names (implies ter=3, left=1, wrap=0) (default 0)
• original (1||0) – revert atom names to the ones parsed in from PDB (default 0)
• left (1||0) – left-align atom names (as in amber pdbs)(default 0)
• wrap (1||0) – write e.g. ‘NH12’ as ‘2NH1’ (default 0)
• headlines (list of tuples) – [( str, dict or str)], list of record / data tuples:: e.g. [ (‘SEQRES’, ‘ 1 A 22 ALA GLY ALA’), ]
• taillines (list of tuples) – same as headlines but appended at the end of file

saveAs(path)

Pickle this PDBModel to a file, set the ‘source’ field to this file name and mark atoms, xyz, and profiles as unchanged. Normal pickling of the object will only dump those data that can not be reconstructed from the source of this model (if any). saveAs creates a ‘new source’ without further dependencies.

Parameters:path (str OR LocalPath instance) – target file name

maskF(atomFunction, numpy=1)

Create list whith result of atomFunction( atom ) for each atom. (Depending on the return value of atomFunction, the result is not necessarily a mask of 0 and 1. Creating masks should be just the most common usage).

Note:

This method is slow compared to maskFrom because the dictionaries that are given to the atomFunction have to be created from aProfiles on the fly. If performance matters, better combine the result from several maskFrom calls, e.g. instead of:

r = m.maskF( lambda a: a['name']=='CA' and a['residue_name']=='ALA' )

use:

r = m.maskFrom( 'name', 'CA' ) * m.maskFrom('residue_name', 'ALA')

Parameters:

• atomFunction (1||0) – function( dict_from_aProfiles.toDict() ), true || false (Condition)
• numpy (int) – 1(default)||0, convert result to Numpy array of int

Returns:

Numpy array( [0,1,1,0,0,0,1,0,..], Int) or list

Return type:

array or list

maskFrom(key, cond)

Create an atom mask from the values of a specific profile. Example, the following three statements are equivalent:

>>> mask = m.maskFrom( 'name', 'CA' )
>>> mask = m.maskFrom( 'name', lambda a: a == 'CA' )
>>> mask = N0.array( [ a == 'CA' for a in m.atoms['name'] ] )

However, the same can be also achieved with standard numpy operators:

>>> mask = numpy.array(m.atoms['name']) == 'CA'

Parameters:

• key (str) – the name of the profile to use
• cond (function OR any OR [ any ]) – either a function accepting a single value or a value or an iterable of values (to allow several alternatives)

Returns:

array or list of indices where condition is met

Return type:

list or array of int

maskCA(force=0)

Short cut for mask of all CA atoms.

Parameters:force (0||1) – force calculation even if cached mask is available Returns:array( 1 x N_atoms ) of 0||1 Return type:array

maskBB(force=0, solvent=0)

Short cut for mask of all backbone atoms. Supports standard protein and DNA atom names. Any residues classified as solvent (water, ions) are filtered out.

Parameters:

• force (0||1) – force calculation even if cached mask is available
• solvent (1||0) – include solvent residues (default: false)

Returns:

array( 1 x N_atoms ) of 0||1

Return type:

array

maskHeavy(force=0)

Short cut for mask of all heavy atoms. (‘element’ <> H)

Parameters:force (0||1) – force calculation even if cached mask is available Returns:array( 1 x N_atoms ) of 0||1 Return type:array

maskH()

Short cut for mask of hydrogens. (‘element’ == H)

Returns:array( 1 x N_atoms ) of 0||1 Return type:array

maskCB()

Short cut for mask of all CB I{and} CA of GLY.

Returns:mask of all CB plus CA of GLY Return type:array

maskH2O()

Short cut for mask of all atoms in residues named TIP3, HOH and WAT

Returns:array( 1 x N_atoms ) of 0||1 Return type:array

maskSolvent()

Short cut for mask of all atoms in residues named TIP3, HOH, WAT, Na+, Cl-, CA, ZN

Returns:array( 1 x N_atoms ) of 0||1 Return type:array

maskHetatm()

Short cut for mask of all HETATM

Returns:array( 1 x N_atoms ) of 0||1 Return type:array

maskProtein(standard=0)

Short cut for mask containing all atoms of amino acids.

Parameters:standard (0|1) – only standard residue names (not CYX, NME,..) (default 0) Returns:array( 1 x N_atoms ) of 0||1, mask of all protein atoms (based on residue name) Return type:array

maskDNA()

Short cut for mask of all atoms in DNA (based on residue name).

Returns:array( 1 x N_atoms ) of 0||1 Return type:array

maskRNA()

Short cut for mask of all atoms in RNA (based on residue name).

Returns:array( 1 x N_atoms ) of 0||1 Return type:array

maskNA()

Short cut for mask of all atoms in DNA or RNA (based on residue name).

Returns:array( 1 x N_atoms ) of 0||1 Return type:array

indicesFrom(key, cond)

Get atom indices conforming condition applied to an atom profile. Corresponds to:

>>> numpy.nonzero( m.maskFrom( key, cond) )

Parameters:

• key (str) – the name of the profile to use
• cond (function OR any OR [any]) – either a function accepting a single value or a value or an iterable of values

Returns:

array of indices where condition is met

:rtype : array of int

indices(what)

Get atom indices conforming condition. This is a convenience method to ‘normalize’ different kind of selections (masks, atom names, indices, functions) to indices as they are e.g. required by PDBModel.take.

Parameters:what (function OR list of str or int OR int) –

Selection:: - function applied to each atom entry,

e.g. lambda a: a[‘residue_name’]==’GLY’

• list of str, allowed atom names
• list of int, allowed atom indices OR mask with only 1 and 0
• int, single allowed atom index

Returns:N_atoms x 1 (0||1 ) Return type:Numeric array Raises:PDBError – if what is neither of above

mask(what)

Get atom mask. This is a convenience method to ‘normalize’ different kind of selections (masks, atom names, indices, functions) to a mask as it is e.g. required by PDBModel.compress.

Parameters:what (function OR list of str or int OR int) –

Selection:: - function applied to each atom entry,

e.g. lambda a: a[‘residue_name’]==’GLY’

• list of str, allowed atom names
• list of int, allowed atom indices OR mask with only 1 and 0
• int, single allowed atom index

Returns:N_atoms x 1 (0||1 ) Return type:Numeric array Raises:PDBError – if what is neither of above

index2map(index, len_i)

Create a map of len_i length, giving the residue(/chain) numer of each atom, from list of residue(/chain) starting positions.

Parameters:

• index ([ int ] or array of int) – list of starting positions, e.g. [0, 3, 8]
• len_i (int) – length of target map, e.g. 10

Returns:

list mapping atom positions to residue(/chain) number, e.g. [0,0,0, 1,1,1,1,1, 2,2] from above example

Return type:

array of int (and of len_i length)

map2index(imap)

Identify the starting positions of each residue(/chain) from a map giving the residue(/chain) number of each atom.

Parameters:imap ([ int ]) – something like [0,0,0,1,1,1,1,1,2,2,2,…] Returns:list of starting positions, e.g. [0, 3, 8, …] in above ex. Return type:array of int

extendMask(mask, index, len_i)

Translate a mask that is defined,e.g., on residues(/chains) to a mask that is defined on atoms.

:param mask : mask marking positions in the list of residues or chains :type mask : [ bool ] or array of bool or of 1||0 :param index: starting positions of all residues or chains :type index: [ int ] or array of int :param len_i: length of target mask :type len_i: int

Returns:mask that blows up the residue / chain mask to an atom mask Return type:array of bool

extendIndex(i, index, len_i)

Translate a list of positions that is defined, e.g., on residues (/chains) to a list of atom positions AND also return the starting position of each residue (/chain) in the new sub-list of atoms.

:param i : positions in higher level list of residues or chains :type i : [ int ] or array of int :param index: atomic starting positions of all residues or chains :type index: [ int ] or array of int :param len_i: length of atom index (total number of atoms) :type len_i: int

Returns:(ri, rindex) - atom positions & new index Return type:array of int, array of int

atom2resMask(atomMask)

Mask (set 0) residues for which all atoms are masked (0) in atomMask.

Parameters:atomMask (list/array of int) – list/array of int, 1 x N_atoms Returns:1 x N_residues (0||1 ) Return type:array of int

atom2resIndices(indices)

Get list of indices of residues for which any atom is in indices.

Note: in the current implementation, the resulting residues are returned in their old order, regardless of the order of input positions.

Parameters:indices (list of int) – list of atom indices Returns:indices of residues Return type:list of int

res2atomMask(resMask)

Convert residue mask to atom mask.

Parameters:resMask (list/array of int) – list/array of int, 1 x N_residues Returns:1 x N_atoms Return type:array of int

res2atomIndices(indices)

Convert residue indices to atom indices.

Parameters:indices (list/array of int) – list/array of residue indices Returns:array of atom positions Return type:array of int

atom2chainIndices(indices, breaks=0)

Convert atom indices to chain indices. Each chain is only returned once.

Parameters:

• indices (list of int) – list of atom indices
• breaks (0||1) – look for chain breaks in backbone coordinates (def. 0)

Returns:

chains any atom which is in indices

Return type:

list of int

atom2chainMask(atomMask, breaks=0)

Mask (set to 0) chains for which all atoms are masked (0) in atomMask. Put another way: Mark all chains that contain any atom that is marked ‘1’ in atomMask.

Parameters:atomMask (list/array of int) – list/array of int, 1 x N_atoms Returns:1 x N_residues (0||1 ) Return type:array of int

chain2atomMask(chainMask, breaks=0)

Convert chain mask to atom mask.

Parameters:

• chainMask (list/array of int) – list/array of int, 1 x N_chains
• breaks (0||1) – look for chain breaks in backbone coordinates (def. 0)

Returns:

1 x N_atoms

Return type:

array of int

chain2atomIndices(indices, breaks=0)

Convert chain indices into atom indices.

Parameters:indices (list/array of int) – list/array of chain indices Returns:array of atom positions, new chain index Return type:array of int

res2atomProfile(p)

Get an atom profile where each atom has the value its residue has in the residue profile.

Parameters:p (str) – name of existing residue profile OR … [ any ], list of lenResidues() length Returns:[ any ] OR array, atom profile Return type:list or array

atom2resProfile(p, f=None)

Get a residue profile where each residue has the value that its first atom has in the atom profile. :param p: name of existing atom profile OR …

[ any ], list of lenAtoms() length

Parameters:f (func) – function to calculate single residue from many atom values f( [atom_value1, atom_value2,…] ) -> res_value (default None, simply take value of first atom in each res.) Returns:[ any ] OR array, residue profile Return type:list or array

profile2mask(str_profname[, cutoff_min, cutoff_max=None])

Parameters:

• cutoff_min (float) – low value cutoff (all values >= cutoff_min)
• cutoff_max (float) – high value cutoff (all values < cutoff_max)

Returns:

mask len( profile(profName) ) x 1||0

Return type:

array

Raises:

ProfileError – if no profile is found with name profName

profile2atomMask(str_profname[, cutoff_min, cutoff_max=None])

Same as profile2mask, but converts residue mask to atom mask.

Parameters:

• cutoff_min (float) – low value cutoff
• cutoff_max (float) – high value cutoff

Returns:

mask N_atoms x 1|0

Return type:

array

Raises:

ProfileError – if no profile is found with name profName

profile2resList(p)

Group the profile values of each residue’s atoms into a separate list. :param p: name of existing atom profile OR …

[ any ], list of lenAtoms() length

Returns:a list (one entry per residue) of lists (one entry per resatom) Return type:[ [ any ] ]

mergeChains(c1, id='', segid='', rmOxt=True, renumberAtoms=False, renumberResidues=True)

Merge two adjacent chains. This merely removes all internal markers for a chain boundary. Atom content or coordinates are not modified.

PDBModel tracks chain boundaries in an internal _chainIndex. However, there are cases when this chainIndex needs to be re-built and new chain boundaries are then infered from jumps in chain- or segment labelling or residue numbering. mergeChains automatically re-assigns PDB chain- and segment IDs as well as residue numbering to prepare for this situation.

:param c1 : first of the two chains to be merged :type c1 : int :param id : chain ID of the new chain (default: ID of first chain) :type id : str :param segid: ew chain’s segid (default: SEGID of first chain) :type segid: str :param renumberAtoms: rewrite PDB serial numbering of the adjacent

chain to be consequtive to the last atom of the first chain (default: False)

Parameters:renumberResidues (bool) – shift PDB residue numbering so that the first residue of the adjacent chain follows the previous residue. Other than for atom numbering, later jumps in residue numbering are preserved. (default: True)

mergeResidues(r1, name='', residue_number=None, chain_id='', segment_id='', renumberAtoms=False)

Merge two adjacent residues. Duplicate atoms are labelled with alternate codes ‘A’ (first occurrence) to ‘B’ or later. :param r1: first of the two residues to be merged :type r1: int :param name: name of the new residue (default: name of first residue) :type name: str

concat(*models, **kw)

Concatenate atoms, coordinates and profiles. source and fileName are lost, so are profiles that are not available in all models. model0.concat( model1 [, model2, ..]) -> single PDBModel.

Parameters:

• models (one or more PDBModel instances) – models to concatenate
• newRes (bool) – treat beginning of second model as new residue (True)
• newChain (bool) – treat beginning of second model as new chain (True)

Note: info records of given models are lost.

take(i, rindex=None, cindex=None, *initArgs, **initKw)

Extract a PDBModel with a subset of atoms:

take( atomIndices ) -> PDBModel

All other PDBModel methods that extract portions of the model (e.g. compress, takeChains, takeResidues, keep, clone, remove) are ultimately using take() at their core.

Note: take employs fast numpy vector mapping methods to re-calculate the residue and chain index of the result model. The methods generally work but there is one scenario were this mechanism can fail: If take is used to create repetitions of residues or chains directly next to each other, these residues or chains can get accidentally merged. For this reason, calling methods can optionally pre-calculate and provide a correct version of the new residue or chain index (which will then be used as is).

Parameters:

• i (list/array of int) – atomIndices, positions to take in the order to take
• rindex (array of int) – optional residue index for result model after extraction
• cindex (array of int) – optional chain index for result model after extraction
• initArgs – any number of additional arguments for constructor of result model
• initKw – any additional keyword arguments for constructure of result model

Returns:

new PDBModel or sub-class

Return type:

PDBModel

keep(i)

Replace atoms,coordinates,profiles of this(!) model with sub-set. (in-place version of N0.take() )

Parameters:i (list or array of int) – atom positions to be kept

clone()

Clone PDBModel.

Returns:PDBModel / subclass, copy of this model, see comments to numpy.take() Return type:PDBModel

compress(mask, *initArgs, **initKw)

Compress PDBmodel using mask.

compress( mask ) -> PDBModel

Parameters:mask (array) –

array( 1 x N_atoms of 1 or 0 ):

• 1 .. keep this atom

Returns:compressed PDBModel using mask Return type:PDBModel

remove(what)

Convenience access to the 3 different remove methods. The mask used to remove atoms is returned. This mask can be used to apply the same change to another array of same dimension as the old(!) xyz and atoms.

Parameters:what (list of int or int) –

Decription of what to remove:

• function( atom_dict ) -> 1 || 0 (1..remove) OR
• list of int [4, 5, 6, 200, 201..], indices of atoms to remove
• list of int [11111100001101011100..N_atoms], mask (1..remove)
• int, remove atom with this index

Returns:array(1 x N_atoms_old) of 0||1, mask used to compress the atoms and xyz arrays. Return type:array Raises:PDBError – if what is neither of above

takeResidues(i)

Copy the given residues into a new model.

Parameters:i ([ int ]) – residue indices Returns:PDBModel with given residues in given order Return type:PDBModel

takeChains(chains, breaks=0, force=0)

Get copy of this model with only the given chains.

Note, there is one very special scenario where chain boundaries can get lost: If breaks=1 (chain positions are based on normal chain boundaries as well as structure-based chain break detection) AND one or more chains are extracted several times next to each other, for example chains=[0, 1, 1, 2], then the repeated chain will be merged. So in the given example, the new model would have chainLength()==3. This case is tested for and a PDBIndexError is raised. Override with force=1 and proceed at your own risk. Which, in this case, simply means you should re-calculate the chain index after takeChains(). Example:

>>> repeat = model.takeChains( [0,0,0], breaks=1, force=1 )
>>> repeat.chainIndex( force=1, cache=1 )

This works because the new model will have back-jumps in residue numbering.

Parameters:

• chains (list of int) – list of chains, e.g. [0,2] for first and third
• breaks (0|1) – split chains at chain breaks (default 0)
• maxDist (float) – (if breaks=1) chain break threshold in Angstrom
• force (bool) – override check for chain repeats (only for breaks==1)

Returns:

PDBModel consisting of the given chains in the given order

Return type:

PDBModel

addChainFromSegid(verbose=1)

Takes the last letter of the segment ID and adds it as chain ID.

addChainId(first_id=None, keep_old=0, breaks=0)

Assign consecutive chain identifiers A - Z to all atoms.

Parameters:

• first_id (str) – str (A - Z), first letter instead of ‘A’
• keep_old (1|0) – don’t override existing chain IDs (default 0)
• breaks (1|0) – consider chain break as start of new chain (default 0)

renumberResidues(mask=None, start=1, addChainId=1)

Make all residue numbers consecutive and remove any insertion code letters. Note that a backward jump in residue numbering (among other things) is interpreted as end of chain by chainMap() and chainIndex() when a PDB file is loaded.

Parameters:

• mask (list of int) – [ 0||1 x N_atoms ] atom mask to apply BEFORE
• start (int) – starting number (default 1)
• addChainId (1|0) – add chain IDs if they are missing

atomRange()

>>> m.atomRange() == range( m.lenAtoms() )

Returns:integer range for lenght of this model Return type:[ int ]

lenAtoms(lookup=True)

Number of atoms in model.

Returns:number of atoms Return type:int

lenResidues()

Number of residues in model.

Returns:total number of residues Return type:int

lenChains(breaks=0, maxDist=None, singleRes=0, solvent=0)

Number of chains in model.

Parameters:

• breaks (0||1) – detect chain breaks from backbone atom distances (def 0)
• maxDist (float) – maximal distance between consequtive residues [ None ] .. defaults to twice the average distance
• singleRes (1||0) – allow chains consisting of single residues (def 0)
• solvent (1||0) – also check solvent residues for “chain breaks” (def 0)

Returns:

total number of chains

Return type:

int

resList(mask=None)

Return list of lists of atom pseudo dictionaries per residue, which allows to iterate over residues and atoms of residues.

Parameters:mask – [ 0||1 x N_atoms ] atom mask to apply BEFORE Returns:a list (one per residue) of lists (one per atom) of dictionaries

[ [ CrossView{'name':'N', ' residue_name':'LEU', ..},
    CrossView{'name':'CA', 'residue_name':'LEU', ..} ],

  [ CrossView{'name':'CA', 'residue_name':'GLY', ..}, .. ]
]

Return type:[ [ biskit.ProfileCollection.CrossView ] ]

resModels(i=None)

Creates one new PDBModel for each residue in the parent PDBModel.

Parameters:i ([ int ] or array( int )) – range of residue positions (default: all residues) Returns:list of PDBModels, one for each residue Return type:[ PDBModel ]

resMapOriginal(mask=None)

Generate list to map from any atom to its ORIGINAL(!) PDB residue number.

Parameters:mask (list of int (1||0)) – [00111101011100111…] consider atom: yes or no len(mask) == N_atoms Returns:list all [000111111333344444..] with residue number for each atom Return type:list of int

resIndex(mask=None, force=0, cache=1)

Get the position of the each residue’s first atom.

Parameters:

• force (1||0) – re-calculate even if cached result is available (def 0)
• cache (1||0) – cache the result if new (def 1)
• mask (list of int (1||0)) – atom mask to apply before (i.e. result indices refer to compressed model)

Returns:

index of the first atom of each residue

Return type:

list of int

resMap(force=0, cache=1)

Get list to map from any atom to a continuous residue numbering (starting with 0). A new residue is assumed to start whenever the ‘residue_number’ or the ‘residue_name’ record changes between 2 atoms.

See resList() for an example of how to use the residue map.

Parameters:

• force (0||1) – recalculate map even if cached one is available (def 0)
• cache (0||1) – cache new map (def 1)

Returns:

array [00011111122223333..], residue index for each atom

Return type:

list of int

resEndIndex()

Get the position of the each residue’s last atom.

Returns:index of the last atom of each residue Return type:list of int

chainIndex(breaks=0, maxDist=None, force=0, cache=0, singleRes=0, solvent=0)

Get indices of first atom of each chain.

Parameters:

• breaks (1||0) – split chains at chain breaks (def 0)
• maxDist (float) – (if breaks=1) chain break threshold in Angstrom
• force (1||0) – re-analyze residue numbering, chain and segids to find chain boundaries, use with care! (def 0)
• cache (1||0) – cache new index even if it was derrived from non-default parameters (def 0) Note: a simple m.chainIndex() will always cache
• singleRes (1||0) – allow chains consisting of single residues (def 0) Otherwise group consecutive residues with identical name into one chain.
• solvent (1||0) – also check solvent residues for “chain breaks” (default: false)

Returns:

array (1 x N_chains) of int

Return type:

list of int

chainEndIndex(breaks=0, solvent=0)

Get the position of the each residue’s last atom.

Returns:index of the last atom of each residue Return type:list of int

chainMap(breaks=0, maxDist=None)

Get chain index of each atom. A new chain is started between 2 atoms if the chain_id or segment_id changes, the residue numbering jumps back or a TER record was found.

Parameters:

• breaks (1||0) – split chains at chain breaks (def 0)
• maxDist (float) – (if breaks=1) chain break threshold in Angstrom

Returns:

array 1 x N_atoms of int, e.g. [000000011111111111122222…]

Return type:

list of int

chainBreaks(breaks_only=1, maxDist=None, force=0, solvent=0, z=6.0)

Identify discontinuities in the molecule’s backbone. By default, breaks are identified from the distribution of distances between the last backbone atom of a residue and the first backbone atom of the next residue. The median distance and standard deviation are determined iteratively and outliers (i.e. breaks) are identified as any pairs of residues with a distance that is more than z standard deviations (default 10) above the median. This heuristics can be overriden by specifiying a hard distance cutoff (maxDist).

Parameters:

• breaks_only (1|0) – don’t report ends of regular chains (def 1)
• maxDist (float) – maximal distance between consequtive residues [ None ] .. defaults median + z * standard dev.

:param z : z-score for outlier distances between residues (def 6.) :type z : float :param solvent: also check selected solvent residues (buggy!) (def 0) :type solvent: 1||0 :param force: force re-calculation, do not use cached positions (def 0) :type force: 1||0

Returns:atom indices of last atom before a probable chain break Return type:list of int

removeRes(what)

Remove all atoms with a certain residue name.

Parameters:what (str OR [ str ] OR int OR [ int ]) – indices or name(s) of residue to be removed

rms(other, mask=None, mask_fit=None, fit=1, n_it=1)

Rmsd between two PDBModels.

Parameters:

• other (PDBModel) – other model to compare this one with
• mask (list of int) – atom mask for rmsd calculation
• mask_fit (list of int) – atom mask for superposition (default: same as mask)
• fit (1||0) – superimpose first (default 1)
• n_it (int) – number of fit iterations:: 1 - classic single fit (default) 0 - until convergence, kicking out outliers on the way

Returns:

rms in Angstrom

Return type:

float

transformation(refModel, mask=None, n_it=1, z=2, eps_rmsd=0.5, eps_stdv=0.05, profname='rms_outlier')

Get the transformation matrix which least-square fits this model onto the other model.

Parameters:

• refModel (PDBModel) – reference PDBModel
• mask (list of int) – atom mask for superposition
• n_it (int) – number of fit iterations:: 1 - classic single fit (default) 0 - until convergence
• z (float) – number of standard deviations for outlier definition (default 2)
• eps_rmsd (float) – tolerance in rmsd (default 0.5)
• eps_stdv (float) – tolerance in standard deviations (default 0.05)
• profname (str) – name of new atom profile getting outlier flag

Returns:

array(3 x 3), array(3 x 1) - rotation and translation matrices

Return type:

array, array

transform(*rt)

Transform coordinates of PDBModel.

Parameters:rt (array OR array, array) – rotational and translation array: array( 4 x 4 ) OR array(3 x 3), array(3 x 1) Returns:PDBModel with transformed coordinates Return type:PDBModel

fit(refModel, mask=None, n_it=1, z=2, eps_rmsd=0.5, eps_stdv=0.05, profname='rms_outlier')

Least-square fit this model onto refMode

Parameters:

• refModel (PDBModel) – reference PDBModel
• mask (list of int (1||0)) – atom mask for superposition
• n_it (int) – number of fit iterations:: 1 - classic single fit (default) 0 - until convergence
• z (float) – number of standard deviations for outlier definition (default 2)
• eps_rmsd (float) – tolerance in rmsd (default 0.5)
• eps_stdv (float) – tolerance in standard deviations (default 0.05)
• profname (str) – name of new atom profile containing outlier flag

Returns:

PDBModel with transformed coordinates

Return type:

PDBModel

magicFit(refModel, mask=None)

Superimpose this model onto a ref. model with similar atom content. magicFit( refModel [, mask ] ) -> PDBModel (or subclass )

Parameters:

• refModel (PDBModel) – reference PDBModel
• mask (list of int (1||0)) – atom mask to use for the fit

Returns:

fitted PDBModel or sub-class

Return type:

PDBModel

structureFit(refModel, mask=None)

Structure-align this model onto a reference model using the external TM-Align program (which needs to be installed).

structureFit( refModel [, mask] ) -> PDBModel (or subclass)

The result model has additional TM-Align statistics in its info record: r = m.structureFit( ref ) r.info[‘tm_score’] -> TM-Align score the other keys are: ‘tm_rmsd’, ‘tm_len’, ‘tm_id’

See also

biskit.TMAlign

Parameters:

• refModel (PDBModel) – reference PDBModel
• mask (list of int (1||0)) – atom mask to use for the fit

Returns:

fitted PDBModel or sub-class

Return type:

PDBModel

centered(mask=None)

Get model with centered coordinates.

Parameters:mask (list of int (1||0)) – atom mask applied before calculating the center Returns:model with centered coordinates Return type:PDBModel

center(mask=None)

Geometric centar of model.

Parameters:mask (list of int (1||0)) – atom mask applied before calculating the center Returns:xyz coordinates of center Return type:(float, float, float)

centerOfMass()

Center of mass of PDBModel.

Returns:array(Float32) Return type:(float, float, float)

masses()

Collect the molecular weight of all atoms in PDBModel.

Returns:1-D array with mass of every atom in 1/12 of C12 mass. Return type:array of floats Raises:PDBError – if the model contains elements of unknown mass

mass()

Molecular weight of PDBModel.

Returns:total mass in 1/12 of C12 mass Return type:float Raises:PDBError – if the model contains elements of unknown mass

residusMaximus(atomValues, mask=None)

Take list of value per atom, return list where all atoms of any residue are set to the highest value of any atom in that residue. (after applying mask)

Parameters:

• atomValues (list) – values per atom
• mask (list of int (1||0)) – atom mask

Returns:

array with values set to the maximal intra-residue value

Return type:

array of float

argsort(cmpfunc=None)

Prepare sorting atoms within residues according to comparison function.

Parameters:

• cmpfunc (function) – old style function(m.atoms[i], m.atoms[j]) -> -1, 0, +1
• key (function) – new style sort key function(m.atoms[i]) -> sortable

Returns:

suggested position of each atom in re-sorted model ( e.g. [2,1,4,6,5,0,..] )

Return type:

list of int

sort(sortArg=None)

Apply a given sort list to the atoms of this model.

Parameters:sortArg (function) – comparison function Returns:copy of this model with re-sorted atoms (see numpy.take() ) Return type:PDBModel

unsort(sortList)

Undo a previous sorting on the model itself (no copy).

Parameters:sortList (list of int) – sort list used for previous sorting. Returns:the (back)sort list used ( to undo the undo…) Return type:list of int Raises:PDBError – if sorting changed atom number

atomNames(start=None, stop=None)

Return a list of atom names from start to stop RESIDUE index

Parameters:

• start (int) – index of first residue
• stop (int) – index of last residue

Returns:

[‘C’,’CA’,’CB’ …. ]

Return type:

list of str

filterIndex(mode=0, **kw)

Get atom positions that match a combination of key=values. E.g. filter( chain_id=’A’, name=[‘CA’,’CB’] ) -> index

Parameters:

• mode (0||1) – 0 combine with AND (default), 1 combine with OR
• kw (filter options, see example) – combination of atom dictionary keys and values/list of values that will be used to filter

Returns:

sort list

Return type:

list of int

filter(mode=0, **kw)

Extract atoms that match a combination of key=values. E.g. filter( chain_id=’A’, name=[‘CA’,’CB’] ) -> PDBModel

Parameters:

• mode (0||1) – 0 combine with AND (default), 1 combine with OR
• kw (filter options, see example) – combination of atom dictionary keys and values/list of values that will be used to filter

Returns:

filterd PDBModel

Return type:

PDBModel

equals(ref, start=None, stop=None)

Compares the residue and atom sequence in the given range. Coordinates are not checked, other profiles are not checked.

Parameters:

• start (int) – index of first residue
• stop (int) – index of last residue

Returns:

[ 1||0, 1||0 ], first position sequence identity 0|1, second positio atom identity 0|1

Return type:

list if int

compareAtoms(ref)

Get list of atom indices for this and reference model that converts both into 2 models with identical residue and atom content.

E.g.

>>> m2 = m1.sort()    ## m2 has now different atom order
>>> i2, i1 = m2.compareAtoms( m1 )
>>> m1 = m1.take( i1 ); m2 = m2.take( i2 )
>>> m1.atomNames() == m2.atomNames()  ## m2 has again same atom order

Returns:indices, indices_ref Return type:([int], [int])

unequalAtoms(ref, i=None, iref=None)

Identify atoms that are not matching between two models. This method returns somewhat of the opposite of compareAtoms().

Not matching means: (1) residue is missing, (2) missing atom within a residue, (3) atom name is different. Differences in coordinates or other atom profiles are NOT evaluated and will be ignored.

(not speed-optimized)

Parameters:

• ref (PDBModel) – reference model to compare to
• i (array( int ) or [ int ]) – pre-computed positions that are equal in this model (first value returned by compareAtoms() )
• iref – pre-computed positions that are equal in ref model (first value returned by compareAtoms() )

Returns:

missmatching atoms of self, missmatching atoms of ref

Return type:

array(int), array(int)

reportAtoms(i=None, n=None)

Parameters:i ([ int ]) – optional list of atom positions to report (default: all) Returns:formatted string with atom and residue names similar to PDB Return type:str

compareChains(ref, breaks=0, fractLimit=0.2)

Get list of corresponding chain indices for this and reference model. Use takeChains() to create two models with identical chain content and order from the result of this function.

Parameters:

• ref (PDBModel) – reference PDBModel
• breaks (1||0) – look for chain breaks in backbone coordinates
• fractLimit (float) –

Returns:

chainIndices, chainIndices_ref

Return type:

([int], [int])

biomodel(assembly=0)

Return the ‘biologically relevant assembly’ of this model according to the information in the PDB’s BIOMT record (captured in info[‘BIOMT’]).

This removes redundant chains and performs symmetry operations to complete multimeric structures. Some PDBs define several alternative biological units: usually (0) the author-defined one and (1) software-defined – see lenBiounits.

Note: The BIOMT data are currently not updated during take/compress calls which may change chain indices and content. This method is therefore best run on an original PDB record before any other modifications are performed.

Parameters:assembly (int) – assembly index (default: 0 .. author-determined unit) Returns:PDBModel; biologically relevant assembly

lenBiounits()

Number of biological assemblies defined in PDB BIOMT record, if any.

Returns:number of alternative biological assemblies defined in PDB header Return type:int

atomkey(compress=True)

Create a string key encoding the atom content of this model independent of the order in which atoms appear within residues. Atom names are simply sorted alphabetically within residues and then concatenated.

Parameters:compress (bool) – compress key with zlib (default: true) Returns:key formed from sorted atom content of model Return type:str