Ligand Modeler
==============

Create Ligand Modeler project
-----------------------------

Let’s walk through how to create a Ligand Reader & Modeler project. You will need at least one ligand SDF file. If you plan to use a PDB Reader project, make sure that the corresponding PDB Reader project contains a ligand. In the example below, we’ll use only an SDF file.

If you are creating the project based on a PDB Reader project, you will need to provide the following options:

* pdbreader_project_id (str): The project ID of a PDB Reader project that contains at least one ligand.
* native_ligand (str): The name of the native ligand from the specified PDB Reader project.
* Optional Advanced Options when using `pdbreader_project_id`:
    - complete_ring_chain (bool): Match only when the atoms inside each ring are exactly the same — requires an identical ring subgraph (atoms and bonds). `default: False`
    - strict_match (bool): For pre-aligned molecules, tightly enforce coordinate agreement by snapping positions within a small tolerance for a stricter fit. `default: True`
    - handle_chirality (bool): Preserve stereochemistry during alignment by considering chirality centers and geometric isomers. `default: True`

Note: You can check the available `native_ligand` values by using the `get_native_ligands(pdbreader_project_id)` method.

::

   lrmbuilder = molcube.create_ligand_modeler_project()

   # alt: pdbreader_project_id = pdbreader.projectId
   pdbreader_project_id = '78080ec8-bfcd-4141-8f22-f0ae805374ff'

   ligands_data = lrmbuilder.get_native_ligands(pdbreader_project_id)
   # Native ligand found - Chain: HETE_C, Residue Name: 53U, Residue Index: 2001

   lrmbuilder.create_project(
       title="test_LRM",
       ff="amberff",
       sdf_paths=["./1a.sdf", "1b.sdf"],
       pdbreader_project_id=pdbreader_project_id,
       native_ligand={
           "chainIndex": "HETE_C",
           "residueIndex": 2001
       },
   )

Modify SDF file (optional)
--------------------------

You can optionally modify the dihedral angle in the ligand SDF file. This step can be skipped.

To do this, first use the ``check_atom_index()`` method along with interactive clicking to identify the indices of the atoms involved.
The ``check_atom_index()`` method requires the name of the SDF file as input, which you can find via ``lrmbuilder.files_data``.

Once the desired atom indices are known, use the ``change_dihedral()`` method to obtain a dictionary containing the modified ligand data needed for the next step.
You should create a ``list`` and ``append`` each output from ``change_dihedral()`` to this list for use in the following step.

``check_atom_index()`` options:

* file_name (str): The name of the target SDF file where the dihedral will be changed.
* visual_protein (bool): Whether to visualize the protein together with the ligand (default: False).

``change_dihedral()`` options:

* file_name (str): The name of the target SDF file.
* atom_index_1 (int): The first atom defining the rotation axis. The rotation axis is directed from atom_index_1 to atom_index_2.
* atom_index_2 (int): The second atom defining the rotation axis. The part of the molecule connected to this atom (excluding the bond to atom_index_1) will be rotated.
* angle (int): The rotation angle in degrees (between 0 and 360).
* visual_protein (bool): Whether to visualize the protein together with the ligand (default: False).

Note: The direction from ``atom_index_1`` to ``atom_index_2`` determines which fragment of the molecule will rotate. The atoms connected to ``atom_index_2``, excluding the path back to ``atom_index_1``, will be rotated around the axis defined by the bond.

   >>> lrmbuilder.check_atom_index('1a.sdf')
   [return value is a nglview; click an atom to show its index]

   >>> modified_ligand = lrmbuilder.change_dihedral('1a.sdf', 30, 8, 180)
   [another nglview object showing the new conformation]

Finally, use the ``gen_ligand_ff()`` method to generate ligand force fields.
The following arguments are available for this method:

* ligand_ff (list[LigandForceField]): A list of ligand force fields to be generated.
* modified_ligands (list, optional): A list of modified ligand outputs from the ``change_dihedral()`` method. Default is an empty list ([]).

::

   from molcube.ligand_modeler.enum import *

   ligand_ff = [LigandForceField.OPENFF_FAST]
   lrmbuilder.gen_ligand_ff(ligand_ff)