Name

table — a table of data elements that can be used as a lookup table

Synopsis

Content Model


	    <table> = lookup table data

      

Attributes

NameTypeDefault
idA label that is used to identify the lookup table (required)REQUIRED
splitA string regular expression used for the field separator, or if not specified then fixed column fields will be read."," (split on commas)
missingThe token to represent a missing input value"" (empty cells have missing values)
replacemissingA token that will be used to replace missing valuesNone
fileThe name of the file that the table data will be read fromNone
selectAn expression that will be evaluated to select the rows that will be included from the specified file.true (select all records)

Description

This element specifies rows and columns of values that make up a lookup table. The values in the rows are separated by field separator characters, typically a comma. Use the split attribute to specify a different field splitting value.

The first row of the table contains column headings. The tablemap function can be used to lookup a value in one column, and return the value in the same row but from a different column.

Parents

These elements contain table: ForestModel.

Children

No other elements can occur in a table.

Attributes

id

A label used to identify this table. This attribute is required. Any label may be used, but it is an error to specify the same label twice. The label 'fragments' is prepopulated with a reference to the fragments table, and cannot be redefined.

split

A character used to split each line in to fields. The default is to split the data by commas (split=",").

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

A value that will be used to replace missing values.

file

A file name or TableSpec string that references the file that contains the lookup table data. The file attribute and embedded table 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.

select

A Patchworks Query Language expression that will limit the rows in the lookup table to only those that match the query. This only applies to external file (all embedded data is always included).

See Also

tablemap , tablelist

Examples

Example 1

In the following example an table has been added in CSV format. The table is given a label of 'Operability'. The split character is not specified and the default comma character is used.

The tablemap function can be used to retrieve values from one column that are matched to values in another column. The function tablemap('Operability','Type','SWD','Min') will operate on the 'Operability' table. It will search the 'Type' column for the 'SWD' value. If this value is found then the value in the same row from the 'Min' column will be returned.

  <table id="Operability">
Type,Min,Max
AWR,0,9
SWD,27,60
HWD A,12,61
HWD,12,42
min26,26,28
Native,60,61
  </table>
    

Example 2

In the next example a lookup table is loaded from an external file. A selection expression is provided to limit records to those where the Version column contains the value 'v2'.

  <table id="Costs" file="'../data/cost_lookup.dbf'" select="Version='v2'"/>

Example 3

In the next example the table data is loaded from a sheet within a Microsoft Excel workbook. The contents of the file attribute is a TableSpec specification that identifies the workbook and sheet name. The sheet 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.

  <table id="roading" file="'Excel Assumptions_v1.xlxs &quot;Road Costs&quot;'" />

Example 4

The following example shows the use of a defined constant, a repeat loop, and query language expression to calculate the id and file attributes. The advantage of this approach is that it extracts the key values to single locations allows rapid and reliable updating should changes be required.

   <-– define a constant to contain the file name -->
   <define field="loaderFile" constant="'../yield_202112/LDR_Dec21_2201a - HRV Lock2.xlsb'" />

   <-– Loop through a series of sheet names -->
   <repeat name="sheet" list="'Plunits,Rotation,Silviculture,Replanting,Transport'">
      <table id="getEnv('repeat.sheet')" missing="N/A" replacemissing=""
             file="'Excel &quot;'+loaderFile+'&quot; '+getEnv('repeat.sheet')+' skip=3'"/>
   </repeat>