SILCS-Kinetics
--------------

Background
^^^^^^^^^^


SILCS-Kinetics is a computational workflow designed to efficiently predict ligand
dissociation kinetics, specifically the off rate (koff), which is often more
relevant to drug efficacy than binding affinity alone. Traditional approaches rely
on enhanced-sampling molecular dynamics (MD) simulations, which are computationally
intensive and less practical for evaluating large ligand libraries in drug design.

To address this, SILCS-Kinetics combines physics-based and machine learning (ML)
methodologies. The workflow uses the Site Identification by Ligand Competitive
Saturation (SILCS) method to enumerate potential ligand dissociation pathways and
calculate free-energy profiles along those pathways. These profiles, together with
molecular properties, serve as features for training ML models—including tree-based
and neural network approaches—to predict koff values.

The protocol has been developed and validated on a diverse set of 329 ligands
across 13 proteins, demonstrating the robustness and efficiency of the ML workflow
built upon SILCS-derived free-energy profiles. SILCS-Kinetics provides a powerful
and scalable tool for drug design, enabling rapid quantitative estimates of ligand
dissociation kinetics and atomic or functional group contributions to unbinding
events. Additional details on the development and validation of SILCS-Kinetics can
be found in the original publication :cite:`Yu:2025-2`.

.. thumbnail:: images/kinetics_overview.png
   :width: 100%


SILCS-Kinetics Using the SilcsBio CLI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. **Cluster Generation and SILCS-MC Slab Preparation**

	This step prepares and runs the cluster-generation phase of the SILCS-Kinetics workflow for a given protein structure. It identifies ligand trajectory clusters using a specified cutoff, then creates and organizes SILCS-MC input files for every cluster–ligand pair.

	*Usage*
	::

		${SILCSBIODIR}/silcs-kinetics/1_gen_silcsmc_slab prot=<protein PDB file>

	*Required parameters*

	- ``prot``: Path to the protein PDB file.

	*Optional parameters*

	- ``outputdir``: Output directory for results (default: 5_kinetics).
	- ``pathwaydir``: Path to the silcs-pathway output directory (default: 4_pathway).
	- ``paramsfile``: Path to SILCS-MC parameters template file.
	- ``cutoff``: Minimum number of members in a cluster to be included in kinetics runs (minimum: 2) (default: 2).

	*Output*

	- SILCS-MC input files for each cluster–ligand pair in pathclusters/.
	- Log files and cluster information.

	*Notes*

	- The script checks for valid input files and parameters.
	- Clusters with fewer members than the cutoff are excluded.

2. **SILCS-MC Job Submission**

	This step submits SILCS-MC simulations for all cluster–ligand pairs identified in the previous step.

	*Usage*

	::

		${SILCSBIODIR}/silcs-kinetics/2_submit_jobs prot=<protein PDB file> ligdir=<ligand directory>

	*Required parameters*

	- ``prot``: Path to the protein PDB file.
	- ``ligdir``: Directory containing ligand mol2/sdf files.

	*Optional parameters*

	- ``outputdir``: Output directory for results (default: 5_kinetics).
	- ``sdfile``: SD file to overwrite ligdir.

	*Output*

	- SILCS-MC simulation outputs for each cluster–ligand pair.
	- Log files and job status information.

	*Notes*

	- The script checks for valid input files and parameters.
	- Output directory must be prepared by step 1.

3. **Energy Extraction and Barrier Calculation**

	This step processes the output from SILCS-MC simulations to extract energy terms and calculate barriers for each ligand–protein cluster. It also prepares data files for machine learning predictions.

	*Usage*

	::

		${SILCSBIODIR}/silcs-kinetics/3_extract_energy prot=<protein PDB file>

	*Required parameters*

	- ``prot``: Path to the protein PDB file.

	*Optional parameters*

	- ``outputdir``: Output directory for results (default: 5_kinetics).

	*Output*

	- Extracted energy terms and barrier calculations for each cluster–ligand pair.
	- Data files for ML predictions.

	*Notes*

	- The script checks for valid input files and parameters.
	- Output directory must contain successful SILCS-MC results.
	- Adds script extract_pathway_lgfe.py to outputdir which given a pc# will extract the ligand grid free energy (LGFE) along the pathway for that cluster.
	
	*Usage*

		::

			python extract_pathway_lgfe.py --pc N [--ligand ligand1 ligand2 ...] [--save_plot true/false] [--show_plot true/false]

	*Example*
	
	.. thumbnail:: images/kinetics_free_energy_plot.png
		:width: 100%


4. **Machine Learning Inference**

	This step performs the final ML inference, extracting features from SILCS-MC outputs and applying trained models to predict –log(koff) values for each ligand–protein cluster pair.

	*Usage*

	::

		${SILCSBIODIR}/silcs-kinetics/4_ml_inference prot=<protein PDB file>

	*Required parameters*

	- ``prot``: Path to the protein PDB file.

	*Optional parameters*

	- ``outputdir``: Output directory for results (default: 5_kinetics).
	- ``ml_model``: ML model type to use for inference (RF, RNN, or both; default: RF).
	- ``python``: Path to Python executable.

	*Output*

	- Predicted –log(koff) values for each ligand–protein cluster pair.
	- ML inference log files and results.

	*Notes*

	- The script checks for valid input files, parameters, and model type.
	- Output directory must contain successful energy extraction results.