Ecosystem services operators

`services.carbon`#

Carbon storage of a landscape and its change between two land use maps: InVEST's carbon model (natcap.invest 3.20) bit for bit, through landschaft. Each class holds a density (t C / ha) in four pools (above and below ground biomass, soil, dead matter); the storage is their sum, the sequestration the future minus the baseline, valued with a price.

Input	Type	What it is
`lulc`required	map	the baseline land use (class codes; projected, metres)
`pools`required	table	by class: lucode, c_above, c_below, c_soil, c_dead (Mg C / ha)
`future`	map	the alternate (future) land use, on the same grid

Output	Type	What it is
`storage`	map	the baseline's carbon, t / ha (float32)
`pools`	stack	each pool's map (c_above, c_below, c_soil, c_dead)
`storage_future`	map	the future's carbon (with future)
`pools_future`	stack	the future's pools (with future)
`change`	map	sequestration: future minus baseline (with future)
`npv`	map	the change's net present value per ha (with a price)
`totals`	table	tons of carbon: baseline, alternate, change; npv in currency

Setting	Type	What it is
`price`	number	of a ton of carbon (valuation of the change)
`discount_rate`	number	per year, percent
`rate_change`	number	of the price per year, percent (0)
`year`	integer	of the baseline map
`future_year`	integer	of the future map

`services.habitat_quality`#

Habitat degradation, quality and rarity: InVEST's habitat quality model (natcap.invest 3.20) bit for bit, through landschaft. Each threat degrades the habitat around it, decaying linearly or exponentially with the distance to its nearest cell up to its maximum distance, weighed by its weight, the sensitivity of the cell's class and the access; quality h (1 - D^2.5 / (D^2.5 + k^2.5)). With a base map, the rarity of each class.

Input	Type	What it is
`lulc`required	map	the current land use (class codes; projected, metres)
`sensitivity`required	table	by class: lucode, habitat (0 to 1) and a column per threat (its sensitivity, 0 to 1)
`threat_maps`required	stack	the current map of each threat, by its name (0 to 1)
`future`	map	a future land use
`future_threat_maps`	stack	the future's threat maps
`base`	map	a base land use, for the rarity
`base_threat_maps`	stack	the base's threat maps (optional)
`access`	any	accessibility to threats, 0 to 1: a raster, or polygons with an access attribute (1 outside)

Output	Type	What it is
`quality`	map	the current habitat quality
`degradation`	map	the current total degradation
`threats`	stack	the current degradation of each threat
`quality_future`	map	with a future
`degradation_future`	map	with a future
`quality_base`	map	with the base's threat maps
`degradation_base`	map	with the base's threat maps
`rarity`	map	the rarity of the current classes (with a base)
`rarity_future`	map	of the future classes (with a base and a future)
`rarity_table`	table	scenario (0 current, 1 future), lucode, rarity

Setting	Type	What it is
`threats`required	any	a list of {threat, max_dist (metres), weight (0 to 1), decay (linear or exponential)}, or InVEST's threats table (a file)
`half_saturation`required	number	k, often half the highest degradation

`services.ndr`#

Nutrient export and retention: InVEST's nutrient delivery ratio model (natcap.invest 3.20) bit for bit, through landschaft. The nitrogen and phosphorus loads of each land use (scaled by the runoff proxy over its mean) split into a surface part and, for nitrogen, a dissolved subsurface part; the surface load reaches a stream in the share NDR = (1 - eff') / (1 + exp((IC_0 - IC) / k)), eff' the retention of the cells it crosses on its way down and IC the index of connectivity (Borselli et al. 2008), the subsurface load in the share 1 - eff_sub (1 - exp(-5 l / l_sub)). The DEM filled and routed by pygeoprocessing's algorithms, as InVEST; the subsurface distance in metres (InVEST takes it in cells).

Input	Type	What it is
`dem`required	map	elevations (projected, metres)
`lulc`required	map	land use (class codes)
`runoff_proxy`required	map	the capacity of the runoff to carry nutrients (any units)
`biophysical`required	table	by class: lucode, load_n, eff_n, crit_len_n, proportion_subsurface_n (nitrogen); load_p, eff_p, crit_len_p (phosphorus)
`watersheds`required	vector	the watershed polygons (the model runs inside them)

Output	Type	What it is
`n_surface_export`	map	the surface nitrogen that reaches the streams, kg/ha/yr
`n_subsurface_export`	map	the dissolved nitrogen that reaches them
`n_total_export`	map	surface plus subsurface nitrogen export
`p_surface_export`	map	the phosphorus that reaches the streams, kg/ha/yr
`ndr_n`	map	the surface delivery ratio of nitrogen
`ndr_p`	map	the surface delivery ratio of phosphorus
`effective_retention_n`	map	the nitrogen retained on its way down
`effective_retention_p`	map	the phosphorus retained on its way down
`ic`	map	the index of connectivity
`stream`	map	the streams (1)
`drains_to_stream`	map	1 where the flow reaches a stream
`watershed_table`	table	by watershed: the surface loads, the exports and the subsurface load (kg / yr)
`ic_0`	number	the IC_0 of the delivery ratio (half way between the extremes)
`runoff_proxy_mean`	number	the mean the runoff proxy was divided by

Setting	Type	What it is
`threshold`required	number	the flow accumulation (cells) of a stream
`k`	number	Borselli's k (2)
`nitrogen`	bool	model nitrogen (default true)
`phosphorus`	bool	model phosphorus (default true)
`subsurface_critical_length`	number	the distance (m) over which the soil reaches its largest retention of dissolved nitrogen
`subsurface_efficiency`	number	that largest retention, 0 to 1
`runoff_proxy_mean`	number	the proxy's mean (default: of the map)
`load_type_n`	any	measured-runoff (default: the load as given) or application-rate (times 1 - eff_n), for every class; or by class, {"": type}
`load_type_p`	any	the same for phosphorus
`method`	text	the routing: mfd (default) or d8

`services.pollination`#

Crop pollination by wild bees: InVEST's pollination model (natcap.invest 3.20) bit for bit, through landschaft. Each species nests where the land uses (and the farms) offer its substrates and forages on their flowers by season within its flight distance (an exponential kernel of mean alpha); its supply and its abundance by season follow, summed over the species by season; with farms, the pollinator abundance on them (their half saturation), the total and wild pollinator yields and the means by farm.

Input	Type	What it is
`lulc`required	map	the land use (class codes; projected, metres)
`biophysical`required	table	by class: lucode, nesting_availability_index, floral_resources_index
`farms`	vector	farm polygons: crop_type, half_sat, season, p_dep, p_managed, fr_, n_

Output	Type	What it is
`supply`	stack	the pollinator supply of each species
`abundance`	stack	the abundance of each species in each season (_)
`total_abundance`	stack	the abundance of all species, by season
`farm_pollinators`	map	the pollinator abundance on the farms (with farms)
`total_yield`	map	the yield owed to pollinators, wild and managed
`wild_yield`	map	the yield owed to wild pollinators
`farm_table`	table	by farm: p_abund, y_tot, pdep_y_w, y_wild

Setting	Type	What it is
`guilds`required	any	a list of {species, alpha (metres), relative_abundance, foraging_activity_index, nesting_suitability_index}, or InVEST's guild table (a file)

`services.sdr`#

Sediment export, deposition and retention: InVEST's sediment delivery ratio model (natcap.invest 3.20), through landschaft. The soil loss of the RUSLE (R K LS C P, the LS of Desmet & Govers from the flow accumulation) and the share that reaches a stream, SDR = SDR_max / (1 + exp((IC_0 - IC) / k)) of the index of connectivity (Borselli et al. 2008); the DEM filled and routed by pygeoprocessing's algorithms, as InVEST.

Input	Type	What it is
`dem`required	map	elevations (projected, metres)
`erosivity`required	map	rainfall erosivity R (MJ mm / ha h yr)
`erodibility`required	map	soil erodibility K (t ha h / ha MJ mm)
`lulc`required	map	land use (class codes)
`biophysical`required	table	by class: lucode, usle_c, usle_p
`watersheds`required	vector	the watershed polygons (the model runs inside them)
`drainage`	map	other cells that drain to the streams (1)

Output	Type	What it is
`usle`	map	soil loss, t / ha / yr
`sed_export`	map	the soil loss that reaches the streams
`sed_deposition`	map	sediment from upslope the cell traps
`avoided_export`	map	total retention
`avoided_erosion`	map	RKLS - USLE
`rkls`	map	the soil loss of bare soil
`sdr`	map	the sediment delivery ratio
`ic`	map	the index of connectivity
`stream`	map	the streams (1)
`drains_to_stream`	map	1 where the flow reaches a stream
`watershed_table`	table	by watershed: usle_tot, sed_export, sed_dep, avoid_exp, avoid_eros (t / yr)

Setting	Type	What it is
`threshold`required	number	the flow accumulation (cells) of a stream
`k`	number	Borselli's k (2)
`ic_0`	number	Borselli's IC_0 (0.5)
`sdr_max`	number	the largest SDR (0.8)
`l_max`	number	the largest L factor (122)
`method`	text	the routing: mfd (default) or d8

`services.seasonal_water_yield`#

Quickflow, local recharge and baseflow: InVEST's seasonal water yield model (natcap.invest 3.20) bit for bit, through landschaft. The quickflow of each month from the curve numbers of the land use and soil group and the rain events; the local recharge P - QF - AET, the evapotranspiration limited by the water from upslope (alpha, beta, gamma); the baseflow the recharge gives the cells down to the streams; with a recharge map instead (and no climate), its routing only. The DEM filled and routed by pygeoprocessing's algorithms, as InVEST.

Input	Type	What it is
`dem`required	map	elevations (projected, metres)
`lulc`	map	land use (class codes; with the climate)
`biophysical`	table	by class: lucode, cn_a, cn_b, cn_c, cn_d (curve numbers), kc_1 ... kc_12 (with the climate)
`watersheds`required	vector	the watershed polygons (the totals by polygon)
`precipitation`	stack	the twelve months' precipitation, mm
`et0`	stack	the twelve months' reference evapotranspiration, mm
`soil_group`	map	hydrologic soil groups, 1 (A) to 4 (D)
`climate_zones`	map	climate zones (with the climate zone table)
`climate_zone_table`	table	by zone: cz_id, jan ... dec (the rain events of each month)
`recharge`	map	a local recharge map (mm), instead of the climate

Output	Type	What it is
`quickflow`	map	the annual quickflow, mm
`local_recharge`	map	the local recharge L, mm
`l_avail`	map	the recharge available to the cell, mm
`l_sum_avail`	map	the recharge available from upslope, mm
`l_sum`	map	the recharge from upslope, mm
`baseflow`	map	the baseflow the cell gives, mm
`b_sum`	map	the baseflow from upslope, mm
`vri`	map	the cell's share of the total recharge
`aet`	map	the annual actual evapotranspiration, mm
`annual_precipitation`	map	the annual precipitation, mm
`stream`	map	the streams (1)
`quickflow_monthly`	stack	the quickflow of each month (1 to 12), mm
`watershed_table`	table	by watershed: qb (mean recharge), vri_sum, geom_id
`monthly_table`	table	by watershed and month: geom_id, month, quickflow, baseflow, precipitation (m³)

Setting	Type	What it is
`threshold`required	number	the flow accumulation (cells) of a stream
`rain_events`	any	the rain events of each month, twelve numbers (or the climate zones)
`alpha`	any	the share of the annual recharge upslope available each month: a number (1/12) or twelve
`beta`	any	the share of the upslope recharge available to the cell (1)
`gamma`	any	the share of the cell's recharge available downslope (1)
`method`	text	the routing: mfd (default) or d8
`precision`	text	the type of the precipitation, ET0 and recharge rasters in InVEST: float32, float64, or auto (default: float64 when a raster has a value float32 cannot hold)

`services.water_yield`#

Annual water yield, consumption and hydropower: InVEST's annual water yield model (natcap.invest 3.20) bit for bit, through landschaft. The water balance of each cell on the Budyko curve (Fu and Zhang): AET / P from the potential evapotranspiration Kc ET0, the plant available water and the seasonality Z; the yield P - AET. With watersheds, their means and volumes; with a demand table, the consumption and the realized supply; with a valuation table, the hydropower energy and value.

Input	Type	What it is
`lulc`required	map	the land use (class codes; projected, metres)
`biophysical`required	table	by class: lucode, lulc_veg (1 or 0), root_depth (mm), kc
`precipitation`required	map	annual precipitation, mm
`eto`required	map	annual reference evapotranspiration, mm
`depth`required	map	depth to the root restricting layer, mm
`pawc`required	map	plant available water content, 0 to 1
`watersheds`	vector	polygons with a ws_id
`subwatersheds`	vector	polygons with a subws_id
`demand`	table	by class: lucode, demand (m³ per year and cell)
`valuation`	table	by watershed: ws_id, efficiency, fraction, height, kw_price, cost, time_span, discount

Output	Type	What it is
`wyield`	map	water yield, mm
`aet`	map	actual evapotranspiration, mm
`pet`	map	potential evapotranspiration, mm
`fractp`	map	AET / P
`demand_map`	map	consumptive use per cell, m³ / year (with demand)
`watershed_table`	table	by watershed: means, volumes, supply, hydropower
`subwatershed_table`	table	by subwatershed

Setting	Type	What it is
`seasonality`required	number	Z, about 1 to 30
`precision`	text	InVEST's arithmetic: float32 (its float32 rasters), float64, or auto (default: float64 when a raster has a value float32 cannot hold)

services.carbon#

services.habitat_quality#

services.ndr#

services.pollination#

services.sdr#

services.seasonal_water_yield#

services.water_yield#