feat: use transformer number assumptions during transmission building

prereise/gather/griddata/hifld/data/transformer_number_assumptions.csv

@@ -0,0 +1,5 @@
+sub_id,low_kV,high_kV,number
+300060,69,138,4
+300940,69,138,2
+304621,69,138,3
+308608,69,138,3

prereise/gather/griddata/hifld/data_process/transmission.py

@@ -12,6 +12,7 @@
 from prereise.gather.griddata.hifld.data_access.load import (
     get_hifld_electric_power_transmission_lines,
     get_hifld_electric_substations,
+    get_transformer_number_overrides,
     get_transformer_parameters,
     get_zone,
 )
@@ -539,7 +540,9 @@ def create_buses(lines):
     return buses
 
 
-def create_transformers(bus, lines, transformer_designs):
+def create_transformers(
+    bus, lines, transformer_designs, transformer_number_assumptions=None
+):
     """Add transformers between buses within the same substation. The assumed topology
     is that the highest-voltage bus in each substation is connected via a tansformer to
     every other voltage.
@@ -549,21 +552,37 @@ def create_transformers(bus, lines, transformer_designs):
     :param pandas.DataFrame transformer_designs: representative transformer data. Index
         is (low_kV, high_kV), columns are 'x', 'r', and 'MVA'. 'x' and 'r' values are
         per-unit, 'MVA' is in megawatts.
+    :param pandas.Series transformer_number_assumptions: assumptions about the number
+        of transformers between any two buses. The index should be a MultiIndex of
+        (sub_id, low_kV, high_kV), and values are integer. If None, this parameter will
+        not be used.
     :return: (*pandas.DataFrame*) -- each row is one transformer, columns are
         ["from_bus_id", "to_bus_id", "x", "r", and "rateA"].
     """
-    bus_pairs = [
-        (b, volt_series.sort_values().index[i + 1])
+    bus_pair_data = [
+        {
+            "sub_id": sub,
+            "from_bus_id": b,
+            "to_bus_id": volt_series.sort_values().index[i + 1],
+            "from_kV": bus.loc[b, "baseKV"],
+            "to_kV": bus.loc[volt_series.sort_values().index[i + 1], "baseKV"],
+        }
         for sub, volt_series in bus.groupby("sub_id")["baseKV"]
         for i, b in enumerate(volt_series.sort_values().index[:-1])
         if len(volt_series) > 1
     ]
-    bus_pairs_df = pd.DataFrame(bus_pairs, columns=["from_bus_id", "to_bus_id"])
-    transformer_details = bus_pairs_df.apply(
+    bus_pairs_df = pd.DataFrame(bus_pair_data)
+    transformer_details = bus_pairs_df[["from_bus_id", "to_bus_id"]].apply(
         lambda x: estimate_transformers(x, lines, bus["baseKV"], transformer_designs),
         axis=1,
     )
     single_transformers = pd.concat([bus_pairs_df, transformer_details], axis=1)
+    if transformer_number_assumptions is not None:
+        single_transformers["number"].update(
+            single_transformers[["sub_id", "from_kV", "to_kV"]]
+            .apply(tuple, axis=1)
+            .map(transformer_number_assumptions)
+        )
     repeated_transformers = single_transformers.drop(columns="number").reindex(
         single_transformers.index.repeat(single_transformers["number"])
     )
@@ -831,6 +850,9 @@ def build_transmission(method="line2sub", **kwargs):
     hifld_data_dir = os.path.join(os.path.dirname(__file__), "..", "data")
     hifld_zones = get_zone(os.path.join(hifld_data_dir, "zone.csv"))  # noqa: F841
     transformer_designs = get_transformer_parameters(hifld_data_dir)
+    transformer_number_assumptions = get_transformer_number_overrides(
+        os.path.join(hifld_data_dir, "transformer_number_assumptions.csv")
+    )
 
     # Filter substations based on their `LINES` attribute, check for location dupes
     hifld_substations.loc[const.substations_lines_filter_override, "LINES"] = None
@@ -908,7 +930,9 @@ def build_transmission(method="line2sub", **kwargs):
     add_substation_info_to_buses(bus, substations, hifld_zones)
 
     # Add transformers, and calculate rating and impedance for all branches
-    transformers = create_transformers(bus, ac_lines, transformer_designs)
+    transformers = create_transformers(
+        bus, ac_lines, transformer_designs, transformer_number_assumptions
+    )
     transformers["type"] = "Transformer"
     transformers["interconnect"] = transformers["from_bus_id"].map(bus["interconnect"])
     first_new_id = ac_lines.index.max() + 1