Documentation

A full documentation website is under development.

Installation

Currently we recommend using the provided conda environment files to install dependencies. Download the appropriate .yml file e.g. on Windows env_windows.yml and then install and activate it. If you don’t have conda get it here. To install dependencies in a virtual environment run

$ conda env create -f env_windows.yml

To activate the environment before using gridwxcomp run

$ activate gridwxcomp

on windows, or on Linux, Mac

$ source activate gridwxcomp

Next install using pip,

$ pip install gridwxcomp

Due to dependency conflicts you may have issues directly installing with pip before activating the conda environment.

Alternatively, or if there are installation issues, you can manually install. First activate the gridwxcomp conda environment (above). Next, clone or download the package from GitHub or PyPI and then install locally with pip in “editable” mode. For example with cloning,

$ git clone https://github.com/WSWUP/gridwxcomp.git
$ cd gridwxcomp
$ pip install -e .

If you downloaded the source distribution then run pip install -e . in the root directory where the setup.py file is located. This installation method is ideal if you want to be able to modifying the source code.

Lastly, gridwxcomp uses the Google Earth Engine API to download gridMET data, therefore you will need a Google account and before the first use on a machine you will need to verify your account. From the command line type:

$ python -c "import ee; ee.Initialize()"

and follow the instructions.

Quick start from command line

This workflow will use the example data given in “gridwxcomp/gridwxcomp/example_data” which includes four climate stations. To find the location of this data from the command line type

$ python -c "import pkg_resources; print(pkg_resources.resource_filename('gridwxcomp', 'example_data/Station_Data.txt'))"

Once complete, this example workflow will calculate bias ratios between station and gridMET ETr, spatially interpolate GeoTIFF rasters of bias ratios at 400m resolution, and calculate zonal statistics of mean bias ratios for each gridMET cell in the region of the stations, similar to what is shown below.

The same workflow can be done on climate variables other than ETr using gridwxcomp, e.g. observed ET, temperature, precipitation, wind speed, short wave radiation, etc.

After installing with pip the gridwxcomp command line interface can be used from any directory,

$ gridwxcomp prep-input -i <PATH_TO example_data/Station_Data.txt>

This will result in the file “merged_input.csv”. Next download matching gridMET climate time series by running

$ gridwxcomp download-gridmet-ee merged_input.csv -y 2016-2017

The time series of gridMET data that correpond with the stations in “merged_input.csv” will be saved to a new folder called “gridmet_data” by defualt. In this case only the years 2016-2017 are used because the test station data time coverage only includes recent years plus it saves time.

Next, this command calculates monthly (and annual) bias ratios for each station/gridMET pair and saves them to CSV files

$ gridwxcomp calc-bias-ratios merged_input.csv -o monthly_ratios

Last, to calculate interpolated surfaces of mean bias ratios and extract zonal means to gridMET cells using the default interpolation method (inverse distance weighting):

$ gridwxcomp spatial monthly_ratios/etr_mm_summary_comp.csv -b 5

The [-b 5] option indicates that we want to expand the rectangular bounding area for interpolation by five gridMET cells (extrapolation in the outer regions).

The final output file “monthly_ratios/spatial/etr_mm_invdist_400m/gridMET_stats.csv” contains monthly bias ratios for each gridMET cell in the interpolation region, similar to what is shown below.

GRIDMET_ID	Jan_mean	Feb_mean	Mar_mean	…
515902	0.66	0.76	0.96	…
514516	0.66	0.77	0.96	…
513130	0.67	0.77	0.97	…
511744	0.67	0.78	0.97	…
510358	0.68	0.79	0.97	…
…	…	…	…	…

Note GRIDMET_ID is the index of the master gridMET dataset 4 km fishnet grid starting at 0 in the upper left corner and moving across rows and down columns. This value can be joined with previously created data to relate the ID values to centroid locations of cells.

GeoTIFF rasters of interpolated ratios will be saved to “monthly_ratios/spatial/etr_mm_invdist_400m/”. Note, the gridMET variable name (etr_mm), the interpolation method (invdist), and the raster resolution (400m) are specified in the output directory. A fishnet grid with gridMET id values and a point shapefile of station ratios should all be created and saved in the “monthly_ratios/spatial/” directory.

To get help with any of the above gridwxcomp commands use the [--help] option, e.g.

$ gridwxcomp spatial --help