sanitary-issues: utils.py with EU27 codes, country name mapping, README stats docs, fix copilot-instructions Code Structure

[Copilot]

Several housekeeping items: new utils.py for shared static data, EU27 country code → full name resolution in pyam.IamDataFrame, documentation for the statistics function contract, and corrected Code Structure diagram in copilot instructions.

Changes

• pypsa_validation_processing/utils.py (new)
  EU27 member state mapping (ISO 2-letter → full name) plus "EU27_{year}" aggregate, mirroring the eurostat-energy-balance_processing sister package.

• class_definitions.py
  Resolves the long-standing TODO — region=self.country is replaced with a lookup against EU27_COUNTRY_CODES:

  region=EU27_COUNTRY_CODES.get(self.country, self.country),

  Falls back to the raw code if not in the mapping.

• README.md
  New Variable Statistics section documenting the fixed function contract:

  • Naming convention: | → __, spaces → _
  • Input: n: pypsa.Network
  • Output: pd.Series with multi-level index including a "unit" level
  • Role of mapping.default.yaml

• .github/copilot-instructions.md (Code Structure section only)

  • Adds utils.py node to the class diagram
  • Fixes method name typos: structure_pyan_from_pandas → structure_pyam_from_pandas, calculate_variable_values → calculate_variables_values
  • Corrects dsd_with_values: dict → dsd_with_values: pyam.IamDataFrame | None
  • Adds missing _postprocess_statistics_result() method

• tests/test_utils.py (new)
  Unit tests for EU27_COUNTRY_CODES completeness, sample values, aggregate key, and type constraints.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>sanitary-issues</issue_title>
<issue_description>- [ ] create a new file utils.py, that is ment to include static informations and general utils-functions.

• integrate EU27 country codes for the pyam.IamDataFrame
  • same structure as in eurostat-energy-balance_processing here
  • integrate this mapping here, so that eg. instead of "AT", region= "Austria", using the mapping.
• add a comprehensive Documentation in README for variable statistics including
  • convention on naming of function
  • input to function (fixed!)
  • output-structure (also fixed!)
  • role of the mapping-file
• update Code structure in copilot-instructions.md to current structure here, therefore only manipulate this section of the copilot-instructions.md-file!</issue_description>

<agent_instructions>create a pull request with this implementations to branch 5-create-minimal-set-of-variable-functions-for-final-energy</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes sanitary-issues #7

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

[maxnutz]

All review changes already directly integrated in last commits.