Integrate pairwise distance calculations and visualization features (simplot-like plots)

[jonas-fuchs]

This pull request introduces several improvements and refactors to both the core msaexplorer library and the Shiny app frontend. The main changes include standardizing the use of the alignment object interface, adding support for a new "simplot-like similarity" plot type, improving UI options for distance metrics, and documenting repository coding standards. These updates enhance code maintainability, add new features, and ensure consistency across the codebase.

Interface and API Consistency:

• Refactored code throughout app_src/shiny_server.py, app_src/shiny_plots.py, and msaexplorer/__init__.py to use next(iter(aln)) and len(aln) instead of accessing the .alignment dictionary directly. This change standardizes how alignment objects are iterated and measured, improving abstraction and maintainability. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]

New Features:

• Added "simplot-like similarity" as a selectable plot/statistic type in the draw module and Shiny app, including automatic window and step size selection, and appropriate UI updates for both amino acid and nucleotide alignments. [1] [2] [3] [4]

UI and Analysis Improvements:

• Enhanced the UI for selecting pairwise distance metrics in the analysis tab, adding new options (jc69, k2p) for nucleotide alignments and displaying explanatory info for each metric. [1] [2]
• Updated statistics download logic to handle new data types and ensure correct handling of AlignmentStats objects. [1] [2]

Documentation and Standards:

• Added a .github/copilot-instructions.md file detailing repository-specific coding, documentation, and testing standards to guide future contributions and AI-assisted edits.
• Minor improvements to the README.md, including clarifying feature lists and package capabilities. [1] [2]

[Copilot]

Pull request overview

This PR refactors msaexplorer to standardize alignment iteration/length access, introduces new dataclass-based result containers, and adds a new “simplot-like similarity” visualization that leverages pairwise distance calculations across sliding windows.

Changes:

• Refactor core + app code to use __iter__/__len__-style access (next(iter(aln)), len(aln)) and return dataclasses for stats/variants/ORFs/distances.
• Add simplot-like similarity plotting (library + Shiny integration) and expand nucleotide distance metric options (incl. jc69, k2p).
• Add export helpers/tests and document repo-specific coding standards for future contributions.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
msaexplorer/explore.py	Introduces dataclass outputs (stats, SNPs, ORFs, pairwise distances) and centralizes distance calculation mapping.
msaexplorer/draw.py	Refactors plotting utilities to new alignment interface and adds simplot() plotting helper.
msaexplorer/export.py	Updates exporters to consume new dataclasses and adds support for AlignmentStats export.
msaexplorer/_helpers.py	Adds shared internal helpers for alignment parsing, distance metrics, path creation, and draw utilities.
msaexplorer/_data_classes.py	Adds frozen dataclasses for SNPs, stats, ORFs, and pairwise distance results.
msaexplorer/__init__.py	Updates examples to use iterator-based alignment access.
app_src/shiny_server.py	Updates Shiny server logic for new interfaces, adds new plot type/metric choices, and adapts download handling for dataclasses.
app_src/shiny_plots.py	Adds simplot-like plot option and adapts analysis heatmap to new PairwiseDistance result type.
tests/test_stats_calculations.py	Updates tests to new dataclass return types and adds coverage for reference-distance calculations.
tests/test_orf_detection.py	Updates ORF tests to new OrfCollection/OpenReadingFrame structures.
tests/test_export.py	Adds new export tests for SNP/FASTA/stats/ORF/character frequencies/percent recovery exporters.
tests/test_draw_plots.py	Adds plotting tests (including simplot) using a non-interactive matplotlib backend.
tests/test_alignment_parsing.py	Switches parsing tests to _helpers._read_alignment.
tests/README.md	Updates test suite scope description.
README.md	Refreshes feature bullets and clarifies package capabilities.
pyproject.toml	Bumps package version to 0.5.
.github/copilot-instructions.md	Documents repository coding/testing/style conventions for AI-assisted edits.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.