apzubarev/Degree-of-nontrivial-ultrametricity-for-RNA-macrostates: Calculation of the degree of nontrivial ultrametricity for RNA macrostates Version 3

Calculation of the degree of nontrivial ultrametricity for RNA macrostates. PHYSICALLY RIGOROUS APPROACH: distance between basins via spectral decomposition of the transition rate matrix (Mahalanobis distance in the space of eigenvectors of the symmetrized matrix K).

METHOD:

1. A transition rate matrix K is built between all structures (N x N, where N ~ 2000) based on the Kramers formula.
2. K is symmetrized taking detailed balance into account.
3. The m smallest eigenvalues in magnitude and corresponding eigenvectors are computed (Lanczos method for sparse matrices).
4. Automatic filtering of noise modes is performed by finding a spectral gap: if the ratio |λ_k| / |λ_{k-1}| exceeds a threshold (default 10^6), modes with indices < k are discarded as numerical noise.
5. Each attraction basin is represented by a characteristic vector χ_A in the space of structures.
6. The distance between basins A and B is defined as the weighted Euclidean distance between projections of χ_A and χ_B onto eigenvectors (Mahalanobis distance).
7. The resulting distance matrix is a metric and is tested for ultrametricity.

HANDLING DISCONNECTED GRAPHS: Before constructing the K_sym matrix, the connectivity of the structure graph is checked. If the graph contains multiple connected components, each component is processed separately: its own K_sym matrix is built, spectral decomposition is performed, and ultrametricity is checked. Components with fewer than 3 basins are skipped.

STATISTICAL MODE (NUM_STAT > 1): When NUM_STAT > 1, NUM_STAT independent runs are performed for each sequence with different random samples of structures (seed varies: RANDOM_SEED, RANDOM_SEED+1, ..., RANDOM_SEED+NUM_STAT-1). Results are averaged, and the final table shows mean values and standard deviations (mean ± std). Integer quantities (number of structures, basins, connected components) are rounded to integers.

OUTPUT MODES: VERBOSE = True — full log (steps, components, spectral analysis). VERBOSE = False — brief log: sequence header and parameters are printed once, then only RUN/COMPLETED, followed by a statistics block.

ADVANTAGES:

• Takes into account all possible transition paths (via spectral decomposition).
• Context-independent (distance between A and B is determined only by them, not by the presence of other basins).
• Symmetric and guaranteed to be a metric.
• Automatically filters out numerical noise via spectral gap detection.
• Correctly handles disconnected structure graphs.
• Computational complexity O(m·N·E + K²·m), allowing processing of N ~ 2000 structures and K ~ 100 basins in seconds.

STRUCTURE GENERATION MODE: Stochastic sampling (pbacktrack) from the Gibbs distribution.

Dependencies: pip install viennarna numpy scipy biopython