Add stratum observation records

Adds stratum observation records to a VegX object from a data table where rows are stratum observations.

addStratumObservations(
  target,
  x,
  mapping,
  methods,
  stratumDefinition,
  date.format = "%Y-%m-%d",
  missing.values = c(NA, ""),
  verbose = TRUE
)

Arguments

target

The initial object of class VegX to be modified

x

A data frame where each row corresponds to one stratum observation. Columns can be varied.

mapping

A named list whose elements are strings that correspond to column names in x. Names of the list should be:

  • plotName - A string identifying the vegetation plot within the data set (required).

  • subPlotName - A string identifying a subplot of the plot given by plotName (optional).

  • obsStartDate - Plot observation start date (required; see date.format).

  • stratumName - A string used to identify a stratum (see stratumDefinition; required).

  • lowerLimitMeasurement, upperLimitMeasurement- Lower and upper limits, respectively, of strata (e.g. height limits in m).

  • ... - User defined names used to map stratum measurements, such as percent cover (optional).

methods

A list measurement methods for lowerLimitMeasurement, upperLimitMeasurement and other stratum measurements (each one is object of class VegXMethodDefinition). Alternatively, methods can be specified using strings if predefined methods exist (see predefinedMeasurementMethod).

stratumDefinition

An object of class VegXStrataDefinition indicating the definition of strata.

date.format

A character string specifying the input format of dates (see as.Date).

missing.values

A character vector of values that should be considered as missing observations/measurements.

verbose

A boolean flag to indicate console output of the data integration process.

Value

The modified object of class VegX.

Details

Missing value policy:

  • Missing plotName, obsStartDate or stratumName values are interpreted as if the previous non-missing value has to be used to define plot observation.

  • Missing subPlotName values are interpreted in that observation refers to the parent plotName.

  • Missing measurements are simply not added to the Veg-X document.

References

Wiser SK, Spencer N, De Caceres M, Kleikamp M, Boyle B & Peet RK (2011). Veg-X - an exchange standard for plot-based vegetation data

Examples

# Load source data
data(mokihinui)

# Define mapping
mapping = list(plotName = "Plot", obsStartDate = "PlotObsStartDate", 
               stratumName = "Tier",
               lowerLimitMeasurement = "TierLower", upperLimitMeasurement = "TierUpper",
               cover = "CoverClass")


# Define cover scale
coverscale = defineOrdinalScaleMethod(name = "Recce cover scale",
                   description = "Recce recording method by Hurst/Allen",
                   subject = "plant cover",
                   citation = "Hurst, JM and Allen, RB. (2007) 
                     The Recce method for describing New Zealand vegetation – 
                     Field protocols. Landcare Research, Lincoln.",
                   codes = c("P","1","2","3", "4", "5", "6"),
                   quantifiableCodes = c("1","2","3", "4", "5", "6"),
                   breaks = c(0, 1, 5, 25, 50, 75, 100),
                   midPoints = c(0.05, 0.5, 15, 37.5, 62.5, 87.5),
                   definitions = c("Presence", "<1%", "1-5%","6-25%", "26-50%", 
                                   "51-75%", "76-100%"))


# Define strata
strataDef = defineMixedStrata(name = "Recce strata",
                   description = "Standard Recce stratum definition",
                   citation = "Hurst, JM and Allen, RB. (2007) 
                       The Recce method for describing New Zealand vegetation – 
                       Field protocols. Landcare Research, Lincoln.",
                   heightStrataBreaks = c(0, 0.3,2.0,5, 12, 25, 50),
                   heightStrataNames = paste0("Tier ",1:6),
                   categoryStrataNames = "Tier 7",
                   categoryStrataDefinition = "Epiphytes")

# Create new Veg-X document with stratum observations
x = addStratumObservations(newVegX(), moki_str, mapping = mapping,
                        methods = list(lowerLimitMeasurement = "Stratum height/m",
                                       upperLimitMeasurement = "Stratum height/m",
                                       cover=coverscale),
                        stratumDefinition = strataDef)
#>  1 stratum measurement variables found.
#>  Measurement method 'Stratum height/m' added for 'lowerLimitMeasurement'.
#>  Measurement method 'Stratum height/m' for 'upperLimitMeasurement' already included.
#>  Measurement method 'Recce cover scale' added for 'cover'.
#>  Stratum definition method 'Recce strata' added.
#>  7 new stratum definitions added.
#>  5 plot(s) parsed, 5 new added.
#>  5 plot observation(s) parsed, 5 new added.
#>  35 record(s) parsed, 35 new stratum observation(s) added.
#>  7 measurement(s) with missing value(s) not added.

# Examine results
head(showElementTable(x, "stratumObservation"))
#>   plotName obsStartDate stratumName lowerLimit_method lowerLimit_value
#> 1   LGM38h   2011-02-20      Tier 1  Stratum height/m             25.0
#> 2   LGM38h   2011-02-20      Tier 2  Stratum height/m             12.0
#> 3   LGM38h   2011-02-20      Tier 3  Stratum height/m              5.0
#> 4   LGM38h   2011-02-20      Tier 4  Stratum height/m              2.0
#> 5   LGM38h   2011-02-20      Tier 5  Stratum height/m              0.3
#> 6   LGM45h   2011-02-11      Tier 1  Stratum height/m             25.0
#>   upperLimit_method upperLimit_value      str_1_method str_1_value
#> 1  Stratum height/m               50 Recce cover scale           3
#> 2  Stratum height/m               25 Recce cover scale           3
#> 3  Stratum height/m               12 Recce cover scale           4
#> 4  Stratum height/m                5 Recce cover scale           5
#> 5  Stratum height/m                2 Recce cover scale           4
#> 6  Stratum height/m               50              <NA>        <NA>