Skip to content

Commit

Permalink
Doc/update readme (#778)
Browse files Browse the repository at this point in the history
* Add detailed citation recommendations

* Small tweaks in readme

* Remove preprint citation

* Update README.md

Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>

* Update README.md

Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>

* Update README.md

Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>

* Update README.md

Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>

* Add citation guide

* Update citation guide

* Make citation guide an RST document.
* Add table for recommended publications.
* Rename REFERENCES.bib to climada_publications.bib
* Add citation guide to documentation toctree.

* Add documentation link for citation guide to README.md

* Copy README.md to doc/misc/README.md

---------

Co-authored-by: Chahan Kropf <chahan.kropf@posteo.com>
Co-authored-by: Lukas Riedel <34276446+peanutfun@users.noreply.github.com>
Co-authored-by: emanuel-schmid <schmide@ethz.ch>
  • Loading branch information
4 people committed Sep 11, 2023
1 parent 9b08d1f commit 525842d
Show file tree
Hide file tree
Showing 5 changed files with 138 additions and 36 deletions.
28 changes: 10 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@

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.
As of today, CLIMADA provides global coverage of major climate-related extreme-weather hazards at high resolution (4x4km) via a [data API](https://climada.ethz.ch/data-api/v1/docs) For select hazards, historic and probabilistic events sets, for past, present and future climate exist at distinct time horizons.
You will find a repository containing scientific peer-reviewed articles that explain software components implemented in CLIMADA [here](https://github.com/CLIMADA-project/climada_papers).

CLIMADA is divided into two parts (two repositories):

Expand All @@ -15,30 +16,32 @@ CLIMADA is divided into two parts (two repositories):

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).
This is the Python (3.9+) version of CLIMADA - please see [here](https://github.com/davidnbresch/climada) for backward compatibility with the MATLAB version.

## Getting started

CLIMADA runs on Windows, macOS and Linux.
The released versions of the CLIMADA core can be installed directly through Anaconda:

```shell
conda install -c conda-forge climada
```

It is **highly recommended** to install CLIMADA into a **separate** Anaconda environment.
See the [installation guide](https://climada-python.readthedocs.io/en/latest/guide/install.html) for further information.

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.
Follow the [tutorials](https://climada-python.readthedocs.io/en/stable/tutorial/1_main_climada.html) in a Jupyter Notebook to see what can be done with CLIMADA and how.

## Documentation

Documentation is available on Read the Docs:
The online documentation is available on [Read the Docs](https://climada-python.readthedocs.io/en/stable/).The documentation of each release version of CLIMADA can be accessed separately through the drop-down menu at the bottom of the left sidebar. Additionally, the version 'stable' refers to the most recent release (installed via `conda`), and 'latest' refers to the latest unstable development version (the `develop` branch).

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/)
* [core Tutorials on GitHub](https://github.com/CLIMADA-project/climada_python/tree/main/doc/tutorial)

CLIMADA petals:

Expand All @@ -50,23 +53,12 @@ The documentation can also be [built locally](https://climada-python.readthedocs

## 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:
See the [Citation Guide](https://climada-python.readthedocs.io/en/latest/misc/citation.html).

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
Please use the following logo if you are presenting results obtained with or through CLIMADA:

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).
Expand Down
3 changes: 3 additions & 0 deletions doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ CLIMADA stands for CLIMate ADAptation and is a probabilistic natural catastrophe

CLIMADA is primarily developed and maintained by the `Weather and Climate Risks Group <https://wcr.ethz.ch/>`_ at `ETH Zürich <https://ethz.ch/en.html>`_.

If you use CLIMADA for your own scientific work, please reference the appropriate publications according to the :doc:`misc/citation`.

This is the documentation of the CLIMADA core module which contains all functionalities necessary for performing climate risk analysis and appraisal of adaptation options. Modules for generating different types of hazards and other specialized applications can be found in the `CLIMADA Petals <https://climada-petals.readthedocs.io/en/stable/>`_ module.

Jump right in:
Expand Down Expand Up @@ -111,3 +113,4 @@ Jump right in:
Changelog <misc/CHANGELOG>
List of Authors <misc/AUTHORS>
Contribution Guide <misc/CONTRIBUTING>
misc/citation
28 changes: 10 additions & 18 deletions doc/misc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

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.
As of today, CLIMADA provides global coverage of major climate-related extreme-weather hazards at high resolution (4x4km) via a [data API](https://climada.ethz.ch/data-api/v1/docs) For select hazards, historic and probabilistic events sets, for past, present and future climate exist at distinct time horizons.
You will find a repository containing scientific peer-reviewed articles that explain software components implemented in CLIMADA [here](https://github.com/CLIMADA-project/climada_papers).

CLIMADA is divided into two parts (two repositories):

Expand All @@ -11,30 +12,32 @@ CLIMADA is divided into two parts (two repositories):

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).
This is the Python (3.9+) version of CLIMADA - please see [here](https://github.com/davidnbresch/climada) for backward compatibility with the MATLAB version.

## Getting started

CLIMADA runs on Windows, macOS and Linux.
The released versions of the CLIMADA core can be installed directly through Anaconda:

```shell
conda install -c conda-forge climada
```

It is **highly recommended** to install CLIMADA into a **separate** Anaconda environment.
See the [installation guide](https://climada-python.readthedocs.io/en/latest/guide/install.html) for further information.

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.
Follow the [tutorials](https://climada-python.readthedocs.io/en/stable/tutorial/1_main_climada.html) in a Jupyter Notebook to see what can be done with CLIMADA and how.

## Documentation

Documentation is available on Read the Docs:
The online documentation is available on [Read the Docs](https://climada-python.readthedocs.io/en/stable/).The documentation of each release version of CLIMADA can be accessed separately through the drop-down menu at the bottom of the left sidebar. Additionally, the version 'stable' refers to the most recent release (installed via `conda`), and 'latest' refers to the latest unstable development version (the `develop` branch).

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/)
* [core Tutorials on GitHub](https://github.com/CLIMADA-project/climada_python/tree/main/doc/tutorial)

CLIMADA petals:

Expand All @@ -46,23 +49,12 @@ The documentation can also be [built locally](https://climada-python.readthedocs

## 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:
See the [Citation Guide](https://climada-python.readthedocs.io/en/latest/misc/citation.html).

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
Please use the following logo if you are presenting results obtained with or through CLIMADA:

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).
Expand Down
42 changes: 42 additions & 0 deletions doc/misc/citation.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
==============
Citation Guide
==============

If you use CLIMADA for your work, please cite the appropriate publications.
A list of all CLIMADA code related articles is available on `Zotero <https://www.zotero.org/groups/2502787/climada_open/collections/WZN2U7EK>`_ and can be downloaded as single Bibtex file: :download:`climada_publications.bib`


Publications by Module
----------------------

If you use specific tools and modules of CLIMADA, please cite the appropriate publications presenting these modules according to the following table:

.. list-table::
:widths: 1 3
:header-rows: 1

* - Module or tool used
- Publication to cite
* - *Any*
- The `Zenodo archive <https://doi.org/10.5281/zenodo.4598943>`_ of the CLIMADA version you are using
* - :doc:`Impact calculations </tutorial/climada_engine_Impact>`
- 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-14-351-2021
* - :doc:`Cost-benefit analysis </tutorial/climada_engine_CostBenefit>`
- 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
* - :doc:`Uncertainty and sensitivity analysis </tutorial/climada_engine_unsequa>`
- Kropf, C. M. et al. (2022): Uncertainty and sensitivity analysis for probabilistic weather and climate-risk modelling: an implementation in CLIMADA v.3.1.0. Geosci. Model Dev. 15, 7177–7201, https://doi.org/10.5194/gmd-15-7177-2022
* - :doc:`Lines and polygons exposures </tutorial/climada_entity_Exposures_polygons_lines>` *or* `Open Street Map exposures <https://climada-petals.readthedocs.io/en/latest/tutorial/climada_exposures_openstreetmap.html>`_
- Mühlhofer, E., et al. (2023): OpenStreetMap for Multi-Faceted Climate Risk Assessments https://eartharxiv.org/repository/view/5615/
* - :doc:`LitPop exposures </tutorial/climada_entity_LitPop>`
- Eberenz, S., et al. (2020): Asset exposure data for global physical risk assessment. Earth System Science Data 12, 817–833, https://doi.org/10.3929/ethz-b-000409595

Please find the code to reprocduce selected CLIMADA-related scientific publications in our `repository of scientific publications <https://github.com/CLIMADA-project/climada_papers>`_.

Links and Logo
--------------

In presentations or other graphical material, as well as in reports etc., where applicable, please add the following logo: :download:`climada_logo_QR.png <https://github.com/CLIMADA-project/climada_python/blob/main/doc/guide/img/CLIMADA_logo_QR.png?raw=true>`:

.. image:: 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 provides a brief introduction especially for those not familiar with GitHub.
73 changes: 73 additions & 0 deletions doc/misc/climada_publications.bib
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
@article{Aznar-Siguan2019,
title = {{{CLIMADA}} v1: A Global Weather and Climate Risk Assessment Platform},
shorttitle = {{{CLIMADA}} V1},
author = {{Aznar-Siguan}, Gabriela and Bresch, David N.},
year = {2019},
journal = {Geoscientific Model Development},
volume = {12},
number = {7},
pages = {3085--3097},
publisher = {{Copernicus GmbH}},
issn = {1991-959X},
doi = {10.5194/gmd-12-3085-2019}
}

@article{Bresch2021,
title = {{{CLIMADA}} v1.4.1: Towards a Globally Consistent Adaptation Options Appraisal Tool},
shorttitle = {{{CLIMADA}} v1.4.1},
author = {Bresch, David N. and {Aznar-Siguan}, Gabriela},
year = {2021},
journal = {Geoscientific Model Development},
volume = {14},
number = {1},
pages = {351--363},
publisher = {{Copernicus GmbH}},
issn = {1991-959X},
doi = {10.5194/gmd-14-351-2021}
}

@article{Eberenz2020,
title = {Asset Exposure Data for Global Physical Risk Assessment},
author = {Eberenz, Samuel and Stocker, Dario and R{\"o}{\"o}sli, Thomas and Bresch, David N.},
year = {2020},
journal = {Earth System Science Data},
volume = {12},
number = {2},
pages = {817--833},
publisher = {{Copernicus GmbH}},
issn = {1866-3508},
doi = {10.5194/essd-12-817-2020}
}

@article{Kropf2022c,
title = {Uncertainty and Sensitivity Analysis for Probabilistic Weather and Climate-Risk Modelling: An Implementation in {{CLIMADA}} v.3.1.0},
shorttitle = {Uncertainty and Sensitivity Analysis for Probabilistic Weather and Climate-Risk Modelling},
author = {Kropf, Chahan M. and Ciullo, Alessio and Otth, Laura and Meiler, Simona and Rana, Arun and Schmid, Emanuel and McCaughey, Jamie W. and Bresch, David N.},
year = {2022},
journal = {Geoscientific Model Development},
volume = {15},
number = {18},
pages = {7177--7201},
publisher = {{Copernicus GmbH}},
issn = {1991-959X},
doi = {10.5194/gmd-15-7177-2022}
}

@article{Muhlhofer2023b,
title = {{{OpenStreetMap}} for {{Multi-Faceted Climate Risk Assessments}}},
author = {M{\"u}hlhofer, Evelyn and Kropf, Chahan M. and Bresch, David N. and Koks, Elco E.},
year = {2023},
publisher = {{EarthArXiv}},
url = {https://eartharxiv.org/repository/view/5615/}
}

@article{Muhlhofer2023c,
title = {A Generalized Natural Hazard Risk Modelling Framework for Infrastructure Failure Cascades},
author = {M{\"u}hlhofer, Evelyn and Koks, Elco E. and Kropf, Chahan M. and Sansavini, Giovanni and Bresch, David N.},
year = {2023},
journal = {Reliability Engineering \& System Safety},
volume = {234},
pages = {109194},
issn = {0951-8320},
doi = {10.1016/j.ress.2023.109194}
}

0 comments on commit 525842d

Please sign in to comment.