natcap.invest.annual_water_yield

InVEST Annual Water Yield model.

natcap.invest.annual_water_yield.compute_rsupply_volume(watershed_results_vector_path)

Calculate the total realized water supply volume.

And the mean realized water supply volume per pixel for the given sheds. Output units in cubic meters and cubic meters per pixel respectively.

Parameters:

watershed_results_vector_path (string) – a path to a vector that contains fields ‘wyield_vol’ and ‘wyield_mn’.

Returns:

None.

natcap.invest.annual_water_yield.compute_water_yield_volume(watershed_results_vector_path)

Calculate the water yield volume per sub-watershed or watershed.

Results are added to a ‘wyield_vol’ field in watershed_results_vector_path. Units are cubic meters.

Parameters:

watershed_results_vector_path (str) – Path to a sub-watershed or watershed vector. This vector’s features should have a ‘wyield_mn’ attribute.

Returns:

None.

natcap.invest.annual_water_yield.compute_watershed_valuation(watershed_results_vector_path, val_df)

Compute net present value and energy for the watersheds.

Parameters:

  • watershed_results_vector_path (string) – Path to an OGR shapefile for the watershed results. Where the results will be added.

  • val_df (pandas.DataFrame) – a dataframe that has all the valuation parameters for each watershed.

Returns:

None.

natcap.invest.annual_water_yield.convert_vector_to_csv(base_vector_path, target_csv_path)

Create a CSV with all the fields present in vector attribute table.

Parameters:

  • base_vector_path (string) – Path to the watershed shapefile in the output workspace.

  • target_csv_path (string) – Path to a CSV to create in the output workspace.

Returns:

None

natcap.invest.annual_water_yield.copy_vector(base_vector_path, target_vector_path)

Wrapper around CreateCopy that handles opening & closing the dataset.

Parameters:

  • base_vector_path – path to the vector to copy

  • target_vector_path – path to copy the vector to

Returns:

None

natcap.invest.annual_water_yield.execute(args)

Annual Water Yield: Reservoir Hydropower Production.

Executes the hydropower/annual water yield model

Parameters:

  • args['workspace_dir'] (string) – a path to the directory that will write output and other temporary files during calculation. (required)

  • args['lulc_path'] (string) – a path to a land use/land cover raster whose LULC indexes correspond to indexes in the biophysical table input. Used for determining soil retention and other biophysical properties of the landscape. (required)

  • args['depth_to_root_rest_layer_path'] (string) – a path to an input raster describing the depth of “good” soil before reaching this restrictive layer (required)

  • args['precipitation_path'] (string) – a path to an input raster describing the average annual precipitation value for each cell (mm) (required)

  • args['pawc_path'] (string) – a path to an input raster describing the plant available water content value for each cell. Plant Available Water Content fraction (PAWC) is the fraction of water that can be stored in the soil profile that is available for plants’ use. PAWC is a fraction from 0 to 1 (required)

  • args['eto_path'] (string) – a path to an input raster describing the annual average evapotranspiration value for each cell. Potential evapotranspiration is the potential loss of water from soil by both evaporation from the soil and transpiration by healthy Alfalfa (or grass) if sufficient water is available (mm) (required)

  • args['watersheds_path'] (string) – a path to an input shapefile of the watersheds of interest as polygons. (required)

  • args['sub_watersheds_path'] (string) – a path to an input shapefile of the subwatersheds of interest that are contained in the args['watersheds_path'] shape provided as input. (optional)

  • args['biophysical_table_path'] (string) – a path to an input CSV table of land use/land cover classes, containing data on biophysical coefficients such as root_depth (mm) and Kc, which are required. A column with header LULC_veg is also required which should have values of 1 or 0, 1 indicating a land cover type of vegetation, a 0 indicating non vegetation or wetland, water. NOTE: these data are attributes of each LULC class rather than attributes of individual cells in the raster map (required)

  • args['seasonality_constant'] (float) – floating point value between 1 and 30 corresponding to the seasonal distribution of precipitation (required)

  • args['results_suffix'] (string) – a string that will be concatenated onto the end of file names (optional)

  • args['demand_table_path'] (string) – (optional) if a non-empty string, a path to an input CSV table of LULC classes, showing consumptive water use for each landuse / land-cover type (cubic meters per year) to calculate water scarcity. Required if valuation_table_path is provided.

  • args['valuation_table_path'] (string) – (optional) if a non-empty string, a path to an input CSV table of hydropower stations with the following fields to calculate valuation: ‘ws_id’, ‘time_span’, ‘discount’, ‘efficiency’, ‘fraction’, ‘cost’, ‘height’, ‘kw_price’

  • args['n_workers'] (int) – (optional) The number of worker processes to use for processing this model. If omitted, computation will take place in the current process.

Returns:

None

natcap.invest.annual_water_yield.fractp_op(Kc, eto, precip, root, soil, pawc, veg, nodata_dict, seasonality_constant)

Calculate actual evapotranspiration fraction of precipitation.

Parameters:

  • Kc (numpy.ndarray) – Kc (plant evapotranspiration coefficient) raster values

  • eto (numpy.ndarray) – potential evapotranspiration raster values (mm)

  • precip (numpy.ndarray) – precipitation raster values (mm)

  • root (numpy.ndarray) – root depth (maximum root depth for vegetated land use classes) raster values (mm)

  • soil (numpy.ndarray) – depth to root restricted layer raster values (mm)

  • pawc (numpy.ndarray) – plant available water content raster values

  • veg (numpy.ndarray) – 1 or 0 where 1 depicts the land type as vegetation and 0 depicts the land type as non vegetation (wetlands, urban, water, etc…). If 1 use regular AET equation if 0 use: AET = Kc * ETo

  • nodata_dict (dict) – stores nodata values keyed by raster names

  • seasonality_constant (float) – floating point value between 1 and 30 corresponding to the seasonal distribution of precipitation.

Returns:

numpy.ndarray (float) of actual evapotranspiration as fraction

of precipitation.

natcap.invest.annual_water_yield.write_output_vector_attributes(target_vector_path, ws_id_name, stats_path_list, valuation_df)

Add data attributes to the vector outputs of this model.

Join results of zonal stats to copies of the watershed shapefiles. Also do optional scarcity and valuation calculations.

Parameters:

  • target_vector_path (string) – Path to the watersheds vector to modify

  • ws_id_name (string) – Either ‘ws_id’ or ‘subws_id’, which are required names of a unique ID field in the watershed and subwatershed shapefiles, respectively. Used to determine if the polygons represent watersheds or subwatersheds.

  • stats_path_list (list) – List of file paths to pickles storing the zonal stats results.

  • valuation_df (pandas.DataFrame) – dataframe built from args[‘valuation_table_path’]. Or None if valuation table was not provided.

Returns:

None

natcap.invest.annual_water_yield.wyield_op(fractp, precip)
natcap.invest.annual_water_yield.zonal_stats_tofile(base_vector_path, raster_path, target_stats_pickle)

Calculate zonal statistics for watersheds and write results to a file.

Parameters:

  • base_vector_path (string) – Path to the watershed shapefile in the output workspace.

  • raster_path (string) – Path to raster to aggregate.

  • target_stats_pickle (string) – Path to pickle file to store dictionary returned by zonal stats.

Returns:

None