refactor: sort functions in clean_projects (#803)

* refactor: sort functions in clean_projects

* doc: add release note

* doc: add missing docstrings

* Apply suggestions from code review

Co-authored-by: Daniel Rüdt <117752024+daniel-rdt@users.noreply.github.com>

---------

Co-authored-by: Daniel Rüdt <117752024+daniel-rdt@users.noreply.github.com>

Author: tgilon

doc/release_notes.md

@@ -87,6 +87,8 @@
 
 * Reduce dependency on upstream retrieves ([#798](https://github.com/open-energy-transition/open-tyndp/pull/798)).
 
+* Sort functions in `clean_projects` into a logical order ([#803](https://github.com/open-energy-transition/open-tyndp/pull/803)).
+
 
 ## Upcoming PyPSA-Eur Release
 

scripts/cba/clean_projects.py

@@ -7,21 +7,25 @@
 Reads transmission projects from the "Trans.Projects" sheet of the CBA projects Excel file.
 For projects with multiple borders (newline-separated in the Excel), the script explodes
 these into separate rows, creating one row per border. Bus codes are extracted from the
-border strings (expected format: "BUS0-BUS1") and projects that don't match this format
-are filtered out with a warning.
+border strings (expected format: "BUS0-BUS1") and rows are filtered out with a warning
+when the format does not match, when either bus is absent from the TYNDP node list, or
+when no capacity is reported in either direction.
 
 Storage project extraction is not yet implemented and returns an empty DataFrame.
 
 **Inputs**
 
 - `data/tyndp_2024_bundle/cba_projects/20250312_export_transmission.xlsx`: Excel file containing CBA transmission projects
 - `data/tyndp_2024_bundle/cba_projects/20250312_export_storage.xlsx`: Excel file containing CBA storage projects (not yet processed)
+- `rules.retrieve_tyndp.output.nodes`: TYNDP electricity node list used to validate borders
+- `rules.retrieve_cba_guidelines_reference_projects.output.file`: Table of projects as defined in the Implementation Guidelines Appendix B.1
 
 **Outputs**
 
 - `resources/cba/transmission_projects.csv`: Cleaned CSV with columns:
   - `project_id`: Integer project identifier
   - `project_name`: Project name
+  - `is_crossborder`: Whether the project is reported as cross-border
   - `border`: Border string in format "BUS0-BUS1"
   - `p_nom 0->1`: Transfer capacity increase from bus0 to bus1 (MW)
   - `p_nom 1->0`: Transfer capacity increase from bus1 to bus0 (MW)
@@ -33,6 +37,8 @@
 
 - `resources/cba/storage_projects.csv`: Empty CSV with columns project_id and project_name (stub implementation)
 
+- `resources/cba/cba_project_methods.csv`: Table defining the assignment method of each project.
+
 """
 
 import logging
@@ -59,48 +65,58 @@
 }
 
 
-def extract_investment_attributes(excel_path: Path) -> pd.DataFrame:
+def read_tyndp_electricity_buses(buses_fn: str) -> pd.Index:
     """
-    Extract length, CAPEX, and underwater fraction from Trans.Investments sheet.
+    Read the list of electricity nodes from the TYNDP input data.
 
-    Aggregates investment-level data to the project level by summing route
-    lengths and CAPEX, and computing the underwater fraction from offshore
-    cable lengths.
-    """
-    inv = pd.read_excel(
-        excel_path,
-        sheet_name="Trans.Investments",
-        skiprows=1,
-        usecols=[
-            "This investment belongs to project number…",
-            "Total route length (km)",
-            "Estimated CAPEX (MEUR)",
-            "Type of Element",
-        ],
-    ).rename(
-        columns={
-            "This investment belongs to project number…": "project_id",
-            "Total route length (km)": "length_km",
-            "Estimated CAPEX (MEUR)": "capex_meur",
-            "Type of Element": "element_type",
-        }
-    )
+    Parameters
+    ----------
+    buses_fn : str
+        Path to the list of nodes from the TYNDP bundle.
 
-    is_offshore = inv["element_type"].isin(OFFSHORE_ELEMENT_TYPES)
+    Returns
+    -------
+    pd.Index
+        Electricity buses as used in Open-TYNDP.
 
-    agg = inv.groupby("project_id").agg(
-        length_km=("length_km", "sum"),
-        capex_meur=("capex_meur", "sum"),
+    See Also
+    --------
+    build_tyndp_network.build_buses
+    """
+    buses = pd.Index(
+        pd.read_excel(buses_fn)
+        .replace("UK", "GB", regex=True)
+        .rename({"NODE": "bus_id"}, axis=1)["bus_id"]
     )
-    offshore_km = inv.loc[is_offshore].groupby("project_id")["length_km"].sum()
-    agg["underwater_fraction"] = (offshore_km / agg["length_km"]).fillna(0).round(3)
 
-    return agg
+    # Manually add Italian virtual nodes
+    buses = buses.union(["ITCO", "ITVI"])
+
+    return buses
 
 
 def extract_transmission_projects(
     excel_path: Path, existing_buses: pd.Index
 ) -> pd.DataFrame:
+    """
+    Read and clean the transmission projects from the "Trans.Projects" sheet.
+
+    Projects reporting several expected capacity increases are exploded into one row per
+    border. Rows are dropped when the border cannot be parsed or when no capacity is
+    reported in either direction.
+
+    Parameters
+    ----------
+    excel_path : Path
+        Path to the Excel export defining the transmission projects.
+    existing_buses : pd.Index
+        Electricity buses as used in Open-TYNDP.
+
+    Returns
+    -------
+    pd.DataFrame
+        List of projects with their detailed characteristics. One row per project and border.
+    """
     projects = (
         pd.read_excel(
             excel_path,
@@ -183,6 +199,55 @@ def extract_transmission_projects(
     return projects
 
 
+def extract_investment_attributes(excel_path: Path) -> pd.DataFrame:
+    """
+    Extract length, CAPEX, and underwater fraction from Trans.Investments sheet.
+
+    Aggregates investment-level data to the project level by summing route
+    lengths and CAPEX, and computing the underwater fraction from offshore
+    cable lengths.
+
+    Parameters
+    ----------
+    excel_path : Path
+        Path to the Excel export defining the transmission projects and their investment attributes.
+
+    Returns
+    -------
+    pd.DataFrame
+        Route length, CAPEX and underwater fraction per project, indexed by ``project_id``.
+    """
+    inv = pd.read_excel(
+        excel_path,
+        sheet_name="Trans.Investments",
+        skiprows=1,
+        usecols=[
+            "This investment belongs to project number…",
+            "Total route length (km)",
+            "Estimated CAPEX (MEUR)",
+            "Type of Element",
+        ],
+    ).rename(
+        columns={
+            "This investment belongs to project number…": "project_id",
+            "Total route length (km)": "length_km",
+            "Estimated CAPEX (MEUR)": "capex_meur",
+            "Type of Element": "element_type",
+        }
+    )
+
+    is_offshore = inv["element_type"].isin(OFFSHORE_ELEMENT_TYPES)
+
+    agg = inv.groupby("project_id").agg(
+        length_km=("length_km", "sum"),
+        capex_meur=("capex_meur", "sum"),
+    )
+    offshore_km = inv.loc[is_offshore].groupby("project_id")["length_km"].sum()
+    agg["underwater_fraction"] = (offshore_km / agg["length_km"]).fillna(0).round(3)
+
+    return agg
+
+
 def extract_storage_projects(
     excel_path: Path, existing_buses: pd.Index
 ) -> pd.DataFrame:
@@ -209,6 +274,22 @@ def compute_method(flag: str) -> str:
 def build_method_assignments(
     guidelines: pd.DataFrame, projects: pd.DataFrame
 ) -> pd.DataFrame:
+    """
+    Define the assignment method of the project. Can be TOOT (Take Out One at a Time) or PINT (Put IN one at a Time).
+    Leverage the Implementation Guidelines to define the method.
+
+    Parameters
+    ----------
+    guidelines : pd.DataFrame
+        Table of projects as defined in the Implementation Guidelines Appendix B.1.
+    projects: pd.DataFrame
+        List of projects with their detailed characteristics.
+
+    Returns
+    -------
+    pd.DataFrame
+        Table defining the assignment method of each project.
+    """
     guidelines = guidelines.rename(
         columns={
             "ID": "project_id",
@@ -262,34 +343,6 @@ def build_method_assignments(
     return projects.merge(assigned, on="project_id", how="left")
 
 
-def read_tyndp_electricity_buses(buses_fn: str):
-    """
-    Read node list for electricity from tyndp data input.
-
-    Parameters
-    ----------
-        - buses_fn (str): Path to "LIST OF NODES.xlsx" from tyndp bundle
-
-    Returns
-    -------
-        - buses: Index of electricity buses as used in Open-TYNDP
-
-    See Also
-    --------
-        build_tyndp_network.py : build_buses
-    """
-    buses = pd.Index(
-        pd.read_excel(buses_fn)
-        .replace("UK", "GB", regex=True)
-        .rename({"NODE": "bus_id"}, axis=1)["bus_id"]
-    )
-
-    # Manually add Italian virtual nodes
-    buses = buses.union(["ITCO", "ITVI"])
-
-    return buses
-
-
 if __name__ == "__main__":
     if "snakemake" not in globals():
         from scripts._helpers import mock_snakemake