Master

This project contains Python implementations of various climate indices, which provide a geographical and temporal picture of the severity of precipitation and temperature anomalies:

• SPI: the number of standard deviations that the observed cumulative precipitation deviates from a normalized climatological average. Since it is possible to experience dry conditions over one time scale while simultaneously experiencing wet conditions over a different time scale, the provided implementation computes SPI for any monthly time scale (for example 1-month, 3-month, 12-month, etc.). To compute the SPI a long-term time series of precipitation accumulations over a specified time scale are first used to estimate a probability density function (either the gamma or Pearson Type III distribution). Once the precipitation time-series is fitted to the distribution it is then transformed into a normal distribution. Finally each time step is compared against this normalized distribution, with the resulting sigma as the SPI value for the time step. A zero index value for a particular time step reflects the median of the distribution of precipitation, a -3 indicates a very extreme dry spell, and a +3 indicates a very extreme wet spell. The more the index value departs from zero, the drier or wetter an event lasting X-months is when compared to the long-term climatology of the location. The SPI allows for comparison of precipitation observations at different locations with markedly different climates; an index value at one location expresses the same relative departure from median conditions at one location as at another location.
• SPEI: the number of standard deviations that the observed cumulative precipitation minus potential evapotranspiration (P - PET) deviates from a normalized climatological average. The SPEI is designed to take into account both precipitation and potential evapotranspiration (PET) in determining drought. Thus, unlike the SPI, the SPEI captures the main impact of increased temperatures on water demand. Like the SPI, the SPEI can be calculated on a range of timescales from 1-48 months. At longer timescales (>~18 months), the SPEI has been shown to correlate with the self-calibrating PDSI (sc-PDSI). The SPEI is designed to take into account both precipitation and potential evapotranspiration (PET) in determining drought. Thus, unlike the SPI, the SPEI captures the main impact of increased temperatures on water demand. Like the SPI, the SPEI can be calculated on a range of timescales from 1-48 months. At longer timescales (>~18 months), the SPEI has been shown to correlate with the self-calibrating PDSI (sc-PDSI). PET is estimated using the Thornthwaite method (described below), and as such variables that can affect PET such as wind speed, surface humidity and solar radiation are not accounted for. The SPEI includes the role of temperature by subtracting the potential evapotranspiration from the precipitation and then applying the same distribution fitting and normalization process to find the sigma for each time step. SPEI is like SPI in that it also can be computed over any time scale, and the provided implementation computes values for any monthly time scale (for example 1-month, 3-month, 12-month, etc.).
• PET: potential evapotranspiration, computed using Thornthwaite's equation. This is the maximum amount of water that would be evapotranspired if enough water were available from precipitation and soil moisture, computed based on temperature and latitude inputs.
• PNP: percentage of normal precipitation, where the normal precipitation for a calendar month is the average over a specified calibration period. The provided implementation allows for computation of values over multiple month scales, as with the SPI and SPEI indices.
• PDSI: Palmer Drought Severity Index an index of drought based on precipitation, temperature, and soil moisture capacity, the basis of which the difference between the amount of precipitation required to retain a normal water-balance level and the amount of actual precipitation. The other parts of the PDSI calculation account for climatic differences between locations and seasons of the year. These computations attempt to scale the index values to allow for comparisons across time and space. Developed by Wayne Palmer, 1965. Using a two-level water balance model and PET computed using Thornthwaite's method (see PET above), various coefficients, climatically appropriate for existing conditions (CAFEC) precipitation, and weighting factors (K) are calculated to then produce a moisture anomaly index (see Z-Index below) and then (optionally through a series of backtracking steps) a corresponding PDSI value is selected.
• scPDSI: Self-calibrated Palmer Drought Severity Index, a version of the Palmer which automatically calibrates the behavior of the index at any location by replacing empirical constants in the index computation with dynamically calculated values. The self-calibrated PDSI computes a locally weighted climatic characteristic, which affects the range of PDSI values, and the automatic calculation of the duration factors, which adjusts the sensitivity of the index. These two modifications cause the index to behave in a consistent, predictable manner as well as to more realistically represent the climates of diverse locations.
• PHDI: Palmer Hydrologic Drought Index
• Z-Index: Palmer moisture anomaly index (Z-index), much less sensitive to changes in the calibration periods, and also has some desirable characteristics which may make it preferable to the PDSI for some agricultural and forest fire applications, i.e., it is more responsive to short-term moisture anomalies.
• PMDI: Palmer Modified Drought Index

We welcome you to use, make suggestions, and contribute to this code.

• Read our contributing guidelines
• File an issue, or submit a pull request
• Send us an email

This project's code is written for Python 3. It's recommended that you use an installation of the Anaconda Python 3 distribution. The below instructions will be Anaconda specific, and initially aimed at Linux users.

For users without an existing Python/Anaconda installation we recommend either

• installing the Miniconda (minimal Anaconda) distribution or
• installing the full Anaconda distribution

This library and the example processing scripts use the netCDF4, numpy, scipy, and numba Python modules. The NetCDF Operators (NCO) software package is also useful for the processing scripts, and can optionally be installed as a Python module via conda.

A new Anaconda environment containing all required modules can be created through the use of the provided environment.yml file, which specifies an environment named indices_reference containing all required modules:

$ conda env create -f environment.yml

The environment created by the above command can be activated using the following command:

$ source activate indices_reference

For users who'd prefer to not utilize the above approach using the provided environment.yml file, the required module dependencies can instead be installed into an Anaconda environment piecemeal via multiple conda install commands:

$ conda create --name <env_name> python=3 $ source activate <env_name> $ conda install numba $ conda install scipy $ conda install netCDF4 $ conda install hdf4=4.2.12 (this may be required in order to get around a broken HDF dependency issue with the netCDF4 module)

Initially all tests should be run for validation:

$ python -m unittest test_*.py

There are example climate indices processing scripts provided which compute the full suite of indices for various input dataset types. These process input files in the NetCDF format, and produce output NetCDF files in a corresponding format.

The script process_nclimgrid.py is used to compute climate indices from nClimGrid input datasets. Usage of this script requires specifying the input file names and corresponding variable names for prcipitation, temperature, and soil constant datasets, as well as the month scales over which the scaled indices (SPI, SPEI, and PAP) are to be computed, plus the base output file name and the initial and final years of the calibration period.

This script has the following required command line arguments:

Example command line invocation:

$ nohup python -u process_nclimgrid.py --precip_file example_inputs/nclimgrid_lowres_prcp.nc --temp_file example_inputs/nclimgrid_lowres_tavg.nc --awc_file example_inputs/nclimgrid_lowres_soil.nc --precip_var_name prcp --temp_var_name tavg --awc_var_name awc --month_scales 1 2 3 6 12 24 --calibration_start_year 1931 --calibration_end_year 1990 --output_file_base nclimgrid_lowres --destination_dir /indices

The script process_nclimdiv.py is used to compute climate indices from nClimDiv input datasets. Usage of this script requires specifying the input file name and corresponding variable names for precipitation, temperature, and soil constant datasets, as well as the month scales over which the scaled indices (SPI, SPEI, and PAP) are to be computed, plus the base output file name and the initial and final years of the calibration period.

This script has the following required command line arguments:

Example command line invocation:

$ nohup python -u process_nclimdiv.py --input_file example_inputs/nclimdiv_20170404.nc --precip_var_name prcp --temp_var_name tavg --awc_var_name awc --month_scales 1 2 3 6 12 24 --calibration_start_year 1931 --calibration_end_year 1990 --output_file nclimdiv_20170404_indices.nc

This project is in the public domain within the United States, and we waive worldwide copyright and related rights through CCO universal public domain dedication. Read more on our license page.