PDB

The module PDB defines types and methods to work with protein structures inside Julia. It is useful to link structural and sequential information, and needed for measure the predictive performance at protein contact prediction of mutual information scores.

Features

• Read and parse mmCIF, PDB and PDBML files.
• Calculate distance and contacts between atoms or residues
• Determine interaction between residues

using MIToS.PDB

BioStructures.MolecularStructure(residues::Vector{PDBResidue})

Build a BioStructures.MolecularStructure from a vector of PDBResidue objects without creating an intermediate mmCIF dictionary.

A Coordinates object is a fixed size vector with the coordinates x,y,z.

MMCIFFile <: FileFormat

macromolecular Crystallographic Information File (mmCIF) format.

A PDBAtom object contains the information from a PDB atom, without information of the residue. It has the following fields that you can access at any moment for query purposes:

- `coordinates` : x,y,z coordinates, e.g. `Coordinates(109.641,73.162,42.7)`.
- `atom` : Atom name, e.g. `"CA"`.
- `element` : Element type of the atom, e.g. `"C"`.
- `occupancy` : A float number with the occupancy, e.g. `1.0`.
- `B` : B factor as a string, e.g. `"23.60"`.
- `alt_id` : Alternative location ID, e.g. `"A"`.
- `charge` : Charge of the atom, e.g. `"0"`.

PDBFile <: FileFormat

Protein Data Bank (PDB) format. It provides a standard representation for macromolecular structure data derived from X-ray diffraction and NMR studies.

PDBML <: FileFormat

Protein Data Bank Markup Language (PDBML), a representation of PDB data in XML format.

A PDBResidue object contains all the information about a PDB residue. It has the following fields that you can access at any moment for query purposes:

- `id` : A `PDBResidueIdentifier` object.
- `atoms` : A vector of `PDBAtom`s.

A PDBResidueIdentifier object contains the information needed to identity PDB residues. It has the following fields that you can access at any moment for query purposes:

- `PDBe_number` : It's only used when a PDBML is readed (PDBe number as a string).
- `number` : PDB residue number, it includes insertion codes, e.g. `"34A"`.
- `name` : Three letter residue name in PDB, e.g. `"LYS"`.
- `group` : It can be `"ATOM"` or `"HETATM"`.
- `model` : The model number as a string, e.g. `"1"`.
- `chain` : The chain as a string, e.g. `"A"`.

Covalent radius in Å of each element from the Additional file 1 of PICCOLO (Bickerton et al.). Hydrogen was updated using the value on Table 2 from (Cordero et al.).

References

- [Bickerton, George R., Alicia P. Higueruelo, and Tom L. Blundell. "Comprehensive, 
  atomic-level characterization of structurally characterized protein-protein 
  interactions: the PICCOLO database." BMC bioinformatics 
  12 (2011): 1-15.](@cite 10.1186/1471-2105-12-313)
- [Cordero, Beatriz, et al. "Covalent radii revisited." Dalton Transactions 
  21 (2008): 2832-2838.](@cite 10.1039/B801115J)

van der Waals radius in Å from the Additional file 1 of Bickerton et al.

References

- [Bickerton, George R., Alicia P. Higueruelo, and Tom L. Blundell. "Comprehensive, 
  atomic-level characterization of structurally characterized protein-protein 
  interactions: the PICCOLO database." BMC bioinformatics 
  12 (2011): 1-15.](@cite 10.1186/1471-2105-12-313)

@atoms ... model ... chain ... group ... residue ... atom ...

These return a vector of PDBAtoms with the selected subset of atoms from a list of residues. You can use the type All to avoid filtering that option.

DEPRECATED: This macro is deprecated. Use the select_atoms function instead.

@residues ... model ... chain ... group ... residue ...

These return a new vector with the selected subset of residues from a list of residues. You can use the type All to avoid filtering that option.

DEPRECATED: This macro is deprecated. Use the select_residues function instead.

@residuesdict ... model ... chain ... group ... residue ...

This macro returns a dictionary (using PDB residue numbers as keys) with the selected subset of residues from a list of residues. You can use the type All to avoid filtering that option.

DEPRECATED: This macro is deprecated. Use the residuesdict function instead.

angle(a::Coordinates, b::Coordinates, c::Coordinates)

Angle (in degrees) at b between a-b and b-c

any(f::Function, a::PDBResidue, b::PDBResidue, criteria::Function)

Test if the function f is true for any pair of atoms between the residues a and b. This function only test atoms that returns true for the fuction criteria.

any(f::Function, a::PDBResidue, b::PDBResidue)

Test if the function f is true for any pair of atoms between the residues a and b

Returns a matrix with the x, y and z coordinates of the Cα with best occupancy for each PDBResidue of the ATOM group. If a residue doesn't have a Cα, its Cα coordinates are NaNs.

There's an aromatic interaction if centriods are at 6.0 Å or less.

Returns true if an sulphur and an aromatic atoms are 5.3 Å or less"

Takes a Vector of PDBAtoms and returns a Vector of the PDBAtoms with best occupancy.

center!(A::AbstractMatrix{Float64})

Takes a set of points A as an NxD matrix (N: number of points, D: dimension). Translates A in place so that its centroid is at the origin of coordinates

Returns a Matrix{Float64} with the centered coordinates of all the atoms in residues. An optional positional argument CA (default: true) defines if only Cα carbons should be used to center the matrix.

Returns a new Vector{PDBResidue} with the PDBResidues having centered coordinates. An optional positional argument CA (default: true) defines if only Cα carbons should be used to center the matrix.

change_b_factor!(residue::PDBResidue, value; atom=All)

Change the B-factor of the selected atoms in residue in place and return the modified residue. By default all atoms in the residue are updated. Atom selection follows the same conventions as select_atoms.

change_b_factor(atom::PDBAtom, value)

Return a new PDBAtom with the B-factor changed to value. value is formatted using the PDB Real(6.2) specification and must not exceed six characters once formatted.

change_b_factor(residue::PDBResidue, value; atom=All)

Return a new PDBResidue with the B-factor of the selected atoms changed to value. By default all atoms in the residue are updated. Atom selection follows the same conventions as select_atoms.

change_coordinates(residue::PDBResidue, coordinates::AbstractMatrix{Float64}, offset::Int=1)

Returns a new PDBResidues with (x,y,z) from a coordinates AbstractMatrix{Float64} You can give an offset indicating in which matrix row starts the (x,y,z) coordinates of the residue.

change_coordinates(residues::AbstractVector{PDBResidue}, coordinates::AbstractMatrix{Float64})

Returns a new Vector{PDBResidues} with (x,y,z) from a coordinates Matrix{Float64}

change_coordinates(atom::PDBAtom, coordinates::Coordinates)

Returns a new PDBAtom but with a new coordinates

This function takes a PDBResidue and returns true only if all the atoms can be used for checking interactions.

contact(a::Coordinates, b::Coordinates, limit::AbstractFloat)

It returns true if the distance is less or equal to the limit. It doesn't call sqrt because it does squared_distance(a,b) <= limit^2.

contact(A::PDBResidue, B::PDBResidue, limit::AbstractFloat; criteria::String="All")

Returns true if the residues A and B are at contact distance (limit). The available distance criteria are: Heavy, All, CA, CB (CA for GLY)

contact(residues::Vector{PDBResidue}, limit::AbstractFloat; criteria::String="All")

If contact takes a Vector{PDBResidue}, It returns a matrix with all the pairwise comparisons (contact map).

Returns a matrix with the x, y, z coordinates of each atom in each PDBResidue

Returns true if the distance between atoms is less than the sum of the covalentradius of each atom.

It calculates the squared euclidean distance.

distance(residues::Vector{PDBResidue}; criteria::String="All")

If distance takes a Vector{PDBResidue} returns a PairwiseListMatrix{Float64, false} with all the pairwise comparisons (distance matrix).

Returns true if two CYS's S are at 2.08 Å or less

download_alphafold_structure(uniprot_accession::AbstractString; format::Type{T}=MMCIFFile) where T<:FileFormat

This function downloads the structure file (PDB or mmCIF) for a given UniProt Accession from AlphaFoldDB. The uniprot_accession parameter specifies the UniProt Accession of the protein, e.g. "P00520". The format parameter specifies the file format to download, with the default being mmCIF, i.e. MMCIFFile. You can set format to PDBFile if you want to download a PDB file.

downloadpdb(pdbcode::String; format::Type{T} = MMCIFFile, filename, baseurl, kargs...)

It downloads a gzipped PDB file from PDB database. It requires a four character pdbcode. Its default format is MMCIFFile (mmCIF) and It uses the baseurl "http://www.rcsb.org/pdb/files/". filename is the path/name of the output file. This function calls MIToS.Utils.download_file that calls Downloads.download. So, you can use keyword arguments, such as headers, from that function.

It downloads a JSON file containing the PDB header information.

Returns a vector of indices for CB (CA for GLY)

findatoms(res::PDBResidue, atom::String)

Returns a index vector of the atoms with the given atom name.

Returns a list with the index of the heavy atoms (all atoms except hydrogen) in the PDBResidue

Returns the Cα with best occupancy in the PDBResidue. If the PDBResidue has no Cα, missing is returned.

Access general information about a PDB entry (e.g., Header information) using the GraphQL interface of the PDB database. It parses the JSON answer into a JSON3.Object that can be used as a dictionary.

This function only works if there are hydrogens in the structure. The criteria for a hydrogen bond are:

• d(Ai, Aj) < 3.9Å
• d(Ah, Aacc) < 2.5Å
• θ(Adon, Ah, Aacc) > 90°
• θ(Adon, Aacc, Aacc-antecedent) > 90°
• θ(Ah, Aacc, Aacc-antecedent) > 90°

Where Ah is the donated hydrogen atom, Adon is the hydrogen bond donor atom, Aacc is the hydrogen bond acceptor atom and Aacc-antecednt is the atom antecedent to the hydrogen bond acceptor atom.

There's an hydrophobic interaction if two hydrophobic atoms are at 5.0 Å or less.

There's an ionic interaction if a cationic and an anionic atoms are at 6.0 Å or less.

is_aminoacid(residue::PDBResidue)
is_aminoacid(residue_id::PDBResidueIdentifier)

This function returns true if the PDB residue is an amino acid residue. It checks if the residue's three-letter name exists in the MIToS.Utils.THREE2ONE dictionary, and returns false otherwise.

Returns true if the atom, e.g. ("GLU","CD"), is an anionic atom in the residue.

Returns true if the atom, e.g. ("HIS","CG"), is an aromatic atom in the residue.

It tests if the atom has the indicated atom name.

Returns true if the atom, e.g. ("ARG","NE"), is a cationic atom in the residue.

Returns true if the atom, e.g. ("ARG","O"), is an acceptor in H bonds.

Returns true if the atom, e.g. ("ARG","N"), is a donor in H bonds.

 isresidue(res; model=All, chain=All, group=All, residue=All)

This function tests if a PDBResidue has the indicated model, chain, group and residue names/numbers. You can use the type All (default value) to avoid filtering that level.

kabsch(A::AbstractMatrix{Float64}, B::AbstractMatrix{Float64})

This function takes two sets of points, A (refrence) and B as NxD matrices, where D is the dimension and N is the number of points. Assumes that the centroids of A and B are at the origin of coordinates. You can call center! on each matrix before calling kabsch to center the matrices in the (0.0, 0.0, 0.0). Rotates B so that rmsd(A,B) is minimized. Returns the rotation matrix. You should do B * RotationMatrix to get the rotated B.

Calculates the average/mean position of each atom in a set of structure. The function takes a vector (AbstractVector) of vectors (AbstractVector{PDBResidue}) or matrices (AbstractMatrix{Float64}) as first argument. As second (optional) argument this function can take an AbstractVector{Float64} of matrix/structure weights to return a weighted mean. When a AbstractVector{PDBResidue} is used, if the keyword argument calpha is false the RMSF is calculated for all the atoms. By default only alpha carbons are used (default: calpha=true).

modelled_sequences(residue_list::AbstractArray{PDBResidue,N}; 
    model::Union{String,Type{All}}=All, chain::Union{String,Type{All}}=All, 
    group::Union{String,Regex,Type{All}}=All) where N

This function returns an OrderedDict where each key is a named tuple (containing the model and chain identifiers), and each value is the protein sequence corresponding to the modelled residues in those chains. Therefore, the obtained sequences do not contain missing residues. All modelled residues are included by default, but those that don't satisfy specified criteria based on the model, chain, or group keyword arguments are excluded. One-letter residue names are obtained from the MIToS.Utils.THREE2ONE dictionary for all residue names that return true for is_aminoacid.

There's a Π-Cation interaction if a cationic and an aromatic atoms are at 6.0 Å or less

proximitymean calculates the proximity mean/average for each residue as the average score (from a scores list) of all the residues within a certain physical distance to a given amino acid. The score of that residue is not included in the mean unless you set include to true. The default values are 6.05 for the distance threshold/limit and "Heavy" for the criteria keyword argument. This function allows to calculate pMI (proximity mutual information) and pC (proximity conservation) as in Buslje et al..

References

• Marino Buslje, Cristina, et al. "Networks of high mutual information define the structural proximity of catalytic sites: implications for catalytic residue identification." PLoS computational biology 6.11 (2010): e1000978.

query_alphafolddb(uniprot_accession::String)

This function queries the AlphaFoldDB API to retrieve structure information for a given uniprot_accession, e.g. "P00520". This function returns the structure information as a JSON3.Object. The download is performed via download_file, which already retries the request using an exponential backoff strategy.

It creates a NamedArray containing a PairwiseListMatrix where each element (column, row) is identified with a PDBResidue from the input vector. You can indicate the value type of the matrix (default to Float64), if the list should have the diagonal values (default to Val{false}) and the diagonal values (default to NaN).

The residues function for AbstractArray{PDBResidue,N} is deprecated. Use the select_residues function instead. So, residues(residue_list, model, chain, group, residue) becomes select_residues(residue_list; model=model, chain=chain, group=group, residue=residue).

 residuesdict(residue_list; model=All, chain=All, group=All, residue=All)

This function returns a dictionary (using PDB residue numbers as keys) with the selected subset of residues. The residues are selected using the keyword arguments model, chain, group and residue. You can use the type All (default value) to avoid filtering at a particular level.

rmsd(A::AbstractMatrix{Float64}, B::AbstractMatrix{Float64})

Return RMSD between two sets of points A and B, given as NxD matrices (N: number of points, D: dimension).

rmsd(A::AbstractVector{PDBResidue}, B::AbstractVector{PDBResidue}; superimposed::Bool=false)

Returns the Cα RMSD value between two PDB structures: A and B. If the structures are already superimposed between them, use superimposed=true to avoid a new superimposition (superimposed is false by default).

Calculates the RMSF (Root Mean-Square-Fluctuation) between an atom and its average position in a set of structures. The function takes a vector (AbstractVector) of vectors (AbstractVector{PDBResidue}) or matrices (AbstractMatrix{Float64}) as first argument. As second (optional) argument this function can take an AbstractVector{Float64} of matrix/structure weights to return the root weighted mean-square-fluctuation around the weighted mean structure. When a Vector{PDBResidue} is used, if the keyword argument calpha is false the RMSF is calculated for all the atoms. By default only alpha carbons are used (default: calpha=true).

select_atoms(residue_list; model=All, chain=All, group=All, residue=All, atom=All, alt_id=All, charge=All)

This function returns a vector of PDBAtoms with the selected subset of atoms from a list of residues. The atoms are selected using the keyword arguments model, chain, group, residue, atom, alt_id, and charge. You can use the type All (default value) to avoid filtering at a particular level.

select_residues(residue_list; model=All, chain=All, group=All, residue=All)

This function returns a new vector with the selected subset of residues from a list of residues. You can use the keyword arguments model, chain, group and residue to select the residues. You can use the type All (default value) to avoid filtering at a particular level.

Takes a PDBResidue and a Vector of atom indices. Returns the index value of the Vector with maximum occupancy.

It calculates the squared euclidean distance, i.e. it doesn't spend time in sqrt

squared_distance(A::PDBResidue, B::PDBResidue; criteria::String="All")

Returns the squared distance between the residues A and B. The available criteria are: Heavy, All, CA, CB (CA for GLY)

Asuper, Bsuper, RMSD = superimpose(A, B, matches=nothing)

This function takes A::AbstractVector{PDBResidue} (reference) and B::AbstractVector{PDBResidue}. Translates A and B to the origin of coordinates, and rotates B so that rmsd(A,B) is minimized with the Kabsch algorithm (using only their α carbons). Returns the rotated and translated versions of A and B, and the RMSD value.

Optionally provide matches which iterates over matched index pairs in A and B, e.g., matches = [(3, 5), (4, 6), ...]. The alignment will be constructed using just the matching residues.

Test if two atoms or residues are in van der Waals contact using: distance(a,b) <= 0.5 + vanderwaalsradius[a] + vanderwaalsradius[b]. It returns distance <= 0.5 if the atoms aren't in vanderwaalsradius.

Returns true if the distance between the atoms is less than the sum of the vanderwaalsradius of the atoms. If the atoms aren't on the list (i.e. OXT), the vanderwaalsradius of the element is used. If there is not data in the dict, distance 0.0 is used.

parse_file(pdbml, ::Type{PDBML}; chain=All, model=All, group=All, atomname=All, onlyheavy=false, label=true, occupancyfilter=false)

Reads a LightXML.XMLDocument representing a pdb file. Returns a list of PDBResidues (view MIToS.PDB.PDBResidues). Setting chain, model, group, atomname and onlyheavy values can be used to select of a subset of all residues. If not set, all residues are returned. If the keyword argument label (default: true) is false,the auth_ attributes will be use instead of the label_ attributes for chain, atom and residue name fields. The auth_ attributes are alternatives provided by an author in order to match the identification/values used in the publication that describes the structure. If the keyword argument occupancyfilter (default: false) is true, only the atoms with the best occupancy are returned.

parse_file(io, ::Type{MMCIFFile}; chain=All, model=All, group=All, atomname=All, onlyheavy=false, label=true, occupancyfilter=false)

Parse an mmCIF file and returns a list of PDBResidues. Setting chain, model, group, atomname and onlyheavy values can be used to select a subset of residues. Group can be "ATOM" or "HETATM". If those keyword arguments are not set, all residues are returned. If the keyword argument label (default: true) is false, the auth_ attributes will be used instead of the label_ attributes for chain, atom, and residue name fields. The auth_ attributes are alternatives provided by an author in order to match the identification/values used in the publication that describes the structure. If the keyword argument occupancyfilter (default: false) is true, only the atoms with the best occupancy are returned.

parse_file(io, ::Type{PDBFile}; chain=All, model=All, group=All, atomname=All, onlyheavy=false, occupancyfilter=false)

Reads a text file of a PDB entry. Returns a list of PDBResidue (view MIToS.PDB.PDBResidues). Setting chain, model, group, atomname and onlyheavy values can be used to select of a subset of all residues. Group can be "ATOM" or "HETATM". If not set, all residues are returned. If the keyword argument occupancyfilter (default: false) is true, only the atoms with the best occupancy are returned.

print_file(io, res, format::Type{PDBFile}) print_file(res, format::Type{PDBFile})

Print a PDBResidue or a vector of PDBResidues in PDB format.