Installation

This guide provides general installation instructions for users who are comfortable with the command line and knowledgeble about git, pip and conda. For more detailed instructions see the CLIMADA Installation Step by Step tutorial.

Please execute the instructions of the following text boxes in a Terminal or Anaconda Prompt. Choose an installation directory, e.g., the user’s home directory. In the following it will be referred to as $[installation directory].

It’s highly recommanded to install CLIMADA into a Conda environment. Without Conda, the installation of the dependencies can be cumbersome. If it is not already installed, download the latest version of Anaconda or Miniconda and execute it.

Install CLIMADA from sources (for developers)

What does “from sources” mean?

This method is usually used by developers, since it gives you the opportunity to modify the source code and install CLIMADA from any branch of climada_python, including the develop branch where the latest changes are incorporated. If you are not sure whether this is the right option for you or if you are happy with the official CLIMADA releases, you’re suggested to pick the method introduced in the section below: Install CLIMADA from PyPI (users). But if you need a particular branch or if you intend to change the code yourself, this is your choice.

What is Git/Github?

Git is software for tracking changes in any set of files, usually used for coordinating work among programmers collaboratively developing source code during software development. GitHub is a provider of Internet hosting for software development and version control using Git. We will use Git commands here to download the project CLIMADA from GitHub.

Download the latest version

cd $[installation directory]

git clone https://github.com/CLIMADA-project/climada_python.git
cd climada_python
git checkout develop
cd ..

Set up the environment

Reminder: Conda must be installed.

Open a command prompt (Windows) or shell (Mac, Linux) and run:

conda env create -n climada_env -f climada_python/requirements/env_climada.yml
conda activate climada_env

Install the climada package

Include the CLIMADA path into the Conda environment as follows:

pip install -e climada_python

With this setup, changes to CLIMADA’s source code will immediately take effect. It removes the need to reinstall during development.

Install CLIMADA from PyPI (for users)

Published releases of CLIMADA (not CLIMADA-petals) can also be installed from the PyPI repository https://PyPI.org/project/climada/, since version 3.0.

What is PyPI/pip?

The Python Package Index, abbreviated as PyPI is the official third-party software repository for Python. pip is a package manager that is used to download and install packages directly from PyPI.

Download the environment specification file

Download the environment specification file from the git repository and save it locally. If you are using Linux, run:

curl -o env_climada.yml https://raw.githubusercontent.com/CLIMADA-project/climada_python/main/requirements/env_climada.yml

Set up the environment

Reminder: Conda must be installed.

Create the conda environment:

conda env create -n climada_env -f env_climada.yml
conda activate climada_env

If this was successful, env_climada.yml can be safely deleted.

Install the climada package

pip install climada

Install CLIMADA-petals (optional)

Why is CLIMADA-petals optional?

CLIMADA is divided into two parts (two repositories): 1. the core 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. Litpop is included as demo Exposures module, and Tropical cyclones is included as a demo Hazard module. 2. CLIMADA-petals climada_petals contains all the modules for generating data (e.g., TC_Surge, WildFire, OpenStreeMap, …). Most development is done here. CLIMDA-petals builds upon the core and does not work as stand-alone. You need the core to use CLIMDA-petals, but not the other way around. However, there is data created with CLIMADA-petals (e.g. RiverFlood or CropYield) available from the CLIMADA Data API. This data can be downloaded and used directly with just the core installed. CLIMADA-petals is only required to generate additional data of this type. Nevertheless, users who want to calculate, e.g., RiverFlood impacts by core and API may still want to look into the tutorial RiverFlood to understand how RiverFlood is calculated.

Download the latest version

cd $[installation directory]

git clone https://github.com/CLIMADA-project/climada_petals.git
cd climada_petals
git checkout develop
cd ..

Update the environment

It is possible that CLIMADA-petals has slightly different dependencies than CLIMADA-core, hence the conda environment should be updated.

conda env update -n climada_env -f climada_petals/requirements/env_climada.yml
conda activate climada_env

Install the climada_petals package

Include the CLIMADA-petals path into the Conda environment as follows:

pip install -e climada_petals

Test the installation

Run the following command:

python -m unittest climada.engine.test.test_impact climada.engine.test.test_cost_benefit

If the installation has been successful, an OK will appear at the end (the execution shouldn’t last more than 2 min).

Run tutorials

In the Home section of Anaconda, with climada_env selected, install and launch jupyter notebook. A browser window will show up. Navigate to your climada_python repository and open doc/tutorial/1_main_CLIMADA.ipynb. This is the tutorial which will guide you through all CLIMADA’s functionalities. Execute each code cell to see the results, you might also edit the code cells before executing. See tutorials for more information.

Working with Spyder

It is possible to use climada in combination with the Spyder-IDE. However, depending on OS, CLIMADA version, Spyder version and installation tool, installing spyder into the climada_env environment may fail. In particular, MacOS and conda install spyder don’t work well together. Although there are cases where pip install spyder bears satisfactory results, it is suggested to install spyder in a separate Conda environment and run it with the python interpreter from the climada_env environment instead. To do so, follow these instructions:

  • Start Anaconda, create a new python_env environment (just click create and enter the name, then press Create) and install latest Spyder in there (currently 4.2.5). Start this version of Spyder. After Spyder has started, navigate to Preferences > Python Interpreter > Use the following interpreter and paste the output of the following terminal command into the text box:

conda activate climada_env
python -c "import sys; print(sys.executable)"
# this returns a path, like /Users/XXX/opt/anaconda3/envs/climada_env/bin/python

  • Obtain the version of the package spyder-kernels (currently 1.10.2) that has automatically been installed along with Spyder in the Anaconda environment and install the same version of spyder-kernels in the climada_env environment:

conda activate climada_env
conda install spyder-kernels=1.10.2

  • Start a new IPython console in Spyder and run tests_install.py.

FAQs

  • ModuleNotFoundError

    • the CLIMADA packages are not found. Check whether the climada environment is activated. If not, activate it (conda activate climada_env). Otherwise, the installation has failed. Try and follow the installation instructions above.

    • an external python library is not found. It might happen that the pip dependencies of env_climada.yml (the ones specified after pip:) have not been installed in the environment climada_env. They can be installed manually one by one as follows:

    conda activate climada_env
pip install library_name
    where library_name is the missing library.
    Another reason may be a recent update of the operating system (macOS). In this case removing and reinstalling Anaconda will be required.
  • Conda permission error
    (operation not permitted) in macOS Mojave: try the solutions suggested here https://github.com/conda/conda/issues/8440
  • No ‘impf_TC’ column in GeoDataFrame
    This may happen when a demo file from CLIMADA was not updated after the change in the impact function naming pattern from ‘if_’ to ‘impf_’ (climada v2.2.0).
    To solve it, run python -c 'import climada; climada.setup_climada_data(reload=True) in a terminal.
  • How to change the log level
    By default the logging level is set to 'INFO', which is quite verbose. This can be changed

    • through configuration, by editing the config file climada.conf (see Guide_configuration.ipynb) and setting the value of the global.log_level property.

    • programmatically, globally, in a script or interactive python environment (Spyder, Jupyter, IPython) by executing e.g.,

    from climada.util.config import LOGGER
from logging import WARNING
LOGGER.setLevel(WARNING)

    • programmatically, context based, using climada.util.log_level:

    from climada.util import log_level
with log_level(level='WARNING'):
      quietly_do_something()
  • How to install climada_petals in a separate environment
    If you want to have a separate environment for CLIMADA-petals, proceed as described above but create a new environment instead of updating:
    conda env create -n petals_env -f climada_petals/requirements/env_climada.yml
conda activate petals_env

    and before running pip install -e climada_petals install the core package, either with the package from PyPi (pip install climada) or from local sources (pip install -e climada_python)