GitHub

Atomic and molecular 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"

The formula or stoichiometry of a selection can also be retrieved:

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

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

julia> stoichiometry(select(atoms,"water"))
H₂O₁
PDBTools.mass — Function
mass(s::Sequence)

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

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
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.0067

julia> mass(atoms)
26.017699999999998
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. Othwerwise, 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.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
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

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::String, 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, "C", "Carbon", 6, 12.011, true)

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

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

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

julia> mass(atoms)
26.017699999999998

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, "N", "Nitrogen", 7, 14.0067, true)

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

julia> remove_custom_elements!();

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

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

source

Additional property-retrieving 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.

FunctionExampleOutput
atomic_number(::PDBTools.Atom)atomic_number(Atom(name="NE2"))7
atomic_symbol(::PDBTools.Atom)atomic_symbol(Atom(name="NE2")):N
atomic_mass(::PDBTools.Atom)atomic_mass(Atom(name="NE2"))14.0067
position(::PDBTools.Atom)position(Atom(name="NE2"))SVector{3,Float64}(0,0,0)
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
Base.position — Function
position(atom::Atom)

Returns the position of an atom given the Atom structure.

source