Add .tools.graph_viz_tool

[macflo8]

Following on the 2024-12-12 MESSAGE meeting and #580, this PR aims to add a tool that can visualise a MESSAGEix model structure as a graph.

The initial commit adds the standalone tool developed by @macflo8, which can serve as a basis for a tool that is fully integrated in the message_ix code base. The standalone tool offers two visualisation options:

• a static "RES-style" visualisation that relies on the graphviz package that is similar to the VBA tool mentioned in Support autogeneration of RES data/diagram #580 (comment)
• an interactive graph that relies on the pyvis package that is more suited to visualise a subset of the model

How to review

• The general methodology should be reviewed to make sure the tool is computationally efficient.
• The design should be reviewed to make sure it fits with the patterns used in message_ix.
• The ease of use should be reviewed, to increase the probability that current (and future) message_ix users will actually use it.

PR checklist

• Continuous integration checks all ✅
• Add or expand tests; coverage checks both ✅
• Add, expand, or update documentation.
• Update release notes.

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 22.1%. Comparing base (59f3d82) to head (30c873c).
⚠️ Report is 304 commits behind head on main.

⚠️ Current head 30c873c differs from pull request most recent head cd6a3da

Please upload reports for the commit cd6a3da to get more accurate results.

❗ There is a different number of reports uploaded between BASE (59f3d82) and HEAD (30c873c). Click for more details.

HEAD has 213 uploads less than BASE

Flag	BASE (59f3d82)	HEAD (30c873c)
	216	3

Additional details and impacted files

@@           Coverage Diff            @@
##            main    #906      +/-   ##
========================================
- Coverage   95.6%   22.1%   -73.6%     
========================================
  Files         48      48              
  Lines       4394    4390       -4     
========================================
- Hits        4204     971    -3233     
- Misses       190    3419    +3229     

see 45 files with indirect coverage changes

[khaeru]

Thanks! Let's work together on this branch to address the TODOs from the description.

Some thoughts before jumping in:

1. At the 2025-01-09 MESSAGE team meeting, @OFR-IIASA reminded of a suite of checks that he and @gidden developed for common issues in constructing MESSAGEix models. I mentioned Add .tools.check() #506, still a draft. One of the examples we discussed was the case where there is (potentially) input from/output to a (level, commodity, node, time) that does not have a corresponding source/sink. (This is not necessarily an error, as some such technologies may never need to be active.) This check can be implemented by inspection of the same abstract graph data structure that is used here to make a graphical visualization.
2. In Add .tools.sankey and tutorial #770, the data used is a similar abstract graph, except a weighted graph where the edge weights are the magnitudes of the respective flows. There it is expressed in the IAMC structure particular to pyam.
3. As revealed by Add .tools.sankey and tutorial #770, the RES structure can potentially differ by MESSAGE node and year (period). (This is potentially confusing as a modeling practice, thus discouraged, but the framework does not prevent it.) So we may need to provide similar options here, e.g. select one (node, year) or sum across many.
4. We should be careful in documentation (comments, docstrings, docs, files) to distinguish the "MESSAGE node [set/dimension]" from a "graph node", the common mathematical concept.

[khaeru]

See also this Slack thread in which @Tyler-lc has shared scripts to create interactive Sankey diagrams using the Plotly and Holoviz packages. This adds up to 3 different methods/diagrams that could potentially be integrated here, in addition to the one already merged/released.