This function defines the translation table used as input to TranslateStoxBiotic and similar functions to translate values of one or more columns to new values given by a table or read from a CSV file.
DefineTranslation(
processData,
UseProcessData = FALSE,
DefinitionMethod = c("ResourceFile", "Table"),
FileName = character(),
VariableName = character(),
Conditional = FALSE,
ConditionalVariableNames = character(),
TranslationTable = data.table::data.table(),
ValueColumn = character(),
NewValueColumn = character(),
ConditionalValueColumns = character()
)The current data produced by a previous instance of the function.
Logical: If TRUE use the existing function output in the process.
Character: A string naming the method to use, one of "ResourceFile", for reading the table from the file given by FileName; and "Table", for defining the TranslationTable directly as an input.
The csv file holding a table with the TranslationTable. Required columns are given by ValueColumn and NewValueColumn, and, in the case that Conditional == TRUE, ConditionalValueColumns.
The name of the variable to translate. This will be the name of the first column of the TranslationTable when generated from the StoX GUI.
Logical: If TRUE condition the translation on values of other variables.
The names of the variables to condition the translation on. Must be given if Conditional == TRUE. This will be the name(s) of the third column and onwards of the TranslationTable when generated from the StoX GUI.
A table holding the values to translate FROM in the first column, the values to translate TO (column NewValue), and zero or more columns named by the conditional variables specified in ConditionalVariableNames giving the values of these variables at which to perform the translation. Use NA to translate missing values (shown as "-" in Preview in the StoX GUI, and usually as empty cell in excel). Values in the TranslationTable can be given either as single values or as expressions of functions of the variable specified by the column name. See details of DefineTranslation.
The name of the columns of FileName representing the current values and the values to translate to, respectively.
The names of the columns of FileName representing the conditional values.
A Translation object.
The columns of the TranslationTable can be given in one of two ways: (1) A single value or a string to be evaluated and matched using the "%in%" operator, such as "HER" or "c(\"HER\", \"CLU\")"; or (2) a string expressing a function of the variable given by the column name, such as "function(IndividualTotalLength) IndividualTotalLength > 10".
Specifying NewValue as a function can be used to transform numeric values, e.g. "function(IndividualTotalLength) IndividualTotalLength * 1.1" to compensate for different length measurement. This can be useful for length that are not total length, in which case TranslateBiotic can be used to translate the lengthmeasurement (NMDBiotic) or LengthType (ICESBiotic) to the accepted "E" or "1", respectively. For BioticData read from ICESBiotic XML files the the LengthType specifies the type of length measurement. These values are not translated using the vocabulary from the XML file, so that total length is represented as "AC_LengthMeasurementType_1" instead of the code "1". For these data the translation can be either to "AC_LengthMeasurementType_1" or to "1".
Similar to transforming IndividualTotalLength, IndividualRoundWeight can also be transformed if the individualproducttype is not 1 for NMDBiotic XML files.
When the TranslationnTable is given in the StoX GUI the strings need not be escaped ((1) HER or c("HER", "CLU"); or (2) function(IndividualTotalLength) IndividualTotalLength > 10).
As an example, if there are three columns in the TranslationTable named "IndividualAge", "NewValue" and "IndividualSex" (as specified by ConditionalVariableNames), with values 3, 4 and "F" in the first row, female fish at age 3 are translated to age 4.
As another example, to set all individuals with missing IndividualMaturity as "Adult" if longer than 10 cm, use function(IndividualMaturity) is.na(IndividualMaturity) in the first column named "IndividualMaturity", Adult in the "NewValue" column, and function(IndividualTotalLength) IndividualTotalLength > 10 in the third (conditional) column named "IndividualTotalLength". To translate all IndividualMaturity to a e.g. NA, use function(IndividualMaturity) TRUE in the "IndividualMaturity" column and NA in the "NewValue" column.
TranslateStoxBiotic, TranslateStoxAcoustic, TranslateBiotic, TranslateAcoustic, TranslateStoxLanding, TranslateLanding, TranslateICESBiotic and TranslateICESAcoustic for applying the translation.