MDAnalysis中文教程-The topology system

拓扑系统

拓扑信息分为3类：

原子容器(Residues和Segments)
原子属性(如name、mass、tempfactor)
拓扑对象: 如bonds、angles、dihedrals、impropers

用户几乎不会直接与拓扑结构进行交互。修改原子容器或拓扑属性通常是通过“Universe”来完成的。而查看容器或拓扑属性的方法，或者计算拓扑对象值的方法，则是通过“AtomGroup”来实现的。

拓扑属性

MDAnalysis 对每个Atom和AtomGroup都支持一系列的拓扑属性。如果为某个原子定义了某个属性，那么该属性也将适用于该原子组，反之亦然——不过，它们的访问方式分别是使用属性的单数形式和复数形式。

标准属性

这些属性派生于Universe，包括empty()创建的空Universe。它们对每个对象的 MDAnalysis 顺序进行编码。

Atom	AtomGroup	描述
index	indices	MDAnalysis的标准原子索引(记数始于0)
resindex	resindices	MDAnalysis的标准残基索引(记数始于0)
segindex	segindices	MDAnalysis的标准片段索引(记数始于0)
从 MDAnalysis 支持的每种格式中读取或猜测以下属性。

Atom	AtomGroup	描述
id	ids	原子ID(记数始于1，除了PSF/DMS/TPR格式)
mass	masses	原子质量(猜测，默认0.0)
resid	resids	残基id(记数始于1，除了TPR)
resnum	resnums	resid的别名
segid	segids	片段名(默认: ‘SYSTEM’)
type	types	原子名，原子元素，或者力场原子类型

特定格式属性

以下表格列出了从支持格式读取的属性。这些属性可以添加到从不支持它们的文件读取创建的Universe。

Atom	AtomGroup	描述	支持格式
altLoc	altLocs	原子备用位置	MMTF, PDB, ENT, PDBQT, XPDB
angles	angles	原子角度	DATA, GSD, PSF, TOP, PRMTOP, PARM7, TPR, XML
aromaticity	aromaticities
atomiccharge	atomiccharges		GMS
atomnum	atomnums		DMS
bonds	bonds		DATA, DMS, GSD, MMTF, MOL2, PSF, TOP, PRMTOP, PARM7, TPR, TXYZ, ARC, XML
chainID	chainIDs	chain ID	DMS, PDB, ENT, PDBQT, TPR, XPDB
charge	charges	partial atomic charge	DATA, DMS, GSD, MMTF, MOL2, PDBQT, PQR, PSF, TOP, PRMTOP, PARM7, TPR, XML
chargegroup	chargegroups
chirality	chiralities
cmaps	cmaps
dihedrals	dihedrals		DATA, GSD, PSF, TOP, PRMTOP, PARM7, TPR, XML
element	elements	atom element	IN, FHIAIMS, MOL2, PDB, ENT, TPR, TXYZ, ARC, XYZ
epsilon	epsilons
epsilon14	epsilon14s
formalcharge	formalcharges
gbscreen	gbscreens
icode	icodes	atom insertion code	MMTF, PDB, ENT, PDBQT, PQR, XPDB
impropers	impropers		DATA, GSD, PSF, TOP, PRMTOP, PARM7, TPR, XML
mass	masses		CONFIG, CRD, DATA, DMS, GMS, GRO, GSD, HISTORY, IN, FHIAIMS, LAMMPSDUMP, MMTF, MOL2, PDB, ENT, PDBQT, PQR, PSF, TOP, PRMTOP, PARM7, TPR, TXYZ, ARC, XML, XPDB, XYZ
model	models	model number (from 0)	MMTF
molnum	molnums	[molecules] number (from 0)	TPR
moltype	moltypes	[moleculetype] name	TPR
name	names	atom names	CONFIG, CRD, DMS, GMS, GRO, GSD, HISTORY, IN, FHIAIMS, MMTF, MOL2, PDB, ENT, PDBQT, PQR, PSF, TOP, PRMTOP, PARM7, TPR, TXYZ, ARC, XPDB, XYZ
nbindex	nbindices
occupancy	occupancies	atom occupancy	MMTF, PDB, ENT, PDBQT, XPDB
radius	radii	atomic radius	GSD, PQR, XML
record_type	record_types	ATOM / HETATM	PDB, ENT, PDBQT, PQR, XPDB
resname	resnames	residue name (except GSD has ints)	CRD, DMS, GRO, GSD, MMTF, MOL2, PDB, ENT, PDBQT, PQR, PSF, TOP, PRMTOP, PARM7, TPR, XPDB
rmin	rmins
rmin14	rmin14s
solventradius	solventradii
tempfactor	tempfactors	B-factor	CRD, MMTF, PDB, ENT, PDBQT, XPDB
type	types		CONFIG, CRD, DATA, DMS, GMS, GRO, GSD, HISTORY, IN, FHIAIMS, LAMMPSDUMP, MMTF, MOL2, PDB, ENT, PDBQT, PQR, PSF, TOP, PRMTOP, PARM7, TPR, TXYZ, ARC, XML, XPDB, XYZ
type_index	type_indices	amber atom type number	TOP, PRMTOP, PARM7
ureybradleys	ureybradleys

连接属性

MDAnalysis 还能够读取连接信息(前提是文件中提供了此类信息)。这些信息会以拓扑对象的形式呈现出来，而这些对象还具有额外的功能。

Atom	AtomGroup	Supported formats
angles	angles	DATA, GSD, PSF, TOP, PRMTOP, PARM7, TPR, XML
bonds	bonds	DATA, DMS, GSD, MMTF, MOL2, PSF, TOP, PRMTOP, PARM7, TPR, TXYZ, ARC, XML
dihedrals	dihedrals	DATA, GSD, PSF, TOP, PRMTOP, PARM7, TPR, XML
impropers	impropers	DATA, GSD, PSF, TOP, PRMTOP, PARM7, TPR, XML

添加TopologyAttrs

上述的每一个属性都可以使用“add_TopologyAttr()”添加到“Universe”中，如果该属性在原始文件中不存在。add_TopologyAttr()需要两个参数：

topologyattr: 一个 TopologyAttr或MDAnalysis的TopologyAttr对象的单数形式或复数形式名称。此名称必须已定义为 TopologyAttr(详见advanced_topology篇)。
values: (可选)。如果topologyattr是字符串，则为该属性赋值。如果该属性有默认值，则为None，如tempfactors。

import MDAnalysis as mda
from MDAnalysis.tests.datafiles import PSF

psf = mda.Universe(PSF)
hasattr(psf.atoms, 'tempfactors')
## False

psf.add_TopologyAttr('tempfactors')
psf.atoms.tempfactors
## array([0., 0., 0., ..., 0., 0., 0.], shape=(3341,))

修改拓扑属性的一种方法是用add_TopologyAttr()简单地将它们替换：

psf.add_TopologyAttr('tempfactors', range(len(psf.atoms)))

psf.atoms.tempfactors
## array([0.000e+00, 1.000e+00, 2.000e+00, ..., 3.338e+03, 3.339e+03, 3.340e+03], shape=(3341,))

提供的值数量应与属性的“级别”相对应。例如，B 因子是原子级信息，B因子的数量应与原子数相同。但是，残基名称和残基 ID 适用于残基。详见默认值和属性级别

修改TopologyAttrs

可以通过分配新值直接修改现有拓扑属性。

import MDAnalysis as mda
from MDAnalysis.tests.datafiles import PDB

pdb = mda.Universe(PDB)
pdb.residues[:3].resnames
## array(['MET', 'ARG', 'ILE'], dtype=object)

pdb.residues[:3].resnames = ['RES1', 'RES2', 'RES3']
pdb.residues[:3].atoms.resnames

## array(['RES1', 'RES1', 'RES1', 'RES1', 'RES1', 'RES1', 'RES1', 'RES1',
##        'RES1', 'RES1', 'RES1', 'RES1', 'RES1', 'RES1', 'RES1', 'RES1',
##        'RES1', 'RES1', 'RES1', 'RES2', 'RES2', 'RES2', 'RES2', 'RES2',
##        'RES2', 'RES2', 'RES2', 'RES2', 'RES2', 'RES2', 'RES2', 'RES2',
##        'RES2', 'RES2', 'RES2', 'RES2', 'RES2', 'RES2', 'RES2', 'RES2',
##        'RES2', 'RES2', 'RES2', 'RES3', 'RES3', 'RES3', 'RES3', 'RES3',
##        'RES3', 'RES3', 'RES3', 'RES3', 'RES3', 'RES3', 'RES3', 'RES3',
##        'RES3', 'RES3', 'RES3', 'RES3', 'RES3', 'RES3'], dtype=object)

注意：这种方式不适用于连接属性，如bonds, angles, dihedrals, impropers。

与使用 add_TopologyAttr() 方法添加拓扑属性的方式类似，属性的“级别”也至关重要。残基属性只能分配给Residue或ResidueGroup级别的属性。对于Atom和Segment的属性也是如此。例如，如果我们试图将 residename 分配给AtomGroup，就会得到一个NotImplementedError错误。

pdb.residues[0].atoms.resnames = ['new_name']
## NotImplementedErrorTraceback (most recent call last)
## <ipython-input-15-0f99b0dc5f49> in <module>
## ----> 1 pdb.residues[0].atoms.resnames = ['new_name']
## ...
## NotImplementedError: Cannot set resnames from AtomGroup. Use 'AtomGroup.residues.resnames = '

默认值和属性级别

在 MDAnalysis 中，拓扑信息总是与一个级别相关联：即原子、残基或片段级别。例如，indices 表示原子信息，resindices 表示残基信息，而 segindices 则表示片段信息。许多拓扑属性也有默认值，这样就可以在不提供明确值和预期类型的情况下将它们添加到一个Universe中。下面的表格列出了哪些属性具有默认值、它们的值是什么以及对应的信息级别。

Atom	AtomGroup	default	level	type
altLocs	altLoc	‘’	atom	<class ‘object’>
angles	angles	No default values	atom
aromaticities	aromaticity	False	atom	<class ‘bool’>
atomiccharges	atomiccharge	No default values	atom
atomnums	atomnum	No default values	atom
bonds	bonds	No default values	atom
chainIDs	chainID	‘’	atom	<class ‘object’>
chargegroups	chargegroup	No default values	atom
charges	charge	0.0	atom	<class ‘float’>
chiralities	chirality	No default values	atom	U1
cmaps	cmaps	No default values	atom
dihedrals	dihedrals	No default values	atom
elements	element	‘’	atom	<class ‘object’>
epsilon14s	epsilon14	0.0	atom	<class ‘float’>
epsilons	epsilon	0.0	atom	<class ‘float’>
formalcharges	formalcharge	0.0	atom	<class ‘int’>
gbscreens	gbscreen	0.0	atom	<class ‘float’>
icodes	icode	‘’	residue	<class ‘object’>
ids	id	continuous sequence from 1 to n_atoms	atom	<class ‘int’>
impropers	impropers	No default values	atom
masses	mass	0.0	atom	<class ‘numpy.float64’>
models	model	No default values	segment
molnums	molnum	No default values	residue	<class ‘numpy.int64’>
moltypes	moltype	‘’	residue	<class ‘object’>
names	name	‘’	atom	<class ‘object’>
nbindices	nbindex	0	atom	<class ‘int’>
occupancies	occupancy	0.0	atom	<class ‘float’>
radii	radius	0.0	atom	<class ‘float’>
record_types	record_type	‘ATOM’	atom	<class ‘object’>
resids	resid	continuous sequence from 1 to n_residues	residue	<class ‘int’>
resnames	resname	‘’	residue	<class ‘object’>
resnums	resnum	continuous sequence from 1 to n_residues	residue	<class ‘int’>
rmin14s	rmin14	0.0	atom	<class ‘float’>
rmins	rmin	0.0	atom	<class ‘float’>

segids     |     segid     |                    ‘’                    | segment |    &lt;class ‘object’&gt;     |

拓扑对象

MDAnalysis通过连接性定义了TopologyObject的四种类型: Bond, Angle, Dihedral, ImproperDihedral。
每个拓扑对象的值使用.value()计算。
每个TopologyObject也包含以下属性：

atoms: 对象中有序原子
indices: 对象中有序的原子索引
type: bond/angle/dihedral/improper或者atom类型列表
is_guessed: MDAnalysis 可以猜测键。此属性记录对象是从文件中读取还是被猜测。

这些组存放在“TopologyGroups”中。TopologyObjects的主组可通过“Universe”的属性进行访问。TopologyObjects通常是通过包含连接信息的文件读取而来(格式详见上文)。然而，它们也可以通过两种方式创建：将它们添加到“Universe”中，或者从“AtomGroup”创建。可以根据距离和范德华半径通过“AtomGroup.guess_bonds”来猜测成键。

向Universe添加

在0.21.0版本中，有特定的方式向Universe添加TopologyObject: add_bonds(), add_angles(), add_dihedrals(), add_impropers().它们接受三个值: TopologyGroup, 原子索引的迭代器, TopologyObjects的迭代器。
在0.21.0之前的版本，使用add_TopologyAttr()向Universe添加对象。

hasattr(pdb, 'angles')
## False

pdb.add_TopologyAttr('angles', [(0, 1, 2), (2, 3, 4)])
pdb.angles
## <TopologyGroup containing 2 angles>

两种方式都可以将新对象添加到相应的Universe的TopologyGroup中。

使用AtomGroup创建

一个AtomGroup可以通过其相应的属性被表示为bond, angle, dihedral angle, improper angle的TopologyObjects: bond, angle, dihedral, improper。
AtomGroup必须包含所需顺序相应数量的原子。例如，一根键不能由三个原子创建。

## pdb.atoms[[3, 4, 2]].bond
## 
## ValueErrorTraceback (most recent call last)
## <ipython-input-21-e59c36ab66f4> in <module>
## ----> 1 pdb.atoms[[3, 4, 2]].bond
## ...
## ValueError: bond only makes sense for a group with exactly 2 atoms

而原子2-4-3的角度可以计算，无论它们是否连接。
这些AtomGroup的TopologyObjects没有被添加到Universe的相应主TopologyGroup中。

从Universe删除

在0.21.0版本中，有特定的方式向Universe删除TopologyObject: delete_bonds(), delete_angles(), delete_dihedrals(), delete_impropers().

拓扑特定方法

针对AtomGroup、ResidueGroup和SegmentGroup定义了多种分析和转换方法，这些方法需要特定属性的存在。首要的要求是“位置”属性。有了位置信息，您就可以轻松计算出几何中心。以下方法都需要坐标：

bbox()
bsphere()
center()
center_of_geometry()
centroid()
pack_into_box()
rotate()
rotate_by()
transform()
translate()
unwrap()
wrap()

当在“Universe”中定义了某些拓扑属性时，还会提供其他方法。以下列出了这些方法。

方法	描述	需要
center_of_charge()	绝对电荷中心	charges
dipole_moment()	偶极矩	charges
dipole_vector()	偶极矢量	charges
quadrupole_moment()	四极矩	charges
quadrupole_tensor()	无迹四极矩张量	charges
total_charge()	总电荷	charges
align_principal_axis()	指定主轴与给定向量对齐	masses
asphericity()	非球面性	masses
center_of_mass()	质心	masses
gyration_moments()	转动张量矩	masses
moment_of_inertia()	相对于质心的惯性张量矩	masses
principal_axes()	惯性矩的主轴	masses
radius_of_gyration()	回转半径	masses
shape_parameter()	形状参数	masses
total_mass()	总质量	masses

以上参数详见文档

翻译https://userguide.mdanalysis.org/stable/topology_system.html