Add aggregate organism observation records

Adds aggregate organism observation records to a VegX object from a data frame where rows are observation records.

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

Arguments

target

The initial object of class VegX to be modified

x

A data frame where each row corresponds to one aggregate organism 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).
organismName - The string of a name, defined by the dataset author, and which does not follow nomenclatural codes.
taxonName - The string of a taxon name (not necessarily including authority).
stratumName - A string used to identify a stratum (see stratumDefinition; optional).
heightMeasurement - Optional height at which the aggregated observation was made, e.g. in meters. It applies to all aggregate measurements (optional).
... - User defined names used to map aggregate organism measurements, such as percent cover (optional).

methods

A list with measurement methods for heightMeasurement and all the user defined aggregate organism measurements (each method is an 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

The mapping should include either organismName or taxonName, but can include both of them if the source data set contains both taxon names and others that are not taxa. Missing value policy:

Missing plotName and obsStartDate values are interpreted as if the previous non-missing value has to be used to define aggregate organism observation.
Missing subPlotName values are interpreted in that observation refers to the parent plotName.
When stratumName values are missing the aggregate organism observation is not assigned to any stratum.
When both organismName and taxonName are missing (i.e. missing organism identity) the function generates an error.
Missing aggregate organism measurements are 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",
               taxonName = "NVSSpeciesName",
               stratumName = "Tier", cover = "Category")

# Define abundance 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 aggregate organism observations
x = addAggregateOrganismObservations(newVegX(), moki_tcv,
                 mapping = mapping,
                 methods = list(cover=coverscale),
                 stratumDefinition = strataDef)
#>  1 additional aggregate organism measurements found: Category.
#>  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.
#>  148 organism names(s) parsed, 148 new added.
#>  148 organism identitie(s) parsed, 148 new added.
#>  33 stratum observation(s) parsed, 33 new added.
#>  582 record(s) parsed, 582 new aggregate organism observation(s) added.

# Inspect the result
head(showElementTable(x, "aggregateOrganismObservation"))
#>   plotName obsStartDate  organismIdentityName stratumName      agg_1_method
#> 1   LGM38h   2011-02-20 Dacrydium cupressinum      Tier 1 Recce cover scale
#> 2   LGM38h   2011-02-20 Dacrydium cupressinum      Tier 2 Recce cover scale
#> 3   LGM38h   2011-02-20 Dacrydium cupressinum      Tier 6 Recce cover scale
#> 4   LGM38h   2011-02-20   Weinmannia racemosa      Tier 2 Recce cover scale
#> 5   LGM38h   2011-02-20   Weinmannia racemosa      Tier 3 Recce cover scale
#> 6   LGM38h   2011-02-20   Weinmannia racemosa      Tier 4 Recce cover scale
#>   agg_1_value
#> 1           3
#> 2           3
#> 3           1
#> 4           3
#> 5           4
#> 6           3


# Example with individual counts
data(mtfyffe)
mapping = list(plotName = "Plot", subPlotName = "Subplot", obsStartDate = "PlotObsStartDate",
               taxonName = "NVSSpeciesName", stratumName = "Tier", counts = "Value")
strataDef = defineHeightStrata(name = "Standard seedling/sapling strata",
               description = "Seedling/sapling stratum definition",
               heightBreaks = c(0, 15, 45, 75, 105, 135, 200),
               strataNames = as.character(1:6),
               strataDefinitions = c("0-15 cm", "16-45 cm", "46-75 cm", 
                                     "76-105 cm", "106-135 cm", "> 135 cm"))
x = addAggregateOrganismObservations(newVegX(), mtfyffe_counts, mapping,
               methods = list(counts="Individual plant counts"),
               stratumDefinition = strataDef)
#>  1 additional aggregate organism measurements found: Value.
#>  Measurement method 'Individual plant counts' added for 'counts'.
#>  Stratum definition method 'Standard seedling/sapling strata' added.
#>  6 new stratum definitions added.
#>  131 plot(s) parsed, 131 new added.
#>  194 plot observation(s) parsed, 194 new added.
#>  55 organism names(s) parsed, 55 new added.
#>  55 organism identitie(s) parsed, 55 new added.
#>  170 stratum observation(s) parsed, 170 new added.
#>  533 record(s) parsed, 533 new aggregate organism observation(s) added.
head(showElementTable(x, "aggregateOrganismObservation"))
#>   plotName obsStartDate     organismIdentityName            agg_1_method
#> 1   12 1_E   1980-02-07   Pseudowintera colorata Individual plant counts
#> 2   12 1_E   1980-02-07          Rubus cissoides Individual plant counts
#> 3   12 1_M   1980-02-07 Pseudopanax crassifolius Individual plant counts
#> 4   12 1_P   1980-02-07 Pseudopanax crassifolius Individual plant counts
#> 5   12 1_P   1980-02-07    Neomyrtus pedunculata Individual plant counts
#> 6   14 2_J   1980-02-07      Coprosma parviflora Individual plant counts
#>   agg_1_value stratumName
#> 1           1        <NA>
#> 2           1        <NA>
#> 3           1        <NA>
#> 4           1        <NA>
#> 5           1        <NA>
#> 6           4        <NA>

# Example with frequency in transects
data(takitimu)
mapping = list(plotName = "Plot", subPlotName = "Subplot", obsStartDate = "PlotObsStartDate",
               taxonName = "NVSSpeciesName", freq = "Value")
x = addAggregateOrganismObservations(newVegX(), taki_freq, mapping,
               methods = list(freq="Plant frequency/%"))
#>  1 additional aggregate organism measurements found: Value.
#>  Measurement method 'Plant frequency/%' added for 'freq'.
#>  5 plot(s) parsed, 5 new added.
#>  5 plot observation(s) parsed, 5 new added.
#>  38 organism names(s) parsed, 38 new added.
#>  38 organism identitie(s) parsed, 38 new added.
#>  94 record(s) parsed, 94 new aggregate organism observation(s) added.
head(showElementTable(x, "aggregateOrganismObservation"))
#>          plotName obsStartDate   organismIdentityName      agg_1_method
#> 1 T2 2 (T2 2_TRA)   1968-02-07           Moss species Plant frequency/%
#> 2 T2 2 (T2 2_TRA)   1968-02-07   Schoenus pauciflorus Plant frequency/%
#> 3 R3 1 (R3 1_TRA)   1968-02-07    Helichrysum species Plant frequency/%
#> 4 T2 2 (T2 2_TRA)   1968-02-07       Coprosma species Plant frequency/%
#> 5 T2 2 (T2 2_TRA)   1968-02-07        Senecio species Plant frequency/%
#> 6 T1 2 (T1 2_TRA)   1968-02-07 Dracophyllum uniflorum Plant frequency/%
#>   agg_1_value
#> 1          38
#> 2           9
#> 3           2
#> 4          34
#> 5          11
#> 6           2

Arguments

Value

Details

References

See also

Examples