Copy-Paste Walkthrough

Run JARI-PROTACS without the archaeology

This is the shortest practical route from PRosettaC model folders to reproducible structural clusters. Copy each block, replace the two paths, and run the commands from top to bottom.

Open the JARI repository ↗ What is JARI?

Before you start

Python 3.10 or newer

A working DockQ installation, including the path to its executable

PRosettaC-derived PDB model folders

Enough disk space for pairwise DockQ score files

Do not start with a single PDB. JARI compares model families. You need a folder of PRosettaC outputs organized by design, ligand, linker, or pose family.

Step 1: check your input layout

Each top-level folder is one model family; each cluster* directory contains the PDBs emitted by the upstream modeling workflow.

your_models/
├── linker_a/
│   ├── cluster1/
│   │   ├── combined_001.pdb
│   │   └── combined_002.pdb
│   └── cluster2/
│       └── combined_003.pdb
├── linker_b/
│   └── cluster1/
│       └── combined_001.pdb
└── linker_c/
    └── cluster1/
        └── combined_001.pdb

Step 2: clone and set up JARI

Paste this once. The last two lines are the only values you must change: your model directory and the DockQ executable path.

git clone https://github.com/Joey305/JARI.git
cd JARI
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

export MODELS_DIR="/absolute/path/to/your_models"
export DOCKQ_BIN="/absolute/path/to/DockQ.py"

Sanity check: run test -d "$MODELS_DIR" and test -f "$DOCKQ_BIN". Both commands should return silently. If either prints an error, fix that path before continuing.

Step 3: run the core pipeline

Run this from the JARI repository directory. With DockQ v2, keep the PRosettaC PDBs unchanged unless a compatibility check shows the legacy preparation step is needed.

# Optional only when legacy PDB normalization is required:
# python scripts/01_prepare_pdbs_for_dockq.py "$MODELS_DIR"

python scripts/02_run_cross_dockq.py "$MODELS_DIR" --dockq-executable "$DOCKQ_BIN"
python scripts/03_run_self_dockq.py "$MODELS_DIR" --dockq-executable "$DOCKQ_BIN"

python scripts/04_export_cross_scores_to_excel.py results/cross_scores
python scripts/05_export_self_scores_to_excel.py results/self_scores
python scripts/06_merge_score_workbooks.py results/workbooks/self_scores.xlsx results/workbooks/cross_scores.xlsx
python scripts/07_average_pairwise_dockq.py results/tables/all_data_combined.csv

python scripts/11_cluster_dbscan_umap.py results/tables/averaged_dockq_scores.csv
python scripts/12_plot_dendrogram.py results/tables/averaged_dockq_scores.csv
python scripts/14_plot_top_cluster_composition.py \
  --cluster-assignments results/tables/dbscan_cluster_assignments.csv \
  --averaged-scores results/tables/averaged_dockq_scores.csv

Step 4: read the outputs in the right order

Inspect score tables: confirm all expected model families appear before interpreting clusters.
Open the averaged DockQ table: higher values indicate more similar structures; JARI uses 1 − Average_DockQ as clustering distance.
Review DBSCAN assignments: identify reproducible structural neighborhoods and outliers.
Use the UMAP and dendrogram together: they are visual aids, not independent evidence.
Return to the original models: inspect representative PDBs, linker geometry, interfaces, and assumptions for every cluster you plan to discuss.

Interpretation rule: a tight structural cluster says the sampled models are similar. It does not establish biological activity, selectivity, ubiquitination, or degradation.

Fast troubleshooting

Input layout

“No PDB files found”

Check that PDBs are inside cluster-named folders beneath each top-level model family.

Review layout

Setup

DockQ cannot be found

Replace DOCKQ_BIN with the exact path to the installed DockQ executable, then rerun the two test commands.

Review setup

Pipeline order

Scores exist but plots do not

Confirm the averaged score table exists before steps 11, 12, and 14; those scripts use it as their shared input.

Review commands

Interpretation

The clusters make no chemical sense

Go back to representative structures and input metadata. Revisit anchor atoms, chain definitions, linkers, and preparation choices before drawing conclusions.

Review modeling handoff

What to do next

Design

Build or refine candidates

Return to the Builder when the results point to a new linker, recruiter, or attachment-vector hypothesis.

Open PROTAC Builder

Reporting

Review model handoff

Keep exports, anchor metadata, model settings, and representative structures together for reproducibility.

Open handoff guide

Advanced use

Read the repository details

Use the JARI README for optional large-score and HPC workflows beyond this standard path.

Open GitHub ↗