Skip to content

feat: add exact and heuristic probability SVGs (steps 8–11) - #259

Merged
martin-raden merged 9 commits into
docs/257-base-pair-probability-planfrom
feat/258-bpsvg
Oct 13, 2026
Merged

martin-raden merged 9 commits into
docs/257-base-pair-probability-planfrom
feat/258-bpsvg

Conversation

@Alexander-Mitrofanov

@Alexander-Mitrofanov Alexander-Mitrofanov commented Oct 9, 2026 •

Copy link
Copy Markdown
Collaborator

Adds actual-pair SVG plots and extends CSV/SVG probability output to exact unseeded and heuristic ensemble predictors. This completes steps 8–11 requested in #258 and Martin's review. It depends on #258 and targets docs/257-base-pair-probability-plan.

The revised SVG starts both strands at the upper-left corner, places the query name below the matrix, adds a subtitle for nondefault names, and uses sequence names in tooltips. Tooltip probabilities use three decimal places, or two-place scientific notation below 0.001; machine-readable values retain full precision. Nucleotide frames now show intramolecular pairing (1-Pu). Orange outlines identify admitted seed pairs; green outlines identify the best reported ensemble interaction region and every pair of a minimum-energy structure reconstructed within that site, including when --outNumber=0. Shared seed/MFE cells have orange left/right edges and green top/bottom edges. The additional fixed-boundary MFE traceback runs only for SVG output; ordinary ensemble ranking and output are preserved. Both outlines have legends. Signed-coordinate guides, gzip, multi-FASTA naming, synchronized shared streams and success-only publication are preserved.

Supported --model=P probability modes:

  • M with stack-only seeds: the existing exact, unique-chain seeded ensemble.
  • M with --noSeed: new reverse calculation over the existing fixed-right-boundary inside recurrence.
  • H with --noSeed: new reverse flow through retained continuation chains.
  • H with computed/explicit seeds of at least two pairs, including bulged seeds: new signed reverse trace over existing seed-extension terms and seed-overlap corrections.

H outputs are explicitly approximate (bpProbApproximate in CSV and an approximate SVG title). They describe the predictor's retained candidate ensemble, including existing path multiplicities, rather than the exact unique-chain ensemble. The unseeded and heuristic paths preserve existing numerical-zero cutoffs and reported ensemble totals. Windows, exact bulged-seed probability output and singleton heuristic seeds remain unsupported.

Adds ten internal SVG recurrence depictions across the original implementation and review revision, including exact unseeded outside and heuristic candidate-flow calculations. They cover noLP transitions, energy/pair ownership, coordinate mapping, regional normalization and implementation anchors. README and ChangeLog document the interface and limitations.

Independent agents reviewed recurrence correctness, failure handling and performance before push. Review fixes include per-strand accessibility scales, cropped-region offsets/bounds, finite-energy boundary underflow, and nonfinite seeded-heuristic denominator rejection. Transferring completed output buffers avoids an extra full-document copy.

Validation:

  • GCC 14.4 release and debug: make tests -j2; all seven suites pass, with 100,947 API assertions in 97 cases each. The October 12 revision also passes both full release/debug suites and visually rendered SVG checks.
  • Independent tiny-chain oracles for exact/unseeded H; seeded H pair-fugacity checks freeze selected continuations and concrete seed families to verify actual pair numerators, including overlapping and bulged seeds.
  • CSV/SVG regressions verify numeric parity, approximation labels, seed masks, upper-left axis/MFE geometry, complete internal MFE pairs, split seed/MFE borders, rounded tooltips, signed coordinates, native/imported/mixed accessibility, empty/failing runs, gzip and parallel streams.
  • All 74 installed public headers compile independently. Installed pkg-config consumers for all four predictor variants compile, link and produce CSV/SVG with expected metadata.
  • make dist includes new implementation/tests. UTF-8/LF and git diff --check pass. New/corrected recurrence diagrams and representative output SVGs parse, render and were visually inspected.

Previous performance audit (before the SVG-only fixed-boundary MFE traceback added in the October 12 layout review): 252 measured runs across native OxyS/fhlA and dense LP/noLP inputs, three predictors, and four output configurations. Existing output-off wall medians changed by −1.2% to +2.4%; all ensemble outputs were byte-identical and all CSV/SVG pair values matched. New CSV output took 1.09–1.92× revised output-off time, and SVG 1.26–2.07× on these cases. Runtime ranges, RSS, limitations and reproduction commands are in doc/analysis/seeded-probabilities-validation.md.

Apple Clang was not available locally. SVG size and serialization memory grow with the full target-by-query matrix; shared streams contain consecutive complete SVG documents. The green outline is omitted when no interaction passes reporting filters.

@Alexander-Mitrofanov Alexander-Mitrofanov changed the title feat: add SVG base-pair probability plots (step 8 of #258) feat: add probability SVGs and recurrence depictions (steps 8-9 of #258) Oct 9, 2026
@martin-raden

martin-raden commented Oct 9, 2026 •

Copy link
Copy Markdown
Member

@Alexander-Mitrofanov

thanks, please revise:

SVG layout revision

  • move the sequence name label of the x-axis sequence to the bottom
  • extend the title with a subtitle that specifies both sequence names (only if they are not the default names "query" and "target")
  • use the sequence names also within the probability tool tips
  • within tooltips: round to 3 digits and use scientific notation (with 2 digits) if below 0.001
  • reverse the indexing of the vertical (y-axis) sequence, i.e. start the sequences at the bottom left corner to be analog to a normal plotting coordinate system
  • reverse the unpaired probabilities to "pair probabilties", i.e. use "1-unpairedProbability" for plotting to show only pair probabilities both intra and intermolecular
    • update the tooltip information respectively
  • if possible, add a green rectangle within the RRI base pair probability area that highlights the region covered by the mfe interaction
    • add a respective information to the legend analogously to the seed base pair highlighting information

(step 10) base pair probability and SVG output also for "noSeed" predictor

to enable a comparison of the base pair probabilities with and without seed constraints:

  • extend the existing predictor that is used for "--model=P --mode=M --noSeed" to support base pair probability output both in the current CSV and SVG output
  • check if approximate base pair probabilities are also possible with the "--model=P --mode=H --noSeed" predictor. if so, extend the implementation for the respective support too.

(step 11) extension of heuristic ensemble predictors to base pair probabilities

  • evaluate whether an approximate base pair probability computation can be implemented for the heuristic seeded and non-seeded predictors that do not cover all possible interactions
  • if extension is possible, implement and enable base pair probability computation and output for heuristic ensemble predictors

@Alexander-Mitrofanov Alexander-Mitrofanov changed the title feat: add probability SVGs and recurrence depictions (steps 8-9 of #258) feat: add exact and heuristic probability SVGs (steps 8–11) Oct 9, 2026
@martin-raden

Copy link
Copy Markdown
Member

@Alexander-Mitrofanov

thanks, please revise:

svg layout

to make the new probability dot plots compatible with existing dot plots ensure both lowest sequence index coordinates are in left upper corner.

  • reverse the y-axis orientation such that the the smallest index is in the upper left (top) corner and the highest in the lower left (bottom) corner
  • update respective documentation if present
  • highlight all mfe base pairs with the same green border rectangle that is used for highlighting the mfe region
    • if the base pair is a seed basepair, draw the left and right boundary orange and the upper and lower boundary green to show that this base pair is both part of seed and mfe

@martin-raden
martin-raden merged commit c3934a1 into docs/257-base-pair-probability-plan Oct 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants