Adding dnascan module - Issue #1634 - and code simplification

[amjjbonvin]

What does this PR do and why?

This PR add a new analysis module, dnascan, similar to the recently added rnascan module, but for DNA.
The main difference is that base pairs are mutated, scanning by default all possible combinations.
The mutations are done in two steps, first the purine to pyrimidine one, and then the pyrimidine to purine. This is required to ensure proper rebuilding of the base and base-pairing.

Tests are added and an example is provided in examples/analysis

code simplification

Refactor scan modules: rename scan.py and extract shared code to libscan
Rename each scan module's scan.py to match its module name
(alascan.py, rnascan.py, dnascan.py) and factor the code the modules
duplicated into libscan.py:

• Nucleic-acid mutation helpers shared by rnascan/dnascan: ring/anchor
  atom constants, norm_atom_name, get_atoms_to_keep (parametrized by
  backbone/purines/pyrimidines) and validate_scan_bases (parametrized
  by allowed set).
• filter_interface / build_resname_dict: the identical interface
  user-filtering block used by all three modules' run().
• BaseInterfaceScanner: the shared InterfaceScanner.init setup.
• ModelPointMutation: the identical point-mutation job + scoring flow
  shared by alascan/rnascan; each module keeps a thin run() that
  forwards its module-level mutate/calc_score (kept patchable in tests).

Also apply small cleanups to dnascan (defaultdict, .get, collapsed
branches, RES_CODES literal, cached get_atoms_to_keep per residue,
halved find_base_pairs distance computations) and rnascan (derive
DEFAULT_SCAN_BASES, correct atoms_to_keep annotation, stream file).

dnascan's ModelBasePairMutation (double/two-pass mutation) is genuinely
different and stays in the module. No behavior change; 83 unit tests
across the three modules pass.

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com

How was this tested?

Using the newly added example, visually inspecting all mutations to ensure they are correct and the base-pairing is maintained.

AI assistance

AI was use to build the module from the rnascan one and for generating the tests.
Code and results were manually checked.

Checklist

• Tests cover the new and/or changed code
• Documentation updated if needed (also in the haddock3 user-manual
• CHANGELOG.md updated for user-facing changes

Related issues

#1634

[AnnaKravchenko]

Please add a title to docs/titles.yaml and also link this module to the user manual - same that was done for rnascan

[AnnaKravchenko]

Please add a title to docs/titles.yaml and also link this module to the user manual - same that was done for rnascan

As a bonus, adding the title should fix broken link that is blocking merge of RNAscan documentation to the user manual:)

[rvhonorato]

this has roughly 90% overlap with rnascan, meaning its a huge code duplication.

the only functions that seem specific to this module are: wc_atom, is_cross_type, find_base_pairs, _mutate_residues, _score_same_type/_score_cross_type, bp_cutoff - everything else that is not boilerplate is repeated.

move the functions used both in rnascan and dnascan to libscan.py rename scan.py into dnascan.py and keep the specific functions there.

when making this AI changes please get used to making the following prompt: "make sure the contributions done in this PR are in line with AI-POLICY.md and CONTRIBUTING.md guidelines"

if you are using claude there is literally a /simplify command you should run before doing a 3.000 line PR full of duplicated code.