Name

expression — A simple linear equation that describes the vertices that make up time series data

Synopsis

Content Model

No content allowed
      

Attributes

NameTypeDefault
statementThe expression defined using the Patchworks query languageRequired
fromThe lowest independent value used for interpolation0
toThe highest independent value used for interpolation300
byThe step sized used to increment the independent value for interpolation5
thinA parameter to the line thinning algorithm to reduce interior points.0.0
ignoreMissingAttributesA flag to indicate if missing attributes in the expression should be treated as a zero (true) or raise an error (false).false

Description

Curve values may also be specified as simple linear equations. The Matrix Builder will evaluate these equations as it is building the tracks dataset. The equations may refer to other curves or attributes, and may involve standard mathematical operations.

The expressions are stated using the Patchworks Query Language. Several functions provide access to previously defined curve and attribute values.

The curve function returns a reference to a curve by its curve idref value. The attributeid function returns a reference to a attribute by the attrribute idref value.

The attribute function returns a reference to a previously defined attribute by its label value. The label will be used to dynamically look up the attribute in the context of the stand that is currently being processed. Note that attributes are evaluated in the order that they are encountered within the ForestModel file, so referenced attributes must be defined before the expressions where they are referenced.

There are a number of functions that operate on curves that can be used in the expression, such as lookupcurve, shiftcurve, curve, offset, operable, etc. These functions and others are described in the the section called “Curve functions”.

There are two ways in which the expression may be evaluated: curve math or sampling. These two methods are chosen by the Patchwork Query Language based on the form of the expression that is being passed in. The curve math method is used when the expression is a simple linear equation, for example when adding curves or multiplying curves by scalars. In this case the expression evaluator will operate on the inflection points of the curves to define the new curve,

In the sampling method the curve is constructed by evaluating the expression over the domain of "from" value to the "to" value,incrementing by the "by" value. At each iteration the offset will return current age value, and the expression value is computed and added to the curve. This method is chosen when the expression contains functions such as offset, or when the expression is too complex for curve math operations. Sampling expressions are typically more verbose and often require lookupcurve functions to specify the required sampling.

The curve that is constructed from the expression has redundant points removed by a point thinning process.

Parents

These elements contain expression: attribute.

Children

Expressions are empty elements that contain no other content.

Attributes

statement

An expression formed using the Patchworks Query Language.

from

A value representing the lower end of the domain of values making up the curve.

to

A value representing the upper end of the domain of values making up the curve.

by

A value representing the increment used to step through from the "from" value to the "to" value.

thin

A value representing a deflection level. If the deflection of the point from it's neighbour points does not exceed the limit the point will be removed. The default thinning value is zero and only interior points on straight line sections will be removed.

ignoreMissingAttributes

Complex expressions may contain subexpressions that refer to other attributes. It may occur that the referenced attribute cannot be resolved (looked up) for a particular block. The default action when this happens is that the matirx builder will throw an exception. This attribute can be used to turn the exception checking off. In this case the sub-expression will be replaced with a zero value.

See Also

attribute, curve

Examples

Example 1. Reference to other attributes

In the following example some stand attributes have already been assigned by previously encountered attribute statements, and the '%f.Yield.%m.yConpulpv' attribute is accessed by name. The operable function returns the specified attribute value during ages when the stand is eligible for harvest, and zero otherwise. The expression is evaluated at each interpolation point in the referenced attribute, and a new curve is generated.

  <select statement="theme2 in T2_MANAGED and theme6 = 'NAT'">
    <features>
      <attribute label="%f.Opgs.%m.soft">
        <expression statement="operable(attribute('%f.Yield.%m.yConpulpv'))" />
      </attribute>
      <attribute label="%f.Opgs.%m.hard">
        <expression statement="operable(attribute('%f.Yield.%m.yHardpulpv'))" />
      </attribute>
    </features>
  </select>
    

Example 2. Using curve math

In the following example several previously defined attributes are multiplied by factors and added together using the Patchworks Query Language. The 'ignoreMissingAttributes' flag specifies that if the attribute lookup should fail then the sub-expression should return a value of 0. If this was not specified, a missing attribute definition would cause the Matrix Builder application to halt with an error message.

  <attribute id="1:?:?:WEST:?:?:?:%f.ECA.%m.ECAPer" label="%f.ECA.%m.ECAPer">
    <expression statement="attribute('%f.attr.%m.AG_ECA') * 0.55 + 
          attribute('%f.attr.%m.AM_ECA') * 0.43 + attribute('%f.attr.%m.AF_ECA') * 0.02" 
       ignoreMissingAttributes="true"/>
  </attribute>
    

Example 3. Interim calculations and the sampling method

In the following example an attribute value is calculated. The output="false" parameter indicates that the attribute value will be calculated and made available for use by name in subsequent expressions. The resulting attribute is transient and will not be output to the matrix. This is useful to simplify complex expressions by breaking them down in to smaller pieces, or when a common sub-expression is used in multiple other expressions.

Several previously defined attributes are divided to compute a ratio using the Patchwork Query Language curve math syntax. The setVar function is used to capture the lookup of the denominator value at each offset. This value is used twice in this expression saving the first lookup in a variable simplifies this expression slightly. An if function is used to test denominator value in order to prevent divisions by zero. In cases where the denominator is zero a result of 0 is produced, otherwise the ratio is calculated. The 'ignoreMissingAttributes' flag specifies that if either the attributes have not been previously defined then the attribute function should return a value of 0. If this parameter was not specified, a missing attribute definition would cause the Matrix Builder application to halt with an error message.

The by="1" parameter indicate that the expression should be sampled annually for all possible ages.

  <select>
    <products>
      <attribute label="%f.Output.%m.HV_HSMP" output="false">
        <expression 
           statement="if(setVar('d',lookupcurve(attribute('%f.Output.%m.HV_HWV'),offset()))==0,0,
                 lookupcurve(attribute('%f.Output.%m.HV_HSM'),offset())/getVar('d')) 
                 by="1" ignoreMissingAttributes="true"/>
      </attribute>
    </products>
  </select>
    

Example 4. Converting continuous values to discrete values

In the next example a query language expression is used calculate a visual quality objective threshold from a height curve. For this example we want the VQO criteria to be a boolean ON/OFF selector (having a value of 1 if the criteria is active and 0 if not), and the input value is a continuously-valued height curve.

The select statement checks that the fragment under consideration has a VQO value, and if not this attribute will be skipped. If it does represent a VQO site, the Matrix Builder will create an attribute having a name defined by an expression that includes the VQO id.

The value of the attribute is computed by the expression statement:

  1. find a height curve with an id value based on the CurrentYieldId value for the current fragment;

  2. look up the value of the curve at each offset value;

  3. if the curve height value at the offset is less than 6 return the value 1, else return the value 0;

  4. Repeat this assessment for the full range of potential offset values, stepping by 1 (in other words, evaluate for every possible annual value from 0 to the oldest possible age);

  5. assemble a curve from the calculated values.

  <select statement="VQO ne ''">
    <features>
      <attribute label="'%f.Layer.VQO.'+VQO">
        <expression 
            statement="if(lookupCurve(curveId('Height.'+CurrentYieldId), offset()) lt 6, 1, 0)"
            by="1" />
      </attribute>
    </features>
  </select>