diff --git a/modules/mol/alg/doc/molalg.rst b/modules/mol/alg/doc/molalg.rst index 842c5a8d8334aa99c997ccb66658018bdcc63b4b..1816100c024249600998e0aae690dc8d9e25e072 100644 --- a/modules/mol/alg/doc/molalg.rst +++ b/modules/mol/alg/doc/molalg.rst @@ -1249,3 +1249,178 @@ to standard amino acids. whether the Cbeta atom was inserted into the ``dst_res``. +Molecular Checker (Molck) +-------------------------------------------------------------------------------- + +Programmatic usage +################## + +Molecular Checker (Molck) could be called directly from the code using Molck +function: + +.. code-block:: python + + #! /bin/env python + + """Run Molck with Python API. + + + This is an exemplary procedure on how to run Molck using Python API which is + equivalent to the command line: + + molck <PDB PATH> --rm=hyd,oxt,nonstd,unk \ + --fix-ele --out=<OUTPUT PATH> \ + --complib=<PATH TO compounds.chemlib> + """ + + from ost.io import LoadPDB, SavePDB + from ost.mol.alg import MolckSettings, Molck + + from ost.conop import CompoundLib + + + pdbid = "<PDB PATH>" + lib = CompoundLib.Load("<PATH TO compounds.chemlib>") + + # Using Molck function + ent = LoadPDB(pdbid) + ms = MolckSettings(rm_unk_atoms=True, + rm_non_std=True, + rm_hyd_atoms=True, + rm_oxt_atoms=True, + rm_zero_occ_atoms=False, + colored=False, + map_nonstd_res=False, + assign_elem=True) + Molck(ent, lib, ms) + SavePDB(ent, "<OUTPUT PATH>", profile="SLOPPY") + +It can also be split into subsequent commands for greater controll: + +.. code-block:: python + + #! /bin/env python + + """Run Molck with Python API. + + + This is an exemplary procedure on how to run Molck using Python API which is + equivalent to the command line: + + molck <PDB PATH> --rm=hyd,oxt,nonstd,unk \ + --fix-ele --out=<OUTPUT PATH> \ + --complib=<PATH TO compounds.chemlib> + """ + + from ost.io import LoadPDB, SavePDB + from ost.mol.alg import (RemoveAtoms, MapNonStandardResidues, + CleanUpElementColumn) + from ost.conop import CompoundLib + + + pdbid = "<PDB PATH>" + lib = CompoundLib.Load("<PATH TO compounds.chemlib>") + map_nonstd = False + + # Using function chain + ent = LoadPDB(pdbid) + if map_nonstd: + MapNonStandardResidues(lib=lib, ent=ent) + + RemoveAtoms(lib=lib, + ent=ent, + rm_unk_atoms=True, + rm_non_std=True, + rm_hyd_atoms=True, + rm_oxt_atoms=True, + rm_zero_occ_atoms=False, + colored=False) + + CleanUpElementColumn(lib=lib, ent=ent) + SavePDB(ent, "<OUTPUT PATH>", profile="SLOPPY") + +API +### + + +.. class:: MolckSettings + + Stores settings used for Molecular Checker. + + .. method:: __init__(rm_unk_atoms=False,rm_non_std=False,rm_hyd_atoms=True,rm_oxt_atoms=False, rm_zero_occ_atoms=False,colored=False,map_nonstd_res=True, assign_elem=True) + + Initializes MolckSettings. + + :param rm_unk_atoms: Remove unknown and atoms not following the nomenclature + :type rm_unk_atoms: :class:`bool` + :param rm_non_std: Remove all residues not one of the 20 standard amino acids + :type rm_non_std: :class:`bool` + :param rm_hyd_atoms: Remove hydrogen atoms + :type rm_hyd_atoms: :class:`bool` + :param rm_oxt_atoms: Remove terminal oxygens + :type rm_oxt_atoms: :class:`bool` + :param rm_zero_occ_atoms: Remove atoms with zero occupancy + :type rm_zero_occ_atoms: :class:`bool` + :param colored: Whether output should be colored + :type colored: :class:`bool` + :param map_nonstd_res: Maps modified residues back to the parent amino acid, for example + MSE -> MET, SEP -> SER + :type map_nonstd_res: :class:`bool` + :param assign_elem: Clean up element column + :type assign_elem: :class:`bool` + + .. method:: ToString() + + String representation of the MolckSettings. + + +.. function:: Molck(ent, lib, settings) + + Runs Molck on provided entity. + + :param ent: Structure to check + :type ent: :class:`~ost.mol.EntityHandle` + :param lib: Compound library + :type lib: :class:`~ost.conop.CompoundLib` + :param settings: Molck settings + :type settings: :class:`MolckSettings` + + +.. function:: MapNonStandardResidues(ent, lib) + + Maps modified residues back to the parent amino acid, for example MSE -> MET. + + :param ent: Structure to check + :type ent: :class:`~ost.mol.EntityHandle` + :param lib: Compound library + :type lib: :class:`~ost.conop.CompoundLib` + +.. function:: RemoveAtoms(ent,lib,rm_unk_atoms=False,rm_non_std=False,rm_hyd_atoms=True,rm_oxt_atoms=False,rm_zero_occ_atoms=False,colored=False) + + Removes atoms and residues according to some criteria. + + :param ent: Structure to check + :type ent: :class:`~ost.mol.EntityHandle` + :param lib: Compound library + :type lib: :class:`~ost.conop.CompoundLib` + :param rm_unk_atoms: Remove unknown and atoms not following the nomenclature + :type rm_unk_atoms: :class:`bool` + :param rm_non_std: Remove all residues not one of the 20 standard amino acids + :type rm_non_std: :class:`bool` + :param rm_hyd_atoms: Remove hydrogen atoms + :type rm_hyd_atoms: :class:`bool` + :param rm_oxt_atoms: Remove terminal oxygens + :type rm_oxt_atoms: :class:`bool` + :param rm_zero_occ_atoms: Remove atoms with zero occupancy + :type rm_zero_occ_atoms: :class:`bool` + :param colored: Whether output should be colored + :type colored: :class:`bool` + +.. function:: CleanUpElementColumn(ent, lib) + + Clean up element column. + + :param ent: Structure to check + :type ent: :class:`~ost.mol.EntityHandle` + :param lib: Compound library + :type lib: :class:`~ost.conop.CompoundLib` \ No newline at end of file diff --git a/modules/mol/alg/doc/molck.rst b/modules/mol/alg/doc/molck.rst new file mode 100644 index 0000000000000000000000000000000000000000..8dd1d1f39ed9ae3ebb1c8bba5126701c58f85476 --- /dev/null +++ b/modules/mol/alg/doc/molck.rst @@ -0,0 +1,59 @@ +========================= +Molecular Checker (Molck) +========================= + +-------------------------------------- +Where can I find the Molck executable? +-------------------------------------- + +The Molck executable can be found at <YOUR-OST-STAGE-DIR>/bin + +----------- +Basic Usage +----------- + +To check one PDB file (struc1.pdb) with Molck, use the following command: + +.. code-block:: bash + + molck --complib <PATH TO COMPOUND LIB> struc1.pdb + +The checked and cleaned file will be saved by default ad struc1-molck.pdb. + +Similarly it is possible to check a list of PDB files: + +.. code-block:: bash + + molck --complib <PATH TO COMPOUND LIB> struc1.pdb struc2.pdb struc3.pdb + + +----------- +All Options +----------- + +The molck executable supports several other command line options, +please find them following: + +.. code-block:: bash + + usage: molck [options] file1.pdb [file2.pdb [...]] + options + --complib=path location of the compound library file. If not provided, the + following locations are searched in this order: + 1. Working directory, + 2. OpenStructure standard library location (if the + executable is part of a standard OpenStructure installation) + --rm=<a>,<b> remove atoms and residues matching some criteria: + - zeroocc - Remove atoms with zero occupancy + - hyd - Remove hydrogen atoms + - oxt - Remove terminal oxygens + - nonstd - Remove all residues not one of the 20 standard amino acids + - unk - Remove unknown and atoms not following the nomenclature + --fix-ele clean up element column + --stdout write cleaned file(s) to stdout + --out=filename write cleaned file(s) to disk. % characters in the filename are + replaced with the basename of the input file without extension. + Default: %-molcked.pdb + --color=auto|on|off whether output should be colored + --map-nonstd maps modified residues back to the parent amino acid, for example + MSE -> MET, SEP -> SER. \ No newline at end of file