CLI Reference

Command-line interface documentation

rescore integrate

Run the complete rescoring pipeline for a single receptor-ligand pair in one command.

Usage

rescore integrate [OPTIONS]

Required Arguments

Optional Arguments

Example

# Default (GB with minimization)
rescore integrate \
  --receptor protein.pdb \
  --ligand ligand.mol2 \
  -o output/

# With uncertainty quantification (RPS)
rescore integrate \
  --receptor protein.pdb \
  --ligand ligand.mol2 \
  -o output/ \
  --rps-replicates 20

# PB method without minimization
rescore integrate \
  --receptor protein.pdb \
  --ligand ligand.mol2 \
  -o output/ \
  --method pb \
  --no-minimize

Workflow Steps

1. Protein preparation: pdb4amber normalization + tleap parameterization (ff14SB)
2. Ligand parameterization: antechamber with GAFF2 and AM1-BCC charges
3. Complex assembly: tleap combines protein and ligand
4. Validation: Structure checks (optional)
5. Minimization: Restrained minimization with GB (optional, default ON)
6. MM/GBSA calculation: Single-frame energy computation

Output Structure

output/
├── protein/         # Receptor topology files
├── ligand/          # Ligand force field files
├── complex/         # Combined topology
├── rescore/         # Energy results
│   ├── minimization/
│   │   └── minimized_complex.pdb
│   ├── rescore_output.dat
│   └── rescore.log
└── rps_analysis/    # RPS results (if --rps-replicates used)
    ├── replicate_001/
    ├── replicate_002/
    ├── ligand_rps_replicates.csv
    ├── ligand_rps_summary.csv
    └── ligand_rps_distribution.png

Rapid Perturbation Sampling (RPS)

RPS is an optional diagnostic feature available only in rescore integrate mode. It quantifies numerical sensitivity of single-frame MM/GBSA scores to small coordinate perturbations.

What RPS Does

• Generates N perturbed copies of the ligand by adding Gaussian noise (default σ = 0.2 Å)
• Runs the complete workflow (coordinate perturbation → assembly → minimization → scoring) for each perturbation
• Computes statistics: mean score, standard deviation, 95% confidence interval, coefficient of variation
• Classifies stability heuristically: HIGH (<5% CV), MODERATE (5-15% CV), LOW (>15% CV)
• Outputs CSV files with per-replicate and summary statistics
• Generates violin + boxplot visualization

What RPS Is NOT

Perturbation Protocol

• Coordinates only: Only ligand x/y/z coordinates are perturbed (protein remains fixed)
• Chemistry frozen: Charges, atom types, and frcmod parameters copied from main workflow
• Perturbations: x_new = x_original + Normal(0, σ) applied independently to x, y, z
• Each atom gets independent random perturbation
• Bonding, atom types, and connectivity are preserved
• Deterministic seeds ensure reproducibility (same ligand + replicate → identical perturbation)
• No re-parameterization: antechamber is NOT invoked per replicate

Usage Example

# Run with 20 perturbation replicates
rescore integrate \
  --receptor protein.pdb \
  --ligand ligand.mol2 \
  -o output/ \
  --rps-replicates 20

# Custom perturbation magnitude
rescore integrate \
  --receptor protein.pdb \
  --ligand ligand.mol2 \
  -o output/ \
  --rps-replicates 20 \
  --rps-sigma 0.3

RPS Outputs

Interpretation Guidelines

• Low CV (<5%): Score is stable, robust to coordinate uncertainty
• Moderate CV (5-15%): Score has moderate sensitivity to perturbations
• High CV (>15%): Score is sensitive to atomic details, interpret with caution

Note: RPS is disabled for rescore batch. If you attempt to use RPS in batch mode, an error will be raised. RPS is designed for ligand-specific diagnostic analysis only.

rescore batch

Rescore multiple ligands against a single receptor. The receptor is prepared once and reused for all ligands, making this efficient for high-throughput screening.

Usage

rescore batch [OPTIONS]

Required Arguments

Optional Arguments

Example

# Batch rescoring with directory of ligands
rescore batch \
  --receptor protein.pdb \
  --ligands ligands_directory/ \
  -o batch_results/

# With score comparison plot
rescore batch \
  --receptor protein.pdb \
  --ligands ligands_directory/ \
  -o batch_results/ \
  --plot

# Single method change for all ligands
rescore batch \
  --receptor protein.pdb \
  --ligands ligands_directory/ \
  -o batch_results/ \
  --method pb

Input Directory Structure

The --ligands directory should contain MOL2 files:

ligands_directory/
├── compound_1.mol2
├── compound_2.mol2
├── compound_3.mol2
└── ...

Output Structure

batch_results/
├── receptor/                # Prepared once, reused
├── ligands/
│   ├── compound_1/
│   │   ├── ligand/
│   │   ├── complex/
│   │   └── rescore/
│   │       ├── minimization/
│   │       └── rescore_output.dat
│   ├── compound_2/
│   └── ...
└── rescore_batch_results.csv    # Summary table

CSV Output

Results are summarized in rescore_batch_results.csv:

ligand_name,delta_g_bind,delta_h,delta_g_gb,status
compound_1,-26.65,-65.65,39.00,success
compound_2,-31.42,-70.18,38.76,success
compound_3,-22.14,-58.90,36.76,success

Processing Details

• Receptor topology is prepared once and validated via SHA256 hash
• Each ligand is parameterized independently
• Complex assembly and rescoring occur per-ligand
• Failed ligands are logged but do not halt the batch

Additional Commands

Rescore provides modular commands for advanced users who want fine-grained control over each pipeline step. These are not required for typical use cases.

For detailed help on any command:

rescore <command> --help