Atomic and molecular properties

Atom properties

Some simple atom properties can be retrieved using special functions, which operate on atoms of the type Atom. For example:

julia> atoms = read_pdb("./file.pdb");

julia> printatom(atoms[1])
   index name resname chain   resnum  residue        x        y        z  beta occup model segname index_pdb
       1   OW     SOL     X        1        1   54.370   45.310   33.970  0.00  0.00     1       -         1

julia> mass(atoms[1])
14.0067

julia> atomic_number(atoms[1])
7

julia> element(atoms[1])
"N"

julia> element_name(atoms[1])
"Nitrogen"

PDBTools.mass — Function

mass(s::Sequence; residue_classes=nothing)

Returns the mass of a sequence of amino acids, given a Sequence struct type.

Note

When retrieving ambiguous codes, protein residue codes will be preferred. Use class=:nucleoside_residues to retrieve only nucleoside data, or data of any other specific class.

Examples

julia> seq = ["Alanine", "Glutamic acid", "Glycine"];

julia> mass(Sequence(seq))
257.2432

julia> seq = "AEG";

julia> mass(Sequence(seq))
257.2432

julia> seq = ["ALA", "GLU", "GLY"];

julia> mass(Sequence(seq))
257.2432

julia> mass(Sequence("AUT"))
755.2310170000001

source

mass(atom::Atom)
mass(atoms::AbstractVector{<:Atoms})

Returns the mass of an atom given its name, or Atom structure, or the total mass of a vector of Atoms.

If a mass is defined as a custom field in the the Atom structure, it is returned. Otherwise, the mass is retrieved from the element mass as inferred from the atom name.

Example

julia> using PDBTools

julia> atoms = [ Atom(name="NT3"), Atom(name="CA") ];

julia> mass(atoms[1])
14.0067f0

julia> mass(atoms)
26.0177f0

source

mass(residue::Residue)

Returns the total mass of all atoms in the residue.

Positional Arguments

residue::Residue: A Residue object.

Returns

Float32: The total mass in atomic mass units (amu).

Example

julia> using PDBTools

julia> atoms = read_pdb(PDBTools.SMALLPDB);

julia> residues = collect(eachresidue(atoms));

julia> mass(residues[1])
73.09489f0

source

mass(chain::Chain)

Returns the total mass of all atoms in the chain.

Positional Arguments

chain::Chain: A Chain object.

Returns

Float32: The total mass in atomic mass units (amu).

Example

julia> using PDBTools

julia> atoms = read_pdb(PDBTools.CHAINSPDB);

julia> chains = collect(eachchain(atoms));

julia> mass(chains[1])
353.3787f0

source

mass(segment::Segment)

Returns the total mass of all atoms in the segment.

Positional Arguments

segment::Segment: A Segment object.

Returns

Float32: The total mass in atomic mass units (amu).

Example

julia> using PDBTools

julia> atoms = read_pdb(PDBTools.DIMERPDB);

julia> segments = collect(eachsegment(atoms));

julia> mass(segments[1])
25222.553f0

source

PDBTools.element — Function

element(atom::Atom)

Returns the element symbol, as a string, of an atom given the Atom structure. If the pdb_element is empty or "X", the element is inferred from the atom name. Otherwise, the pdb_element is returned.

Example

julia> using PDBTools

julia> at = Atom(name="NT3");

julia> element(at)
"N"

source

PDBTools.element_name — Function

element_name(atom::Atom)

Returns the element name of an atom given its name, or Atom structure.

Example

julia> using PDBTools

julia> at = Atom(name="NT3");

julia> element_name(at)
"Nitrogen"

source

PDBTools.element_symbol — Function

element_symbol(atom::Atom)

Returns a symbol for element name of an atom given its name, or Atom structure.

Example

julia> using PDBTools 

julia> at = Atom(name="NT3");

julia> element_symbol(at)
:N

source

PDBTools.element_symbol_string — Function

element_symbol_string(atom::Atom)

Returns a string with the symbol of the element, given the Atom structure.

Example

julia> using PDBTools 

julia> at = Atom(name="NT3");

julia> element_symbol_string(at)
"N"

source

PDBTools.element_vdw_radius — Function

element_vdw_radius(atom::Atom)

Returns the vdW radius of the element of the atom, in Å, or NaN if the data is not available.

Example

julia> using PDBTools 

julia> at = Atom(name="NT3");

julia> element_vdw_radius(at)
1.55f0

source

PDBTools.printatom — Function

printatom(atom::Atom)
printatom(io::IO, atom::Atom)

Prints an Atom structure in a human-readable format, with a title line. By default the output is printed to stdout, and the io argument can be used to specify a different output stream.

Example

julia> using PDBTools

julia> atoms = read_pdb(PDBTools.TESTPDB, "protein and residue 2");

julia> printatom(atoms[1])
   index name resname chain   resnum  residue        x        y        z occup  beta model segname index_pdb
      13    N     CYS     A        2        2   -6.351  -14.461   -5.695  1.00  0.00     1    PROT        13

julia> atoms[1] # default show method
   index name resname chain   resnum  residue        x        y        z occup  beta model segname index_pdb
      13    N     CYS     A        2        2   -6.351  -14.461   -5.695  1.00  0.00     1    PROT        13

source

Molecular formula and stoichiometry

The formula or stoichiometry of a selection can be obtained from a vector of Atoms:

julia> atoms = wget("1LBD","protein and residue 1");

julia> f = formula(atoms)
C₃N₁O₂

julia> stoichiometry(select(atoms,"water"))
H₂O₁

PDBTools.formula — Function

formula(atoms::AbstractVector{<:Atom})

Returns the molecular formula of the current selection. The output is an indexable "Formula" structure, where each element is a tuple with the element name and the number of atoms.

Example

julia> using PDBTools

julia> pdb  = read_pdb(PDBTools.TESTPDB, "residue 1"); # testing PDB file

julia> resname(pdb[1])
"ALA"

julia> f = formula(pdb)
H₇C₃N₁O₁

julia> f[1]
("H", 7)

source

PDBTools.stoichiometry — Function

stoichiometry(atoms::AbstractVector{<:Atom})

Returns the stoichiometry of atom selection in a Formula structure.

Example

julia> using PDBTools

julia> pdb  = read_pdb(PDBTools.TESTPDB, "water"); # testing PDB file

julia> stoichiometry(pdb)
H₂O₁

source

Custom Atom fields

Custom atom fields can be created in Atom objects by defining the custom keyword. By default, custom == nothing. The custom fields can be added on construction, or with the add_custom_field function, which creates a new instance of an Atom with the added value in the custom field:

For example:

julia> using PDBTools

julia> atom = Atom(custom="TEST");

julia> atom.custom
"TEST"

julia> atom = Atom(;name = "CA", resname="ALA"); # no custom field

julia> atom.resname
"ALA"

julia> new_atom = add_custom_field(atom, Dict(:charge => 2.0));

julia> new_atom.resname
"ALA"

julia> new_atom.custom[:charge]
2.0

PDBTools.add_custom_field — Function

add_custom_field(atom::Atom, value)

Adds a custom field to an Atom structure, returning a new Atom structure with the custom field added. The returning Atom structure is parameterized with the type of value.

source

Elements for custom atom types

The types of atoms that PDBTools recognizes is defined in the PDBTools.elements dictionary. If new atom types are defined, it is possible to add these types to the dictionary, such that other functions work for the new types. The function to be used is add_element!.

PDBTools.add_element! — Function

add_element!(symbol::AbstractString, reference_element::PDBTools.Element; elements=PDBTools.elements)

Add a new element to the elements dictionary. If the element already exists, overwrite it.

To remove all custom elements, use remove_custom_elements!().

Example

julia> using PDBTools

julia> remove_custom_elements!(); # if any

julia> atoms = [ Atom(name="A1"), Atom(name="A2") ];

julia> add_element!("A1", PDBTools.elements["C"])
PDBTools.Element(:C, InlineStrings.String15("C"), "Carbon", 6, 12.011f0, true, 1.7f0)

julia> add_element!("A2", PDBTools.elements["N"])
PDBTools.Element(:N, InlineStrings.String15("N"), "Nitrogen", 7, 14.0067f0, true, 1.55f0)

julia> element(atoms[1])
"C"

julia> element(atoms[2])
"N"

julia> mass(atoms)
26.0177f0

julia> remove_custom_elements!();

Here we repeteadly call remove_custom_elements!() to guarantee the proper execution of the test codes, without any custom elements predefined.

source

PDBTools.remove_custom_elements! — Function

remove_custom_elements!()

Remove all custom elements from the elements dictionary.

Example

julia> using PDBTools

julia> remove_custom_elements!();

julia> add_element!("GN", PDBTools.elements["N"])
PDBTools.Element(:N, InlineStrings.String15("N"), "Nitrogen", 7, 14.0067f0, true, 1.55f0)

julia> element(Atom(name="GN"))
"N"

julia> remove_custom_elements!();

julia> element(Atom(name="GN")) # returns `nothing`

Here we repeatedly call remove_custom_elements!() to guarantee the proper execution of the test codes, without any custom elements predefined.

source

Additional property-retrieving and set functions

The following functions are supported as part of the API, as a intending to interface with AtomsBase. Nevertheless, currently these functions do not overload the exported ones from AtomsBase, because that package is in a unstable state.

Function	Example	Output
`atomic_number(::Atom)`	`atomic_number(Atom(name="NE2"))`	`7`
`atomic_symbol(::Atom)`	`atomic_symbol(Atom(name="NE2"))`	`:N`
`atomic_mass(::Atom)`	`atomic_mass(Atom(name="NE2"))`	`14.0067`

PDBTools.atomic_number — Function

atomic_number(atom::Atom)

Returns the atomic number of an atom from its Atom structure.

Example

julia> using PDBTools

julia> at = Atom(name="NT3");

julia> atomic_number(at)
7

source

PDBTools.atomic_symbol — Function

atomic_symbol(atom::Atom)

Returns the atomic symbol of an atom given the Atom structure.

source

PDBTools.atomic_mass — Function

atomic_mass(atom::Atom)

Returns the atomic mass of an atom given the Atom structure.

source

Custom protein and nucleoside residue types

It is possible to add to the list of protein residues, custom residue types. This can be done by simply adding to the PDBTools.protein_residues and PDBTools.nucleoside_residues dictionaries of residues, with the following functions:

PDBTools.add_protein_residue! — Function

add_protein_residue!(resname::AbstractString, reference_residue::PDBTools.ProteinResidue)

Function to add a custom protein residue to the list of protein residues. The function will return the ProteinResidue object that was added. To remove all custom protein residues use remove_custom_protein_residues!().

Example

julia> using PDBTools

julia> remove_custom_protein_residues!();

julia> add_protein_residue!("sA", PDBTools.protein_residues["ALA"])
PDBTools.ProteinResidue("sA", "ALA", "A", "Aliphatic", false, true, 71.037114, 71.0779, 0, true)

julia> isprotein(Atom(resname="sA"))
true

julia> remove_custom_protein_residues!(); # clean up

Here we repeatedly call remove_custom_residues!() to guarantee the proper execution of the test codes, without any custom residues in the list of protein residues.

source

PDBTools.add_nucleoside_residue! — Function

add_nucleoside_residue!(resname::AbstractString, reference_residue::PDBTools.NucleosideResidue)

Add a custom nucleoside residue to the list of nucleoside residues. Returns the added NucleosideResidue. Use remove_custom_nucleoside_residues!() to undo.

Example

julia> using PDBTools

julia> remove_custom_nucleoside_residues!();

julia> add_nucleoside_residue!("MYN", PDBTools.nucleoside_residues["ADO"])
PDBTools.NucleosideResidue("MYN", "ADO", "A", "Purine", 267.094691, 267.094691, 0, true)

julia> isnucleoside(Atom(resname="MYN"))
true

julia> remove_custom_nucleoside_residues!(); # clean up

source

PDBTools.remove_custom_protein_residues! — Function

remove_custom_protein_residues!()

Function to remove all custom protein residues from the list of protein residues.

Example

julia> using PDBTools

julia> remove_custom_protein_residues!(); # clean up

julia> add_protein_residue!("sA", PDBTools.protein_residues["ALA"])
PDBTools.ProteinResidue("sA", "ALA", "A", "Aliphatic", false, true, 71.037114, 71.0779, 0, true)

julia> isprotein(Atom(resname="sA"))
true

julia> remove_custom_protein_residues!();

julia> isprotein(Atom(resname="sA"))
false

Here we repeatedly call remove_custom_residues!() to guarantee the proper execution of the test codes, without any custom residues in the list of protein residues.

source

PDBTools.remove_custom_nucleoside_residues! — Function

remove_custom_nucleoside_residues!()

Remove all custom nucleoside residues from the nucleoside residue list.

Example

julia> using PDBTools

julia> remove_custom_nucleoside_residues!();

julia> add_nucleoside_residue!("MYN", PDBTools.nucleoside_residues["ADO"])
PDBTools.NucleosideResidue("MYN", "ADO", "A", "Purine", 267.094691, 267.094691, 0, true)

julia> isnucleoside(Atom(resname="MYN"))
true

julia> remove_custom_nucleoside_residues!();

julia> isnucleoside(Atom(resname="MYN"))
false

source

For example, here we create a new resiude type NEW with the same properties of an ALA residue. To remove all custom protein residues, use remove_custom_protein_residues!().

using PDBTools
add_protein_residue!("NEW", PDBTools.protein_residues["ALA"])

PDBTools.ProteinResidue("NEW", "ALA", "A", "Aliphatic", false, true, 71.037114, 71.0779, 0, true)

Then, an atom of residue name NEW will be recognized as a protein residue:

atom = Atom(resname="NEW")
isprotein(atom)

true

To remove the elements added, do:

remove_custom_protein_residues!()

OrderedCollections.OrderedDict{String, PDBTools.ProteinResidue} with 28 entries:
  "ALA" => ProteinResidue("Alanine", "ALA", "A", "Aliphatic", false, true, 71.0371, 71.0779, 0, false)
  "ARG" => ProteinResidue("Arginine", "ARG", "R", "Basic", true, false, 156.101, 156.186, 1, false)
  "ASN" => ProteinResidue("Asparagine", "ASN", "N", "Amide", true, false, 114.043, 114.103, 0, false)
  "ASP" => ProteinResidue("Aspartic acid", "ASP", "D", "Acidic", true, false, 115.027, 115.087, -1, false)
  "CYS" => ProteinResidue("Cysteine", "CYS", "C", "Sulfuric", true, false, 103.009, 103.143, 0, false)
  ⋮     => ⋮

The SIRAH force-field residues and element types

Conveniencie functions can be created to add sets of new types of residues and atom types to the list of residues and elements. This is illustrated in the custom_types.jl file of the source code, in this case for the residues and atom types of the SIRAH force field for Coarse-Grained protein simulations.

Note

Masses of the SIRAH beads are not useful in general, and do not have a spcific physical meaning.
Residue sX is interpreted as a bridged Cysteine.
To compute SASAs of SIRAH models, be careful in adding the SIRAH custom elements first, and use the sasa_particles(SIRAH, ...) method.

Defining atom and residue types

Here we repeteadly call remove_custom_residues!() and remove_custom_elements!() to guarantee the proper execution of the test codes, this is not necessary in a regular use of these functions.

With those definitions, adding all SIRAH protein residue types and element names can be done with:

using PDBTools
custom_protein_residues!(SIRAH)
custom_nucleoside_residues!(SIRAH)
custom_elements!(SIRAH)

With that, SIRAH structures have a special support. Let us start reading a CG model:

sirah_pdb = read_pdb(PDBTools.SIRAHPDB)
resname.(eachresidue(sirah_pdb))

5-element Vector{InlineStrings.String15}:
 "sI"
 "sR"
 "sX"
 "sI"
 "sG"

Note that the residue names of the SIRAH force-field are non-standard (sI, sR, etc.), but the sequence is properly retrieved with standard one-letter codes:

getseq(sirah_pdb)

5-element Vector{String}:
 "I"
 "R"
 "C"
 "I"
 "G"

And all protein atoms are recognized:

all(isprotein.(sirah_pdb))

true

Removing the custom types

To remove the custom element types and residues, do:

remove_custom_protein_residues!()
remove_custom_nucleoside_residues!()
remove_custom_elements!()

Dict{String, PDBTools.Element} with 267 entries:
  "Pd"       => Element(:Pd, String15("Pd"), "Palladium", 46, 106.4, false, 1.63)
  "Ag"       => Element(:Ag, String15("Ag"), "Silver", 47, 107.868, false, 1.72)
  "Gd"       => Element(:Gd, String15("Gd"), "Gadolinium", 64, 157.25, false, NaN)
  "Actinium" => Element(:Ac, String15("Ac"), "Actinium", 89, 227.028, false, NaN)
  "Europium" => Element(:Eu, String15("Eu"), "Europium", 63, 151.96, false, NaN)
  ⋮          => ⋮