readthedocs update

CHANGELOG.md

@@ -58,7 +58,8 @@ updated:
 [#620](https://github.com/CLIMADA-project/climada_python/pull/620),
 [#615](https://github.com/CLIMADA-project/climada_python/pull/615),
 [#617](https://github.com/CLIMADA-project/climada_python/pull/617),
-[#622](https://github.com/CLIMADA-project/climada_python/pull/622).
+[#622](https://github.com/CLIMADA-project/climada_python/pull/622),
+[#656](https://github.com/CLIMADA-project/climada_python/pull/656).
 - Updated installation instructions [#644](https://github.com/CLIMADA-project/climada_python/pull/644)
 
 ### Fixed

README.md

@@ -56,8 +56,8 @@ Bresch, D. N. and Aznar-Siguan, G., 2021: CLIMADA v1.4.1: towards a globally con
 
 Please see all CLIMADA-related scientific publications in our [repository of scientific publications](https://github.com/CLIMADA-project/climada_papers) and cite according to your use of select features, be it hazard set(s), exposure(s) ...
 
-In presentations or other graphical material, as well as in reports etc., where applicable, please add the logo as follows:
-![](https://github.com/CLIMADA-project/climada_python/blob/main/doc/guide/img/CLIMADA_logo_QR.png&raw=true)
+In presentations or other graphical material, as well as in reports etc., where applicable, please add the logo as follows:\
+![https://github.com/CLIMADA-project/climada_python/blob/main/doc/guide/img/CLIMADA_logo_QR.png](https://github.com/CLIMADA-project/climada_python/blob/main/doc/guide/img/CLIMADA_logo_QR.png?raw=true)
 
 As key link, please use https://wcr.ethz.ch/research/climada.html, as it will last and provides a bit of an intro, especially for those not familiar with GitHub - plus a nice CLIMADA infographic towards the bottom of the page
 

climada/entity/exposures/base.py

@@ -93,8 +93,6 @@ class Exposures():
         latitude
     longitude : pd.Series
         longitude
-    crs : dict or crs
-        CRS information inherent to GeoDataFrame.
     value : pd.Series
         a value for each exposure
     impf_SUFFIX : pd.Series, optional
@@ -891,7 +889,7 @@ def from_mat(cls, file_name, var_names=None):
     # Extends the according geopandas method
     #
     def to_crs(self, crs=None, epsg=None, inplace=False):
-        """Wrapper of the GeoDataFrame.to_crs method.
+        """Wrapper of the :py:meth:`GeoDataFrame.to_crs` method.
 
         Transform geometries to a new coordinate reference system.
         Transform all geometries in a GeoSeries to a different coordinate reference system.
@@ -930,7 +928,7 @@ def to_crs(self, crs=None, epsg=None, inplace=False):
         return exp
 
     def plot(self, *args, **kwargs):
-        """Wrapper of the ``GeoDataFrame.plot`` method"""
+        """Wrapper of the :py:meth:`GeoDataFrame.plot` method"""
         self.gdf.plot(*args, **kwargs)
 
     def copy(self, deep=True):

climada/util/scalebar_plot.py

@@ -197,9 +197,9 @@ def scale_bar(ax, location, length, metres_per_unit=1000, unit_name='km',
     va :
         Vertical alignment. Default: 'bottom'
     plot_kwargs :
-        Keyword arguments for plot, overridden by **kwargs.
+        Keyword arguments for plot, overridden by `**kwargs`.
     text_kwargs :
-        Keyword arguments for text, overridden by **kwargs.
+        Keyword arguments for text, overridden by `**kwargs`.
     kwargs :
         Keyword arguments for both plot and text.
     """

doc/index.rst

@@ -64,6 +64,13 @@ Jump right in:
    Running CLIMADA on Euler <guide/Guide_Euler>
 
 
+.. toctree::
+   :caption: API Reference
+   :hidden:
+
+   Python Modules <climada/climada>
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Tutorials
@@ -100,7 +107,6 @@ Jump right in:
    :caption: Miscellaneous
    :hidden:
 
-   Python modules <climada/climada>
    README <misc/README>
    Changelog <misc/CHANGELOG>
    List of Authors <misc/AUTHORS>

doc/misc/README.md

@@ -0,0 +1,74 @@
+# CLIMADA
+
+CLIMADA stands for **CLIM**ate **ADA**ptation and is a probabilistic natural catastrophe impact model, that also calculates averted damage (benefit) thanks to adaptation measures of any kind (from grey to green infrastructure, behavioural, etc.).
+
+As of today, CLIMADA provides global coverage of major climate-related extreme-weather hazards at high resolution via a [data API](https://climada.ethz.ch/data-api/v1/docs), namely (i) tropical cyclones, (ii) river flood, (iii) agro drought and (iv) European winter storms, all at 4km spatial resolution - wildfire to be added soon. For all hazards, historic and probabilistic event sets exist, for some also under select climate forcing scenarios (RCPs) at distinct time horizons (e.g. 2040). See also [papers](https://github.com/CLIMADA-project/climada_papers) for details.
+
+CLIMADA is divided into two parts (two repositories):
+
+1. the core [climada_python](https://github.com/CLIMADA-project/climada_python) contains all the modules necessary for the probabilistic impact, the averted damage, uncertainty and forecast calculations. Data for hazard, exposures and impact functions can be obtained from the [data API](https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_util_api_client.ipynb). [Litpop](https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_entity_LitPop.ipynb) is included as demo Exposures module, and [Tropical cyclones](https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_hazard_TropCyclone.ipynb) is included as a demo Hazard module.
+2. the petals [climada_petals](https://github.com/CLIMADA-project/climada_petals) contains all the modules for generating data (e.g., TC_Surge, WildFire, OpenStreeMap, ...). Most development is done here. The petals builds-upon the core and does not work as a stand-alone.
+
+It is recommend for new users to begin with the core (1) and the [tutorials](https://github.com/CLIMADA-project/climada_python/tree/main/doc/tutorial) therein.
+
+This is the Python (3.8+) version of CLIMADA - please see https://github.com/davidnbresch/climada for backward compatibility (MATLAB).
+
+## Getting started
+
+CLIMADA runs on Windows, macOS and Linux. It can be installed from sources or - in case of climada_python - directly with pip. See the [installation guide](https://climada-python.readthedocs.io/en/latest/guide/install.html) for instructions.
+
+Follow the [tutorial](https://climada-python.readthedocs.io/en/latest/tutorial/1_main_climada.html) `climada_python-x.y.z/doc/tutorial/1_main_climada.ipynb` in a Jupyter Notebook to see what can be done with CLIMADA and how.
+
+## Documentation
+
+Documentation is available on Read the Docs:
+
+Note that all the documentations has two versions,'latest' and 'stable', and explicit version numbers, such as 'v3.1.1', in the url path. 'latest' is created from the 'develop' branch and has the latest changes by developers, 'stable' from the latest release. For more details about documentation versions, please have a look at [here](https://readthedocs.org/projects/climada-python/versions/).
+
+CLIMADA python:
+
+* [online (recommended)](https://climada-python.readthedocs.io/en/latest/)
+* [PDF file](https://climada-python.readthedocs.io/_/downloads/en/stable/pdf/)
+
+CLIMADA petals:
+
+* [online (recommended)](https://climada-petals.readthedocs.io/en/latest/)
+* [PDF file](https://climada-petals.readthedocs.io/_/downloads/en/stable/pdf/)
+* [petals Tutorials on GitHub](https://github.com/CLIMADA-project/climada_petals/tree/main/doc/tutorial)
+
+The documentation can also be [built locally](https://climada-python.readthedocs.io/en/latest/README.html).
+
+## Citing CLIMADA
+
+If you use CLIMADA please cite (in general, in particular for academic work) :
+
+The [used version](https://zenodo.org/search?page=1&size=20&q=climada)
+
+and/or the following published articles:
+
+Aznar-Siguan, G. and Bresch, D. N., 2019: CLIMADA v1: a global weather and climate risk assessment platform, Geosci. Model Dev., 12, 3085–3097, https://doi.org/10.5194/gmd-12-3085-2019
+
+Bresch, D. N. and Aznar-Siguan, G., 2021: CLIMADA v1.4.1: towards a globally consistent adaptation options appraisal tool, Geosci. Model Dev., 14, 351-363, https://doi.org/10.5194/gmd-14-351-2021
+
+Please see all CLIMADA-related scientific publications in our [repository of scientific publications](https://github.com/CLIMADA-project/climada_papers) and cite according to your use of select features, be it hazard set(s), exposure(s) ...
+
+In presentations or other graphical material, as well as in reports etc., where applicable, please add the logo as follows:\
+![https://github.com/CLIMADA-project/climada_python/blob/main/doc/guide/img/CLIMADA_logo_QR.png](https://github.com/CLIMADA-project/climada_python/blob/main/doc/guide/img/CLIMADA_logo_QR.png?raw=true)
+
+As key link, please use https://wcr.ethz.ch/research/climada.html, as it will last and provides a bit of an intro, especially for those not familiar with GitHub - plus a nice CLIMADA infographic towards the bottom of the page
+
+## Contributing
+
+See the [Contribution Guide](CONTRIBUTING.md).
+
+## Versioning
+
+We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [releases on this repository](https://github.com/CLIMADA-project/climada_python/releases).
+
+## License
+
+Copyright (C) 2017 ETH Zurich, CLIMADA contributors listed in AUTHORS.
+
+CLIMADA is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License Version 3, 29 June 2007 as published by the Free Software Foundation, https://www.gnu.org/licenses/gpl-3.0.html
+
+CLIMADA is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details: https://www.gnu.org/licenses/gpl-3.0.html

doc/tutorial/climada_engine_unsequa.ipynb

@@ -50,7 +50,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Before doing an uncertainty quantification in CLIMADA, it is imperative that you get first comfortable with the different notions of uncertainty in the modelling world (see e.g.[Pianosi (2016)](https://www.sciencedirect.com/science/article/pii/S1364815216300287) or [Douglas-Smith(2020)](https://doi.org/10.1007/978-1-4899-7547-8_5) for a review). In particular, note that the uncertaintity values will only be as good as the input from the user. In addition, not all uncertainties can be numerically quantified, and even worse, some unkonwns are unknown. This means that sometimes, quantifying uncertainty can lead to false confidence in the output!. For a more philosophical discussion about the types of uncertainties in climate research see [Knüsel (2020)](https://www.research-collection.ethz.ch/handle/20.500.11850/399735) and [Otth (2022)]().\n",
+    "Before doing an uncertainty quantification in CLIMADA, it is imperative that you get first comfortable with the different notions of uncertainty in the modelling world (see e.g.[Pianosi (2016)](https://www.sciencedirect.com/science/article/pii/S1364815216300287) or [Douglas-Smith(2020)](https://doi.org/10.1007/978-1-4899-7547-8_5) for a review). In particular, note that the uncertaintity values will only be as good as the input from the user. In addition, not all uncertainties can be numerically quantified, and even worse, some unkonwns are unknown. This means that sometimes, quantifying uncertainty can lead to false confidence in the output!. For a more philosophical discussion about the types of uncertainties in climate research see [Knüsel (2020)](https://www.research-collection.ethz.ch/handle/20.500.11850/399735) and [Otth (2022)](https://gmd.copernicus.org/articles/15/7177/2022).\n",
     "\n",
     "In this module, it is possible to perform global uncertainty analysis, as well as a sensitivity analysis. The word global is meant as opposition to the 'one-factor-at-a-time' (OAT) strategy. The OAT strategy, which consists in analyzing the effect of varying one model input factor at a time while keeping all other fixed, is popular among modellers, but has major shortcomings [Saltelli (2010)](https://www.sciencedirect.com/science/article/abs/pii/S1364815210001180), [Saltelli(2019)](http://www.sciencedirect.com/science/article/pii/S1364815218302822) and should not be used.\n",
     "\n",

doc/tutorial/climada_entity_ImpactFuncSet.ipynb

@@ -194,7 +194,12 @@
     "## Part 2: Loading impact functions from CLIMADA in-built impact functions\n",
     "\n",
     "In CLIMADA there is several defined impact functions that users can directly load and use them. However, users should be aware of the applications of the impact functions to types of assets, reading the background references of the impact functions are strongly recommended.<br>\n",
-    "Currently available perils include [tropical cyclones](../climada/climada.hazard.html#module-climada.hazard.trop_cyclone), [river floods](https://climada-petals.readthedocs.io/en/stable/climada_petals/climada_petals.entity.impact_funcs.html#module-climada_petals.entity.impact_funcs.river_flood), [European windstorm](../climada/climada.hazard.html#module-climada.hazard.storm_europe), [crop yield](https://climada-petals.readthedocs.io/en/stable/climada_petals/climada_petals.entity.impact_funcs.html#module-climada_petals.entity.impact_funcs.relative_cropyield), and [drought](https://climada-petals.readthedocs.io/en/stable/climada_petals/climada_petals.entity.impact_funcs.html#module-climada_petals.entity.impact_funcs.drought). Continuous updates of perils are available.<br>\n",
+    "Currently available perils include\n",
+    "[tropical cyclones](https://climada-python.readthedocs.io/en/stable/climada/climada.hazard.html#module-climada.hazard.trop_cyclone),\n",
+    "[river floods](https://climada-petals.readthedocs.io/en/stable/climada_petals/climada_petals.entity.impact_funcs.html#module-climada_petals.entity.impact_funcs.river_flood),\n",
+    "[European windstorm](https://climada-python.readthedocs.io/en/stable/climada/climada.hazard.html#module-climada.hazard.storm_europe),\n",
+    "[crop yield](https://climada-petals.readthedocs.io/en/stable/climada_petals/climada_petals.entity.impact_funcs.html#module-climada_petals.entity.impact_funcs.relative_cropyield), and\n",
+    "[drought](https://climada-petals.readthedocs.io/en/stable/climada_petals/climada_petals.entity.impact_funcs.html#module-climada_petals.entity.impact_funcs.drought).Continuous updates of perils are available.<br>\n",
     "Here we use the impact function of tropical cyclones as an example.\n"
    ]
   },