Show:
Module: iLand

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.

Methods

clear

()

Clears the list without affecting any trees.

cutAndDrop

()

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
)
Integer

Remove all selected trees with with the disturbance flag set. Disturbed trees are treated differently with regard to carbon flows and ABE. 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' ...)

Returns:

Integer:

the number of killed trees.

filter

(
  • expression
)
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

Returns:

Integer:

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
)
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.

Returns:

Integer:

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
)
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.

Returns:

Integer:

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

() Integer

Kill all trees which are currently in the tree list.

See also: kill, manageAll

Returns:

Integer:

the number of killed trees.

killPct

(
  • from
  • to
  • n
)
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

Returns:

Integer:

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
)

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
)

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
)
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.

Returns:

Integer:

the number of trees that were loaded.

Example:

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

loadAll

() Integer

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

Returns:

Integer:

the number of trees that were loaded.

loadFromMap

(
  • map
  • standID
  • do_append
)
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.

Returns:

Integer:

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
)
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

Returns:

Integer:

the number of trees that were loaded.

Example:

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

manage

(
  • filter
  • fraction
)
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.

Returns:

Integer:

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

() Integer

Harvest all trees which are currently in the tree list.

See also: manage, killAll

Returns:

Integer:

the number of harvested trees.

managePct

(
  • from
  • to
  • n
)
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

Returns:

Integer:

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
)
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

Returns:

Dobule:

the mean value of expression

Example:

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

percentile

(
  • pct
)
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

Returns:

Dobule:

the value associated with the pct percentile

randomize

()

Shuffle all trees in the list randomly.

removeSoilCarbon

(
  • map
  • standID
  • SWDfrac
  • DWDfrac
  • litterFrac
  • soilFrac
)

(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
)

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
)
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

Returns:

Dobule:

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

() 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

Returns:

Tree:

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

() 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

Returns:

Tree:

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);
                    

Properties

count

Integer

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

See also: SpatialAnalysis/load:method

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: SpatialAnalysis/removeFoliage:method, SpatialAnalysis/removeStem:method

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: SpatialAnalysis/removeBranch:method, SpatialAnalysis/removeStem:method

Example:

// 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: SpatialAnalysis/removeFoliage:method, SpatialAnalysis/removeBranch:method