Distance & restoration operators

`distance.euclidean`#

The Euclidean distance to the foreground's edge, as GuidosToolbox: in cells, positive inside the foreground and negative outside it, with GTB's byte map (130 + the distance inside, 130 - it outside, up to 120 cells) and the mean and largest distance on each side. The foreground is the classes given, or the map is coded 0 missing, 1 background, 2 foreground.

Input	Type	What it is
`map`required	map	the map

Output	Type	What it is
`map`	map	the signed distance in cells
`display`	map	GTB's byte map of the distance
`stats`	table	the foreground (1) and the background (0): their cells, mean and largest distance

Setting	Type	What it is
`foreground`	any	the foreground's classes (a class or a list)

`distance.influence_zones`#

The zones of influence of the foreground objects, as GuidosToolbox's Distance -> Influence Zones (landschaft's influence_zones): the objects (8-connected, holes filled, of min_area cells at least, or their cores) and the watershed of the distance to them; a background buffer around them. Experimental in landschaft: IDL's distance transform is not yet reproduced exactly.

Input	Type	What it is
`map`required	map	the map

Output	Type	What it is
`map`	map	GTB's codes: objects, zones, lines, buffer, missing
`ids`	map	the object of every cell (holes included); 0 zones, -1 holes, -2 foreground of no object, -3 lines, -4 missing, -5 the buffer's edge, -6 buffer
`zones`	map	the zone (watershed basin) of every cell, 0 on the lines
`objects`	table	per object (1..): its area in cells (holes not counted)

Setting	Type	What it is
`buffer`	integer	a background buffer this wide around the objects (0)
`min_area`	integer	the least object, in cells (GTB's 5000)
`core_buffer`	integer	the objects reduced to their core first: this many cells of their edge dropped (0)
`foreground`	any	the foreground's classes (a class or a list)

`distance.objects_proximity`#

The proximity between neighbouring foreground objects, as GuidosToolbox's Distance -> Proximity (landschaft's proximity): the objects (8-connected, holes filled, of min_area cells at least) split the map into zones of influence (the watershed of the distance to them); along the zones' lines the gap between the objects and their connected area gain. Experimental in landschaft: IDL's distance transform is not yet reproduced exactly.

Input	Type	What it is
`map`required	map	the map

Output	Type	What it is
`distance`	map	round(2 x the distance to the nearest object), the lines' updated
`cag`	map	the connected area gain on the lines
`lines`	table	per line cell: its column and row (1-based), the zones it touches, the connector length, the CAG, the first two objects and their areas
`csv`	text	GTB's proximity CSV
`map`	map	GTB's codes: objects, zones, lines, buffer, missing
`ids`	map	the object of every cell (holes included); 0 zones, -1 holes, -2 foreground of no object, -3 lines, -4 missing, -5 the buffer's edge, -6 buffer
`zones`	map	the zone (watershed basin) of every cell, 0 on the lines
`objects`	table	per object (1..): its area in cells (holes not counted)

Setting	Type	What it is
`prox_max`	integer	lines up to this proximity marked 165 (0)
`min_area`	integer	the least object, in cells (GTB's 5000)
`core_buffer`	integer	the objects reduced to their core first: this many cells of their edge dropped (0)
`foreground`	any	the foreground's classes (a class or a list)

`distance.proximity`#

The distance from every cell to the nearest cell of some values (gdal_proximity), in the units of the raster or in cells: a driver such as the distance to roads, rivers or forest edges; done on the file, whatever its size.

Input	Type	What it is
`raster`required	raster	the raster (its band chosen)

Output	Type	What it is
`raster`	raster	the distances

Setting	Type	What it is
`values`required	any	the values to measure from: a value or a list
`units`	text	geo (default: the units of the raster) or cells
`max_distance`	number	beyond it, no value
`path`	text	the file (or folder, for a series) made; else a cache

`restoration.corridor`#

The gain of restoring the least-cost corridor between two areas, as GuidosToolbox's Restoration Planner (landschaft's restoration_corridor): the path's background cells turned habitat, the ECA and coherence before and after, and the gain per resistance restored.

Input	Type	What it is
`resistance`required	map	the resistance, 1-100 (0 or no value: impassable)
`a`required	map	area A: cells above 0
`b`required	map	area B: cells above 0
`distance`	map	a distance (distance.euclidean), for the restored cells' mean
`habitat`required	map	the habitat (0 missing, 1 background, 2 habitat)

Output	Type	What it is
`path`	map	the path: 1, 0 elsewhere
`restored`	map	the habitat with the corridor restored
`stats`	table	the sizes of A and B, the cells restored, their mean distance, the expense, the efficiency (ECA gained per expense), ECA and coherence before, after and their gains

`restoration.cost_distance`#

The accumulated cost of travelling from the sources across a resistance, as GuidosToolbox (landschaft's cost_distance): 8 neighbours, a step the two cells' mean resistance times its length (1, or sqrt(2) diagonally).

Input	Type	What it is
`resistance`required	map	the resistance, 1-100 (0 or no value: impassable)
`sources`required	map	the sources: cells above 0

Output	Type	What it is
`map`	map	the cost (no value where the sources cannot be reached)

`restoration.ecosystem_areas`#

The ecosystems' (ecoregions') natural area now and before conversion and what restoring a cell gives them: restoration.plan's table and gain for the risk of ecosystem collapse. Every cell of an ecoregion counts (counting the problem's cells only would overstate the loss).

Input	Type	What it is
`land_cover`required	stack	the share of each class, by name
`ecoregions`required	map	ecoregion codes (no value: none)

Output	Type	What it is
`table`	table	per ecoregion: its code, natural area (current), natural and anthropic (potential), cells, valid
`gain`	stack	per ecoregion: the area a unit of a cell restored gives it

Setting	Type	What it is
`natural`required	any	the natural classes
`anthropic`required	any	the anthropic classes
`cell_area`	number	a cell's area in km² (default: the grid's)

`restoration.ecosystem_targets`#

Share a restoration target among ecosystems for the least risk of collapse (the targets per ecosystem of Strassburg et al. 2020): every ecosystem between its least share and its converted area, for the most total of ((natural + share) / potential)^z, damped by exp(half_life x the ratio). exact: the optimum; steps: their stepwise procedure. The targets per region for restoration.plan (target: {code: area}).

Input	Type	What it is
`table`required	table	restoration.ecosystem_areas's table

Output	Type	What it is
`targets`	table	per ecosystem: its code (region) and its share (target)

Setting	Type	What it is
`target`required	number	the area to share (km²)
`minimum`	number	every ecosystem's least share, of an equal split (0)
`z`	number	the species-area exponent (0.25)
`half_life`	number	the damping exponent (0: none; below 1 - z)
`method`	text	exact (default) or steps
`steps`	integer	steps: the parts of the target (10)

`restoration.intactness`#

Ecological intactness (Beyer et al. 2020), as Strassburg et al. (2020) compute it: the habitat's quality q = exp(-gamma footprint) of a cell and of those around it (within radius cells, weighted by exp(beta distance in km)), Q = mean of (q q')^z. With a reduction and restored shares, the intactness after restoring them.

Input	Type	What it is
`footprint`required	map	the human footprint
`reduction`	map	the footprint a cell loses per unit restored
`restored`	map	the share of each cell restored

Output	Type	What it is
`map`	map	the intactness of each cell (0-1)

Setting	Type	What it is
`radius`	integer	the neighbourhood's radius in cells (default 3)
`gamma`	number	the footprint's decay of quality (default -ln(0.2)/4)
`beta`	number	the distance's decay per km (default -0.2)
`z`	number	the exponent of the pairs' quality (default 0.5)
`cell_size`	any	a cell's size in km, or [width, height] (default: the grid's, projected)

`restoration.intactness_gradient`#

How much the total ecological intactness grows per unit of each cell restored (its derivative): restoring a cell lowers its footprint by the reduction given per unit. With restored shares, at the footprint they leave.

Input	Type	What it is
`footprint`required	map	the human footprint
`reduction`required	map	the footprint a cell loses per unit restored
`restored`	map	the share of each cell restored already

Output	Type	What it is
`map`	map	d(total intactness) / d(share restored) of each cell

Setting	Type	What it is
`radius`	integer	the neighbourhood's radius in cells (default 3)
`gamma`	number	the footprint's decay of quality (default -ln(0.2)/4)
`beta`	number	the distance's decay per km (default -0.2)
`z`	number	the exponent of the pairs' quality (default 0.5)
`cell_size`	any	a cell's size in km, or [width, height] (default: the grid's, projected)

`restoration.isochrone`#

The isochrone map of GuidosToolbox's Restoration Planner (landschaft's isochrone_map and isochrone_map_ab, GTB's ggeo): the accumulated cost of reaching every cell from object A across a resistance (a step between neighbours their mean resistance, the habitat 1), or with an object B the cost of the cheapest route from A to B through every cell and its least-cost path; scaled 0-100 in GTB's codes.

Input	Type	What it is
`resistance`required	map	the resistance: 2 habitat (cost 1), 3-100 background
`marker`required	map	0 background, 1 object A, 2 object B (the route A-B), 3 missing (not crossed); one object each

Output	Type	What it is
`map`	map	GTB's codes: the cost scaled 0-100, 101 the objects, 102 missing, 103 the least-cost path, 104 unreachable
`cost`	map	the cost as GTB rounds it (no value where unreachable)
`path`	map	A-B: the least-cost path (1)
`stats`	table	the least and the largest cost

`restoration.least_cost_path`#

The least-cost path between two areas across a resistance, as GuidosToolbox (landschaft's least_cost_path): the cells of the least cost from A plus from B.

Input	Type	What it is
`resistance`required	map	the resistance, 1-100 (0 or no value: impassable)
`a`required	map	area A: cells above 0
`b`required	map	area B: cells above 0
`distance`	map	a distance (distance.euclidean), for the restored cells' mean

Output	Type	What it is
`path`	map	the path: 1, 0 elsewhere
`cost`	map	the cost from A plus the cost from B
`stats`	table	the path's length, its cells in the background, their resistance (the expense) and mean distance

`restoration.original_vegetation`#

The original vegetation of converted land (Strassburg et al. 2020): for every cell with anthropic land, the shares of the natural classes it had, from the past cover where it tells, else from the ecoregion's natural shares, else from failsafe shares (the mean over the map); and the shares restored land returns to. The land cover is a stack of each class's share (0-1).

Input	Type	What it is
`land_cover`required	stack	the share of each class, by name
`past`	stack	the past share of each natural class
`ecoregions`	stack	the ecoregion's share of each natural class

Output	Type	What it is
`original`	stack	the original share of each natural class
`restore`	stack	the shares of the natural classes restored land returns to
`source`	map	where the original came from: 0 past, 1 ecoregion, 2 failsafe
`anthropic`	map	the share of anthropic land
`failsafe`	table	the failsafe share of each class filled (in natural's order)

Setting	Type	What it is
`natural`required	any	the natural classes (names of the land cover's layers)
`anthropic`required	any	the anthropic classes
`failsafe`	any	the natural classes the failsafe fills (default all)
`threshold`	number	the share of land a source must explain (default 0.95)
`restore_to`	text	original (default) or current: restored land returns to the current natural cover where it has some

`restoration.plan`#

Restoration planning (Strassburg et al. 2020): how much of every converted cell to restore for the most benefit within area targets and a budget: the reduction of the species' extinction risk (the species-area relationship on their area of habitat, sdm.area_of_habitat's table and gain) and linear benefits (carbon per km²). exact: the optimum within a tolerance (simplicial decomposition with a proven bound); steps: Strassburg et al.'s procedure (the target in steps, the benefits recomputed between them); uniform: every cell by the same share.

Input	Type	What it is
`restorable`	map	the share of every cell that can be restored (anthropic land)
`conservable`	map	the share of every cell's natural land conservation can keep (C): without the plan, threat of it is lost
`convertible`	map	the share of every cell's natural land that can be converted (D; with restorable, R + D)
`threat`	map	conservation: the share of the conservable land lost without it (1)
`loss`	stack	sdm.area_of_habitat's loss (conservation, conversion)
`table`	table	sdm.area_of_habitat's table: current, potential, valid
`gain`	stack	sdm.area_of_habitat's gain: habitat per unit of a cell restored
`linear`	stack	linear benefits per km² restored (carbon...), a layer each
`cost`	map	the cost per km² restored (with budget)
`regions`	map	region codes, for targets per region
`limit`	map	the bound limit: a share per cell multiplying the restorable
`hfi`	map	the human footprint, for the intactness benefit
`reduction`	map	intactness: the footprint a cell loses per unit restored
`increase`	map	intactness: the footprint a cell gains per unit of natural land converted (or lost unconserved)

Output	Type	What it is
`restored`	map	the share of every cell restored
`conserved`	map	the share of every cell's natural land conserved
`converted`	map	the share of every cell's natural land converted
`summary`	table	the weighted benefit, the area (km²), the cost, the bound (exact), optimal (1), the rounds, the extinction risk's reduction and its standard deviation
`tradeoff`	table	with levels: per level its share, the landscape target, the area and the weighted benefit
`gradient`	map	with levels: the levels whose plan acts on the cell (conversion: the levels plus one less that)
`benefits`	table	per benefit (the risk, the linear ones, intactness): value, weight, weighted
`weights`	table	with weights: per set the weights (w.), the benefits, the cost, and Strassburg et al.'s mean, sd, score and rank
`species`	table	per species counted (its row in the area of habitat's table): the habitat gained, the risk without and with the plan, the reduction

Setting	Type	What it is
`method`	text	exact (default), steps or uniform
`levels`	any	a trade-off curve: the landscape target's shares at every level (increasing, in (0, 1])
`nested`	bool	exact trade-offs: every level contains the previous (true)
`threshold`	number	the gradient: a cell counts when its share is above (0)
`projected_change`	any	projected changes of natural land per region ({code: km²}; + spared for restoration, - demanded)
`change_sense`	text	the projected changes' rows (= default)
`restrict`	bool	restore and convert: every region in its direction only (true)
`compensate`	bool	restore only: the land demanded elsewhere taken from it (true)
`steps`	integer	steps: the parts of the target (default 1)
`target`	any	the area restored (km²): a number for the landscape, or {region code: area} with regions
`sense`	text	the targets' sense: <= (default, at most), >=, =
`relative`	bool	the targets are shares of the area that can be restored
`budget`	number	the most the plan may cost (with cost)
`z`	any	the species-area exponent: a number (0.25) or one per species
`weight`	number	the risk benefit's weight (1)
`linear_weights`	any	the linear benefits' weights (1 each)
`restoration_discount`	any	the share of the habitat value restored land does not deliver (0; one or one per species)
`cell_area`	number	a cell's area in km² (default: the grid's)
`z_sd`	any	the standard deviation of z (0.1 in Strassburg et al. 2020; one or one per species counted): the risk reduction's
`uncertainty`	text	how the species' sensitivities to z add up: correlated (default), independent or linear (Strassburg et al.'s)
`intactness_weight`	number	the intactness benefit's weight (1; with hfi)
`intactness_form`	text	linear (default: its gradient at the plan of nothing, recomputed between steps) or exact (the total intactness)
`radius`	integer	intactness: the neighbourhood's radius in cells (3)
`gamma`	number	intactness: the footprint's decay of quality (-ln(0.2)/4)
`beta`	number	intactness: the distance's decay per km (-0.2)
`intactness_z`	number	intactness: the exponent of the pairs' quality (0.5)
`cell_size`	any	intactness: a cell's size in km, or [width, height] (default: the grid's, projected)
`min_benefit`	number	the cheapest plan whose weighted benefit reaches this (with cost; exact)
`weights`	any	sets of weights to compare ([{benefit: weight}]; the benefits extinction_risk, the linear layers' names, intactness): the plan of the best ranked
`tolerance`	number	exact: the relative gap to the bound (1e-7)
`time_limit`	number	exact: seconds (default none)

`restoration.resistance`#

A resistance growing with the distance to the habitat, as GuidosToolbox's Setup Tools -> Distance -> Resistance (landschaft's distance_to_resistance): the background round(distance + 2) up to 100 (3 next to the habitat), the habitat 2, missing 0; IDL's quasi-Euclidean distance.

Input	Type	What it is
`map`required	map	the map (0 missing, 1 background, 2 habitat)

Output	Type	What it is
`map`	map	the resistance

Setting	Type	What it is
`foreground`	any	the foreground's classes (a class or a list)

`restoration.status`#

How connected the habitat is and how much reconnecting it could add, as GuidosToolbox's Restoration Status (landschaft's restoration_status): the habitat's objects (8-connected), the equivalent connected area ECA = sqrt(sum of their areas squared), the coherence ECA / habitat (%), the restoration potential (100 - coherence), the habitat's share of the area with data (RAC), the average patch size and the critical new object area.

Input	Type	What it is
`map`required	map	the habitat map (0 missing, 1 background, 2 habitat)

Output	Type	What it is
`stats`	table	the area with data, objects, habitat, largest object, APS, CNOA, ECA, coherence (%), restoration potential (%), RAC (%)

Setting	Type	What it is
`foreground`	any	the foreground's classes (a class or a list)

distance.euclidean#

distance.influence_zones#

distance.objects_proximity#

distance.proximity#

restoration.corridor#

restoration.cost_distance#

restoration.ecosystem_areas#

restoration.ecosystem_targets#

restoration.intactness#

restoration.intactness_gradient#

restoration.isochrone#

restoration.least_cost_path#

restoration.original_vegetation#

restoration.plan#

restoration.resistance#

restoration.status#