Javascript object "Management"

# Object Management

#### Note

The API documentation for this object moved: Management object.

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.
Use one of the variants of load() to fetch trees from iLand, and modify the list of trees using sort and filter. Actually remove trees using the kill-methods and manage methods.
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()).

## Methods

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

Load all trees passing the filter in a list and return number of trees in the list. filter can be any tree-related expression.

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

### manipulating and accessing tree lists

sort(string statement)
Sort the trees in the list according to the criterion defined by statement. statement can be any expression. Use in combination with percentile() and kill().

int filter(string filter)
Apply a filter on the list of trees (any expression) and return the number of trees remaining in the lists.

int filter(array idList)
Apply a filter in form of a array of tree-ids (see tree variables) and return the number of remaining trees. Use in combination with load()

remain(int number)
remove randomly trees until only number of trees remains.
Note: The function always processes all trees of the system, i.e., it is not affected by filtering (by filter() or loadFromMap()).

double sum(string expression, string filter="")
calculates a sum over all trees in the internal tree list for the expression expression. If filter is provided, only trees matching the criterion are considered.
Returns the sum of expression.

double mean(string expression, string filter="")
calculates the mean value over all trees in the internal tree list for the expression expression. If filter is provided, only trees matching the criterion are considered.
Returns the mean of expression or 0 when list is empty.

### managing trees

int kill()
Remove all trees that are in the list of trees. For actual harvest operations use manage().

int kill(int pctfrom, int pctto, int number)
remove number trees in the percentile interval from to to (0..99). remove all trees, if number' is higher than the actual count of trees. Use manage()'' for harvest operations.
Return the number of removed trees.

int kill(string filter, double fraction)
remove the fraction fraction (0..1) of trees that comply with the filter expression filter. A value of 1 (the default value) of the parameter fraction kills all trees. The operation only removes killed trees from the internal tree list, thus several kill() calls can be issued after a single load() call. See also the filter() and the other kill() functions.
Returns the number of removed trees.
Note: A similar manage() function exists.

int manage()
Executes a harvest operation and removes all trees that are in the list of trees.
Return is the number of trees that was removed.

int manage(int pctfrom, int pctto, int number)
remove number trees in the percentile interval from to to (0..99). remove all trees, if ''number' is higher than the actual count of trees.
Return the number of removed trees.

int manage(string filter, double fraction)
remove the fraction fraction (0..1) of trees that comply with the filter expression filter. The operation only removes managed trees from the internal tree list, thus several manage() calls can be issued after a single load() call. See also the filter() and the other manage() functions.
Returns the number of managed trees.
Note: A similar kill() function exists.

double percentile(int pct)
get current numerical value for the pct' th percentile (1..100). Use after a call to sort()'', otherwise return values will be 0.

### other management functions

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

removeSoilCarbon(Map 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.
SWDfrac: fraction of standing woody debris, DWDfrac: fraction of downed woody debris, litterFrac fraction of litter (yL) to remove, soilFrac: fraction of SOM to remove.

slashSnags(Map map, standID, slash_fraction)
Function to 'manage' snags, i.e. to cut down and move biomass to the soil pools. The spatial approach is as described for removeSoilCarbon(). The parameter slash_fraction describes (from 0..1) the fraction of biomass that should be transferred to the soil (0: nothing, 1: all). Currently, the standing woody debris pool (SWD) and the 'other wood' pools are treated equally.

## Properties

count
Number of trees currently in the list.

removeFoliage
defines the fraction of foliage biomass that is removed from the system during management operations.
All biomass remains at the site when the value is 0, all biomass is removed (100%) if the value is 1.
default value: 0

removeBranch
defines the fraction of branch biomass that is removed from the system during management operations.
All biomass remains at the site when the value is 0, all biomass is removed (100%) if the value is 1.
default value: 0

removeStem
defines the fraction of stem biomass that is removed from the system during management operations.
All biomass remains at the site when the value is 0, all biomass is removed (100%) if the value is 1.
default value: 1

## Additional methods from the Globals object

create trees as specified in content within the resource unit indexed by resourceUnitIndex. content is a string that contains lines equal to the iLand-mode of initialize trees.
Example:

function initFromFile()
{
}

create trees as specified in content on the stand defined by standID. content is a string that contains lines equal to the iLand-mode of initialize trees.
Example:

function initFromFile()
{
}

create trees as specified in content within the resource unit indexed by resourceUnitIndex. content is a string that single tree data in the single tree file format.

addSaplingsOnMap(Map map, int mapId, string species, int n_ha, double height, int age)
add saplings of species species on the polygon mapId of the polygonal map map. The function adds n_ha cohorts/ha (on the same number of 2m pixels). The added trees have the given height (in m) and age (in years).

function initSaplings()
{
var stand_grid = Factory.newMap(); // required only once
// add 1000 cohorts with spruce, 1m height, 5 yrs.
Globals.addSaplingsOnMap(stand_grid, 1, 'piab', 1000, 1, 5);
}

## Examples

### Example 1: simple management

function remove_below(should_remain)
{
print ("remove_below: " + cnt + " trees present.");
management.sort('dbh');
var to_kill = cnt - should_remain;
if (to_kill < 0)
return;
// step 1: remove 80% from the lowest quarter
to_kill -= management.kill(0, 25, to_kill*0.8);
// remove the rest randomly from the next quarter
if (to_kill>0)
to_kill -= management.kill(25, 50, to_kill);
// if not satisfied, remove randomly from the rest.
if (to_kill>0)
management.kill(50, 100, to_kill);
print("remove_below:" + management.load() + " trees left.");

}

### Example 2: using predefined tree lists

We use CSVFile to load a list of trees represented by Ids (see tree variables). We then facilitate the filter() method of the Management to specifically select this set of trees.
First, we define a javascript function that loads the content of a text file in a array:

function load_array()
{
var climFile = new CSVFile;
climFile.captions=false;
climFile.flat = true;
var i = 0;
var arr=[];
while (i<climFile.rowCount)
arr.push(climFile.row(i++));
print ("array has now " + arr.length + " items");
return arr;
}

Then, we apply this array as a filter:

function kill_array()
{
management.filter(arr); // filter trees using the tree list
management.kill(); // remove all trees remaining
}

### Example 3: one (spatial) load, multiple operations

A pair of kill() and manage() functions is available that allows avoiding unnecessary reloads of tree lists.
A call to load() or loadFromMap establishes the internal tree list. In contrary, calling filter() or sort() modify the internal list.
Note that those function calls can be mixed, e.g., filter a list to a specific species and apply several manage() operations on that set.

function op()
{
print("Before: " + management.count);
management.kill('dbh<20', 0.8); // remove 80% of trees with dbh<20
management.kill('dbh>=20 and dbh<40', 0.5); // remove 50%
print("Survived: " + management.count);
}

### Example 4: facilitating sum() and mean()

function basal_area()
{
}