Add a function to initialize an IamDataFrame form an ixmp4 Run

[danielhuppmann]

Please confirm that this PR has done the following:

• Tests Added
• Documentation Added
• Name of contributors Added to AUTHORS.rst
• Description in RELEASE_NOTES.md Added

Description of PR

This PR adds a function to initialize an IamDataFrame directly from an ixmp4.Run, to enable workflows like

platform = ixmp4.Platform("<platform_name>")

run = platform.runs.get("<model>", "<scenario>")
df = pyam.ixmp4.read_run(run, **filters)

# .. some computation to yield `processed_df`

with run.transact("Some message"):
    run.iamc.add(processed_df)

This is an alternative to the currently possible approach

df = pyam.read_ixmp4(
    platform,
    model="<model>",
    scenario="<scenario>",
    **filters,
)

[codecov]

Codecov Report

❌ Patch coverage is 93.75000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 94.8%. Comparing base (1e05b97) to head (6e52909).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
pyam/ixmp4.py	87.5%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##            main    #938     +/-   ##
=======================================
- Coverage   94.8%   94.8%   -0.1%     
=======================================
  Files         68      68             
  Lines       6458    6474     +16     
=======================================
+ Hits        6128    6143     +15     
- Misses       330     331      +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[phackstock]

Looks good to me.
Two small questions below but good to be merged either way.

[phackstock]

Is there a special reason to not put the import at the top of the file?

[danielhuppmann]

There’s a circular dependency. The IamDataFrame in core.py imports the function for writing to an ixmp4 Platform, but the functions read_ixmp4 and read_ixmp4_runshould be exposed as top-level functions.

[phackstock]

Ah ok, maybe there's a good way to rearrange some code to get rid of the circular dependency but that's a job for another day.

[phackstock]

Is this a feature that will be implemented at some point? Otherwise you could also leave year out as one of the input options.

[danielhuppmann]

Yes, that’s on my to-do list.

[phackstock]

Ah alright, python should have a NotImplementedYetError or an IllGetToItError.

[danielhuppmann]

I started working on adding this to the documentation, but found some larger issues, so I will do a follow-up PR with a doc-restructuring.

[danielhuppmann]

Refactor to pyam.ixmp4.read_run() as discussed with @phackstock.