Properties

When reading files, chemfiles read multiple kind of data: positions, velocities, atomic information (name, type, mass, charge, …), bonds and other connectivity elements. This model allow to read the most commonly available data in various formats. But sometimes, a format defines additional information. Instead of adding a new field/function for every kind of data there can be in a file, chemfiles defines a generic interface to read and store this additional data. These additional data are stored inside properties.

A property has a name and a value. The value can either be a real number, a string, a Boolean value (true/false) or a 3 dimensional vector. A property is either stored inside an atom, and associated with this atom (for example the total atomic force), or stored in and associated with a frame. The later case is used for general properties, such as the temperature of the system, or the author of the file.

This section documents which format set and use properties.

Atomic properties

Name

Type

Format

Description

altloc

string

MMTF

On reading, this property is set the the alternative location character stored in both of these formats. On writing, this character is stored with the ATOM or HETATM record. If the property is not set, a space character is used.

mmCIF

On reading, this property is set the the alternative location character stored in both of these formats. On writing, this character is stored with the ATOM or HETATM record. If the property is not set, a space character is used.

hydrogen_count

number

CML

The number of hydrogens attached to the atom. The property is only set if the attribute is given and is non-zero.

SMI

The number of hydrogens attached to the atom. The property is only set if the property ‘H’ is given.

sybyl

string

MOL2

The sybyl atom type is typically stored in a MOL2 file in a column between the Z coordinate and the residue id. These types typically consist of an element ID, a period, then a hybridization state (eg C.2 or O.3). When reading, if the sybyl type column contains a period or is a valid element ID, this property is set to the value in the column. Otherwise, the property is not set and the atom type is guessed from the atom name. When writing, if this propery is set, then this value is written between the Z coordinate and the residue number. Otherwise, the atom’s type is used to replace the sybyl type.

is_aromatic

bool

SMI

Describes if the atom is flagged as aromatic. This flag is set if the atom type is given as ‘b’, ‘c’, ‘o’, ‘p’, or ‘s’. This flag is also set when the atom is lowercase and in a property bracket. If the flag is set when the SMILES string is written, then the atom will be written in lowercase.

smiles_class

number

SMI

The class of the atom given in the SMILES string. This propery is set if a ‘:’ character followed by a number is found in a property bracket while reading. If this property is set when the SMILES string is written, then the atom will be written in a property bracket with the ‘:’ character.

chirality

string

SMI

The chirality tag of the atom. If the chirality given in an atom property bracket is ‘@@’, then this string is set to ‘CW’. If the chirality is given as ‘@’, followed by ‘TH’, ‘AL’, ‘SP’, ‘TB’, or ‘OH’, which is in turn followed by a number, then this string is set to ‘CCW <character tag><number>’. When writing, if the string begins with ‘CW’, then ‘@@’ will be added to the property bracket. Otherwise, ‘@’ will be writing followed by the remaining string. At the moment, no attempt is made to ensure that the chirality of the atom is valid.

wildcard

bool

SMI

Sets if the atom was defined as a wildcard card atom.

atom_type

number

Tinker

The Tinker atom type.

ff_type

string

TPR

Describes the atom type specified in the [atoms] section of the topology. The type can be used to reference a specific set of force field parameters for a given atom.

Residue properties

Name

Type

Format

Description

is_standard_pdb

bool

PDB

When reading, is_standard_pdb is set to true for residues defined with a ATOM record, and false for atoms defined with an HETATM record. When writing, is_standard_pdb is used to determine whether to emit an HETATM or an ATOM record. If the property is not set, HETATM is used.

MMTF

When reading, is_standard_pdb is set to false when the composition_type for the group is related to peptide or nucleotide linkage. See the composition_type property for residues for more information. This property is ignored while writing.

mmCIF

When reading, is_standard_pdb is set to true when _atom_site.group_PDB is ATOM, false when it is HETATM, and is unset in the absense of this field. When writing, is_standard_pdb is used to determine whether to use ATOM or HETATM for _atom_site.group_PDB. If the property is not set, HETATM is used.

chainname

string

PDB

The chainname defines the name assigned to a protein chain by biologists. It is a single character used to group residues which are linked together in a crystallographic file where it may not be unique.

PSF

The chainname is a single character used to group residues which are linked together. For PSF files, it is taken as the first letter of the segname.

mmCIF

The chainname defines the name assigned to a protein chain by biologists. It is a single character used to group residues which are linked together in a crystallographic file where it may not be unique. This name is unique to a given biological assembly, however.

MMTF

The chainname defines the name assigned to a protein chain by biologists. It is a single character used to group residues which are linked together in a crystallographic file where it may not be unique. This name is unique to a given biological assembly, however.

chainid

string

PDB

For PDB files, the chainid is identical to chainname

PSF

For PSF files, the chainid is identical to chainname

mmCIF

The chainname defines the name assigned to a protein chain by biologists. It is is a single character used to group residues which are linked together in a biologic assembly. It is unique to both the biologic assembly and the crystal structure.

MMTF

The chainname defines the name assigned to a protein chain by biologists. It is is a single character used to group residues which are linked together in a biologic assembly. It is unique to both the biologic assembly and the crystal structure.

chainindex

number

MMTF

The chainindex is a numeric representation of the chainindex and it may be removed in a future release. It will be negative if the residue is created through a symmetry operation.

composition_type

string

MMTF

The composition_type defines how residues are chemically bonded. For example, the majority of proteins consist of L-peptide linking residues, RNAs consist of L-RNA linking, DNAs consist of L-DNA linking, and saccharides consist of D-saccharide. See chemCompType in the mmCIF dictionary for more details. Since this is a required group property, other is used when writing unless specified.

mmCIF

The composition_type defines how residues are chemically bonded. For example, the majority of proteins consist of L-peptide linking residues, RNAs consist of L-RNA linking, DNAs consist of L-DNA linking, and saccharides consist of D-saccharide. See chemCompType in the mmCIF dictionary for more details.

assembly

string

MMTF

The assembly property defines the assignment of biologically relevent groupings of residues in a crystal structure. For example, the PDBID 4XUF contains two biologically identical copies of the protein FLT3, labled bioA and bioB, as this protein does not function as a homodimer. The PDBID 3OGF, however, is a homodimer and therefore only contains one biological assembly with two chains. This property is not used for writing.

insertion_code

string

PDB

On reading, this insertion_code is set to the insertion code of the residue. This code is stored as a single character in the PDB file after the residue id. If this character is a space character, the property is not set. On writing, this character is stored with the ATOM or HETATM record. If the property is not set, a space character is used.

secondary_structure

string

PDB

On reading, the secondary_structure is assigned via HELIX, SHEET, and TURN records. If a residue is listed in a SHEET record, then the secondary_structure is set to extended. Similarly, the TURN record will set residues as turn. The HELIX record is more complex as the PDB standard allows for multiple types of helicies include alpha, pi, and 3-10 helicies. This property is not used for writing.

MMTF

On reading, the secondary_structure is assigned via the secStructList field in the MMTF standard. The values assigned match the descriptions by the Define Secondary Strucutre of Proteins (DSSP) algorithm. Examples include extended, alpha helix, pi helix, turn and coil. This property is not set for undefined secondary structures and is not used for writing.

segname

string

PDB

PDB files used with CHARM, NAMD and a few other software package can contain a non-standard segment name associated with a residue. If set when writting a frame, this property is written to the file.

PSF

Name of the segment containing this resiude. A segment is typically a single chain of protein or DNA. Segments may also contain pure solvent or lipid.

Frame properties

Name

Type

Format

Description

name

string

Amber NetCDF

The global attribute title is used as the frame name when reading.

Amber Restart

The global attribute title is used as the frame name when reading.

CML

The text in the name node of a molecule. Only set if the node is present.

PDB

The text described by the TITLE record is used as the frame name when reading.

GRO

The first line of a GRO file is used as the frame name when reading.

SDF

The first line of an SDF file is used as the frame name when reading.

MOL2

The first line after @<TRIPOS>MOLECULE is used as the frame name when reading.

MMTF

The text in the title field is used as the frame name when reading.

mmCIF

The text in the _struct.title field is used as the frame name when reading.

SMI

Any string after a terminating (blank) character in a SMILES string.

TPR

Name of the system as declared in the [system] section of the TOP file.

classification

string

PDB

The classification of a structure assigned by the PDB. Read from the HEADER record.

pdb_idcode

string

PDB

Four letter code for structures deposited in the PDB. Read from the HEADER record.

MMTF

Four letter code for structures deposited in the PDB. Read from the structuresId field.

mmCIF

Four letter code for structures deposited in the PDB. Read from the _entry.id field.

deposition_date

string

PDB

Date (DD-MMM-YY format) of the deposition in the PDB. Read from the HEADER record.

MMTF

Date (YYYY-MM-DD format) of the deposition in the PDB. Read from the depositionDate field.

title

string

CML

The text of the title attribute in a molecule node. Only set if the attribute is present.

DCD

Content of the title lines in the DCD file header. When writing, the first frame writen to a DCD file sets this header field.

time

number

LAMMPS

The time of the frame in time units.

TNG

The time of the frame in pico seconds.

TRR

The time of the frame in pico seconds.

XTC

The time of the frame in pico seconds.

DCD

The time of the frame in the file units, only set when reading a file

lammps_units

string

LAMMPS

Style of units used by LAMMPS for a simulation.

xtc_precision

number

XTC

The precision used to compress the coordinates. Only used for ten or more atoms. Default is 1000.

has_positions

bool

TRR

Set to true if the frame contains positions. All positions are zero if not.

trr_lambda

number

TRR

This is usually the free energy coupling parameter.

is_unwrapped

bool

LAMMPS

Indicates whether the frame contains unwrapped positions. Only set when reading a file.

Additionally, the SDF format reads any property formatted as > <...>, using the value inside the angle brackets (... here) as the property name.