Class: Management

The Management object is used to for operations that remove trees from the simulation environment. The iLand management is accessible using the global object management, which is available when script code is invoked from the iLand management subsystem.

Main functions

  • Loading trees from iLand: use load() and loadFromMap() to load a list of trees
  • manipulating lists of trees: use filter() to select a sub set based on some criterion, or sort() to bring the list in a specific order; you can calculate sum() or mean() values from all trees in the list
  • removing trees: manage() and kill()
  • other functions such as….

Note that by default only living trees are processed. Several special functions exists, e.g. a function to filter based on a predefined list of tree-ids (filter()), of methods that select trees based on some rastered GIS data.

There are several distinct tree removal modes in iLand, namely by harvesting a tree, or by killing a tree, or due to a disturbance. In general, harvesting removes all (aboveground) biomass from the system, while a killed trees’ biomass is moved to the soil pools. Disturbed trees behave similar to killed trees. Note, that there are further subtle differences between removal modes: for instance, resprouting is only possible from harvested trees; or, trees killed by disturbance might be treated differently by management.

The management functions typically affect only individual trees in iLand with a height >4m. However, there are some functions available to alter the state of the saplings (tree cohorts < 4m height).

Expressions and tree variables

Many function of the management object allow to specify a filter (Expression). In the context of management, tree variables can be used within filter expressions: see https://iland-model.org/tree+variables

Tree species can be included in Expressions by using the short name as is; internally, the species (identity) is a integer index of the species, and species short names (such as ‘piab’, ‘fasy’, or ‘pico’) are used as placeholders.

Examples

The wiki contains a small collection of useful management scripts.

Properties Overview

Name Type Description
count integer The number of trees that are currently in the internal list.
removeBranch double The removal fraction for branches [0..1]. 0: 0% will be removed, 1: 100% will be removed from the forest by management operations (i.e. calls to manage())
removeFoliage double The removal fraction for foliage [0..1]. 0: 0% will be removed, 1: 100% will be removed from the forest by management operations (i.e. calls to manage())
removeStem double The removal fraction for the stem biomass [0..1]. 0: 0% will be removed, 1: 100% will be removed from the forest by management operations (i.e. calls to manage())

Methods Overview

Method Return Type Description
clear() void Clears the list without affecting any trees.
cutAndDrop() void Kill all and cut down all trees in the list. The biomass of cut down trees bypasses the standing dead wood pool, and
disturbanceKill(stem_to_soil_fraction, stem_to_snag_fraction, branch_to_soil_fraction, branch_to_snag_fraction, agent) integer Remove all selected trees with with the disturbance flag set. Disturbed trees are treated
filter(expression) integer Apply a filter expression on the list of trees (expressionis a valid iLand Expression)
filterIdList(list) integer Apply a filter in form of a list of ids, return number of remaining trees. This can be useful
kill(filter, fraction) integer Kill fraction (0..1) of all trees for which the Expression filter is true.
killAll() integer Kill all trees which are currently in the tree list.
killPct(from, to, n) integer Use killPct to remove n trees sampled randomly from a given percentile range (given by from and to). All
killSaplings(map, standID) void Kill all saplings (i.e. trees <4m) which are located on grid pixels with the value standID on the grid map.
killSaplingsResourceUnit(ruindex) void Kill all saplings (i.e. trees <4m) which are located on the resource unit identified by ruindex.
load(filter) integer Load all trees passing the filter criterion specified in filter and return number of trees in the list.
loadAll() integer Load all trees into the internal list and return the number of trees.
loadFromMap(map, standID, do_append) integer Load all trees that are located on grid pixels with the value standID on the grid map.
loadResourceUnit(ruindex) integer Load all trees of a resource unit with the index ruindex and return the number of loaded trees.
manage(filter, fraction) integer Remove a fraction (0..1) of all trees for which the Expression filter is true.
manageAll() integer Harvest all trees which are currently in the tree list.
managePct(from, to, n) integer Use managePct to remove n trees sampled randomly from a given percentile range (given by from and to). All
mean(expression, filter) dobule Calculate the mean value for all trees in the internal list for expression (optionally filtered by the filter criterion).
percentile(pct) dobule Retrieve the value associated with the pct percentile [0..100] of the currently loaded trees. A call
randomize() void Shuffle all trees in the list randomly.
removeSoilCarbon(map, standID, SWDfrac, DWDfrac, litterFrac, soilFrac) void (Hacky) function to modify the carbon content of the snag/soil pools of resource units covered by pixels with standID on the map.
sort(expression) void Sort the trees in the internal list in ascending order according to a criterion given
sum(expression, filter) dobule Calculate the sum of expression for all trees in the internal list (optionally filtered by the filter criterion).
tree() Tree tree(index) returns the tree with index index (index is 0-based) from the current list. The returned Javascript object
treeObject() Tree treeObject(index) returns the tree with index index (index is 0-based) from the current list. A new Javascript object

Properties Details

count

integer

The number of trees that are currently in the internal list.

See also: load()

removeBranch

double

The removal fraction for branches [0..1]. 0: 0% will be removed, 1: 100% will be removed from the forest by management operations (i.e. calls to manage())

The default value is 0 (all branches remain in the forest)

See also: removeFoliage(), removeStem()

removeFoliage

double

The removal fraction for foliage [0..1]. 0: 0% will be removed, 1: 100% will be removed from the forest by management operations (i.e. calls to manage())

The default value is 0 (all foliage remains in the forest)

See also: removeBranch(), removeStem()

// full tree extraction
    management.removeFoliage = 1; management.removeBranch=1; management.removeStem = 1;
    management.manageAll();

removeStem

double

The removal fraction for the stem biomass [0..1]. 0: 0% will be removed, 1: 100% will be removed from the forest by management operations (i.e. calls to manage())

The default value is 1 (100% of the stem is removed in case of management). Note that root biomass is never extracted.

See also: removeFoliage(), removeBranch()

Methods Details

clear()

Returns: void

Clears the list without affecting any trees.

cutAndDrop()

Returns: void

Kill all and cut down all trees in the list. The biomass of cut down trees bypasses the standing dead wood pool, and such trees can act as trap trees with regard to bark beetles.

See also: kill(), manageAll()

disturbanceKill(stem_to_soil_fraction, stem_to_snag_fraction, branch_to_soil_fraction, branch_to_snag_fraction, agent)

Returns: integer

Remove all selected trees with with the disturbance flag set. Disturbed trees are treated differently with regard to carbon flows and {{#crossLinkModule “ABE”}}{{/crossLinkModule}}. Biomass of the stem and the branches is routed to the soil and snag pools as indicated by the parameters of the function. The rest of the biomass is removed from the system (e.g., consumed by fire). For example, if stem_to_soil_fraction=0.2, stem_to_snag_fraction=0.3, then 50% of the biomass leaves the system, 20% are added to the soil, 30% to the snag pools.

The agent parameter is the reason of death (i.e. the process that should be mimicked). Recognized values are ‘fire’, ‘wind’, ‘barkbeetle’, and ‘cutdown’. For instance, tree that are removed with the agent set to ‘wind’ act as a breeding material for bark beetles. If the agent parameter is 'fire', then serotinous trees produce extra seeds.

See also: killAll(), manageAll()

Parameters:

  • stem_to_soil_fraction (double): (0..1) of stem biomass that is routed to the soil
  • stem_to_snag_fraction (double): (0..1) of the stem biomass continues as standing dead
  • branch_to_soil_fraction (double): (0..1) of branch biomass that is routed to the soil
  • branch_to_snag_fraction (double): (0..1) of the branch biomass continues as standing dead
  • agent (string): the disturbance agent that is mimicked (‘fire’ ‘wind’, ‘barkbeetle’, ‘cutdown’ …)

Return Value Description: the number of killed trees.

filter(expression)

Returns: integer

Apply a filter expression on the list of trees (expressionis a valid iLand Expression) and return the number of trees remaining in the lists. After calling this function, the list of trees is typically reduced and contains only those trees, who meet the condition in expression.

See the example how to filter by species, and how to combine multiple criteria.

See also: sort(), load()

Parameters:

  • expression (string): Expression used for filtering

Return Value Description: the number of trees in the list after filtering.

Example:

management.loadAll();
    management.filter('dbh>10');
    // is the same as:
    management.load('dbh>10');
    // using tree species names: note, that no "'" or '"" signs
    // are used with species IDs; note also the boolean 'and' operator
    management.filter('species=piab and dbh>20');
    management.loadAll(); // all trees
    management.filter('dbh>10 and species=piab'); // reduce list
    // ... some processing....
    management.filter('dbh>20'); // now only spruce trees > 20cm are still in the list
    management.filter('stress>0'); // now only spruce trees >20cm, that have a non-zero stress rating are in the list
    // ...

filterIdList(list)

Returns: integer

Apply a filter in form of a list of ids, return number of remaining trees. This can be useful to pre-define a management on individual trees.

See the example below.

See also: filter(), https://iland-model.org/initialize+trees

Parameters:

  • list (array): A list of unique tree IDs.

Return Value Description: the number of trees in the list after filtering.

Example:

// array of tree IDs
    var treelist = [10,20,40,43]; // can be loaded form file...
    management.load(); // load all trees
    management.filter(treelist); // filter trees using the tree list
    management.kill(); // remove all trees remaining, i.e. the trees in the tree list.

kill(filter, fraction)

Returns: integer

Kill fraction (0..1) of all trees for which the Expression filter is true.

See also: killAll(), manage()

Parameters:

  • filter (string): A expression to select a subset of the trees.
  • fraction (double): give the fraction (0..1) of trees that should be killed.

Return Value Description: the number of killed trees.

Example:

management.loadAll();
    // kill 30% of larch trees, and 60% of pine
    management.kill('species = lade', 0.3);
    management.kill('species = pisy', 0.6);

killAll()

Returns: integer

Kill all trees which are currently in the tree list.

See also: kill(), manageAll()

Return Value Description: the number of killed trees.

killPct(from, to, n)

Returns: integer

Use killPct to remove n trees sampled randomly from a given percentile range (given by from and to). All trees are removed, if n is higher than the number of trees in that range.

The tree list needs to be sorted, before percentile based selection makes sense.

See also: sort(), percentile()

Parameters:

  • from (integer): lower percentile of the current tree distribution (0..100)
  • to (integer): higher percentile of the current tree distribution (0..100)
  • n (integer): the number of trees to kill in the given percentile

Return Value Description: the number of killed trees

Example:

var n = management.loadAll();
    management.sort('dbh');
    var n_killed = management.killPct(0,50, n*0.25);
    console.log('killed ' + n_killed + ' below median: ' + management.percentile(50) );
    // kill 33% of the trees between the 80th and the 100th percentile.
    management.killPct(80,100, n*0.2 * 0.33);

killSaplings(map, standID)

Returns: void

Kill all saplings (i.e. trees <4m) which are located on grid pixels with the value standID on the grid map.

Parameters:

  • map (Map): A Map object with a stand grid.
  • standID (integer): the ID of the stand to process.

killSaplingsResourceUnit(ruindex)

Returns: void

Kill all saplings (i.e. trees <4m) which are located on the resource unit identified by ruindex.

Parameters:

  • ruindex (integer): the index of the resource unit to process.

load(filter)

Returns: integer

Load all trees passing the filter criterion specified in filter and return number of trees in the list. filter can be any tree-related Expression.

Parameters:

  • filter (string): A valid filter Expression that is applied during the loading of the list.

Return Value Description: the number of trees that were loaded.

Example:

// load all trees with a dbh >30 cm
    management.load('dbh>30');

loadAll()

Returns: integer

Load all trees into the internal list and return the number of trees.

Return Value Description: the number of trees that were loaded.

loadFromMap(map, standID, do_append)

Returns: integer

Load all trees that are located on grid pixels with the value standID on the grid map.

Parameters:

  • map (Map): a GIS grid that defines stand IDs.
  • standID (integer): the ID of the stand that should be loaded.
  • do_append (boolean): if true, the list is not cleared and trees are added to the existing list. Default is false.

Return Value Description: the number of trees that were loaded.

Example:

// Access to the global stand grid (required only once)
    var stand_grid = new Map();
    // load all trees of the forest stand with ID=1
    management.loadFromMap(stand_grid, 1);

loadResourceUnit(ruindex)

Returns: integer

Load all trees of a resource unit with the index ruindex and return the number of loaded trees.

Parameters:

  • ruindex (int): The index (0-based) of the resource unit that should be loaded

Return Value Description: the number of trees that were loaded.

Example:

for (var i=0; i<Globals.resourceUnitCount; ++) {
        management.loadResourceUnit(i);
        // further processing....
    }

manage(filter, fraction)

Returns: integer

Remove a fraction (0..1) of all trees for which the Expression filter is true.

See also: manageAll(), kill()

Parameters:

  • filter (string): A expression to select a subset of the trees.
  • fraction (double): give the fraction (0..1) of trees that should be harvested.

Return Value Description: the number of harvested trees.

Example:

management.loadAll();
    // kill 30% of larch trees, and 60% of pine
    management.manage('species = lade', 0.3);
    management.manage('species = pisy', 0.6);

manageAll()

Returns: integer

Harvest all trees which are currently in the tree list.

See also: manage(), killAll()

Return Value Description: the number of harvested trees.

managePct(from, to, n)

Returns: integer

Use managePct to remove n trees sampled randomly from a given percentile range (given by from and to). All trees are removed, if n is higher than the number of trees in that range.

The tree list needs to be sorted, before percentile based selection makes sense.

See also: sort(), percentile()

Parameters:

  • from (integer): lower percentile of the current tree distribution (0..100)
  • to (integer): higher percentile of the current tree distribution (0..100)
  • n (integer): the number of trees to harvest in the given percentile

Return Value Description: the number of harvested trees

Example:

var n = management.loadAll();
    management.sort('dbh');
    var n_rem = management.managePct(0,50, n*0.25);
    console.log('removed ' + n_rem + ' below median: ' + management.percentile(50) );
    // harvest 33% of the trees between the 80th and the 100th percentile.
    management.managePct(80,100, n*0.2 * 0.33);

mean(expression, filter)

Returns: dobule

Calculate the mean value for all trees in the internal list for expression (optionally filtered by the filter criterion).

See also: sum()

Parameters:

  • expression (string): The expression used for calculating the mean value
  • filter (string): If not empty, the mean is calculated only from those trees that meet the criterion in the expression

Return Value Description: the mean value of expression

Example:

var mean_dbh = management.mean('dbh');

percentile(pct)

Returns: dobule

Retrieve the value associated with the pct percentile [0..100] of the currently loaded trees. A call to sort()() is required in order to prepare valid data.

See also: sort()

Parameters:

  • pct (integer): the percentile [0..100] for which to return the value

Return Value Description: the value associated with the pct percentile

randomize()

Returns: void

Shuffle all trees in the list randomly.

removeSoilCarbon(map, standID, SWDfrac, DWDfrac, litterFrac, soilFrac)

Returns: void

(Hacky) function to modify the carbon content of the snag/soil pools of resource units covered by pixels with standID on the map. If the resource unit is only partially covered, the factors are scaled accordingly. The parameters are remove-fractions, i.e. values of 0 mean no change, values of 1 mean removal of 100% of the carbon of the respective pool.

Parameters:

  • map (Map): A Map object with a stand grid.
  • standID (integer): the ID of the stand to process.
  • SWDfrac (double): fraction of standing woody debris to remove.
  • DWDfrac (double): fraction of downed woody debris to remove.
  • litterFrac (double): fraction of litter (yL) to remove.
  • soilFrac (double): fraction of SOM to remove..

sort(expression)

Returns: void

Sort the trees in the internal list in ascending order according to a criterion given by expression (a valid iLand Expression).

See also: percentile()

Parameters:

  • expression (string): Expression used for sorting

Example:

management.sort('dbh'); // sort by diameter, largest tree are now in the end of the list
    management.sort('-dbh'); // to sort in descending order, reverse the sign of the expression

sum(expression, filter)

Returns: dobule

Calculate the sum of expression for all trees in the internal list (optionally filtered by the filter criterion).

See also: sum()

Parameters:

  • expression (string): The expression used for calculating the mean value
  • filter (string): If not empty, the mean is calculated only from those trees that meet the criterion in the expression

Return Value Description: the mean value of expression

Example:

// select trees that represent 50% of the total basal area
    management.loadAll();
    var total_ba = management.sum('basalarea');
    management.randomize();
    management.filter('incsum(basalarea)<' + total_ba * 0.5 );
    console.log(management.sum('basalarea'));

tree()

Returns: Tree

tree(index) returns the tree with index index (index is 0-based) from the current list. The returned Javascript object is a reference to the represented tree in iLand. See Tree for more details.

See also: treeObject()

Return Value Description: a reference to the tree with index index (see above). If the index is out of range, the valid property of the returned object is false.

Example:

management.loadAll(); // fill the tree list
    // loop over all trees
    for (var i=0;i<management.count;++i)
       console.log( management.tree(i).dbh );

treeObject()

Returns: Tree

treeObject(index) returns the tree with index index (index is 0-based) from the current list. A new Javascript object is created for the tree. See Tree for more details.

See also: tree()

Return Value Description: a object representing the tree with index index (see above), or an invalid Tree object (if index is out of range).

Example:

management.loadAll(); // fill the tree list
    var x = management.treeObject(7); // 8th tree in the list
    // access the tree
    if (x.valid == true)
       console.log(x.dbh);