Add ref_model option to calcSignatureOverlaps with tests

[jamesmkrieger]

Allow calcSignatureOverlaps to overlap each modeset of a ModeEnsemble (or list of modesets) against a single reference model instead of within the ensemble. Supports NMA/ModeSet/Mode/Vector references, including single-mode references (e.g. a deformation vector) and the collapse option, and validates atom/mode-count compatibility.

Add unit tests covering both the manual and SignDy (calcEnsembleENMs) routes for GNM and ANM ensembles: output shapes, value agreement with calcOverlap, collapse/non-collapse consistency, diagonal mode, list input, and error handling.

(code created mostly by me, debugging and tests done with Claude)

[karolamik13]

ref_model works fine for me. Test below.

Test:
from prody import *
import numpy as np

atoms = parsePDB('2k39', subset='ca')

ensemble = PDBEnsemble('2k39')
ensemble.setAtoms(atoms)
ensemble.setCoords(atoms.getCoords())
ensemble.addCoordset(atoms.getCoordsets()[:3])
ensemble.iterpose()

mode_ensemble = calcEnsembleENMs(ensemble, model='anm', n_modes=5, match=True)
ref_model = mode_ensemble[0]
overlaps = calcSignatureOverlaps(mode_ensemble, ref_model=ref_model, diag=False)
print('Overlaps model 2 vs reference:')
print(overlaps[:, :, 1, 0])

Outcome:
@> PDB file is found in working directory (2k39.pdb.gz).
@> 76 atoms and 116 coordinate set(s) were parsed in 0.18s.
@> Starting iterative superposition:
@> Step #1: RMSD difference = 2.0067e+00
@> Step #2: RMSD difference = 1.0467e-02
@> Step #3: RMSD difference = 1.1429e-04
@> Step #4: RMSD difference = 2.1498e-06
@> Iterative superposition completed in 0.00s.
@> Final superposition to calculate transformations.
@> Superposition completed in 0.00 seconds.
@> 5 ANM modes were calculated for each of the 3 conformations in 0.11s.
@> 5 modes across 3 modesets were matched in 0.01s.
Overlaps model 2 vs reference:
[[0.81483829 0.06349447 0.11905709 0.1073479 0.07928038]
[0.14691102 0.4308338 0.01569588 0.10111737 0.04322131]
[0.11941193 0.11608539 0.12140975 0.28137899 0.17505434]
[0.08494323 0.48902284 0.00568987 0.27518305 0.02109716]
[0.07634467 0.12741254 0.09611883 0.13753133 0.28326796]]