The iLand Javascript API The iLand Javascript API

  • API Docs for Version: 1.0

    • APIs

    Show:

    Management Class

    Defined in: iLand\management_doc.js:1
    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

    ()

    Defined in iLand\management_doc.js:136

    Clears the list without affecting any trees.

    cutAndDrop

    ()

    Defined in iLand\management_doc.js:280

    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

    Defined in iLand\management_doc.js:287

    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

    Defined in iLand\management_doc.js:153

    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

    Defined in iLand\management_doc.js:181

    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

    Defined in iLand\management_doc.js:306

    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

    Defined in iLand\management_doc.js:273

    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

    Defined in iLand\management_doc.js:252

    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
    )

    Defined in iLand\management_doc.js:367

    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
    )

    Defined in iLand\management_doc.js:375

    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

    Defined in iLand\management_doc.js:97

    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

    Defined in iLand\management_doc.js:91

    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

    Defined in iLand\management_doc.js:121

    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

    Defined in iLand\management_doc.js:108

    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

    Defined in iLand\management_doc.js:351

    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

    Defined in iLand\management_doc.js:343

    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

    Defined in iLand\management_doc.js:322

    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

    Defined in iLand\management_doc.js:220

    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

    Defined in iLand\management_doc.js:208

    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

    ()

    Defined in iLand\management_doc.js:202

    Shuffle all trees in the list randomly.

    removeSoilCarbon

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

    Defined in iLand\management_doc.js:382

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

    Defined in iLand\management_doc.js:141

    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

    Defined in iLand\management_doc.js:233

    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

    Defined in iLand\management_doc.js:397

    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

    Defined in iLand\management_doc.js:413

    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

    Defined in iLand\management_doc.js:47

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

    See also: SpatialAnalysis/load:method

    removeBranch

    Double

    Defined in iLand\management_doc.js:70

    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

    Defined in iLand\management_doc.js:55

    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

    Defined in iLand\management_doc.js:80

    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