Name

curvetable — a row- or column-oriented table of curves that make up time series data

Synopsis

Content Model


	    <curvetable> = column, tabular data

      

Attributes

NameTypeDefault
agecolumnnumeric column number (columns start at 0) 0
agepatternA pattern used to extract age columns from the table (mutually exclusive with agecolumn) 
factorA numeric curve scaling factor1.0
forcezeroIf specified a number for the year where the curve intersects the y axis 
ignorelistIf specified a list of numbers indicating the the columns that should be ignored 
missingThe token to represent a missing input value 
replacemissingA replacement value to be used when the a missing value is encountered. 
patternThe base pattern used to compute the curve id.%h
splitA string regular expression used for the field separator, or if not specified then fixed column fields will be read 
square

If specified a number indicating that data values will be flat-lined between vertices.

 
xscaleA number to multiply the age value1.0
xshiftA number added to the age value0.0
fileThe name of the file from where the curve data should be read from 

Description

This element specifies tables of curves in a compact column or row format. In the column format one of the columns contains the age field, and the other columns contain values. The table must have a header row that provides the column names. In the row format one of more columns contain stratification columns, and other columns contain the values by age.

The table may have fixed position columns, or be separated by field separator characters. For fixed position columns the data must line up on the right side of the column heading. Otherwise, specify a regular expression to split up the fields, such as split="," to split on commas.

The xscale and xshift attributes are used to convert age values from periods to years. The age value is first multiplied by the scale value and then added to the shift value.

The y values are multiplied by the factor attribute.

Blank or missing values in any of the table cells will be skipped and that age will not be added to the curve.

Column oriented curve table

Each row contains the values for a single age. A series of values are contained in rows all having the same stratification values.

The rows in the table may be stratified in to curve sets by using classifier specifications in the pattern attribute. Classifier specifications indicate the columns that contain the classifier category values. Each unique combination of classifier values demarcates a curve set.

The position of the column containing the age value is indicated by the agecolumn attribute, with column numbering starting at zero.

The curve names are composed by starting with the pattern attribute as the base, and replacing each occurrence of '%h' with the table column heading, and each occurrence of '%<n>c' with a classifier value.

The pattern attribute must contain references to all of the stratification columns as well as the %h column heading value (see the following description for the pattern attribute). All columns that are not identified as the age column and are not stratification columns used in the pattern attribute are converted in to curves. If there are columns that should not be converted to curves (such as interim calculation columns) these may be ignored using the ignorelist column (described below).

The data must be sorted in ascending order by age. If the input data contains multiple curve sets and the pattern attribute has classifier information then each curve set must be contiguous, and within each curve set the data must be sorted by age.

Row oriented curve table

Row oriented curve tables contain one or more stratification columns plus columns for each age value. Each row contains one curve. The column headings indicate the ages for the values in that column.

Age columns are identified using the agepattern attribute. Stratification columns are indicated by the values in the pattern attribute. All other columns are ignored.

Curves are named based on the pattern attribute, with substitutions for the classifier values

Parents

These elements contain curvetable: ForestModel.

Children

Column oriented curve tables may contain the following elements: column.

Row oriented curve tables may not contain any elements.

Attributes

agecolumn

The column number in the data table that contains the age column. Column numbers start at zero..

agepattern

A regular expression that identifies age columns for row-based curves, similar to those used in the TigerMoth model. Each row in the table represents a curve. The column headings contain the age for each column. The regular expression determines how to extract the age value from the column heading label. The age value is taken from the first capture group in the regular expression. For example, if the column heading contain the age, then a pattern such as "(\d+)" would capture a string of digits.

The agepattern attribute is mutually exclusive with the agecolumn attribute: you may only specify one or the other.

When using the agepattern attribute the %h column heading substitution symbol is unavailable.

factor

A scaling factor that will be used to multiply the data values.

forcezero

Add a point that forces the curve to y=0. The number that is specified is the x-value where the y-value should be zero. This value must be less than the lowest age in the curve table.

ignorelist

A list of comma-separated column numbers indicating column that should be ignored and not converted to a curve.

missing

The token that is used to represent a missing value in the input data. Blank values are always ignored, but input data that uses space characters to separate columns will require an explicit missing value token.

replacemissing

If the replacemissing attribute is specified then this value will be used in place of missing values and will be included in the curve. This value must evaluate to a number.

pattern

The curve id values are calculated by starting with the pattern attribute as the base, and replacing each occurence of '%h' with the table column heading. For example, pattern="PRF.HDSEL.PRESNT.%h" with input column headings of "BA", "bargr" ,"GTVol", "GMVol" and "NMVol" will yield names of "PRF.HDSEL.PRESNT..BA", "PRF.HDSEL.PRESNT.bargr", "PRF.HDSEL.PRESNT.GTVol", etc.

The pattern attribute may also classifier column values that are used to classify the input in to curve sets. This is done by including a "%<n>c" token in the pattern, where <n> is replaced with a number of the column that contains the subdividing classifier. Whenever the value in the specified column changes the values collected so far will be turned in to curves, and the curve names will be composed from the value of the classifier columns and the column headings. Multiple classifier columns may be used at the same time (for example to subset on analysis unit and treatment regime, such as pattern="PRF.%0c.%1c.%h" which will use the values in the first and second column to determine subsets). See the example 2 below for a sample usage of the %c token.

Classifier columns (%<n>c in the pattern) are not converted to curve values (they are classifiers).

When using classifiers the curve set data must be arranged so that all rows in the same classifier category are adjacent. An error will occur if rows from different categories are interleaved.

Note that if using the agepattern attribute then the %h substitution symbol will not be available, and %<n>c tokens must be used in the pattern.

split

A regular expression used to split each line in to fields. For example to split the data by commas use split=",". To split by multiple whitespace characters use "\s*". The default value is that the table will be split using fixed space columns that line up under the right-most character of the column heading.

square

If the square attribute is specified the values will be flat-lined between vertices. In flat lining mode the values will remain constant until prior to the next inflection point. The numeric value of the square attribute will indicate how many years prior to the next inflection point where the additional flat-line point will be inserted. Use a value of 1 to have the flat-line point one year prior.

xscale

Used to convert periodic age values to years. The age value is first multiplied by this number.

xshift

Used to convert periodic age values to years. This number is added to the age value.

file

A file name or TableSpec string that references the file that contains the curve data. The file attribute and embedded curve data are mutually exclusive: only one may be specified.

The file attribute is specified as a Patchworks Query Language expression. Literal file names must be enclosed in single quotes. Other query language functions and operators, such as repeat variables or defined constants, may be used to compose the file name.

See Also

curve

Examples

Example 1. CSV format

In the following example a set of curves have been added in CSV format. The split attribute indicates to split the lines at commas. The pattern attribute will create curves named PRF.HDSEL.CT18.BA, PRF.HDSEL.CT18.bargr, etc. The default is that the first column (column 0) contains the age column.


  <curvetable split="," pattern="PRF.HDSEL.CT18.%h">
    Age,BA,bargr,GTVol,GMVol,NMVol
    0,18,0.331611,147.83184,92.58579,78.59373224
    3,18.994833,0.308920255,156.002284,97.70286773,82.93748993
    6,19.92159377,0.554832428,163.613659,102.4698054,86.98402257
    9,21.58609105,0.519188674,177.2839755,111.0314052,94.25174778
    12,23.14365707,0.4873855,190.0760783,119.0429874,101.0525771
    15,24.60581357,0.458894776,202.0845942,126.563816,107.436818
    18,25.9824979,0.433277143,213.3911374,133.6450053,113.4478602
    21,27.28232933,0.410164621,224.0664969,140.3308897,119.1233381
    24,28.5128232,0.38924709,234.1723954,146.6601256,124.4960662
    27,29.68056446,0.370261668,243.7629143,152.6665838,129.5947965
    30,30.79134947,0.35298432,252.8856582,158.3800786,134.4448375
    33,31.85030243,0.33722315,261.5827118,163.8269673,139.0685634
    36,32.86197188,0.322813024,269.8914316,169.030646,143.4858344
  </curvetable>
    

Example 2. Classifying subsets

This example shows the use of a classifier column to indicate subsets of rows that make up individual curve sets. In this case the pattern variable contains %0c which indicates that column 0 contains a classifier. As the curvetable is read values are collected until the classifier changes. At this point the curves containing the values read so far are added to the curve library, the input mechanism is reset, and the next set of curve values for the new classifier is processed.

The agecolumn parameter indicates that the age value is read from column 1 (the second column).

The curves are named by substituting classifier values (%0c) and column headings (%h) according to the pattern. For this example curves will named "Yield.21.Ba", "Yield.21.Decid", Yield.21.Pl", "Yield.21.Sx", "Yield.24.Ba", etc. These curves may be references within the Matrix Builder using the curveid function, for example curveid('Yield.21.Pl').

Note that no curves will be created for the Fd column in either curve set because this column is missing values for all rows.

  <curvetable split="," pattern="%0c.%h" agecolumn="1">
Id,Age,Ba,Decid,Fd,Pl,Sx
Yield.21,0,0,0,,0,0
Yield.21,5,0,0,,0,0
Yield.21,10,0,0,,0,0
Yield.21,15,0,0,,0,0
Yield.21,20,0,0,,0.25245,0
Yield.21,25,0,0,,7.554375,0
Yield.21,30,0,0,,22.4383,0
Yield.21,35,0,0,,40.00249,0
Yield.24,0,0,0,,0,0
Yield.24,5,0,0,,0,0
Yield.24,10,0,0,,0,0
Yield.24,15,0,0,,0,0
Yield.24,20,0,0,,0,0
Yield.24,25,0,0,,3.02175,0
Yield.24,30,0,0,,13.47972,0
Yield.24,35,0,0,,26.38995,0
  </curvetable>

Example 3. Fixed column format

The following example uses the same data but in a fixed column format. Each column lines up under the right-most character of the column heading. This example also contains a <column> element that provides an explicit ID value for the BA column.

  <curvetable pattern="PRF.HDSEL.CT18.%h">
    <column label="BA" id="PRF.HDSEL.CT18.BasalArea"/>
   Age          BA       bargr       GTVol       GMVol       NMVol
     0          18    0.331611   147.83184    92.58579 78.59373224
     3   18.994833 0.308920255  156.002284 97.70286773 82.93748993
     6 19.92159377 0.554832428  163.613659 102.4698054 86.98402257
     9 21.58609105 0.519188674 177.2839755 111.0314052 94.25174778
    12 23.14365707   0.4873855 190.0760783 119.0429874 101.0525771
    15 24.60581357 0.458894776 202.0845942  126.563816  107.436818
    18  25.9824979 0.433277143 213.3911374 133.6450053 113.4478602
    21 27.28232933 0.410164621 224.0664969 140.3308897 119.1233381
    24  28.5128232  0.38924709 234.1723954 146.6601256 124.4960662
    27 29.68056446 0.370261668 243.7629143 152.6665838 129.5947965
    30 30.79134947  0.35298432 252.8856582 158.3800786 134.4448375
    33 31.85030243  0.33722315 261.5827118 163.8269673 139.0685634
    36 32.86197188 0.322813024 269.8914316  169.030646 143.4858344
  </curvetable>
      

Example 4. Woodstock format

The next example shows data copied unchanged from a Woodstock yld file. This data may have come from a growth and yield model and arranged in to Woodstock format. The leftmost column again represents age, and as this matches the default assumption nothing additional needs to be specified. Woodstock format separates data in to columns using one or more space characters, and this is indicated with the split="\s+" attribute (one or more whitespace characters). The initial age value is 5, so the curves do not start at the origin. The forcezero="0" attribute will inject a vertice of (0,0) in to the start of each curve so that each curve will intercept the origin. The missing attribute specifies that data values of "-" will be considered to be missing, so the value for that row will be ignored. The pattern template includes the theme information as well as the yield curve column heading.

<curvetable split="\s+" forcezero="0" missing="-" pattern="?,?,5303000,?,?,?,?,GROW,EX,?,?,?,?,?,?:%h">
  _AGE   Ytpa     Yba    Yqmd  yAG  yBG   Ybole  Ytotal     Yce     Ydf     Yww 
  5       - 1.00000 0.70000  0.00000  0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 
  10       - 2.00000 1.30000  0.00000  0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 
  15       - 7.00000 3.00000  0.00000  0.00000 0.00000 0.00000 0.00000 0.00000 0.00000 
  20 122.500 26.0000 5.70000  5.60000  1.60000 3.40000 0.00000 0.00000 0.00000 0.00000 
  25 122.400 46.0000 7.60000 12.40000  3.40000 7.40000 0.00000 0.00000 0.00000 0.00000 
  30 122.300 69.0000 9.40000 23.50000  6.10000 14.6000 0.00000 0.00000 0.00000 0.00000 
  35 122.200 96.0000 11.1000 40.30000 10.10000 26.3000 0.00000 0.00000 0.00000 0.00000 
  40 122.200 125.000 12.7000 62.20000 15.10000 41.9000 7.33000 0.00000 0.00000 0.00000 
  45 119.800 148.000 15.0000 86.40000 20.50000 59.5000 13.1800 0.00000 0.00000 0.00000 
  50 111.200 163.000 16.4000 105.2000 24.60000 73.8000 15.5600 0.00000 0.00000 0.00000 
  55 100.300 170.000 17.6000 118.1000 27.40000 84.1000 19.0500 0.00000 0.00000 0.00000 
  60 88.1000 170.000 18.8000 124.3000 28.70000 89.6000 19.3700 0.00000 0.00000 0.00000 
  65 78.5000 170.000 19.9000 130.0000 29.90000 94.7000 21.9900 0.00000 0.00000 0.00000 
  70 71.0000 170.000 20.9000 135.3000 31.00000 99.4000 24.1500 0.00000 0.00000 0.00000 
  75 64.7000 170.000 21.9000 140.1000 32.10000 103.800 25.2300 0.00000 0.00000 0.00000 
  80 58.7000 170.000 23.0000 144.6000 33.00000 108.000 26.9900 0.00000 0.00000 0.00000 
  85 54.0000 169.000 24.0000 148.7000 33.90000 111.800 29.6800 0.00000 0.00000 0.00000 
  90 49.9000 169.000 24.9000 152.7000 34.70000 115.500 28.9500 0.00000 0.00000 0.00000 
  95 46.4000 169.000 25.9000 156.3000 35.50000 118.900 30.6400 0.00000 0.00000 0.00000 
  100 43.3000 169.000 26.8000 159.8000 36.20000 122.200 32.4400 0.00000 0.00000 0.00000 
  105 40.3000 169.000 27.7000 163.1000 36.90000 125.400 33.8900 0.00000 0.00000 0.00000 
  110 38.0000 169.000 28.6000 166.2000 37.50000 128.300 34.5400 0.00000 0.00000 0.00000 
  115 35.4000 169.000 29.6000 169.1000 38.20000 131.200 36.1200 0.00000 0.00000 0.00000 
</curvetable>
       

Example 5. FVS format

This example below uses output from the FVS growth and yield model. The age value is in column 1 (agecolumn="1", numbering starts at column zero), and since this table is in CSV format the columns are separated by commas (split=","). This data table lists multiple subsets of curve data, one for each unique StandID value. The pattern attribute includes a "%0c" token. This indicates that column 0 is a classifier and be used to subset distinct curve sets, and the resulting curve name will include the column 0 "StandID" at he position indicated in the pattern. The data table is read until the StandID value changes, the curves are processed and assigned unique curve id labels. The remaining part of the of the input data is processed in a similar way, breaking input rows in to curve sets at each change in the StandID value.

The pattern value is in a format that represents the model stratification values where '?' characters represent values that are inconsequential for yield stratification purposes (perhaps administrative categories). Curves may be retrieved from the library using the curveid function, but this type of curve naming scheme works well with the curvematch function.

<curvetable agecolumn="1" split="," forcezero="0" pattern="?,?,%0c,?,?,?,?,GROW,EX,?,?,?,?,?,?:%h">
  StandID,Age,Tpa,BA,SDI,CCF,TopHt,QMD,TCuFt,MCuFt,BdFt
  6340008,77,773,274,424,182,100,8.07,9305,6971,19912
  6340008,82,499,242,360,144,101,9.43,8528,6520,20451
  6340008,87,451,243,358,140,103,9.95,8712,6833,21867
  6340008,92,402,244,354,136,105,10.55,8846,7016,23175
  6340008,97,362,245,351,131,106,11.13,8995,7180,24497
  6340008,102,329,245,347,128,109,11.68,9135,7358,25587
  6340008,107,296,246,343,123,111,12.33,9295,7575,26971
  6340008,112,269,246,339,120,113,12.95,9446,7757,28506
  6340008,117,228,142,205,76,103,10.70,5262,4269,16084
  6340008,122,303,150,215,79,105,9.54,5610,4572,17419
  6340008,127,300,160,227,84,107,9.88,5986,4875,18869
  6340008,132,297,170,241,88,108,10.24,6379,5226,20563
  6340008,137,294,180,255,92,110,10.60,6826,5573,22275
  6340008,142,291,191,269,96,111,10.97,7263,5915,24034
  6340008,147,288,201,282,100,113,11.32,7714,6284,25846
  6340008,152,286,213,297,104,115,11.69,8224,6716,27872
  6340008,157,277,223,309,106,116,12.14,8642,7035,30145
  6340008,162,265,231,319,108,117,12.66,9019,7372,31568
  6340008,167,235,157,229,82,105,11.06,5858,4537,19469
  6340008,172,311,169,246,87,107,9.98,6308,5016,21850
  6340008,177,308,182,265,92,108,10.41,6818,5402,23665
  6340008,182,305,196,285,98,110,10.86,7378,5915,26831
  6340008,187,299,210,303,102,112,11.36,7960,6538,29081
  6340009,81,572,277,398,157,120,9.41,10645,8678,33863
  6340009,86,524,163,253,107,103,7.56,5848,4664,18013
  6340009,91,597,176,272,114,105,7.35,6271,5015,19882
  ... lines omitted for brevity
</curvetable>
      

Example 6. Row format

The next example shows row-base curves. Each row contains a single curve, and the column headings contain the age values. The agepattern attribute identifies the columns to use and extracts the age values. The pattern value is "%0c:%1c". Since this is a row format table the %h substitution symbol is not available. The curves will be named by composing of the contents of the first column (column position 0), a semicolon, and the contents of the second column (column position 1).

<curvetable agepattern="(\d+)" split="," pattern="%0c:%1c">
StandId,Type,0,5,10,15,20,25,30,35,40,45,50
41,Yield.BF,0,1,2,3,4,5,6,7,8,9,10
41,Yield.PJ,0,0,0,0,6,25,56,83,74,57,65
41,Yield.PW,0,0,0,0,0,0,2,9,12,13,17
41,Yield.PR,0,0,0,0,0,0,0,4,10,19,33
41,Habitat.Marten,0,0,0,0,0,0,0,0,0.01,0.04,0.10
41,Habitat.Ovenbird,0,0,0,0,0,0,0,0,0,0.01,0.03
</curvetable>
      

Example 7. External CSV format

In this example curves are read from an external cvs file that is in the same directory as the ForestModel xml file. Note that the file name 'regime.csv' is enclosed in single quotes. This string is evaluated as a Patchworks Query Language expression and may make use of query language functions and operators such as repeat variables or substitution with defined constants.

 <curvetable file="'regime.csv'" agepattern="(\d+)" split="," 
             pattern="%1c.Regime:%2c" missing="- 0" forcezero="0"/>

Example 8. Tigermoth format

In this example the curve data is being read from a Microsoft Excel spreadsheet. A TableSpec reference is used to identify the workbook and sheet name. The workbook name includes embedded space characters and so the entire name needs to be quoted. However, the file attribute that it is part of is already within quotes. The XML specification requires that we use &quot; entities to indicate that quote characters should be inserted in these locations within an already quoted string.

An optional parameter (skip=3) indicates that the Excel worksheet reader should skip over the first three rows of the worksheet, which are known to contain decorative header data. The column headings are on line 4, and data follows after that.

<curvetable file="'Excel &quot;LDR_Dec21_2201a - HRV Lock2.xlsb&quot; Croptype skip=3'"
            agepattern="(\d+)" split="," pattern="%1c.Yield:%2c" missing="- 0" forcezero="0"/>