From 9d33ffc5bcf8a1543ac584b984c271c5b8304750 Mon Sep 17 00:00:00 2001
From: Measrainsey Meng <measrainsey@pm.me>
Date: Wed, 27 Nov 2024 16:39:20 +0100
Subject: [PATCH] Add docstrings for new functions

---
 message_ix_models/tools/costs/decay.py | 47 ++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

diff --git a/message_ix_models/tools/costs/decay.py b/message_ix_models/tools/costs/decay.py
index 66e29bfa8..65e5acd07 100644
--- a/message_ix_models/tools/costs/decay.py
+++ b/message_ix_models/tools/costs/decay.py
@@ -10,6 +10,29 @@
 
 
 def _get_module_scenarios_reduction(module, energy_map_df, tech_map_df):
+    """Get scenarios reduction categories for a module.
+
+    Parameters
+    ----------
+    module : str
+        The module for which to get scenarios reduction categories.
+    energy_map_df : pandas.DataFrame
+        The technology mapping for the energy module.
+    tech_map_df : pandas.DataFrame
+        The technology mapping for the specific module.
+
+    Returns
+    -------
+    pandas.DataFrame
+        DataFrame with columns:
+        - message_technology: name of technology in MESSAGEix
+        - SSP1: scenario reduction category for SSP1
+        - SSP2: scenario reduction category for SSP2
+        - SSP3: scenario reduction category for SSP3
+        - SSP4: scenario reduction category for SSP4
+        - SSP5: scenario reduction category for SSP5
+        - LED: scenario reduction category for LED
+    """
     # Get reduction scenarios for energy module
     scenarios_energy = pd.read_csv(
         package_data_path("costs", "energy", "scenarios_reduction.csv")
@@ -131,9 +154,29 @@ def _get_module_scenarios_reduction(module, energy_map_df, tech_map_df):
     return scenarios_all if module != "energy" else scenarios_energy
 
 
-# do similar in _get_module_scenarios_reduction but for cost_reduction.csv
-# and call it _get_module_cost_reduction
 def _get_module_cost_reduction(module, energy_map_df, tech_map_df):
+    """Get cost reduction values for technologies in a module.
+
+    Parameters
+    ----------
+    module : str
+        The module for which to get cost reduction values.
+    energy_map_df : pandas.DataFrame
+        The technology mapping for the energy module.
+    tech_map_df : pandas.DataFrame
+        The technology mapping for the specific module.
+
+    Returns
+    -------
+    pandas.DataFrame
+        DataFrame with columns:
+        - message_technology: name of technology in MESSAGEix
+        - very_low: cost reduction for "none" scenario
+        - low: cost reduction for "low" scenario
+        - medium: cost reduction for "moderate" scenario
+        - high: cost reduction for "high" scenario
+        - very_high: cost reduction for "very high" scenario
+    """
     # Get cost reduction for energy module
     reduction_energy = pd.read_csv(
         package_data_path("costs", "energy", "cost_reduction.csv"), comment="#"