WIP: Add AR5 TCR diagnosis definition

notebooks/Diagnose-TCR-ECS.ipynb

@@ -4,7 +4,20 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Diagnosing MAGICC's TCR and ECS"
+    "# Diagnosing MAGICC's TCR and ECS\n",
+    "\n",
+    "The equilibrium climate sensitivity (ECS) is defined as the equilibrium temperature response of the climate system to a doubling of atmospheric CO$_2$ concentrations from pre-industrial levels.\n",
+    "\n",
+    "There can be a little bit of confusion about the definition of the transient climate response (TCR). In particular, in the [Third Assessment Report (TAR)](https://www.ipcc.ch/ipccreports/tar/wg1/345.htm), TCR is defined as\n",
+    "\n",
+    "> the global mean temperature change which occurs at the time of CO$_2$ doubling for the specific case of a 1%/yr increase of CO2 is termed the transient climate response (TCR) of the system.\n",
+    "\n",
+    "However, in the [Fifth Assessment Report (AR5)](http://www.climatechange2013.org/images/report/WG1AR5_Chapter09_FINAL.pdf), TCR is defined as \n",
+    "\n",
+    "> The transient climate response (TCR) is the change in global and annual\n",
+    "mean surface temperature from an experiment in which the CO$_2$ concentration is increased by 1% yr$^{–1}$, and calculated using the difference between the start of the experiment and a 20-year period centred on the time of CO$_2$ doubling.\n",
+    "\n",
+    "Because it seems like the more common and appropriate definition for a simple climate model like MAGICC (which has no internal variability), and for simplicity's sake, we choose to use the definition used in the TAR. "
    ]
   },
   {
@@ -115,7 +128,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python [default]",
    "language": "python",
    "name": "python3"
   },

pymagicc/api.py

@@ -244,7 +244,24 @@ def set_years(self, startyear=1765, endyear=2100):
     def get_executable(self):
         return config["executable_{}".format(self.version)]
 
-    def diagnose_tcr_ecs(self, **kwargs):
+    def diagnose_tcr_ecs(self, method=None, **kwargs):
+        """
+        Diagnose the transient climate response (TCR) and Equilibrium climate sensitivity (ECS)
+
+        # Parameters
+        method (str): If "IPCCTAR" then tcr is diagnosed as the surface warming after 70 years of 1%/yr increases in atmospheric CO$_2$ concentrations, this follows the definition provided in the IPCC's Third Assessment Report. If "IPCCAR5" then tcr is diagnosed as the mean surface warming between years 60 and 80 of 1%/yr increases in atmospheric CO$_2$ concentrations, following the definition provided in the IPCC's Fifth Assessment Report (AR5)
+
+        how do we write defaults in here and this long docstring properly?
+
+        # Returns
+        results (dict): Dictionary containing the results with keys:
+            - tcr: diagnosed tcr value (K)
+            - ecs: diagnosed tcr value (K)
+            - timeseries: timeseries used to diagnose tcr and ecs
+        """
+        if method is not None:
+            raise NotImplementedError("WIP")
+
         self._diagnose_tcr_ecs_config_setup(**kwargs)
         timeseries = self.run(
             only=["CO2_CONC", "TOTAL_INCLVOLCANIC_RF", "SURFACE_TEMP"]
@@ -255,7 +272,7 @@ def diagnose_tcr_ecs(self, **kwargs):
     def _diagnose_tcr_ecs_config_setup(self, **kwargs):
         self.set_years(
             startyear=1750, endyear=4200
-        )  # 4200 seems to be the max I can push too without an error
+        )  # 4200 seems to be the max I can push to without an error
 
         self.set_config(
             FILE_CO2_CONC="TCRECS_CO2_CONC.IN",

tests/test_api.py

@@ -356,16 +356,25 @@ def test_check_tcr_ecs_temp(valid_tcr_ecs_diagnosis_results, magicc_base):
 
 # integration test (i.e. actually runs magicc) hence slow
 @pytest.mark.slow
-def test_integration_diagnose_tcr_ecs(package):
-    actual_result = package.diagnose_tcr_ecs()
+@pytest.mark.parametrize("diagnosis_method,expected_tcr,expected_ecs", [
+    (None, 1.9733976000000002, 2.9968448),
+    ("IPCCTAR", 1.9733976000000002, 2.9968448),
+    ("IPCCAR5", 1.0, 2.0),
+])
+def test_integration_diagnose_tcr_ecs(package, diagnosis_method, expected_tcr, expected_ecs):
+    if diagnosis_method is None:
+        actual_result = package.diagnose_tcr_ecs()
+    else:
+        actual_result = package.diagnose_tcr_ecs(method=diagnosis_method)
     assert isinstance(actual_result, dict)
     assert "tcr" in actual_result
     assert "ecs" in actual_result
     assert actual_result["tcr"] < actual_result["ecs"]
     if isinstance(package, MAGICC6):
         assert (
-            actual_result["tcr"] == 1.9733976000000002
+            actual_result["tcr"] == expected_tcr
         )  # MAGICC6 shipped with pymagicc should be stable
         assert (
-            actual_result["ecs"] == 2.9968448
+            actual_result["ecs"] == expected_ecs
         )  # MAGICC6 shipped with pymagicc should be stable
+