🚀 Quick Start

March 13, 2026 · View on GitHub

Follow these numbered steps to run AISAR scoring and conformer selection.

1. Install Requirements

Python

pip install numpy pandas

R

install.packages(c("cluster", "DescTools", "RColorBrewer", "bio3d", "minpack.lm", "zeallot", "RColorBrewer"))

macOS MUSCLE (for bio3d):

brew install brewsci/bio/muscle

2. Prepare Input Files

Your dataset directory should contain:

<protein>/data_runs/
├─ ESmodels/        # All AFsample / AlphaFold PDB models
├─ RPF/             # Folder for RPF scoring
├─ RCI.csv          # Edited RCI output (Number, RCI, Residue)
└─ scores.sc        # Output scoring metric file generated by the AFsample protein structure prediction software

Requirements for RCI.csv

Columns: Number, RCI, Residue
Sequence must match PDB sequence in ESmodels
Include residues even if RCI is missing

Requirments for ESmodels

All relaxed pdb files
Examples: https://github.com/MontelioneLab/AISAR/blob/main/docs/data.md

6. Perform PCA and Clustering

In Rstudio, first set the working directory to data_runs/ and then open the script:

dmPCAClustering.R

and run it inside RStudio.

At line 41:

grps <- cutree(hc2, k=1)

Change k to the number of clusters you would like to generate.

This produces:

PCA projections
clusters (1,2,3,4,,,) Output file:

cluster_pc_dm.csv

7. Combine All Scores Into One Table

python ../../scripts/getScores.py scores.sc pLDDT.sc scc.sc rpf.sc cluster_pc_dm.csv > scores.all

Or use default filenames:

python ../../scripts/getScores.py > scores.all

Output: scores.all

8. Select Conformers Based on Combined Scores

python ../../scripts/selectModels.py scores.all ESmodels 5 selectedModels| tee selectedModels.log

Outputs: selectedModels/ and selectedModels.log

What this command does

scores.all – the table of combined scores (Recall, Precision, pNOE, RCI agreement, pNMR, etc.).
ESmodels – directory containing all ensemble-sampled conformers (e.g., model_0001.pdb, model_0002.pdb, …).
5 – the number of top conformers to select. can be set to 10, 20, ...
selectedModels – output directory where the chosen models will be copied.

tee selectedModels.log → prints the selection summary to the screen and writes it to selectedModels.log.

The selectedModels/ directory contains only the top-ranked conformers that satisfy the combined AISAR scoring criteria. Its' subfolders are named using a state label (a–d) followed by the cluster index. The letter denotes the ranked state assignment based on pNMR support (A highest, B second, etc.), whereas the number indicates the original geometric cluster index.

2. `selectedModels.log`

A readable log file showing:

ranking
combined score per model
pTM/pLDDT/SCC/Recall/DP/pNMR scores
cluster assignment
final selection decision

This log is useful for state selection and combination.

9. Group Selected Conformers Into Ensembles

python ../../scripts/groupModels.py selectedModels/a1/

Output: selectedModels/a1.pdb

10. Validate Multi-State via DoubleRecall

After selecting conformer sets, run the RPF webserver and download the resulting ZIP file.

DoubleRecall - ensemble A vs ensemble B: https://colab.research.google.com/drive/1IPXZVDdxG1xpn-6tgIErWJOSLa9Rx87A
DoubleRecall - ensemble A vs ensembles B1+B2: https://colab.research.google.com/drive/1YShoUAQWdKu0EccMJgkLeeiojUWKT0SJ

11. Saving the DoubleRecall Colab Notebook

After running DoubleRecall in Google Colab, you can save your work for documentation or future reruns:

Download the notebook

In Colab: File → Download → Download .ipynb

Upload the notebook later

To reopen your saved notebook: File → Upload notebook → Select your .ipynb file