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

loading data

int load()
Load all trees into the internal list and return the number of trees.

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

int loadFromMap(Map map, standID)
Load all trees that are located on grid pixels with the value standID on the grid map.
See also: 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().
See also: load() and filter().

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.
See also: load(), filter(), kill() and the biomass removal fractions (removeFoliage, removeBranch, removeStem)

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.
See also: load(), filter(), kill() and the biomass removal fractions (removeFoliage, removeBranch, removeStem)

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.
See also: sort()

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.
See also: 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

addTrees(int resourceUnitIndex, QString content)
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.
See also: addSingleTrees
Example:

function initFromFile()
{
	init_file_content = Globals.loadTextFile("temp/iTest_script.csv");
	alert("Filecontent: " + init_file_content);
	Globals.addTrees(1, init_file_content);
}

addTreesOnStand(int standID, QString content)
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.
See also: addSingleTrees, addTrees
Example:

function initFromFile()
{
	init_file_content = Globals.loadTextFile("temp/iTest_script.csv");
	alert("Filecontent: " + init_file_content);
	Globals.addTreesOnStand(127, init_file_content);
}

addSingleTrees(int resourceUnitIndex, QString content)
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.
See also: addTrees

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

See also: addTrees

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)
{
	var cnt = management.load();
	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;
   climFile.loadFile(Globals.currentDir + "kill_list.txt");
   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()
{
	var arr = load_array(); // load (see javascript function above)
	management.load(); // load all trees
	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()
{
	management.loadFromMap(mgmt_map, 1); // load all trees of polygon '1'
	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()
{
	management.loadFromMap(mgmt_map, 1); // load all trees of polygon '1'
	var sum_ba = management.sum('basalarea');
	// randomly shuffle the list
	management.randomize();	
	// manage 40% of the basal area
	management.manage('incsum(basalarea)<' + sum_ba*0.4); 	

}