ValueError following Reporter.add_sankey() with 2+ regions

[khaeru]

@behnam-zakeri reported (here, in IIASA ECE Slack, not public) the following error after using Reporter.add_sankey() added in #770:

import ixmp
from message_ix import Scenario
from message_ix.report import Reporter

mp = ixmp.Platform("ixmp_dev")

# Load the scenario
scen = Scenario(mp, "MESSAGEix-AT", "baseline_3")

# Build a reporter object and make a sankey diagram
rep = Reporter.from_scenario(scen, units={"replace": {"-": ""}})
key = rep.add_sankey(year=2025, node="Austria")
fig = rep.get(key)

…giving:

Traceback (most recent call last):

  Cell In[18], line 1
    fig = rep.get(key)

  File ~\AppData\Local\anaconda3\envs\py311\Lib\site-packages\genno\core\computer.py:691 in get
    raise ComputationError(exc) from None

ComputationError: computing 'sankey figure fb2a75' using:

<Task 'sankey figure fb2a75' sankey(Alias('message sankey fb2a75::1'), Alias('message sankey fb2a75::2'))>

Use Computer.describe(...) to trace the computation.

Computation traceback:
  File "C:\Users\zakeri\AppData\Local\anaconda3\envs\py311\Lib\site-packages\pyam\figures.py", line 48, in sankey
    raise ValueError(f"Non-unique values in column {col}: {levels}")
ValueError: Non-unique values in column region: ['Austria|Austria', 'Austria|GLB', 'GLB|GLB']

This appears to occur because there are (at least) 3 combinations of (node_loc, node_{dest,origin}) in the 'input' and 'output' parameter data that are converted to IAMC data structure and passed on to pyam; and pyam.figures.sankey() cannot handle multiple values in this column.

To resolve, there are several alternatives, not necessarily mutually exclusive:

1. Provide guidance in the docs/tutorial on using rep.set_filters() to exclude nodes/technologies such that there is only 1 unique value in the regions column.
2. Set such filters automatically within Reporter.add_sankey():

   message_ix/message_ix/report/__init__.py

   Lines 279 to 286 in 6ee45ca

   	# Concatenate 'out' and 'in' data
   	self.add(k[0], "concat", "out::pyam", "in::pyam", strict=True)
   	# `df` argument to pyam.figures.sankey()
   	self.add(k[1], partial(IamDataFrame.filter, year=year), k[0])
   	# `mapping` argument to pyam.figures.sankey()
   	self.add(k[2], map_for_sankey, k[1], node=node, exclude=exclude)
   	# Generate the plotly.Figure object; return the key
   	return str(self.add(f"sankey figure {unique}", sankey, k[1], k[2]))

3. Provide 1+ additional step(s) that replace the distinct region values with uniform values.

In any case, a test confirming the bug and fixed behaviour should be added.

Output of message-ix show-versions

ixmp:        3.10.1.dev5+gc2b2729f
     8a762c16 (HEAD -> main) Bump jinja2 from 3.1.5 to 3.1.6 in /doc (#561)
message_ix:  3.10.1.dev12+g3439b1a4.d20250502
     145f4b75 (HEAD -> iiasa_main) Merge pull request #931 from iiasa/issue/927
message_ix_models: 2025.1.10
message_data: 2020.6.21.dev1836+g1142919fe.d20250508
     1142919fe (HEAD -> ecemf-dev-wp1, iiasa/project/ecemf) Adjust softlink to skip combinations without scenario data

click:       8.1.7
dask:        2025.3.0
genno:       installed
graphviz:    0.20.3
jpype:       1.5.2
… JVM path:  C:\Program Files\Amazon Corretto\jdk21.0.7_6\bin\server\jvm.dll
openpyxl:    3.1.4
pandas:      2.2.2
pint:        0.24.3
xarray:      2025.3.1
yaml:        6.0.1

iam_units:   installed
jupyter:     installed
matplotlib:  3.9.1
plotnine:    0.14.5
pyam:        2.2.3

GAMS:        49.4.0

python:      3.11.9 | packaged by conda-forge | (main, Apr 19 2024, 18:27:10) [MSC v.1938 64 bit (AMD64)]
python-bits: 64
OS:          Windows
OS-release:  10
machine:     AMD64
processor:   Intel64 Family 6 Model 94 Stepping 3, GenuineIntel
byteorder:   little
LC_ALL:      None
LANG:        None
LOCALE:      ('English_United States', '1252')