User Tools

Site Tools


documentation:data_extractors_user_options

Data Extractors Configuration

What are Data Extractors ?

Capsis data extractors inspect the data history calculated during the simulations and pick values in the various steps to draw graphics (curves, histograms, tables…). The user can use such graphics to check the calculated variables in the simulation.

To open a graphic on the current step, double-click on the graphic name in the lateral bar. To add another step in the graphic, click on the step and Ctrl-click in the graphic.

This results in the creation of two data extractors, each synchronized on a source step. The extractors can show only this step or data coming from the scenario from the initial step to the source step (e.g. Basal Area / Time). The resulting data series are shown in a data renderer (e.g. Curves).

A graphic with 2 sources: steps v.60a and v2.55a

Configure the Data Extractors

It is possible to configure the extractors to change options such as “per hectare” or “class width” to have a custom result.

Right clicking on the graphic shows a contextual menu. Several Data Renderer options swap between various views of the same data series. A “Configuration” option helps for Common or Individual configuration.

There are several tabs in the configuration panel, including:

  • Common: changing options in this tab will alter the configuration for all the extractors in the same graphic, e.g. “all curves per hectare”
  • Individual (optional): this tab shows one sub panel per extractor in the graphic, thus allowing to change option values only for the chosen extractor, e.g. “show tree #1”
  • Curves (or another renderer name): configure the renderer, e.g. show the curves with thicker points
  • Properties: name and description of the extractor with the author name.

Thus, a “grouping line” in the Common tab will switch all the extractors on the chosen group. The same “grouping line” in the Individual tab will only switch the related extractors. The user will choose one or the other depending on his purpose.

Where to add the configuration items ?

All the extractors extend the DataExtractor class. The configuration items should be declared in the setConfigProperties () method. Each property has a simple name such as “xIsHdom”, meaning that the x axis represents Hdom.

All the property names must be translated in the extension translation files (extensionName_fr and _en.properties) so they will be presented translated on the user interface (e.g. xIsHdom = X asix is dominant height“.

See the next sections to see how to add new configuration properties in your extractor.

How to add Common Configuration options

Boolean property

A Boolean property is turned into a Checkbox in the extractor configuration panel.

public void setConfigProperties () {
    // adding a boolean property
    addBooleanProperty ("xIsHdom");
    ...
}
 
private void someMethod () {
    // testing a boolean property
    if (isSet ("xIsHdom")) {...}

Double property (or Int property)

A property to get a number. A default value can be provided, it will be returned if no change occurs.

public void setConfigProperties () {
    // adding a double property with a default value
    addDoubleProperty ("classWidthInCm", 5d);
    // addIntProperty ("classWidthInCm", 5);  // for an int
    ...
}
 
private void someMethod () {
    // getting the value of the property
    double classWidth = getDoubleProperty ("classWidthInCm");
    // int classWidth = getIntProperty ("classWidthInCm");  // for an int
    ...
}    

Radio properties

A set of Radio properties is turned into a list of exclusive radio buttons on the user interface. The user can select one option only at a time.

The name of each radio property in a same list of exclusion must start with the same word (here: “aflabel”), then an underscore “_”, then the name of the option (e.g: “AlleleName”).

public void setConfigProperties () {
    // adding a set of radio properties
    addRadioProperty (new String[] {"afLabel_AlleleName", "afLabel_Both",
            "afLabel_Frequency", "afLabel_None"});
    ...
}
 
private void someMethod () {
    // testing the properties
    if (isSet ("afLabel_None")) {
        ...
    } else if (isSet ("afLabel_Frequency")) {
        ...

Combo properties

A Combo property can be used to select one option among several. It will be drawn as a combo box in the user interface. Possible values are Strings. The item found in first position will be selected by default.

public void setConfigProperties () {
    // add a combo property
    LinkedList<String> speciesNames = ...
    addComboProperty ("speciesName", speciesNames);
    ...
}
 
private void someMethod () {
    // get the species name property value
    String speciesName = getComboProperty ("speciesName");
    ...

Set property

A Set property selects a sublist of options in a list of String. It is created in setConfigProperties (), then it can be updated with a new set of String options and it is possible to get the subset of selected options with getSetProperty ().

This property only manages options of type String.

public void setConfigProperties () {
    // adding a set property
    addSetProperty ("afLociIds", new String[] {"n_1"}, null);
    ...
}
 
...
private void someMethod () {
    // update the posible values of the property
    updateSetProperty ("afLociIds", ids);
    ...
 
private void someOtherMethod () {
    // get the selected values, e.g. "n_1" and "n_2"
    Set loci = getSetProperty ("afLociIds");
    ...

Group property

A group property is for restraining the graphic to the elements in a given group. The option must be selected (first checkbox) to be activated. Then choose the type of group (e.g. Tree group). Then select the group in the combo box. It is possible to select the complementary group with the “Not” checkbox. If needed, the last icon opens the group Catalog to create a new group on the fly to be selected in the combo box.

public void setConfigProperties () {
    // adding a group property
    addConfigProperty (DataExtractor.TREE_GROUP);
    ...
}
 
private void someMethod () {
    // restricting to the current group
    GScene stand = step.getScene ();
    Collection treesInTheGroup = doFilter (stand);
    ...
}

Other examples

It is possible to group checkboxes into a titled panel.

public void setConfigProperties () {
    addBooleanProperty ("DETimeRW.n03obj_avg", true);
    addBooleanProperty ("DETimeRW.n03obj_minmax", false);
    ...
}

How to add Individual Configuration options

Use the prefix “i-” for your property names and they will be considered as individual properties. They will appear on the “Individual” confiduration panel and will be applied only to the matching extractor in the graphic.

Individual Group property

A group property for each extractor in the same graphic.

public void setConfigProperties () {
    // add an individual group property
    addConfigProperty (DataExtractor.I_TREE_GROUP);
    ...
}
 
private void someMethod () {
    // restrain to the given group
    GScene stand = s.getScene ();
    Collection trees = doFilter (stand);
    ...
}
documentation/data_extractors_user_options.txt · Last modified: 2021/12/13 09:28 by 127.0.0.1