API Reference

This page documents all routines provided by gridwxcomp. Tools for different routines are listed roughly in the order that they would normally be used.

Command Line Interface

gridwxcomp

Access gridwxcomp functionality from the command line

The gridwxcomp tools are accesible via a command line interface using the console command “gridwxcomp”. To print a list of all available commands from the command line type,:

gridwxcomp --help

Or to print information on a specific command,:

gridwxcomp COMMAND --help

Basic usage to run a command:

gridwxcomp [OPTIONS] COMMAND [ARGS]...

Commands

calc-bias-ratios

Bias ratio statistics of station-to-gridMET…

download-gridmet-opendap

Download gridMET climate time series using…

plot

Create comparison or diagnostic graphics Plot…

prep-input

Pairs climate metadata with grid.

spatial

Spatially interpolate ratio statistics 2-D…

gridwxcomp prep-input

Pairs climate metadata with grid.

Read climate station metadata file, e.g. from PyWeatherQAQC and match each station with gridcell locations, save CSV. The required argument STATION_META_PATH is a file containing metadata of climate stations, if it was not built from PyWeatherQAQC, the file should be in CSV format and contain at least these four columns:

• Latitude

• Longitude

• Station

• Filename

For example the “Station_Data.txt” file is included as an example at gridwxcomp/gridwxcomp/example_data/, contains

Latitude	Longitude	Station	Filename
40.37232	-110.20918	Bluebell (Neola Area)	BluebellUT_Daily_output
38.38346	-111.63583	Loa	LoaUT_Daily_output
38.32829	-108.85549	Bedrock	BedrockCO_Daily_output
38.64294	-109.39880	Castle Valley near Moab	CastleValleyUT_Daily_output

Also, if not created by PyWeatherQaQc, the climate station time series files should be in CSV format with a date column with datetime formats, e.g. ‘12/01/2018’. By default gridwxcomp prep-input creates the file “merged_input.csv” in the current working directory which contains metadata from climate stations as well as the lat, long, and gridMET ID (cell index) of the nearest gridMET cell centroid.

If using a gridded product that is not gridMET this routine has the ability to create a grid metadata file if --grid-path and --grid-id-name arguments are given. The grid should be a uniform grid with a resolution in decimal degrees, it should also have a cell identifier that is of integer data type- the name of this property in your grid is what is passed as --grid-id-name. Also if using a different grid, the time series files associated with the cell IDs that match your station locations should be in the directory given as --grid-data-dir.

gridwxcomp prep-input [OPTIONS] STATION_META_PATH

Options

-o, --out-path <out_path>

File path to save output CSV

-gm, --grid-meta <grid_meta>

File path to grid metadata, e.g. gridmet_cell_data.csv

-gp, --grid-path <grid_path>

File path to master grid vector file if not using gridMET

-gin, --grid-id-name <grid_id_name>

Name of gridcell identifier if not using gridMET

-gdd, --grid-data-dir <grid_data_dir>

Directory with grid time series if not using gridMET

--quiet

Supress command line output

Arguments

STATION_META_PATH

Required argument

gridwxcomp calc-bias-ratios

Bias ratio statistics of station-to-gridMET

Calculates mean bias ratios between climate station to gridMET variables at multiple time periods: monthly, annual, growing season. Other statistics include day counts, standard deviation, and coefficient of variation. Options allow for excluding statistics on months with less than a certain number of days (default 10). gridMET variable names available and their default paired climate variable names include:

gridMET	station
‘u2_ms’	‘ws_2m (m/s)’
‘tmin_c’	‘TMin (C)’
‘tmax_c’	‘TMax (C)’
‘srad_wm2’	‘Rs (w/m2)’
‘ea_kpa’	‘Vapor Pres (kPa)’
‘prcp_mm’	‘Precip (mm)’
‘etr_mm’	‘Calc_ETr (mm)’
‘eto_mm’	‘Calc_ETo (mm)’

If --grid-var is given from the default options, the corresponding default station variable name will be looked up in the input station data and used, otherwise you must assign both the gridMET name (from table above) and station variable based on the variable names in your station time series CSV file(s).

The required argument INPUT_CSV is the CSV file that is produced by prep-input and download-gridmet-opendap or download-gridmet-ee.

gridwxcomp calc-bias-ratios [OPTIONS] INPUT_CSV

Options

-o, --out-dir <out_dir>

Folder to save correction ratio summary CSV files

-meth, --method <method>

Mean ratio calculation, “long_term_mean” or “mean_of_annual”

-gin, --grid-id-name <grid_id_name>

Name of gridcell identifier, need to specify if using own grid

-gv, --grid-var <grid_var>

Name of grid climatic variable, e.g. etr_mm

-sv, --station-var <station_var>

Name of station climatic variable

-sdn, --station-date-name <station_date_name>

Name of date column in station time series files

-gdn, --grid-date-name <grid_date_name>

Name of date column in grid time series files

-id, --grid-id <grid_id>

grid ID for calculating ratios only for stations in that cell

-d, --day-limit <day_limit>

Monthly day threshold, if missing more exclude month from calc

-y, --years <years>

Year(s) to use, e.g. 2010 or 2000-2010

-c, --comp

Flag to NOT save comprehensive output CSV

--quiet

Supress command line output

Arguments

INPUT_CSV

Required argument

gridwxcomp download-gridmet-opendap

Download gridMET climate time series using OpeNDAP

Download gridMET time series for cells that are paired to climate stations in a CSV file that is first created by gridwxcomp prep-input. Options allow for downloading all years available (default) or select years, it is also possible to redownload data for specified year(s). If --out-dir is not specified, gridMET time series CSVs are saved to a new directory named “gridmet_data” within the current working directory.

gridwxcomp download-gridmet-opendap [OPTIONS] INPUT_CSV

Options

-o, --out-dir <out_dir>

Folder to save downloaded gridMET time series

-y, --years <years>

Year(s) to download, single year (YYYY) or range (YYYY-YYYY)

-u, --update-data

Redownload existing data for given year(s)

--quiet

Supress command line output

Arguments

INPUT_CSV

Required argument

gridwxcomp spatial

Spatially interpolate ratio statistics

2-D interpolation of mean bias ratios or other statistics that exist in the SUMMARY_COMP_CSV file created by gridwxcomp calc-bias-ratios. Interpolation algorithms include those provided by gdal_grid: ‘invdist’ (default), ‘invdistnn’, ‘linear’, ‘average’, and ‘nearest’ and scipy.interpolate.Rbf: ‘multiquadric’, ‘inverse’, ‘gaussian’, ‘linear_rbf’, ‘cubic’, ‘quintic’, and ‘thin_plate’. Parameters for gdal algorithms are set using --params whereas the --smooth parameter (default 0) is used by scipy radial basis functions. Default parameters for gdal are stored in gridwxcomp.InterpGdal.default_params.

Interpolation resampling resolution can be down- or up-scaled using --scale-factor (default 0.1) which is applied to gridMET resolution of 4 km.

On the first run this command will produce a fishnet of gridMET cells that bound the climate stations in SUMMARY_COMP_CSV with optional buffer of gridMET cells which can later be overwritten.

All mean bias ratios found within gridwxcomp.InterpGdal.default_layers are interpolated by default unless --layers are specified. Interpolated residuals to station point ratios are also estimated. Zonal means for gridMET cells in the fishnet grid are extracted by default and assigned to each gridMET cell by its index (GRIDMET_ID) in the full gridMET fishnet that covers the CONUS. In total interpolated rasters, station point shapefiles, fishnet grid for zonal stats, and CSVs of bias ratios and zonal statistics are all created and stored in a file structure that is explained in gridwxcomp.spatial.make_grid. and gridwxcomp.spatial.interpolate.

gridwxcomp spatial [OPTIONS] SUMMARY_COMP_CSV

Options

-o, --out <out>

Subdirectory for saving interpolated rasters

-l, --layer <layer>

Layers to interpolate comma separated, e.g. Jan_mean,Aug_mean

-gin, --grid-id-name <grid_id_name>

Name of gridcell integer ID, must specify if not using gridMET

-b, --buffer <buffer>

Buffer for expanding interpolation region (number of gridcells)

-s, --scale <scale>

Scale factor for gridMET interpolation, applied to 4 km res

-f, --function <function>

Algorithm name for spatial interpolation

--smooth <smooth>

Smoothing parameter for radial basis funciton interpolation

-p, --params <params>

Parameters for gdal_grid interpolation e.g. :power=2:smooth=0

--grid-res <grid_res>

Grid resolution in decimal degrees if not using gridMET

-z, --no-zonal-stats

Flag to NOT extract zonal means of interpolated results

--overwrite-grid

Flag to overwrite grid for zonal stats if already exists

-r, --no-resid-plot

Flag to NOT plot station residuals between observed and interpolated data for layer

--options <options>

Extra command line arguments for gdal_grid interpolation

-gm, --grid-meta <grid_meta>

file path to gridcell metadata if not using gridMET

--quiet

Supress command line output

Arguments

SUMMARY_COMP_CSV

Required argument

gridwxcomp plot

Create comparison or diagnostic graphics

Plot time series and scatter comparison plots between station and gridMET paired variables at daily or monthly average time periods. Also allows for plotting a single variable as a bar plot that compares multiple climate stations. Plots are interactive (can be panned, zoomed, etc.) HTML files.

Currently there are two major plot types provided which are specified by [-t, --plot-type]: 1) “station-grid-comp” which creates time series comparison plots of all gridMET variables to station values; and 2) the second type “station-bar” which compares stations for a single variable. For time series comparisons a plot is created for each station if time frequency of plots, i.e. --freq is “monthly” and for each month for each station if --freq is “daily” (default). For producing a station bar plot you must assign the variable to plot using [-v, --variable].

By default, if --out-dir is not specified time series plots are saved in “[freq]_comp_plots” in the current directory where [freq] is set to --freq. Station bar plots are saved by default to “station_bar_plots” directory created in the same directory containing the summary CSV assigned to INPUT_CSV.

Note: Both daily and monthly comparison plots between station and gridMET i.e. when plot-type = “station-grid-comp” require station data to be within excel files that follow the format produced by PyWeatherQAQC.

gridwxcomp plot [OPTIONS] INPUT_CSV

Options

-t, --plot-type <plot_type>

Plot type, station comparison bar plot “station-bar” for a single variable, or station to gridMET time series comparison for multiple variables “station-grid-comp”

-v, --variable <variable>

Variable to plot for –type=”station-bar” plots, default “annual_mean”, can also pass a comma separated list: e.g. “Jan_mean,Jan_res,Jan_est”

-f, --freq <freq>

Time frequency for station-grid-comp plots “daily” or “monthly”

-o, --out-dir <out_dir>

Folder to save plots

-y, --year <year>

Years for time series, single year YYYY or range YYYY-YYYY

--x-label <x_label>

X-axis label for station-bar plot

--y-label <y_label>

Y-axis label for station-bar plot

--title <title>

Title for station-bar plot

--subtitle <subtitle>

Subtitle for station-bar plot, comma separated list for multiple

--year-subtitle

Print subtitle with years used for station-bar plots

--quiet

Supress command line output

Arguments

INPUT_CSV

Required argument

Python functions, classes, and modules

prep_input

gridwxcomp.prep_input(station_path, out_path='merged_input.csv', grid_meta_path=None, grid_path=None, grid_id_name=None, grid_data_dir=None)

Read list of climate stations and match each with its closest gridcell, save CSV with information from both.

Station time series files must be in the same directory as station_path metadata file.

If using gridded data other than gridMET this function may be used to create a metadata CSV file of cell data for any arbitrary rectangular grid. The grid must be passed to grid_path and it must contain a cell identifier attribute (name must be passed in as grid_id_name) that is an integer which increases monotonically by steps of 1 without gaps, e.g. 1,2,3,4,… although the cell order does not have to follow any rule. For example, the first cell may be in any location and the next may be anywhere and so forth. Also if using a different grid, the time series files associated with the cell IDs that match your station locations should be in the directory given as grid_data_dir.

Parameters

station_path (str) – path to CSV file containing metadata of climate stations that will later be used to calculate bias ratios to GridMET.

Keyword Arguments

• out_path (str) – path to save output CSV, default is to save as ‘merged_input.csv’ to current working directory.

• grid_meta_path (str or None) – default None. Path to save grid metadata CSV, if None save to “grid_cell_data.csv” in current directory. This is only used if working with a user provided gridded dataset, i.e. if grid_path and grid_id_name (if creating a new grid meta file are given.

• grid_path (str) – path to grid vector file if not using gridMET.

• grid_id_name (str) – name of gridcell identifier present in grid, ID data values should be integers.

• grid_data_dir (str) – directory that contains grid time series files, each file should have the integer grid ID value in its name and should be in CSV format. Only used when gridded time series data already exists on disk.

Returns

None

Example

>>> from gridwxcomp import prep_input
>>> prep_input('gridwxcomp/example_data/Station_Data.txt','outfile.csv')

outfile.csv will be created containing station and corresponding gridMET cell data. This file is later used as input for gridwxcomp.download_gridmet_opendap and gridwxcomp.calc_bias_ratios.

Important

Make sure the following column headers exist in your input station metadata file (station_path) and are spelled exactly:

• Latitude

• Longitude

• Station

• Filename

Also, the “Filename” column should match the names of the climate time series files that should be in the same directory as the station metadata file. For example, if one of the time series files is named “Bluebell_daily_data.csv” then the following are permissiable entries as the “Filename”: “Bluebell_daily_data” or “Bluebell_daily_data.csv”.

Raises

• FileNotFoundError – if the grid_meta_path is not passed as a command line argument and it is not in the current working directory and named “gridmet_cell_data.csv” (i.e. if other grid data is not given) and if gridwxcomp was not installed to the user’s PATH, i.e. pip or python setup.py install.

• ValueError – if one or more of the following mandatory columns are missing from the input CSV file (station_path parameter): ‘Longitude’, ‘Latitude’, ‘Station’, or ‘Filename’.

Note

If climate station time series files do NOT follow the format created by pyWeatherQAQC i.e. microsoft excel files with data stored in a tab named ‘Corrected Data’. Then station files should be in text (CSV) format with a column containing datetime strings e.g. ‘12/01/2018’, that are able to be parsed by Pandas. The CSV file produced by prep_input contains latitude, longitude, and other fields for both the station and nearest gridcell centroid coordinates. Fields that may refer to both grid and station data have prefixes to distinguish, the climate station data are prefixed with ‘STATION’ and those refering to grid data have no prefix.

download_gridmet_opendap

gridwxcomp.download_gridmet_opendap(input_csv, out_folder, year_filter='', update_data=False, optional_vars=None)

Download gridMET time series data for multiple climate variables for select gridMET cells as listed in input_csv. Uses OpeNDAP.

Parameters

• input_csv (str) – file path of input CSV produced by prep_input.py

• out_folder (str) – directory path to save gridmet timeseries CSV files

Keyword Arguments

• year_filter (list) – default ‘’. Single year or range to download

• update_data (bool) – default False. Re-download existing data

• optional_vars (None or list) – default None. List of additional gridMET vars to download using gridMET short names, currently only wind direction named “th” is available.

Returns

None

Examples

Say we wanted to download data for 2016 through 2018, from the command line,

$ download_gridmet_opendap.py -i merged_input.csv -o gridmet_data -y 2016-2018

note, “merged_input.csv” should have been created by first running prep_input.py. If the [-y, --years] option is note given the default behaviour is to download gridMET data from 1979 up through yesterday.

If the data for 2018 has changed since the last run or for debugging purposes you can re-download data for all or select years with the [-u, --update-data] option

$ download_gridmet_opendap.py -i merged_input.csv -o gridmet_data -y 2018 -u

To download the same gridMET data within Python

>>> from gridwxcomp import download_gridmet_opendap
>>> download_gridmet_opendap('merged_input.csv',
        'gridmet_data',
        '2016-2018'
    )

Running download_gridmet_opendap.py also updates the CSV file produced from prep_input.py to include file paths to gridMET time series files that are paired with climate stations.

calc_bias_ratios

Calculate monthly bias ratios of variables from climate station to overlapping gridMET (or other gridded dataset) cells.

Input file for this module must first be created by running gridwxcomp.prep_input followed by gridwxcomp.download_gridmet_opendap.

gridwxcomp.calc_bias_ratios.GRIDMET_STATION_VARS

mapping dictionary with gridMET variable names as keys and station variable names as values. Used to determine which station variable to calculate bias ratios according to the given gridMET variable.

Type

dict

Default values:

GRIDMET_STATION_VARS = {
    'u2_ms' : 'ws_2m (m/s)',
    'tmin_c' : 'TMin (C)',
    'tmax_c' : 'TMax (C)',
    'srad_wm2' : 'Rs (w/m2)',
    'ea_kpa' : 'Vapor Pres (kPa)',
    'prcp_mm' : 'Precip (mm)',
    'etr_mm' : 'ETr (mm)',
    'eto_mm' : 'ETo (mm)'
}

Note: The module attribute GRIDMET_STATION_VARS can be manually adjusted,

if gridwxcomp is installed in editable mode or used as scripts from the root directory. New pairs of station-to-grid variables can then be made or removed to efficiently use gridwxcomp on station data that was not created by PyWeatherQAQC. Otherwise, the same can be achieved by the var_dict or grid_var and station_var arguments to calc_bias_ratios.

gridwxcomp.calc_bias_ratios.calc_bias_ratios(input_path, out_dir, method='long_term_mean', grid_id_name='GRIDMET_ID', grid_var='etr_mm', station_var=None, var_dict=None, station_date_name='date', grid_date_name='date', grid_ID=None, day_limit=10, years='all', comp=True)

Read input CSV file and calculate mean monthly bias ratios between station to corresponding grid cells for all station and grid pairs, optionally calculate ratios for a single gridcell.

Parameters

• input_path (str) – path to input CSV file with matching station climate and grid metadata. This file is created by running gridwxcomp.prep_input followed by gridwxcomp.download_gridmet_opendap.

• out_dir (str) – path to directory to save CSV files with monthly bias ratios of etr.

Keyword Arguments

• method (str) – default ‘long_term_mean’. How to calculate mean station to grid ratios, currently two options ‘long_term_mean’ takes the mean of all dates for the station variable that fall in a time periods, e.g. the month of January, to the mean of all paired January dates in the gridded product. The other option is ‘mean_of_annual’ which calculates ratios, for each time period if enough paired days exist, the ratio of sums for each year in the record and then takes the mean of the annual ratios. This method is always used to calculate standard deviation and coefficient of variation of ratios which describe interannual variation of ratios.

• grid_id_name (str) – default ‘GRIDMET_ID’. Name of index/cell identifier for gridded dataset, only change if supplying user grid data.

• grid_var (str) – default ‘etr_mm’. Grid climate variable to calculate bias ratios.

• station_var (str) – default None. Climate station variable to use to calculate bias ratios. If None, look up using grid_var as a key to GRIDMET_STATION_VARS dictionary found as a module attribute to gridwxcomp.calc_bias_ratios.

• var_dict (dict) – default None. Dictionary that maps grid variable names to station variable names to overide gridMET and PyWeatherQaQc defaules used by GRIDMET_STATION_VARS.

• grid_ID (int) – default None. Grid ID (int cell identifier) to only calculate bias ratios for a single gridcell.

• day_limit (int) – default 10. Threshold number of days in month of missing data, if less exclude month from calculations. Ignored when method='long_term_mean'.

• years (int or str) – default ‘all’. Years to use for calculations e.g. 2000-2005 or 2011.

• comp (bool) – default True. Flag to save a “comprehensive” summary output CSV file that contains station metadata and statistics in addition to the mean monthly ratios.

Returns

None

Examples

To use within Python for observed ET,

>>> from gridwxcomp import calc_bias_ratios
>>> input_path = 'merged_input.csv'
>>> out_dir = 'monthly_ratios'
>>> grid_variable = 'eto_mm'
>>> calc_bias_ratios(input_path, out_dir, grid_var=grid_variable)

To use custom station data, give the keyword argument station_var, e.g. if we had climate daily time series data for precipitation with the column named “p” then,

>>> calc_bias_ratios(input_path, out_dir, grid_var='prcp_mm',
>>>     station_var='p')

This results in two CSV files in out_dir named “prcp_mm_summary_all_yrs.csv” and “prcp_mm_summary_comp_all_yrs.csv”.

Raises

• FileNotFoundError – if input file is invalid or not found.

• KeyError – if the input file does not contain file paths to the climate station and grid time series files. This occurs if, for example, the gridwxcomp.prep_input and/or gridwxcomp.download_gridmet_opendap scripts have not been run first (if using gridMET data). Also raised if the given grid_var, station_var, or values of var_dict kwargs are invalid.

• ValueError – if the method kwarg is invalid.

Note

Growing season and summer periods over which ratios are calculated are defined as April through October and June through August respectively.

Note

If an existing summary file contains a climate station that is being reprocessed its monthly bias ratios and other data will be overwritten. Also, to proceed with spatial analysis scripts, the comprehensive summary file must be produced using this function first. If grid_var keyword argument is given but the station_var is left as default (None), the corresponding station variable is looked up from the mapping dictionary in calc_bias_ratios.py named GRIDMET_STATION_VARS. To use climate data that was not created by pyWeatherQAQC for station data and/or gridded data other than gridMET, which is where the default names are derived, the grid and station variable names need to be explicitly passed as function arguments.

spatial

Perform multiple workflows needed to estimate the spatial surface (and other related outputs) of monthly and annual station-to-grid bias ratios for meteorological variables. The input file is first created by gridwxcomp.calc_bias_ratios.

gridwxcomp.spatial.GRIDMET_RES

constant gridMET cell size in decimal degrees, value = 0.041666666666666664.

Type

float

gridwxcomp.spatial.PT_ATTRS

all attributes expected to be in point shapefile created for stations except station and drid IDs.

Type

tuple

Note

All spatial files, i.e. vector and raster files, utilize the ESRI Shapefile or GeoTiff format.

gridwxcomp.spatial.make_points_file(in_path, grid_id_name='GRIDMET_ID')

Create vector shapefile of points with monthly mean bias ratios for climate stations using all stations found in a comprehensive CSV file created by gridwxcomp.calc_bias_ratios.

Parameters

in_path (str) – path to [var]_summary_comp.CSV file containing monthly bias ratios, lat, long, and other data. Shapefile “[var]_summary_pts.shp” is saved to parent directory of in_path under “spatial” subdirectory.

Returns

None

Example

Create shapefile containing point data for all climate stations in input summary file created by gridwxcomp.calc_bias_ratios

>>> from gridwxcomp import spatial
>>> # path to comprehensive summary CSV
>>> summary_file = 'monthly_ratios/etr_mm_summary_comp_all_yrs.csv'
>>> spatial.make_points_file(summary_file)

The result is the file “etr_mm_summary_pts.shp” being saved to a subdirectory created in the directory containing in_path named “spatial”, i.e.:

"monthly_ratios/spatial/etr_mm_summary_pts.shp".

Raises

FileNotFoundError – if input summary CSV file is not found.

Note

make_points_file will overwrite any existing point shapefile of the same climate variable.

gridwxcomp.spatial.get_subgrid_bounds(in_path, buffer, grid_res=None)

Calculate bounding box for spatial interpolation grid from comprehensive summary CSV file containing monthly bias ratios and station locations.

Parameters

• in_path (str) – path to comprehensive summary file containing monthly bias ratios, created by gridwxcomp.calc_bias_ratios.

• buffer (int) – number of gridMET cells to expand the rectangular extent of the subgrid fishnet.

Returns

tuple with coordinates in decimal degrees that

define the outer bounds of the subgrid fishnet in the format (min long, max long, min lat, max lat)

Return type

bounds (tuple)

Raises

FileNotFoundError – if input summary CSV file is not found.

Note

By expanding the grid to a larger area encompassing the climate stations of interest interpolate can be used to extrapolate passed the bounds of the outer station locations.

gridwxcomp.spatial.make_grid(in_path, bounds=None, buffer=25, overwrite=False, grid_id_name='GRIDMET_ID', grid_meta_path=None, grid_res=None)

Make fishnet grid (vector file of polygon geometry) for select gridcells based on bounding coordinates.

Add grid ID values to each cell based on their centroid. If using gridMET, lookup in gridwxcomp/gridmet_cell_data.csv. Assigns the WGS84 reference coordinate system. The grid is later used to spatially interpolate point data. Modified from the Python GDAL/OGR Cookbook.

Parameters

in_path (str) – path to [var]_summary_comp_[years].csv file containing monthly bias ratios, lat, long, and other data. Created by gridwxcomp.calc_bias_ratios.

Keyword Arguments

• bounds (tuple or None) – default None. Tuple of bounding coordinates in the following order (min long, max long, min lat, max lat) which need to be in decimal degrees. Need to align with grid resolution outer corners. If None, get extent from centoid locations of climate stations in in_path summary CSV.

• buffer (int) – default 25. Number of gridcells to expand the rectangular extent of the subgrid fishnet and interpolated output raster.

• overwrite (bool) – default False. If True overwrite the grid shapefile at out_path if it already exists.

• grid_id_name (str) – default “GRIDMET_ID”. Name of gridcell identifier if using a non-gridMET gridded dataset.

• grid_meta_path (str) – default None. Path to metadata CSV file that contains all grid cells. If None it is looked for at the install directory of gridwxcomp (i.e. with pip install) or within the current directory as “gridmet_cell_data.csv”. Only needed when using a gridded product other than the default gridMET.

• grid_res (float) – default None. Cell size of grid in decimal degrees if using a grid that is not gridMET.

Returns

None

Examples

Build a fishnet uniform grid that matches gridMET cells around climate stations found in in_path summary CSV file with a 25 cell buffer.

>>> from gridwxcomp import spatial
>>> # assign input paths
>>> summary_file = 'monthly_ratios/etr_mm_summary_comp_all_yrs.csv'
>>> # make fishnet of gridMET cells for interpolation
>>> spatial.make_grid(summary_file)

The file will be saved as “grid.shp” to a newly created subdirectory “spatial” in the same directory as the input summary CSV file. i.e.:

monthly_ratios/
├── etr_mm_summary_all_yrs.csv
├── etr_mm_summary_comp_all_yrs.csv
└── spatial/
    ├── grid.cpg
    ├── grid.dbf
    ├── grid.prj
    ├── grid.shp
    └── grid.shx

To use a smaller buffer to the extent of the grid assign the buffer keyword argument

>>> spatial.make_grid(summary_file, buffer=5)

If the grid file already exists the default action is to not overwrite. To overwrite an existing grid if, for example, you are working with a new set of climate stations as input, then set the overwrite keyword argument to True.

>>> spatial.make_grid(summary_file, overwrite=True, buffer=5)

Raises

FileNotFoundError – if input summary CSV file is not found.

Note

If cells in the fishnet grid lie outside of the gridMET master fishnet for the contiguous U.S., the grid ID (grid_id_name) will be assigned to -999.

gridwxcomp.spatial.interpolate(in_path, layer='all', out=None, scale_factor=0.1, function='invdist', smooth=0, params=None, bounds=None, buffer=25, z_stats=True, res_plot=True, grid_id_name='GRIDMET_ID', grid_res=None, options=None, grid_meta_path=None)

Use various methods to interpolate a 2-dimensional surface of calculated bias ratios or other statistics for station/gridMET pairs found in input comprehensive summary CSV.

Options allow for modifying down- or up-scaling the resolution of the resampling grid and to select from multiple interpolation methods. Interploated surfaces are saved as GeoTIFF rasters. Zonal statistics using zonal_stats are also extracted to gridMET cells in the fishnet grid built first by make_grid.

Parameters

in_path (str) – path to [var]_summary_comp_[years].csv file containing monthly bias ratios, lat, long, and other data. Created by gridwxcomp.calc_bias_ratios.

Keyword Arguments

• layer (str or list) – default ‘all’. Name of variable(s) in in_path to conduct 2-D interpolation. e.g. ‘Annual_mean’.

• out (str) – default None. Subdirectory to save GeoTIFF raster(s).

• scale_factor (float, int) – default 0.1. Scaling factor to apply to original grid resolution to create resampling resolution. If scale_factor = 0.1, the resolution will be one tenth gridMET resolution or 400 m.

• function (str) –

  default ‘invdist’. Interpolation method, gdal methods include: ‘invdist’, ‘indistnn’, ‘linear’, ‘average’, and ‘nearest’ see gdal_grid. Radial basis functions, see scipy.interpolate.Rbf, include: ‘multiquadric’, ‘inverse’, ‘gaussian’, ‘linear_rbf’, ‘cubic’, ‘quintic’, and ‘thin_plate’.

• smooth (float) – default 0. Smooth parameter for Rbf functions.

• params (dict, str, or None) – default None. Parameters for interpolation using gdal, see defaults in gridwxcomp.InterpGdal.

• bounds (tuple or None) – default None. Tuple of bounding coordinates in the following order (min long, max long, min lat, max lat) which need to be in decimal degrees. Need to align with gridMET resolution outer corners. If None, get extent from centoid locations of climate stations in in_path summary CSV.

• buffer (int) – default 25. Number of grid cells to expand the rectangular extent of the subgrid fishnet and interpolated output raster.

• z_stats (bool) – default True. Calculate zonal means of interpolated surface to gridMET cells in fishnet and save to a CSV file. The CSV file will be saved to the same directory as the interpolated raster file(s).

• res_plot (bool) – default True. Make bar plot for residual (error) between interpolated and station value for layer.

• grid_id_name (str) – default “GRIDMET_ID”. Name of gridcell identifier if using a grid that is not gridMET.

• grid_res (float) – default None. Grid resolution in decimal degrees if not using gridMET as the gridded dataset.

• options (str or None) – default None. Extra command line arguments for gdal interpolation.

• grid_meta_path (str or None) – default None. Path to metadata CSV file that contains all gridcells. If None it is looked for at the install directory of gridwxcomp (e.g. after pip install gridwxcomp) or within the current directory as ‘gridmet_cell_data.csv’. Only used when using a gridded product other than the default gridMET.

Returns

None

Examples

Let’s say we wanted to interpolate the “Annual_mean” bias ratio in an input CSV first created by gridwxcomp.calc_bias_ratios and a fishnet grid was first created by make_grid. This example uses the “invdist” method (default) to interpolate to a 400 m resolution surface. The result is a GeoTIFF raster that has an extent that encompasses station locations in the input file plus an additional optional buffer of outer gridMET cells. Additionally, point residuals of bias ratios are added to CSV and newly created point shapefiles, zonal (gridMET cell) means are also extracted and stored in a CSV.

>>> from gridwxcomp import spatial
>>> summary_file = 'monthly_ratios/etr_mm_summary_comp_all_yrs.csv'
>>> buffer = 10
>>> layer = 'annual_mean'
>>> params = {'power':1, 'smooth':20}
>>> out_dir = 's20_p1' # optional subdir name for saving rasters
>>> interpolate(summary_file, layer=layer, out=out_dir,
>>>     scale_factor=0.1, params=params, buffer=buffer)

The resulting file structure that is created by the above command is:

monthly_ratios/
├── etr_mm_summary_all_yrs.csv
├── etr_mm_summary_comp_all_yrs.csv
└── spatial/
    ├── etr_mm_invdist_400m/
    │   └── s20_p1/
    │       ├── annual_mean.tiff
    │       ├── annual_mean.vrt
    │       ├── etr_mm_summary_comp_all_yrs.csv
    │       ├── etr_mm_summary_pts.cpg
    │       ├── etr_mm_summary_pts.dbf
    │       ├── etr_mm_summary_pts.prj
    │       ├── etr_mm_summary_pts.shp
    │       ├── etr_mm_summary_pts.shx
    │       ├── zonal_stats.csv
    │       └── residual_plots
    │           └── annual_res.html
    ├── grid.cpg
    ├── grid.dbf
    ├── grid.prj
    ├── grid.shp
    └── grid.shx

Specifically, the interpolated raster is saved to:

'monthly_ratios/spatial/etr_mm_invdist_400m/s20_p1/Annual_mean.tiff'

where the file name and directory is based on the variable being interpolated, methods, and the raster resolution. The out keyword argument lets us add any number of subdirectories to the final output directory, in this case the ‘s20_p1’ dir contains info on params. In this case the original gridMET resolution is 4 km therefore the scale facter of 0.1 results in a 400 m resolution.

The final result will be the creation of the CSV:

'monthly_ratios/spatial/etr_mm_invdist_400m/s20_p1/zonal_stats.csv'

In “zonal_stats.csv” the zonal mean for ratios of annual station to gridMET ETr will be stored along with gridMET IDs, e.g.

GRIDMET_ID	Annual_mean
515902	0.87439453125
514516	0.888170013427734
513130	0.90002197265625
…	…

To calculate zonal statistics of bias ratios that are not part of the default or command line workflow we can assign any numeric layer in the input summary CSV to be interpolations. For example if we wanted to interpolate the coefficient of variation of the growing season bias ratio “April_to_oct_cv”, then we could estimate the surface of this variable straightforwardly,

>>> layer = 'April_to_oct_cv'
>>> func = 'invdistnn'
>>> # we can also 'upscale' the interpolation resolution
>>> interpolate(summary_file, layer=layer, scale_factor=2,
>>>     function=func, buffer=buffer)

This will create the GeoTIFF raster:

'monthly_ratios/spatial/etr_mm_invdistnn_400m/April_to_oct_cv.tiff'

And the zonal means will be added as a column named “April_to_oct_cv” to:

'monthly_ratios/spatial/etr_mm_invdistnn_400m/zonal_stats.csv'

As with other components of gridwxcomp, any other climatic variables that exist in the gridMET dataset can be used along with any corresponding station time series data from the user. The input (in_path) to all routines in gridwxcomp.spatial is the summary CSV created by gridwxcomp.calc_bias_ratios, the prefix to this file is what determines the climatic variable that spatial analysis is conducted. See gridwxcomp.calc_bias_ratios for examples of how to use different climatic variables, e.g. TMax or ETo.

Raises

FileNotFoundError – if the input summary CSV file or the fishnet for extracting zonal statistics do not exist. The fishnet should be in the subdirectory of in_path i.e. “<in_path>/spatial/grid.shp”.

Note

This function can be used independently of make_grid however, if the buffer and input [var]_summary_comp_[years].csv files arguments differ from those used for interpolate the raster may not fully cover the fishnet which may result in gaps in the zonal statistics.

gridwxcomp.spatial.calc_pt_error(in_path, out_dir, layer, grid_var, grid_id_name='GRIDMET_ID')

Calculate point ratio estimates from interpolated raster, residuals, and add to output summary CSV and point shapefile. Make copies of updated files and saves to directory with interpolated rasters.

Parameters

• in_path (str) – path to comprehensive summary CSV created by gridwxcomp.calc_bias_ratios

• out_dir (str) – path to dir that contains interpolated raster

• layer (str) – layer to calculate error e.g. “annual_mean”

• grid_var (str) – name of grid variable e.g. “etr_mm”

Returns

None

Note

This function should be run after make_points_file because it copies data from the shapefile it created.

gridwxcomp.spatial.zonal_stats(in_path, raster, grid_id_name='GRIDMET_ID')

Calculate zonal means from interpolated surface of etr bias ratios created by interpolate using the fishnet grid created by make_grid. Save mean values for each gridcell to a CSV file joined to grid IDs.

Parameters

• in_path (str) – path to [var]_summary_comp_[years].csv file containing monthly bias ratios, lat, long, and other data. Created by gridwxcomp.calc_bias_ratios.

• raster (str) – path to interpolated raster of bias ratios to be used for zonal stats. First created by interpolate.

Example

Although it is prefered to use this function as part of interpolate or indirectly using the gridwxcomp.spatial command line usage. However if the grid shapefile and spatial interpolated raster(s) have already been created without zonal stats then,

>>> from gridwxcomp import spatial
>>> # assign input paths
>>> summary_file = 'monthly_ratios/etr_mm_summary_comp_[years].csv'
>>> raster_file = 'monthly_ratios/spatial/etr_mm_invdist_400m/Jan_mean.tiff'
>>> spatial.zonal_stats(summary_file, raster_file)

The final result will be the creation of:

'monthly_ratios/spatial/etr_mm_invdist_400m/gridMET_stats.csv'

The resulting CSV contains the gridMET IDS and zonal means for each gridMET cell in the fishnet which must exist at:

'monthly_ratios/spatial/grid.shp'

also see interpolate

Raises

FileNotFoundError – if the input summary CSV file or the fishnet for extracting zonal statistics do not exist. The fishnet should be in the subdirectory of in_path at “/spatial/grid.shp”.

Note

If zonal statistics are estimated for the same variable on the same raster more than once, the contents of that column in the zonal_stats.csv file will be overwritten.

plot

Create interactive HTML comparison plots between paired station and gridMET climatic variables or bar comparison plots between interpolated and station point data.

gridwxcomp.plot.daily_comparison(input_csv, out_dir=None, year_filter=None)

Compare daily weather station data from PyWeatherQAQC with gridMET for each month in year specified.

The daily_comparison function produces HTML files with time series and scatter plots of station versus gridMET climate variables. It uses the bokeh module to create interactive plots, e.g. they can be zoomed in/out and panned. Separate plot files are created for each month of a single year.

Parameters

input_csv (str) – path to input CSV file containing paired station/ gridMET metadata. This file is created by running gridwxcomp.prep_input followed by gridwxcomp.download_gridmet_opendap.

Keyword Arguments

• out_dir (str or None) – default None. Directory to save comparison plots, if None save to “daily_comp_plots” in currect directory.

• year_filter (str or None) – default None. Single year YYYY or range YYYY-YYYY

Returns

None

Example

The daily_comparison function will generate HTML files with bokeh plots for paired climate variables, e.g. etr_mm, eto_mm, u2_ms, tmin_c, tmax_c, srad_wm2, ea_kpa, and Ko (dew point depression). Monthly plots are created for a single year.

From the command line, use the “plot” command with the [-t, --plot-type] option set to station-grid-comp and the [-f, --freq] option left as default (“daily”),

$ gridwxcomp plot merged_input.csv -t station-grid-comp -o comp_plots_2016 -y 2016

or within Python,

>>> from gridwxcomp.plot import daily_comparison
>>> daily_comparison('merged_input.csv', 'comp_plots_2016', '2016')

Both methods result in monthly HTML bokeh plots being saved to “comp_plots_2016/STATION_ID/” where “STATION_ID” is the station ID as found in the input CSV file. A file is saved for each month with the station ID, month, and year in the file name. If out_dir keyword argument or [-o, --out-dir] command line option is not given the plots will be saved to a directory named “daily_comp_plots”.

Note

If there are less than five days of data in a month the plot for that month will not be created.

gridwxcomp.plot.monthly_comparison(input_csv, out_dir=None, day_limit=10)

Compare monthly average weather station data from PyWeatherQAQC with gridMET.

The monthly_comparison function produces HTML files with time series and scatter plots of station versus gridMET climate variables of monthly mean data. It uses the bokeh module to create interactive plots, e.g. they can be zoomed in/out and panned.

Parameters

input_csv (str) – path to input CSV file containing paired station/gridMET metadata. This file is created by running gridwxcomp.prep_input followed by gridwxcomp.download_gridmet_opendap.

Keyword Arguments

• out_dir (str) – default None. Directory to save comparison plots.

• day_limit (int) – default 10. Number of paired days per month that must exist for variable to be plotted.

Returns

None

Example

The monthly_comparison function will generate HTML files with bokeh plots for paired climate variable, e.g. etr_mm, eto_mm, u2_ms, tmin_c, tmax_c, srad_wm2, ea_kpa, and Ko (dew point depression).

From the command line, use the “plot” command with the [-t, --plot-type] option set to station-grid-comp and the [-f, --freq] option set to “monthly”,

$ gridwxcomp plot merged_input.csv -t station-grid-comp -freq monthly -o monthly_plots

or within Python,

>>> from gridwxcomp.plot import monthly_comparison
>>> monthly_comparison('merged_input.csv', 'monthly_plots')

Both methods result in monthly HTML bokeh plots being saved to “monthly_plots/” which contains a plot file for each station as found in the input CSV file. If out_dir keyword argument or [-o, --out-dir] command line option is not given the plots will be saved to a directory named “monthly_comp_plots”.

Note

If there are less than 2 months of data the plot for that station will not be created.

gridwxcomp.plot.station_bar_plot(summary_csv, layer, out_dir=None, x_label=None, y_label=None, title=None, subtitle=None, year_subtitle=True)

Produce an interactive bar chart comparing multiple climate stations to each other for a particular variable, e.g. bias ratios or interpolated residuals.

Parameters

• summary_csv (str) – path to summary CSV produced by either gridwxcomp.calc_bias_ratios or by gridwxcomp.interpolate. Should contain layer data for plot.

• layer (str) – name of variable to plot.

Keyword Arguments

• out_dir (str or None) – default None. Output directory path, default is ‘station_bar_plots’ in parent directory of summary_csv.

• x_label (str or None) – default None. Label for x-axis.

• y_label (str or None) – default None. Label for y-axis, defaults to layer.

• title (str or None) – default None. Title of plot.

• subtitle (str, list, or None) – default None. Additional subtitle(s) for plot.

• year_subtitle (bool) – default True. If true print subtitle on plot with the max year range used for station data, e.g. ‘years: 1995-2005’

Example

Let’s say we want to compare the mean growing seasion bias ratios of reference evapotranspiration (ETr) for the selection of stations we used to calculate bias ratios. The summary CSV file containing the ratios should be first created using gridwxcomp.calc_bias_ratios.

>>> from gridwxcomp.plot import station_bar_plot
>>> # path to summary CSV with station data
>>> in_file = 'monthly_ratios/etr_mm_summary_all_yrs.csv'
>>> layer = 'growseason_mean'
>>> station_bar_plot(in_file, layer)

The resulting file will be saved using the layer name as a file name:

'monthly_ratios/station_bar_plots/growseason_mean.html'

The plot file will contain the mean growing season bias ratios of ETr for each station, sorted from smallest to largest values.

This function may also be used for any numerical data in the summary CSV files that are created by gridwxcomp.interpolate in addition to those created by gridwxcomp.calc_bias_ratios. The main requirement is that summary_csv must contain the column ‘STATION_ID’ and the layer keyword argument.

Raises

• FileNotFoundError – if summary_csv is not found.

• KeyError – if layer does not exist as a column name in summary_csv.

InterpGdal

class gridwxcomp.InterpGdal(summary_csv_path)

Bases: object

Usage of gdal command line tools within gridwxcomp, currently utilizes the gdal_grid command line tool.

Parameters

summary_csv_path (str) – path to [var]_summary_comp CSV file created by gridwxcomp.calc_bias_ratios containing point bias ratios, lat, and long.

CELL_SIZE

resolution of gridMET dataset in decimal degrees.

Type

float

summary_csv_path

absolute path object to input summary_csv_path.

Type

pathlib.Path

layers

list of layers in summary_csv_path to interpolate e.g. when using InterpGdal.gdal_grid with layer="all" defaults to InterpGdal.default_layers.

Type

list

grid_bounds

default None. Extent for interpolation raster in order (min long, max long, min lat, max lat).

Type

tuple or None

interp_meth

default ‘invdist’. gdal_grid interpolation method.

Type

str

interped_rasters

empty list that is appended with pathlib.Path objects to interpolated rasters after using InterpGdal.gdal_grid.

Type

list

params

default None. After InterpGdal.gdal_grid params is updated with the last used interpolation parameters in the form of a dictionary with parameter names as keys.

Type

dict or None

Example

The InterpGdal class is useful for experimenting with multiple interpolation algorithms provided by gdal which are optimized and often sensitive to multiple parameters. We can use the object to loop over a range of parameter combinations to test how algorithms perform, we might pick a single layer to test, in this case the growing season bias ratios between station and gridMET reference evapotranspiration (etr_mm). Below is a routine to conduct a basic sensitivity analysis of the power and smooth parameters of the inverse distance to a power interpolation method,

>>> from gridwxcomp import InterpGdal
>>> import os
>>> # create instance variable from summary csv
>>> summary_file = 'PATH/TO/etr_mm_summary_comp.csv'
>>> # create a InterpGdal instance
>>> test = InterpGdal(summary_file)
>>> layer = 'growseason_mean' # could be a list
>>> # run inverse distance interpolation with different params
>>> for p in range(1,10):
>>>     for s in [0, 0.5, 1, 1.5, 2]:
>>>         # build output directory based on parameter sets
>>>         out_dir = os.path.join('spatial', 'invdist',
>>>             'power={}_smooth={}'.format(p, s))
>>>         params = {'power': p, 'smooth': s}
>>>         test.gdal_grid(out_dir=out_dir, layer=layer, params=params)

Note, we did not assign the interpolation method ‘invdist’ because it is the default. To use another interpolation method we would assign the interp_meth kwarg to InterpGdal.gdal_grid. Similarly, we could experiment with other parameters which all can be found in the class attribute InterpGdal.default_params. The instance variable InterpGdal.params can also be used to save metadata on parameters used for each run.

GRIDMET_RES = 0.041666666666666664

interp_methods = ('average', 'invdist', 'invdistnn', 'linear', 'nearest')

gdal_grid interpolation algorithms.

Type

interp_methods (tuple)

default_layers = ('Jan_mean', 'Feb_mean', 'Mar_mean', 'Apr_mean', 'May_mean', 'Jun_mean', 'Jul_mean', 'Aug_mean', 'Sep_mean', 'Oct_mean', 'Nov_mean', 'Dec_mean', 'growseason_mean', 'annual_mean', 'summer_mean')

Layers to interpolate created by gridwxcomp.calc_bias_ratios, e.g. “Jan_mean”, found in summary_csv_path.

Type

default_layers (tuple)

default_params = {'average': {'angle': 0, 'min_points': 0, 'nodata': -999, 'radius1': 0, 'radius2': 0}, 'invdist': {'angle': 0, 'max_points': 0, 'min_points': 0, 'nodata': -999, 'power': 2, 'radius1': 0, 'radius2': 0, 'smoothing': 0}, 'invdistnn': {'max_points': 12, 'min_points': 0, 'nodata': -999, 'power': 2, 'radius': 10, 'smoothing': 0}, 'linear': {'nodata': -999, 'radius': -1}, 'nearest': {'angle': 0, 'nodata': -999, 'radius1': 0, 'radius2': 0}}

Dictionary with default parameters for each interpolation algorithm, slightly modified from GDAL defaults. Keys are interpolation method names, keys are dictionaries with parameter names keys and corresponding values.

Type

default_params (dict)

var_residual_names = {'annual_mean': 'annual_res', 'growseason_mean': 'grow_res', 'summer_mean': 'summer_res'}

Dictionary that maps names of bias ratios to the name of their intepolated residual if they are too long for storing as a field name in an ESRI shapefile (i.e. > 10 chars).

Type

var_residual_names (dict)

gdal_grid(layer='all', out_dir='', interp_meth='invdist', params=None, bounds=None, nx_cells=None, ny_cells=None, scale_factor=1, z_stats=True, res_plot=True, grid_res=None, grid_id_name='GRIDMET_ID', options=None)

Run gdal_grid command line tool to interpolate point ratios.

For further information on theinterpolation algorithms including their function, parameters, and options see gdal_grid.

Keyword Arguments

• layer (str or list) – default ‘all’. Name of summary file column to interpolate, e.g. ‘Jan_mean’, or list of names. If ‘all’ use all variables in mutable instance attribute “layers”.

• out_dir (str) – default ‘’. Output directory to save rasters and zonal stats CSV, always appended to the root dir of the input summary CSV parent path that contains point ratios.

• interp_meth (str) – default ‘invdist’. gdal interpolation algorithm

• params (dict, str, or None) – default None. Parameters for interpolation algorithm. See examples for format rules.

• bounds (tuple or None) – default None. Tuple of bounding coordinates in the following order (min long, max long, min lat, max lat) which need to be in decimal degrees. If None, get extent from locations of climate stations in input summary CSV with 25 cell buffer.

• nx_cells (int) – default None. Number of pixels in x dim. of raster, if None calculated from bounds.

• ny_cells (int) – default None. Number of pixels in y dim. of raster, if None calculated from bounds.

• scale_factor (float, int) – default 1. Scaling factor to apply to original gridMET fishnet to create resampling resolution. If scale_factor = 0.1, the resolution will be one tenth gridMET resolution or 400 m.

• z_stats (bool) – default True. Calculate zonal means of interpolated surface to gridMET cells in fishnet and save to a CSV file. The CSV file will be saved to the same directory as the interpolated raster file(s).

• res_plot (bool) – default True. Make bar plot for residual (error) between interpolated and station value for layer.

• options (str or None) – default None. Extra command line options for gdal_grid spatial interpolation.

Returns

None

Examples

The default interpolation algorithm ‘invdist’ or inverse distance weighting to a power to interpolate bias ratios in a summary CSV file that was first created by gridwxcomp.calc_bias_ratios. The default option will interpolate all layers in InterpGdal.default_layers and calculate zonal statistics for all layers. It will also assume the boundaries of the rasters are defined by the centroid locations of the outer station locations in the input summary CSV plus a 25 gridMET cell buffer, the pixel size will be 400m (scale_factor=0.1). We also limit the interpolation to two layers, growing season and annual mean bias ratios,

>>> from gridwxcomp import InterpGdal
>>> summary_file = 'PATH/TO/[var]_summary_comp.csv'
>>> out_dir = 'default_params'
>>> layers = ['growseason_mean', 'annual_mean']
>>> # create a InterpGdal instance
>>> test = InterpGdal(summary_file)
>>> # run inverse distance interpolation
>>> test.gdal_grid(out_dir=out_dir, layer=layers)

Note, zonal statistics to gridMET cells and interpolated residual plots are computed by default. A gridMET fishnet must have been previously created using gridwxcomp.spatial.make_grid.

After running the code above the following files will be created in the ‘default_params’ directory which will be build in the same location as the input summary CSV:

default_params/
├── annual_mean.tiff
├── annual_mean.vrt
├── etr_mm_summary_comp_all_yrs.csv
├── etr_mm_summary_pts.cpg
├── etr_mm_summary_pts.dbf
├── etr_mm_summary_pts.prj
├── etr_mm_summary_pts.shp
├── etr_mm_summary_pts.shx
├── zonal_stats.csv
├── growseason_mean.tiff
├── growseason_mean.vrt
└── residual_plots/
    ├── annual_res.html
    └── grow_res.html

GeoTiff interpolated raster files are now created for select layers as well as VRT (virtual raster) meta files that store info on each raster’s data source. The file “gridMET_stats.csv” contains gridMET ID as an index and each layer zonal mean as columns. For example,

GRIDMET_ID	growseason_mean	annual_mean
511747	0.9650671287940088	0.9078723876243023
510361	0.9658465063428492	0.9097255715561022
508975	0.9667075970344162	0.9117676407214926

There are several InterpGdal instance attributes that may be useful, for example to see the parameters that were used for the last call to InterpGdal.gdal_grid

>>> test.params
{'power': 2,
 'smoothing': 0,
 'radius1': 0,
 'radius2': 0,
 'angle': 0,
 'max_points': 0,
 'min_points': 0,
 'nodata': -999}

Or to find the paths to the interpolated raster files that have been created by the instance (all), the “interped_rasters” instance attribute is a list of all pathlib.Path objects of absolute paths of raster files. To get them as strings,

>>> list(map(str, test.interped_rasters))
['PATH/TO/growseason_mean.tiff',
 'PATH/TO/annual_mean.tiff']

Similary, the raster extent that was used and will be used again for any subsequent calls of InterpGdal.gdal_grid can be retrieved by

>>> test.grid_bounds
(-111.74583329966664,
 -108.74583330033335,
 38.21250000003333,
 40.462499999966674)

Note

The nx_cells and ny_cells arguments are an option for defining the output raster’s resolution. If these arguments are passed then the scale_factor argument has no effect. The latter assumes raster resolution is relative to gridMET (4 km).

Raises

KeyError – if interp_meth is not a valid gdal_grid interpolation algorithm name.

util

Utility functions or classes for gridwxcomp package

gridwxcomp.util.get_gridmet_meta_csv(gridmet_meta_path=None)

Find path to ‘gridmet_cell_data.csv’ packaged with gridwxcomp

gridwxcomp.util.parse_yr_filter(dt_df, years, label)

Parse string year filter and apply it to datetime-indexed DataFrame.

Parameters

• dt_df (pandas.DataFrame) – datetime-indexed DataFrame

• years (str or int) – years to select, e.g. 2015 or 2000-2010

• label (str) – identifier to print warning message if years filter partially overlaps with actual date index

Returns

first element is

input DataFrame dt_df indexed to years filter, second element is string of year range, e.g. ‘2001_2011’

Return type

ret (tuple of (pandas.DataFrame, str))

Example

>>> df = pd.DataFrame(index=pd.date_range('2000', '2015'))
>>> df, yr_str = parse_yr_filter(df, '1998-2002', 'station1')
WARNING: data for station1 starts in 2000 but you gave 1998
Years used will only include 2000 to 2002

Now df will only contain indices with dates between 2000 and 2002 and

>>> yr_str
'1998_2002'

Raises

ValueError – if years is invalid or not found in time series index of DataFrame.