entity.rst



The Molecular Entity
This document describes the :class:`EntityHandle` and the related classes.

The Handle Classes
The entity class represents a molecular structure. Such a structure is in
general made up of one or more chains of residues, which in turn are
formed by one or more atoms.
The interface of entities is tailored to biological macromolecules, but this
does not prevent it to be used for molecules in general: An entity also
represent a ligand or a collection of water molecules - hence the rather
generic name.
A chain of one or more :class:`residues <ResidueHandle>`. Chains are always
part of an entity.
The residue is either used to represent complete molecules or building blocks
in a polymer, e.g. in a protein, DNA or RNA. A residue consists of one or
more :class:`atoms <AtomHandle>`. Residues are always part of a
:class:`ChainHandle`, even if they are ligands or water molecules where the
concept of a chain does not apply.
Represents an atom in a molecular structure. Atoms are always part of a
residue.

The View Classes
An entity view represents a structural subset of an :class:`EntityHandle`. For
an introduction ,see :doc:`../../intro-01`.
A view representation of a :class:`ChainHandle`. Mostly, the same
functionality is provided as for the handle.
A view representation of a :class:`ResidueHandle`. Mostly, the same
functionality is provided as for the handle.
A view representation of an :class:`AtomHandle`. Mostly, the same
functionality is provided as for the handle.

Functions

Boolean Operators

Other Entity-Related Functions

Residue Numbering
Number for a residue. The residue number has a numeric part and an (optional)
insertion-code. You can work with this object as if it was an integer and
comparison will look first at the numeric part and then the insertion-code.
All access to existing objects is read-only.


param num:
Numeric part of residue number.


type num:
:class:`int`


param ins_code:
Alpha-numeric part of residue number (optional insertion
code). Only first character kept.


type ins_code:
:class:`str`


ChainType
A ChainType fills the :attr:`ChainHandle.type` attribute. Different types are
described in the :class:`ChainType` enum. The type is set with an editor in
:meth:`EditorBase.SetChainType`. Further convenience functions are described
here.
The ChainType enum enumerates all types defined by the PDB for the MMCif file
format. Following values are supported:

CHAINTYPE_POLY, CHAINTYPE_NON_POLY, CHAINTYPE_WATER,
CHAINTYPE_POLY_PEPTIDE_D, CHAINTYPE_POLY_PEPTIDE_L,
CHAINTYPE_POLY_DN, CHAINTYPE_POLY_RN, CHAINTYPE_POLY_SAC_D,
CHAINTYPE_POLY_SAC_L, CHAINTYPE_POLY_DN_RN,
CHAINTYPE_UNKNOWN, CHAINTYPE_MACROLIDE,
CHAINTYPE_CYCLIC_PSEUDO_PEPTIDE, CHAINTYPE_POLY_PEPTIDE_DN_RN,
CHAINTYPE_N_CHAINTYPES

Where CHAINTYPE_N_CHAINTYPES holds the number of different types available.

ViewAddFlag
Defines flags controlling behaviour of routines adding handles to views:


INCLUDE_ATOMS - Include all atoms when adding a residue handle to a view

INCLUDE_RESIDUES - Include all residues when adding a chain to a view

INCLUDE_CHAINS - Include all chains when creating a new entity view

INCLUDE_ALL = INCLUDE_ATOMS | INCLUDE_RESIDUES |
INCLUDE_CHAINS - Convenience flags to include all substructures

CHECK_DUPLICATES - If set, it will be checked that no duplicates are
created when adding a new handle

Flags can be ORed to combine them.

SecStructure
Defines a secondary structure type following the types defined by DSSP.


param type:
Type to be set for this object.


type type:
:class:`SecStructure.Type` / :class:`str`


Enumerates all popssible secondary structure types distinguished by DSSP.
Their values with the corresponding character code are listed here:

ChemClass
The chemical class is used to broadly categorize residues based on their
chemical properties. For example, peptides belong to some PEPTIDE_LINKING
class. Possible values as constant variable names and as characters:
Python can implicitly convert characters to objects of this type. Note however
that only the first character of a :class:`str` object is considered!


param chem_class:
Chemical class to set.


type chem_class:
:class:`str`


ChemType
The chemical type of a residue is a classification of all compounds obtained
from the PDB component dictionary. For example, ions belong to the class IONS,
amino acids to AMINOACIDS. Possible values as constant variable names and as
characters:
Python can implicitly convert characters to objects of this type. Note however
that only the first character of a :class:`str` object is considered!


param chem_type:
Chemical type to set.


type chem_type:
:class:`str`