Refactor: Move `plot_venn` into a dedicated `VennComparisonReport` class

[dyrpsf]

Problem or use case

I want to standardize the visualization logic for model comparisons because currently, the plot_venn function resides as a standalone function in analysis.comparison. As refineGEMs moves toward a more modular, object-oriented reporting architecture, leaving standalone plotting functions scattered across analysis modules creates architectural inconsistency and makes maintenance harder.

Proposed solution

Create a new VennComparisonReport class inside the classes.reports module. Migrate the plot_venn logic into this new class so that it perfectly aligns with the rest of the updated reporting architecture.

Affected area

• Python API
• Developer architecture
• Command-line interface
• Sphinx / Read the Docs documentation
• Existing media workflow or media documentation
• Tests
• Packaging, installation, or optional dependencies

Example usage

from refinegems.classes.reports import VennComparisonReport

venn_report = VennComparisonReport(models=[model1, model2, model3])
venn_report.visualise()

Alternatives considered

We considered leaving plot_venn in its current location within analysis.comparison. While this avoids breaking changes in the short term, it leaves the reporting pipeline fragmented and prevents the reporting classes from being fully unified.

Compatibility considerations

This will affect existing APIs and workflows. Scripts that currently import plot_venn directly from analysis.comparison will experience a breaking change. To mitigate this, we can either leave a deprecation wrapper function in the old location that redirects to the new class, or simply note the breaking API change clearly in the documentation and release notes.

Additional context

This refactoring was explicitly discussed and agreed upon with @cb-Hades during the review and merge of PR #190

[GwennyGit]

Original idea:
The idea behind the functions plot_venn and plot_db_entity_overlap is similar. The idea was to have functions to investigate the entity overlap based on either the model’s internal IDs or the annotation content visually. For up to four models, this makes sense as a Venn diagram; for more models, use an UpSet plot.

Current issues:
One issue with these functions is that they currently do not fit the Report class setup, as you have seen. The other issue is that it would also be great if the models could be compared not only by a single namespace but also by overall annotation overlap. So if I have at least one overlapping annotation for an entity, this should count as a model overlap for that entity. Thus, I would rather like to have a Report class ModelComparisonReport or ModelOverlapReport that, depending on the user, either shows the entity overlap for a specific namespace or the model ID or shows the entity overlap without a specific namespace.

Future idea:
For a full ModelComparisonReport, it would probably make more sense to show not only an overlap plot for one entity but multiple plots, like for the ModelInfoReport, for all entity types, and in addition, statistics like in the ModelInfoReport should also be reported, but for all models at the same time. So that in the end, you get a complete model comparison.

[dyrpsf]

Hi @GwennyGit! That expanded scope makes a lot of sense, and a comprehensive ModelComparisonReport sounds like a much more powerful tool than just wrapping the Venn diagram. I completely agree with the dynamic Venn/UpSet approach and the broader annotation overlap logic.

Since this is blocked by the 2.0 release checklist, how would you like to proceed? I am happy to leave this on the back burner until the 2.0 release is unblocked, or I can start drafting the class skeleton and logic for the overall annotation overlap now if you'd like to get a head start on it. Let me know what works best for the roadmap!

[GwennyGit]

Hey @dyrpsf,

Thank you for offering your contribution!
I think a draft sounds great. If you want to start working on it, please feel free to do so on a dedicated feature branch branched from dev-2.1. I am looking forward to the draft.

[dyrpsf]

Awesome, thanks @GwennyGit! I will branch off dev-2.1 and start laying down the skeleton for ModelComparisonReport incorporating the dynamic Venn/UpSet logic and the broader annotation overlap. I'll open a draft PR once I have a working prototype for us to iterate on.

[dyrpsf]

Hi @GwennyGit, I have just opened a Draft PR #213 with the initial prototype for the ModelComparisonReport!

It includes the dynamic Venn/UpSet routing and uses a connected-components algorithm to group entities that share any annotation across models, completely bypassing the namespace restrictions.

I'd love to get your thoughts on the core overlap logic and a minor upsetplot bug workaround I had to implement. Once we are aligned on the foundation, I will build out the table generation and save methods!