Contact map¶

The cmap tool computes residue-level contact maps between reference and selection groups of chains. It supports:

Inter-chain contact maps
Intra-chain contact maps
Reference ↔ Selection contact maps
Symmetric reference ↔ reference and selection ↔ selection maps
Both global cutoff and residue-specific cutoff schemes
Output formats: .dat, .xpm, .xlsx

This tool is implemented in contact_map.py.

Overview¶

A contact map is a 2D matrix where element (i, j) represents the probability of residues i and j being in contact, averaged over selected frames.

The workflow:

Load a trajectory (TPR + XTC + optional NDX).
Choose reference and selection groups (automatic or interactive).
Split them into chains (using splitch).
Validate chain lengths and indices.
Compute atom–atom distances for each analyzed frame.
Apply a global or residue-specific cutoff to define contacts.
Compute inter-chain and intra-chain residue contact matrices.
Output selected matrices in requested formats.

Usage¶

dps cmap -s run.tpr -f run.xtc -cs global -c 0.7 -ref 0 -sel 1 -ors ref_sel.dat

Arguments¶

Required¶

-s, --run-input TPR¶: TPR file defining topology, chain structure, atom/residue properties.

-f, --input XTC¶: Trajectory file used for distance calculations.

-cs, --cutoff-scheme {global,residue}¶

Scheme for defining contact thresholds.

global → same cutoff for all atom pairs
residue → per-residue cutoff based on σ parameters

Selection arguments¶

-ref, --reference-group INT¶: Index group ID used as the reference (x-axis) set of chains.

-sel, --selection-group INT¶: Index group ID used as the selection (y-axis) set of chains.

If omitted, the tool enters interactive selection mode.

-n, --index NDX¶: Optional NDX file defining custom index groups.

Cutoff parameters¶

-c, --cutoff FLOAT¶: Global cutoff (nm) when --cutoff-scheme global is used.

-cm, --cutoff-multiplier FLOAT¶: Multiplier for residue-specific σ values. Used only when --cutoff-scheme residue is chosen.

-ff, --forcefield NAME¶: Forcefield name to load when using residue-specific cutoffs. If not provided, you will be prompted to choose one.

Time-window settings¶

-b, --start-time INT¶

-e, --end-time INT¶

-dt, --delta-time INT¶

Time range and sampling interval (ns). The program internally converts times → frame indices.

PBC handling¶

-pbc, --treat-pbc¶: Apply MDAnalysis unwrap to remove discontinuities across periodic boundaries.

Output options¶

The program can output up to five matrices:

-ors, --output-inter-reference-selection FILE¶

-orr, --output-inter-reference-reference FILE¶

-oss, --output-inter-selection-selection FILE¶

-or, --output-intra-reference FILE¶

-os, --output-intra-selection FILE¶

At least one output must be specified.

-otype, --output-type {dat,xpm,xlsx}¶

Contact maps may be saved as:

dat → numerical table (tab-separated)
xpm → XPM heatmap (GROMACS-compatible)
xlsx → Excel sheet

Algorithm¶

Load trajectory

trajectory = trajectory_class(args.run_input, args.index, args.input)

PBC treatment (optional)

unwrap(trajectory.Universe.atoms)

Cutoff matrix generation

Global scheme:

cutoff_vector = [cutoff * 10.0] * num_atoms

Residue-specific:

Loads .ff parameter file and sets:

cutoff[i] = cutoff_multiplier * sigma[i] * 10.0

Distance cutoff matrix:

cutoff_matrix[i,j] = (cutoff_vector[i] + cutoff_vector[j]) / 2

Frame selection

start_frame, end_frame, interval = time2frame(b, e, dt)

Group selection

Either direct via --ref / --sel or interactively.

Split chains

reference_chains = splitch(reference_group)
selection_chains = splitch(selection_group)

All chains must have equal residue count.

Distance calculation

For each frame:

distance_map = distances.distance_array(frame, frame, box)
contact_map_temp = (distance_map < cutoff_matrix).astype(int)

The raw atom–atom contact map is averaged over frames.

Residue-level chain map construction

Using:

compute_contact_maps(contact_map, reference_chains, selection_chains)

The function returns:

contact_ref_sel
contact_ref_ref
contact_sel_sel
intra_ref
intra_sel

Outputs¶

Depending on user options, the following may be generated:

### 1. Inter-chain Reference ↔ Selection contact_ref_sel → --output-inter-reference-selection

### 2. Inter-chain Reference ↔ Reference contact_ref_ref → --output-inter-reference-reference

### 3. Inter-chain Selection ↔ Selection contact_sel_sel → --output-inter-selection-selection

### 4. Intra-chain Reference intra_ref → --output-intra-reference

### 5. Intra-chain Selection intra_sel → --output-intra-selection

All matrices are averaged across chains and frames.

Example¶

Compute all inter-chain and intra-chain maps using residue-specific cutoffs:

dps cmap \
    -s run.tpr \
    -f run.xtc \
    -n run.ndx \
    -ref 0 \
    -sel 1 \
    -cs residue \
    -cm 1.2 \
    -ors ref_sel.xpm \
    -orr ref_ref.xpm \
    -oss sel_sel.xpm \
    -or intra_ref.dat \
    -os intra_sel.xlsx

Error messages¶

“ERROR: No output file specified.” You must request at least one map.

“Unknown forcefield …” Forcefield name does not match available .ff files.

“Chains in reference/selection groups are not same in length.” Occurs if index groups do not represent proper chain-wise selections.

“Distance will be calculated without PBC.” Printed when --treat-pbc is not used.

“ERROR: Conflict detected! The following .ff files exist in both locations” Both the working directory and system forcefield directory contain files with the same name.

Summary¶

dps cmap computes comprehensive residue-level contact maps for multichain biomolecular systems, supporting:

global and residue-specific cutoffs
full inter/intra chain decomposition
flexible output formats
robust selection + chain-splitting logic

It is one of the core analysis tools in the DROPPS package for quantifying interaction patterns underlying LLPS behavior.