Merge pull request #25 from ecmwf-projects/running_window

Added running window functionality for all debiasers

docs/source/getting_started/overview.rst

@@ -18,25 +18,27 @@ Overview
 
 ibicus currently implements eight state of the art methods for bias adjustment published in peer-reviewed literature, including ISIMIP (Lange 2019) and CDFt (Michelangeli et al. 2009). The package enables the user to modify and refine their settings and parameters, and provides an evaluation framework to assess marginal, temporal, spatial, and multivariate properties as well as a range of climate indices of the bias adjusted climate model.
 
-You can find an introduction-video for ibicus `here <https://www.youtube.com/watch?v=n8QlGLU2gIo>`_.
+You can find an introduction-video to ibicus `here <https://www.youtube.com/watch?v=n8QlGLU2gIo>`_.
 
 What is bias adjustment?
 ------------------------
 
-The bias adjustment or bias correction of climate models is a tricky business: although climate models have gained impressive skill over the recent years, they are still prone to biases. By ‘bias’, we here mean a systematic discrepancy between the simulated climate statistic and the corresponding real-world statistic over a historical period. These biases could be due to unresolved topography, processes such as convection occurring below grid-cell level, or the misplacement of large-scale atmospheric patterns. Bias adjustment cannot fundamentally address these issues. What bias adjustment can do is calibrate an empirical transfer function between simulated and observed distributional parameters in order to improve (“bias adjust”) the climate model.
+Even though climate models have gained impressive skill over the recent years, simulations of both global and regional climate models still exhibit biases. This means that there are systematic discrepancies between statistics of the model output and observational distribution. These discrepancies in the two distributions become especially relevant when using the output of climate models for local impact studies that often require focus on specific threshold metrics such as dry days.
 
-Because experiments with the climate are not possible, and climate models are our only way of finding out what the implications of different scenarios of climatic change are, bias adjustment not only is a useful and necessary step but has de-facto become a standard in climate impact studies.
+Biases could be due to unresolved topography, the parametrization of processes such as convection occurring below grid-cell level, or the misplacement of large-scale atmospheric patterns. Bias adjustment cannot fundamentally address these issues. Rather, bias adjustment calibrates a statistical transfer function between simulated and observed distributional parameters in order to improve (“bias adjust”) the climate model. While bias adjustment can reduce the location-wise bias of the climate model in many cases, the approach is also prone to misuse and can introduce changes in the spatial, temporal and multivariate structure of the climate model as well as the climate change trend. Nevertheless, bias adjustment has de-facto become a standard pre-processing step in climate impact studies.
 
-For more info have a look at: `What is bias adjustment? <whatisdebiasing.html>`_
+For a more detailed introduction, as well as an overview of relevant literature on existing methods and issues, we refer to our paper recently published in Geoscientific Model Development:
+
+How to cite: Spuler, F. R., Wessel, J. B., Comyn-Platt, E., Varndell, J., and Cagnazzo, C.: ibicus: a new open-source Python package and comprehensive interface for statistical bias adjustment and evaluation in climate modelling (v1.0.1), EGUsphere [preprint], https://doi.org/10.5194/egusphere-2023-1481, 2023.
 
 What is ibicus?
 ---------------
 
 *A user-friendly toolkit to bias adjust climate models…*
 
-A variety of methods exist for bias adjustin climate models. Some are better suited for certain variables; others will introduce modifications to the climate change trend while others are explicitly trend-preserving. ibicus provides a unified interface for applying a variety of different methods (8 currently) for bias adjustment published in peer reviewed literature.
+A variety of methods have been developed for the bias adjustment of climate models. Some are better suited for certain variables; others will introduce modifications to the climate change trend while others are explicitly trend-preserving. ibicus provides a unified interface for applying a variety of different methods (8 currently) for bias adjustment published in peer reviewed literature.
 
-Given climate model data: during a reference period (``cm_hist``) and future / application period (``cm_future``) as well as observations or reanalysis data during the reference period (``obs``), ibicus provides a straightforward user-interface for initializing and applying a bias adjustment method:
+Given climate model data: during a reference period (``cm_hist``) and future / application period (``cm_future``) as well as observations or reanalysis data during the reference period (``obs``), ibicus provides a standardized user-interface for initializing and applying a bias adjustment method, for example ISIMIP:
 
 >>> from ibicus import ISIMIP
 >>> debiaser = ISIMIP.from_variable("tas")
@@ -81,7 +83,7 @@ The methods currently implemented in ibicus include:
      - * Maraun 2016
      - Delta Change applies the trend from historical to future climate model to the observations. Although technically not a bias adjustment method, as no transformation is applied to the climate model, it is included here as it provides an adjusted future climatology.
 
-Users can adapt the settings of different debiasers to adapt them to their use-case, for example:
+Users can modify the settings of different debiasers to adapt them to their use-case, for example:
 
 >>> pr_debiaser1 = QuantileMapping.for_precipitation(model_type = "hurdle")
 >>> pr_debiaser2 = pr_debiaser2 = QuantileMapping.for_precipitation(model_type = "censored")
@@ -92,8 +94,6 @@ Bias adjustment is prone to misuse and can generate seemingly meaningful results
 
 ibicus includes a framework that enables the user to conduct this evaluation as part of the bias adjustment process. The evaluation framework consists of three parts:
 
-- Assumptions testing: this component helps the user check some assumptions underlying the use of different bias adjustment methods to choose the most appropriate method and refine its parameters.
-
 - Evaluation of the method on a validation period: This component enables the user to compare the bias corrected model to the ‘raw’ model and observations / reanalysis data, all on a chosen validation period. Both statistical properties as well as threshold based climate indices (threshold metrics) such as dry days, hot days, etc. that are often used for calculating climate impacts can be compared. The following table summarises the types of analysis that can be conducted in this component:
 
 +----------------+------------------------+-----------------------+
@@ -112,14 +112,16 @@ ibicus includes a framework that enables the user to conduct this evaluation as
 
 - Analysis of trend preservation: Bias adjustment can significantly modify the trend projected in the climate model simulation. This component helps the user assess whether a certain method preserves the climate model trend or not, in order to provide the basis for an informed choice on whether trend modification is desirable for the application at hand.
 
-What ibicus is not?
+- Assumptions testing: this component helps the user check some assumptions underlying the use of different bias adjustment methods to choose the most appropriate method and refine its parameters.
+
+What is ibicus not?
 -------------------
 
 After trying to convince you of the advantages of using ibicus, we also want to alert you to what ibicus currently does not do:
 
-1. ibicus does not currently support multivariate bias adjustment, meaning the correction of spatial or inter-variable structure. Whether or not to correct for example the inter-variable structure, which could be seen as an integral feature of the climate model, is a contentious and debated topic of research. If such correction is necessary, the excellent `MBC <https://cran.r-project.org/web/packages/MBC/index.html>`_ or `SBCK <https://github.com/yrobink/SBCK>`_ package are suitable solutions. We refer to Maraun 2016 for a discussion of some of the issues around multivariate bias adjustment. |brr|
+1. ibicus offers a multivariate evaluation of the bias adjusted climate model but does not currently support multivariate bias adjustment, meaning the correction of spatial or inter-variable structure. Whether or not to correct for example the inter-variable structure, which could be seen as an integral feature of the climate model, is a contentious and debated topic of research. If such correction is necessary, the excellent `MBC <https://cran.r-project.org/web/packages/MBC/index.html>`_ or `SBCK <https://github.com/yrobink/SBCK>`_ package are suitable solutions. For a more detailed discussion of the advantages and possible drawbacks of multivariate bias adjustment we refer to Spuler et al. (2023) cited above. |brr|
 
-2. ibicus is not suitable for 'downscaling' the climate model which is a term for methods used to increase the spatial resolution of climate models. Although bias adjustments methods have been used for downscaling, in general they are not appropriate, since they do not reproduce the local scale variability that is crucial on those scales. Maraun 2016 argues that for downscaling, stochastic methods have great advantages. An example of a package addressing the problem of downscaling is: `Rglimclim <https://www.ucl.ac.uk/~ucakarc/work/glimclim.html>`_. |brr|
+2. ibicus is not suitable for 'downscaling' the climate model which is a term for methods used to increase the spatial resolution of climate models. Although bias adjustment methods have been used for downscaling, in general they are not appropriate, since they do not reproduce the local scale variability that is crucial on those scales. Maraun 2016 argues that for downscaling, stochastic methods have great advantages. An example of a package addressing the problem of downscaling is: `Rglimclim <https://www.ucl.ac.uk/~ucakarc/work/glimclim.html>`_. |brr|
 
 3. 'Garbage in, garbage out'. ibicus cannot guarantee that the climate model is suitable for the problem at hand. As mentioned above, although bias adjustment can help with misspecifications, it cannot solve fundamental problems within climate models. The evaluation framework can help you identify whether such fundamental issues exist in the chosen climate model. However, this cannot replace careful climate model selection before starting a climate impact study. |brr|
 
@@ -134,7 +136,16 @@ Jakob Wessel is a PhD student at the University of Exeter where he is working on
 Get in touch
 ------------
 
-This project was conducted as part of the ESoWC challenge 2022. If you have suggestions on additional methods we could add, questions you'd like to ask, issues that you are finding in the application of the methods that are already implemented, or bugs in the code, please contact us under ibicus.py@gmail.com or `raise an issue on github <https://github.com/ecmwf-projects/ibicus/issues>`_.
+If you have suggestions on additional methods we could add, questions you'd like to ask, issues that you are finding in the application of the methods that are already implemented, or bugs in the code, please contact us under ibicus.py@gmail.com or `raise an issue on github <https://github.com/ecmwf-projects/ibicus/issues>`_.
+
+
+Cite the package
+----------------
+
+If you use ibicus for your research, please cite our publication in Geoscientific Model Development:
+
+Spuler, F. R., Wessel, J. B., Comyn-Platt, E., Varndell, J., and Cagnazzo, C.: ibicus: a new open-source Python package and comprehensive interface for statistical bias adjustment and evaluation in climate modelling (v1.0.1), EGUsphere [preprint], https://doi.org/10.5194/egusphere-2023-1481, 2023.
+
 
 References
 ----------

docs/source/getting_started/whatisdebiasing.rst

@@ -15,16 +15,13 @@ convection processes, due to misplacement of large scale processes such as the m
 or many other factors. These model errors then manifest as discrepancies in the values and statistical properties of meteorological variables.
 With biases in place it can be difficult to use this 'raw' climate model output to project real-world impact of climate change.
 
-This is where 'bias adjustment' methods come in, which have now become standard procedure for many climate impact studies.
-The general idea behind bias adjustment is to calibrate an empirical transfer function between simulated and observed distribution,
-that can be used to adjust the climate model output.
+'Bias adjustment' methods, which have now become a standard pre-processing step for climate impact studies, calibrate an empirical transfer function
+between simulated and observed distribution over a historical period that can be used to adjust the climate model output over a future period.
 
-A broad overview of existing methods for bias adjustment
---------------------------------------------------------
+Overview of existing methods for bias adjustment
+------------------------------------------------
 
-A variety of different methods for bias adjustment have been developed over the years. We will just give a very brief overview here --
-for a detailed explanation of the specific bias adjustment methods implemented in this package, please have a look at the `documentation of the
-debiaser class <../reference/debias.html>`_.
+This section provides a brief overview of different methods for bias adjustment that have been developed over the years. For a more detailed overview see the ibicus paper (Spuler et al. 2023), and for a more in-depth explanation of the specific bias adjustment methods implemented in this package and options for modifying them, please have a look at the `documentation of the debiaser class <../reference/debias.html>`_. For a more detailed general overview of different methods see Spuler et al 2023.
 
 Two simple methods include the delta method (adding or multiplying a climate change signal to historical observational data) and
 linear scaling (calculating the present-day bias in mean and variance, leaving the ratio constant and applying it to the future climate model output).
@@ -35,13 +32,12 @@ terms of the fit, but can run into issues of overfitting, whilst parametric meth
 extrapolation outside of observed quantiles (Themeßl et al. 2012) but obviously need the fit to be good enough to produce meaningful results.
 One issue with quantile mapping is that it is in general not trend preserving.
 
-More complex methods include for example Quantile Delta Mapping, CDFt, Equidistant CDF Matching or the ISIMIP3BASD approach. Those
-are oftentimes trend preserving in the mean and other quantiles. The methods are most of the time based on some form of quantile
-mapping as core, but with different additional adjustments. They also have different assumptions. For an overview of the inner workings
-of those and some other methods, please have a look at the :py:mod:`debias`-module.
+A range of more complex methods build on quantile mapping in different ways: these include Quantile Delta Mapping, CDFt, Equidistant CDF Matching or the ISIMIP3BASD approach. Those
+are oftentimes trend preserving in the mean and other quantiles, based on different assumptions. For an overview of the inner workings
+of these and other methods, please have a look at the :py:mod:`debias`-module.
 
-The methods named so far all provide univariate bias adjustment: meaning they work location-wise and do not provide an adjustment of
-either spatial or inter-variable structure. Also, multivariate and spatial quantile mapping methods exist (eg. Vrac et al. 2015) -- allowing for the
+The methods named so far all implement univariate bias adjustment, meaning they work location-wise and do not provide an adjustment of
+either spatial or inter-variable structure. Multivariate and spatial quantile mapping methods exist (eg. Vrac et al. 2015) -- allowing for the
 correction of dependences, next to marginal properties, for multiple meteorological variables, or singular ones at multiple locations.
 Whether or not to correct for example the inter-variable structure, which could be seen as an integral feature of the climate model, and how such a correction could be evaluated
 is a contentious and debated topic of research. If such correction is necessary, the excellent
@@ -63,10 +59,14 @@ feedback such as a misrepresentation of regional responses to large-scale proces
 cannot correct fundamental misrepresentations of the climate model. We refer to Maraun et al. 2017 for a good overview of issues with bias adjustment
 and an appeal to place a solid understanding of the process meant to be bias corrected at the center of any bias adjustment exploration.
 
-Further limitations include the assumptions that exploring the climate model bias of today can tell us anything about the bias the simulations
-of the climate model into the future has under different scenarios (i.e. that the bias is stationary), as well as the issues with observational
+Further limitations include the assumption that the climate model bias of today can tell us anything about the bias the simulations
+of the climate model in the future (i.e. that the bias is stationary), as well as biases and errors in the observational
 and reanalysis data, that is often used to bias correct.
 
+Applying ibicus in a case study over the Mediterranean region using seven CMIP6 global circulation models, Spuler et al (2023) find that the most appropriate bias adjustment method depends on the variable and impact studied. This finding highlight the importance of a use-case-specific choice of method and the need for a rigorous multivariate evaluation of results when applying statistical bias adjustment. Furthermore, the authors find and that even methods that aim to preserve the climate change trend can modify it.
+
+
+
 
 The importance of evaluation as well as climate model and method selection
 --------------------------------------------------------------------------
@@ -98,5 +98,6 @@ See also
 - Maraun, D. (2013). Bias Correction, Quantile Mapping, and Downscaling: Revisiting the Inflation Issue. In Journal of Climate (Vol. 26, Issue 6, pp. 2137–2143). American Meteorological Society. https://doi.org/10.1175/jcli-d-12-00821.1
 - Maraun, D. Bias Correcting Climate Change Simulations - a Critical Review. Curr Clim Change Rep 2, 211–220 (2016). https://doi.org/10.1007/s40641-016-0050-x
 - Maraun, D., Shepherd, T. G., Widmann, M., Zappa, G., Walton, D., Gutiérrez, J. M., Hagemann, S., Richter, I., Soares, P. M. M., Hall, A., & Mearns, L. O. (2017). Towards process-informed bias correction of climate change simulations. In Nature Climate Change (Vol. 7, Issue 11, pp. 764–773). Springer Science and Business Media LLC. https://doi.org/10.1038/nclimate3418
+- Spuler, F. R., Wessel, J. B., Comyn-Platt, E., Varndell, J., and Cagnazzo, C.: ibicus: a new open-source Python package and comprehensive interface for statistical bias adjustment and evaluation in climate modelling (v1.0.1), EGUsphere [preprint], https://doi.org/10.5194/egusphere-2023-1481, 2023.
 - Themeßl, M. J., Gobiet, A., & Heinrich, G. (2011). Empirical-statistical downscaling and error correction of regional climate models and its impact on the climate change signal. In Climatic Change (Vol. 112, Issue 2, pp. 449–468). Springer Science and Business Media LLC. https://doi.org/10.1007/s10584-011-0224-4
 - Vrac, M., & Friederichs, P. (2014). Multivariate—Intervariable, Spatial, and Temporal—Bias Correction*. In Journal of Climate (Vol. 28, Issue 1, pp. 218–237). American Meteorological Society. https://doi.org/10.1175/jcli-d-14-00059.1