Metadata-Version: 2.1
Name: chelsa-cmip6
Version: 1.1
Summary: This package contains function to create monthly high-resolution climatologies for a selected geographic area for min-, max-, and mean temperature, precipitation rate and bioclimatic variables from anomalies and using CHELSA V2.1 as baseline high resolution climatology. Only works for GCMs for which tas, tasmax, tasmin, and pr are available.
Home-page: https://gitlabext.wsl.ch/karger/chelsa_cmip6.git
Author: Dirk Nikolaus Karger
Author-email: dirk.karger@wsl.ch
License: GNU
Download-URL: https://gitlabext.wsl.ch/karger/chelsa_cmip6/-/archive/v1.0/chelsa_cmip6-v1.0.tar.gz
Project-URL: Bug Tracker, https://github.com/pypa/chelsa_cmip6/issues
Keywords: CMIP6,climate,delta-change,CHELSA,bioclimate,growing degree days,gdd,bio
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: xarray
Requires-Dist: rasterio
Requires-Dist: pandas
Requires-Dist: zarr
Requires-Dist: gcsfs
Requires-Dist: scipy

chelsa_cmip6
-----------
This package contains functions to creates monthly high-resolution 
climatologies for min-, max-, and mean temperature, precipitation rate 
and bioclimatic variables from anomalies and using CHELSA V2.1 as 
baseline high resolution climatology. Only works for GCMs for
hich tas, tasmax, tasmin, and pr are available. It is part of the
CHELSA Project: (CHELSA, <https://www.chelsa-climate.org/>).


# INSTALLATION
------------
chelsa-cmip6 can be installed on your machine in different ways. It is compatible with Windows, MacOS, and Linux systems.
## On Linux

Linux usually come already with a version of python preinstalled. 
#### From Github
If you want the latest version its best if you install it directly from github:
Example for Ubuntu 20.04
if you have not installed Git on your linux machine yet, the apt package management tool is the easiest way to install Git.

1. To update the packages, launch a terminal window, and enter:
```bash
sudo apt-get update
```

2. To install from the default repositories, enter the following:
```bash
sudo apt-get install git
```

3. you can now install the latest version from github by typing the following command in the terminal:
```bash
python -m pip install git+https://gitlabext.wsl.ch/karger/chelsa_cmip6.git
```

#### From PyPI:
If you want the latest release version, you can also install it from PyPI using:

using pip:
```bash
python -m pip install chelsa-cmip6
```
## On Windows
#### Install python:
1. Check if python is already installed on your machine. To do so open the command line interface by:
Press: Win + R

2. This will open a run window:
Type: cmd.exe and press enter
This should open the command line interface of Windows

3. In the command line interface type:
```bash
python
```
If python is already installed, you will automatically enter the command line interpreter of python. If
Python is not already installed, a Microsoft Store window will open asking you to install Python. Click 'Get'
and install Python. Make sure your version is at least 3.8.

4. Verify your installation by typing the following in the command line interface:
```bash
python --version
```

#### Install the chelsa-cmip6 package:
##### Using pip
If you want the latest release version, you can also install it from PyPI using:

```bash
python -m pip install chelsa-cmip6
```

##### Using Git
If you want the latest version, you can also install it from Github. If you dont have Git
installed on your machine, you can find the installers here: 
https://git-scm.com/download/win

Follow the steps in the installer and after completion open a new command line interface in windows and type:
```bash
python -m pip install git+https://gitlabext.wsl.ch/karger/chelsa_cmip6.git
```

##### GDAL and rasterio
chelsa-cmip6 depends on rasterio, which in turn depends on GDAL. Sometimes these two modules can create problems with the 
installation routine. If the installation hangs while installing the rasterio module, you can try installing both modules manually
before installing chelsa-cmip6.

GDAL can be quite complex to build and install, particularly on Windows and MacOS
If you run into problems follow the steps provided for your respective system here:

You can get information how to install GDAL on your system here: https://pypi.org/project/GDAL/

After the manual installation of GDAL you can install rasterio by:
```bash
python -m pip install rasterio
```

# HOW TO USE
----------
The chelsa_cmip6 module provides functions to create monthly climatologies from climate
simulation data from CMIP6 using climate observation data from CHELSA V.2.1
at a 0.0083333° grid resolution for a given area of choice.

The GetClim module contains classes and functions to connect to CMIP6 data
via the Google cloud storage and to read the data into xarrays. It also creates
monthly climatologies using the delta change anomally correction method for a given 
time period. 

The BioClim module contains classes calculating various bioclimatic parameters
from climatological data (see: https://chelsa-climate.org/bioclim).

The delta change method that is applied is relatively insensitive towards individual model 
bias of a GCM, as it only uses the difference (ratio) for a given variable between
a reference period and a future period. In case of temperature an additive delta change 
is applied. In case of precipitation a multiplicative delta change is applied by 
adding a constant of 0.0000001 kg m^-2 s^⁻1 to both the reference and the future data
to avoid division by zero. 

The code only runs for CMIP6 models for which all needed variables tas, tasmax, tasmin, pr,
are available for both the reference and the future period.

The standard reference period is 1981-01-01 - 2010-12-31. If another reference period is 
chosen, the code conducts a delta change for this period as well. Best practice would be to 
choose the standard reference period.


EXAMPLE: 
------------
You can use the package in two ways 1. by importing the module in python, and 2. by using
the run_chelsa_cmip6.py wrapper function in the terminal (Linux, MAC) or command prompt (Windows).

To create future climate data within python, first import the main function by:

## Using python
------------
```python
from chelsa_cmip6.GetClim import chelsa_cmip6
```

You can then set the parameters of the chelsa_cmip6 function to create the climate data for the CMIP6 model you want.
If we want to create climatologies and bioclimatic variables for the model MPI-ESM1-2-LR and ssp585 for the years
2041-2070 for the region between 5.3° - 10.4° longitude, and 46.0° - 47.5° latitude and save them in your home 
directory (~/, on a linux system), we need to set the parameters of the function as follows: 
```python
chelsa_cmip6(activity_id='ScenarioMIP', 
             table_id='Amon', 
             experiment_id='ssp585', 
             institution_id='MPI-M', 
             source_id='MPI-ESM1-2-LR', 
             member_id='r1i1p1f1', 
             refps='1981-01-15', 
             refpe='2010-12-15', 
             fefps='2041-01-15', 
             fefpe='2070-12-15', 
             xmin=5.3, 
             xmax=10.4,
             ymin=46.0, 
             ymax=47.5,
             output='~/') 
```
#### on Windows:
If you are on a windows system the 'output' parameter should be in the form windows requires it, e.g.

```python
output='C:/Users/your_user_name/' # the directory you want the output to be saved in 
```

## Use chelsa_cmip6 without using python directly
------------
You can also use the function directly from the terminal if you like. The chelsa_cmip6 package comes with a wrapper function,
run_chelsa_cmip6.py that allows you to simply use it via the terminal without any python knowledge required. It means however that you have to add directory where the wrapper function run_chelsa_cmip6.py is located to your PATH variable, so that your system knows where to look for it. 

#### on Linux
1. Find the directory in which chelsa_cmip6 is located by typing the following in the terminal:
```bash
python -c "import chelsa_cmip6; print(chelsa_cmip6.__file__);"
```
The printed path without the '\__init__.py' at the end is the path you will need to add to your PATH variable.

2. You can now add it to your PATH variable by using:
```bash
export PATH="your_path:$PATH"
```

3. Restart your terminal. You should now be able to use chelsa_cmip6 by running e.g. the following in the terminal:
```bash 
run_chelsa_cmip6.py --activity_id "ScenarioMIP" --table_id "Amon" --experiment_id "ssp585" --institution_id "MPI-M" --source_id "MPI-ESM1-2-LR" --member_id "r1i1p1f1" --refps "1981-01-15" --refpe "2010-12-15" --fefps "2041-01-15" --fefpe "2070-12-15" --xmin 5.3 --xmax 10.4 --ymin 46.0 --ymax 47.5 --output "~/"
```

#### on Windows
On Windows you need to first find out where the python package is installed. You can do so by typing the following in the command line interface:

```bash
python -c "import chelsa_cmip6; print(chelsa_cmip6.__file__);"
```

The printed path without the '\__init__.py' at the end is the path you will need to add to your path variable. On my machine it 
looks like this:

```bash 
C:\Users\Administrator\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.10_qbz5n2kfra8p0\LocalCache\local-packages\Python310\site-packages\chelsa_cmip6\__init__.py
```

You need to add this path to your PATH environment variable. To do so you need to open a command prompt as Administrator. To do so, you need to:
1. Press: Win + R
2. Type: cmd.exe
3. Use Ctrl + Shift + Click/Tap on the OK button

4. Type the following in the command prompt, replacing C:\your\path\here with the your local path
```bash 
setx /M path "%path%;C:\your\path\here"
```
5. Close the command prompt and open a new one. You now should be able to run the the function now by e.g. typing:
```bash 
run_chelsa_cmip6.py --activity_id "ScenarioMIP" --table_id "Amon" --experiment_id "ssp585" --institution_id "MPI-M" --source_id "MPI-ESM1-2-LR" --member_id "r1i1p1f1" --refps "1981-01-15" --refpe "2010-12-15" --fefps "2041-01-15" --fefpe "2070-12-15" --xmin 5.3 --xmax 10.4 --ymin 46.0 --ymax 47.5 --output "C:/Users/<your_user_name>/"
```

```bash
run_chelsa_cmip6.py --activity_id "ScenarioMIP" --table_id "Amon" --experiment_id "ssp585" --institution_id "MPI-M" --source_id "MPI-ESM1-2-LR" --member_id "r1i1p1f1" --refps "1981-01-15" --refpe "2010-12-15" --fefps "2041-01-15" --fefpe "2070-12-15" --xmin 5.3 --xmax 10.4 --ymin 46.0 --ymax 47.5 --output "~/"
```

important is that the combination of activity_id 'ScenarioMIP' and e.g. experiment_id 'ssp585' is set to a combination that exists.
You can also get historical data but in that case, activity_ID, experiment_id, and fefps and fefps need to be changed. E.g. 

```bash
run_chelsa_cmip6.py --activity_id "CMIP" --table_id "Amon" --experiment_id "historical" --institution_id "MPI-M" --source_id "MPI-ESM1-2-LR" --member_id "r1i1p1f1" --refps "1981-01-15" --refpe "2010-12-15" --fefps "1851-01-15" --fefpe "1880-12-15" --xmin 5.3 --xmax 10.4 --ymin 46.0 --ymax 47.5 --output '~/'
```

it is also important that your fefps and fefpe are covered by the experiment_id and activity_id.

These reference periods are possible for example:

'ScenarioMIP' - 2016-01-01 - 2100-12-31

'CMIP' - 1850-01-01 - 2015-12-31

refps and refpe need to be in the range 1850-01-01 - 2015-12-31.

## chelsa_cmip6 in R via the reticulate package
------------
You can also use the chelsa_cmip6 package in R if you want to itegrate it into your R workflow. To do so open an R console or R Studio and follow the steps below. Important: You still need to have python and the chelsa_cmip6 package installed (see instructions above).

Install and load the reticulate package
```R
install.packages("reticulate",dependencies = TRUE)
library(reticulate)
```

The import() function enables you to import the chelsa_cmip6 module and call it’s functions directly from R.
```R
chelsa_cmip6 <- import('chelsa_cmip6')
```

You can then use the chelsa_cmip6 function in R the same you would in python.
```R

```


# REQUIREMENTS
------------
chelsa_cmip6 is written in Python 3. It has been tested to run well with the
following Python release and package versions. The dependencies will be installed automatically.
- python 3.8.10
- xarray 0.16.2
- requests 2.25.1
- numpy 1.19.5
- rasterio 1.2.1
- pandas 1.1.5
- zarr 2.6.1
- gcsfs 0.7.2
- datetime 3.9.2
- scipy 0.19.1


## SINGULARITY
------------
All dependencies are also resolved in the singularity container '/singularity/chelsa_cmip6.sif'. Singularity needs to be installed on the respective linux system you are using. 
An installation guide can be found here: https://sylabs.io/guides/3.3/user-guide/quick_start.html#quick-installation-steps

If you use chelsa_cmip6 together with singularity the command should be slightly modified:

```bash
singularity exec /singularity/chelsa_cmip6.sif python3 chelsa_cmip6.py --activity_id 'CMIP' --table_id 'Amon' --experiment_id 'historical' --institution_id 'MPI-M' --source_id 'MPI-ESM1-2-LR' --member_id 'r1i1p1f1' --refps '1981-01-15' --refpe '2010-12-15' --fefps '1851-01-15' --fefpe '1880-12-15' --xmin 5.3 --xmax 10.4 --ymin 46.0 --ymax 47.5 --output '/home/karger/scratch/'
```

tested with singularity version 3.3.0-809.g78ec427cc
but newer versions usually work as well.


## CHECKING IF ALL NEEDED INPUT IS AVAILABLE
------------
Not all models and activities provide all the necessary input needed for chelsa_cmip6.py.
chelsa_cmip6.py will only work for GCMs that are both available for the historical period
and the respective scenario of interest. You can check this by using the CMIP6 data search
interface on e.g. https://esgf-node.llnl.gov/search/cmip6/ 
There you can filter for the different parameters (e.g. experiment_id) and see if a dataset
exists. E.g. by using the parameters given in the example. To check if also the historical
data exists for the model, just change the activity_id to 'CMIP' and the experiment_id to 'historical'.
Make sure the four variables needed do exist both for the scenario and the historical period:

These variables are needed:
- pr
- tas
- tasmax
- tasmin


## OUTPUT
------------
The output consist of netCDF4 files. There will be different files for each variable and seperatly for
the reference (refps - refpe) and the future period (fefps - fefpe). 
Additionally, there will be netCDF4 files for the 
different bioclimatic variables each for both the reference (refps - refpe) and the future period (fefps - fefpe). 


# COPYRIGHT
---------
(C) 2022 Dirk Nikolaus Karger


# LICENSE
-------
chelsa_cmip6 is free software: you can redistribute it and/or modify it under
the terms of the GNU Affero General Public License as published by the
Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

chelsa_cmip6 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 Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with chelsa_cmip6. If not, see <http://www.gnu.org/licenses/>.


## CITATION:
------------
If you need a citation for the output, please refer to the article describing the high
resolution climatologies:

Karger, D.N., Conrad, O., Böhner, J., Kawohl, T., Kreft, H., Soria-Auza, R.W., Zimmermann, N.E., Linder, P., Kessler, M. (2017). Climatologies at high resolution for the Earth land surface areas. Scientific Data. 4 170122. https://doi.org/10.1038/sdata.2017.122


## CONTACT
-------
<dirk.karger@wsl.ch>


## AUTHOR
------
Dirk Nikolaus Karger
Swiss Federal Research Institute WSL
Zürcherstrasse 111
8903 Birmensdorf 
Switzerland


