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: 1. Load a trajectory (TPR + XTC + optional NDX). 2. Choose reference and selection groups (automatic or interactive). 3. Split them into chains (using ``splitch``). 4. Validate chain lengths and indices. 5. Compute atom–atom distances for each analyzed frame. 6. Apply a global or residue-specific cutoff to define contacts. 7. Compute inter-chain and intra-chain residue contact matrices. 8. Output selected matrices in requested formats. Usage ----- .. code-block:: bash dps cmap -s run.tpr -f run.xtc -cs global -c 0.7 -ref 0 -sel 1 -ors ref_sel.dat Arguments --------- Required -------- .. option:: -s, --run-input TPR TPR file defining topology, chain structure, atom/residue properties. .. option:: -f, --input XTC Trajectory file used for distance calculations. .. option:: -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 ------------------- .. option:: -ref, --reference-group INT Index group ID used as the **reference (x-axis)** set of chains. .. option:: -sel, --selection-group INT Index group ID used as the **selection (y-axis)** set of chains. If omitted, the tool enters interactive selection mode. .. option:: -n, --index NDX Optional NDX file defining custom index groups. Cutoff parameters ----------------- .. option:: -c, --cutoff FLOAT Global cutoff (nm) when ``--cutoff-scheme global`` is used. .. option:: -cm, --cutoff-multiplier FLOAT Multiplier for residue-specific σ values. Used only when ``--cutoff-scheme residue`` is chosen. .. option:: -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 -------------------- .. option:: -b, --start-time INT .. option:: -e, --end-time INT .. option:: -dt, --delta-time INT Time range and sampling interval (ns). The program internally converts times → frame indices. PBC handling ------------ .. option:: -pbc, --treat-pbc Apply MDAnalysis ``unwrap`` to remove discontinuities across periodic boundaries. Output options -------------- The program can output up to **five** matrices: .. option:: -ors, --output-inter-reference-selection FILE .. option:: -orr, --output-inter-reference-reference FILE .. option:: -oss, --output-inter-selection-selection FILE .. option:: -or, --output-intra-reference FILE .. option:: -os, --output-intra-selection FILE At least **one output** must be specified. .. option:: -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 --------- (1) **Load trajectory** .. code-block:: python trajectory = trajectory_class(args.run_input, args.index, args.input) (2) **PBC treatment** (optional) .. code-block:: python unwrap(trajectory.Universe.atoms) (3) **Cutoff matrix generation** - Global scheme: .. code-block:: python 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 (4) **Frame selection** :: start_frame, end_frame, interval = time2frame(b, e, dt) (5) **Group selection** Either direct via ``--ref`` / ``--sel`` or interactively. (6) **Split chains** :: reference_chains = splitch(reference_group) selection_chains = splitch(selection_group) All chains must have equal residue count. (7) **Distance calculation** For each frame: .. code-block:: python 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. (8) **Residue-level chain map construction** Using: .. code-block:: python 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: .. code-block:: bash 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.