Package: loco-hd
Welcome toLoCoHD!LoCoHD(Local Composition Hellinger Distance) is a metric for comparing protein structures. It can be used for one single structure-structure comparison, for the comparison of multiple structures inside ensembles, or for the comparison of structures inside an MD simulation trajectory. It is also a general-purpose metric for labelled point clouds with variable point counts. In contrast toRMSD,
theTM-score,lDDT,
orGDT_TS,
it is based on the measurement of local composition differences, rather than of the Euclidean deviations.Where can I read about it?This work is yet to be published in a scientific journal.Demo scriptsIf you are interested in how to run the Python scripts that are used for the creation of the article, see
thePY_SCRIPTS.mdfile.System requirementsSoftware dependenciesLoCoHD is a Python3 package, so it most definitely requires Python3.
Additionally, it also needs BioPython and Numpy. It was tested withPython version 3.10.10,BioPython version 1.81,Numpy version 1.21.6.Its build-dependencies are Rust (tested withrustcversion 1.70.70) and
Maturin (tested with version 0.14.15).Some of the scripts inpython_codesuse other packages too:Matplotlib version 3.7.1SciPy version 1.10.0MDAnalysis version 2.4.2scikit-learn version 1.2.1The full package and scripts were tested on Linux (Pop!_OS 22.04 LTS).
Installation was tested on Pop!_OS and OpenSUSE Leap 15.3.Hardware requirementsNo special hardware is needed to run LoCoHD. It was written and tested on a
laptop with the following specs:Model = Dell Latitude 5490RAM = 16 GbProcessor = Intel Core i5-8250U CPU @ 1.60GHz x 8Since it doesn't need much RAM and CPU power to run, theoretically it can be also
ran on less capable machines.How can I install it?Using dockerA Dockerfile is provided to install LoCoHD in a containerized manner.
Make sure that you havedockerinstalled on your system.
Clone the GitHub repository and enter it:gitclonehttps://github.com/fazekaszs/loco_hd&&cdloco_hdNext, build the image:dockerbuild-tloco_hd:latest.Using this way, you can either use the LoCoHD CLI from this image...:dockerrun--rmloco_hd:latest[LoCoHDarguments]...or run custom scripts:dockerrun--rm-v[ptscr]:/script-v[ptstr]:/structures--entrypointpythonloco_hd:latest[ptscr]where[ptscr]is the local path to the script to run (can be$(pwd)for example),
and[ptstr]is the path to the structures to be compared (probably used by the script).Note:This docker image only contains LoCoHD, BioPython, NumPy and the standard Python
library installed. Your scripts won't be able to utilize other libraries in it, like SciPy, ScikitLearn or
Matplotlib. If you want to use these, modify the Dockerfile accordingly.Install the Rust compilerIf you install LoCoHD from source or using pip, you definitely need to installRustto your system.
To do this you can choose from several methods. Either you install Rust using the
"standard" way with the official script:curl--proto'=https'--tlsv1.2-sSfhttps://sh.rustup.rs|shwhich installs Rust globally, or if you are using an environment manager, likeAnaconda,Miniconda,
orMambaforge,
you can simply install Rust withcondainstall-cconda-forgerustIf you are a Windows user,
visitthislink.The overall installation time does not exceed a few minutes.Note:Maturin is a build-dependency of LoCoHD, and it won't run outside
a virtual environment!From PyPIWith pip, it is easy to add LoCoHD to your packages:pipinstallloco-hdBuilding from sourceBesides Rust, you will also need Python3, pip, and the packageMaturinif you choose
building from source. Maturin can be installed with the following one-liner:pipinstallmaturinorcondainstall-cconda-forgematurinNext, clone the repository and enter it:gitclonehttps://github.com/fazekaszs/loco_hd&&cdloco_hdRun Maturin to install LoCoHD into your active environment:maturindevelopAnd you are done!Running the Rust unit testsUnit tests can be run with Cargo. Since this is a PyO3 project, an additional--no-default-featuresflag is needed:cargotest--no-default-featuresHow can I use it in the CLI?Although this ishighly experimentalyet and was not thoroughly tested, it is possible to use LoCoHD from the CLI.
Generally, you run it like this:python-mloco_hd[LoCoHDarguments]or using the containerized version:dockerrun[Dockerarguments]loco_hd:latest[LoCoHDarguments]The required LoCoHD arguments are the following (for more information,
use the--helpflag.):-s1specifies the path to the first structure (pdb) file-s2specifies the path to the second structure (pdb) file-ptsspecifies the path to the primitive typing scheme (json) file-afpspecifies the path to an anchor pairing fileThe latter flag must point to a file having the following properties:it should be a simple text file, not a binaryit can contain newline characters, since these will be stripped from the file (but spaces won't!)it must contain primitive atompairdefining parts, separated by semicolonsa primitive atom pair defining part must contain exactly two primitive atom defining part,
separated by a single colona primitive atom defining part contains a chain ID (e.g.:A), a residue ID (e.g.:123-GLY), and
an atom set (e.g.:CA,CB,CG,withoutspaces!) separated by forward-slashesThe latter one is necessary, since primitive atoms can come from multiple true atoms (like centroids
and coarse grained atoms). Here is an example file:/2-GLU/OE1,OE2:B/73-CYS/SG;
 /6-ARG/CZ:B/82-ILE/CB,CG1,CG2,CD1;
 /6-ARG/CZ:B/105-ARG/CZ;
 /21-ARG/CZ:B/105-ARG/CZThis file specifies that a primitive atom coming from chain" "(note the space!), residue Glu2,
atom set{OE1, OE2}should be paired up with a primitive atom coming from chain"B", residue Cys73,
atom set{SG}.
The environments around these anchors will be compared (along with 3 other pairings) using LoCoHD.How can I use it in my scripts?LoCoHD was originally intended to be used within Python scripts (and this is still
the preferred way), mostly throughBioPythonas the main.pdbfile reader.
It is also possible to use it with other protein/molecular structure readers,
but the user has to write the appropriate parser that converts the information
within the file into the information required for LoCoHD.
An example for this can be foundhere, where the structures come from
a molecular dynamics trajectory and parsing is achieved byMDAnalysis.For the comparison of two protein structures with LoCoHD the following simple steps are necessary:1. Loading the structures from pdb filesThe imports defined here are necessary for the following code sections.frompathlibimportPathfromBio.PDB.PDBParserimportPDBParserfromloco_hdimport*structure1=PDBParser(QUIET=True).get_structure("s1","path/to/structure1.pdb")structure2=PDBParser(QUIET=True).get_structure("s2","path/to/structure2.pdb")2. Selecting the primitive typing schemeIn this section, the true protein structures (with "true" atoms) are converted into primitive template structures (lists containingPrimitiveAtomTemplateinstances). These serve as intermediate instances between theAtomclass (from BioPython) and thePrimitiveAtomclass (from loco-hd).primitive_assigner=PrimitiveAssigner(Path("path/to/primitive/typing/scheme.json"))pra_templates1=primitive_assigner.assign_primitive_structure(structure1)pra_templates2=primitive_assigner.assign_primitive_structure(structure2)3. Selecting the anchor atomsHere, it is assumed that the two structures contain the same number of anchor atoms and are paired in the same order. This is not necessary, since the anchor atom selection and pairing is easily customizable by just selecting the primitive atom index pairs.
In these examples it is only assumed to simplify things.In the case, where all atoms are anchor atoms we can use:anchor_pairs=[(idx,idx)foridxinrange(len(pra_templates1))]Or if only primitive atoms with the"Cent"primitive type are anchors:anchor_pairs=[(idx,idx)foridx,pratinenumerate(pra_templates1)ifprat.primitive_type=="Cent"]The only important thing is that the indices inside the tuples must be valid within the first and second primitive atom (template) lists.
An example for a more complicated pairing is given here, where we only considerPrimitiveAtompairs,
where one has a primitive type of"O_neg"and the other has a primitive type of"C_aro":anchor_pairs=[(idx_a,idx_b)foridx_a,prat_ainenumerate(pra_templates1)ifprat_a.primitive_type=="O_neg"foridx_b,prat_binenumerate(pra_templates2)ifprat_b.primitive_type=="C_aro"]4. Conversion ofPrimitiveAtomTemplateinstances toPrimitiveAtominstancesThe intermediate templates are only necessary, so we can have an opportunity to set thetagfield of ourPrimitiveAtoms. This field is used for the conditional setting of the "environment" of each anchor atom. For example, this can be used to ban homo-residue contacts, i.e. to ban a primitive atom from the environment of an anchor atomifthe primitive atom comes from the same residue as the anchor. For further explanation see section #5.To do the conversion in a clean and effective manner we can define the following function:defprat_to_pra(prat:PrimitiveAtomTemplate)->PrimitiveAtom:resi_id=prat.atom_source.source_residueresname=prat.atom_source.source_residue_namesource=f"{resi_id[2]}/{resi_id[3][1]}-{resname}"returnPrimitiveAtom(prat.primitive_type,source,# this is the tag field!prat.coordinates)After this, a simplemapwill do:pra1=list(map(prat_to_pra,pra_templates1))pra2=list(map(prat_to_pra,pra_templates2))5. Creating theLoCoHDinstanceThis will create a simple LoCoHD instance that operates with a uniform weight function between 3 and 10 angströms and doesn't consider thetagfield of the primitive atoms (i.e. it accepts any anchor atom - primitive atom contacts):lchd=LoCoHD(primitive_assigner.all_primitive_types)To explicitly state the weight function use:w_func=WeightFunction("uniform",[3.,10.])lchd=LoCoHD(primitive_assigner.all_primitive_types,w_func)There is a collection of weight functions available.Or to explicitly state the tag-pairing rule:w_func=WeightFunction("uniform",[3.,10.])tag_pairing_rule=TagPairingRule({"accept_same":False})lchd=LoCoHD(primitive_assigner.all_primitive_types,w_func,tag_pairing_rule)The latter code creates aLoCoHDinstance that considers thetagfield and disregards primitive atoms in the environment that have the same tag as the anchor atom.Other tag pairing rules are also available.Finally, the number of parallel threads LoCoHD can use can also be set as a last argument:lchd=LoCoHD(primitive_assigner.all_primitive_types,w_func,tag_pairing_rule,4)6. Calculation of the LoCoHD scoresThe LoCoHD class offers several methods for LoCoHD score calculation. These are the:from_anchorsmethod, calculating asingleLoCoHD score from two anchor atom environments,from_dmxsmethod, calculatingseveralLoCoHD scores, each belonging to corresponding row-pairs of primitive atom distance-matrices,from_coordsmethod, calculatingseveralLoCoHD scores from the coordinates of primitive atoms (it uses thefrom_dmxsmethod under the hood),from_primitivesmethod, calculatingseveralLoCoHD scores from a list ofPrimitiveAtominstances.Most of the time thefrom_primitivesmethod should be used. This is the only method that usesPrimitiveAtominstances, takes tag pairing rules into account, and speeds up calculations through the use of an upper distance cutoff for the environments.lchd_scores=lchd.from_primitives(pra1,pra2,anchor_pairs,10.# upper distance cutoff at 10 angströms)This gives a list of LoCoHD scores (floats), each describing the environmental difference/distance/dissimilarity between two anchor atom environments. This is a score between 0 and 1, with larger values meaning greater dissimilarity.