Add surface cover observation records

Adds surface cover observation records to a VegX object from a data frame where rows are cover observations.

addSurfaceCoverObservations(
  target,
  x,
  mapping,
  coverMethod,
  surfaceTypeDefinition,
  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 surface cover observation (e.g. bare rock percent cover). 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).
surfaceName - The string of the name of a surface type (see surfaceTypeDefinition; required).
coverMeasurement - Surface cover values (required).

coverMethod

A method definition for surface cover measurements (an object of class VegXMethodDefinition). Alternatively, the method can be specified using a string if a predefined method exists (see predefinedMeasurementMethod).

surfaceTypeDefinition

An object of class VegXSurfaceTypeDefinition indicating the definition of surface types.

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

Named elements in mapping other than those used by this function will be ignored. Missing value policy:

Missing plotName, obsStartDate or surfaceName 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 values of coverMeasurement 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(mtfyffe)

# Examine surface cover data
head(mtfyffe_groundcover)
#>     PlotGroundCoverID Plot Subplot                  Project PlotGroundCover
#> 14               6157  6 4      NA FYFFE, MOUNT FOREST 1980      Vegetation
#> 17               4176 17 3      NA FYFFE, MOUNT FOREST 1980      Vegetation
#> 21               1353 14 2      NA FYFFE, MOUNT FOREST 1980      Vegetation
#> 32              12252 12 1      NA FYFFE, MOUNT FOREST 1980      Vegetation
#> 90              70957  6 4      NA FYFFE, MOUNT FOREST 1980            Moss
#> 101             84522 14 2      NA FYFFE, MOUNT FOREST 1980            Moss
#>                      TechniqueName           MeasureName Value ParentPlotID
#> 14  Standard Ground Cover Estimate Ground Cover Category    20          217
#> 17  Standard Ground Cover Estimate Ground Cover Category    20          229
#> 21  Standard Ground Cover Estimate Ground Cover Category    20          226
#> 32  Standard Ground Cover Estimate Ground Cover Category    20          221
#> 90  Standard Ground Cover Estimate Ground Cover Category    20          217
#> 101 Standard Ground Cover Estimate Ground Cover Category    20          226
#>     ParentPlotObsID PlotObsID ProjectID PlotObsStartDate
#> 14            52241     52241       867       1980-02-07
#> 17            52221     52221       867       1980-02-07
#> 21            52261     52261       867       1980-02-07
#> 32            52256     52256       867       1980-02-07
#> 90            52241     52241       867       1980-02-07
#> 101           52261     52261       867       1980-02-07

# Define mapping
mapping = list(plotName = "Plot", obsStartDate = "PlotObsStartDate",
               surfaceName = "PlotGroundCover", coverMeasurement = "Value")


# Get cover measurement method from predefined list
coverMethod = predefinedMeasurementMethod("Surface cover/%")

# Define surface types from the data
unique(mtfyffe_groundcover$PlotGroundCover)
#> [1] "Vegetation"   "Moss"         "Litter"       "Exposed Soil" "Rock"        
surfaceTypes = defineSurfaceTypes(name = "Default surface types",
                  description = "Five surface categories",
                  surfaceNames = c("Vegetation", "Moss", "Litter", "Exposed Soil", "Rock"))

# Create new Veg-X document with surface cover observations
x = addSurfaceCoverObservations(newVegX(), mtfyffe_groundcover, mapping,
                                coverMethod, surfaceTypes)
#>  Measurement method 'Surface cover/%' added for 'coverMeasurement'.
#>  Surface type definition method 'Default surface types' added.
#>  5 new surface type definitions added.
#>  4 plot(s) parsed, 4 new added.
#>  8 plot observation(s) parsed, 8 new added.
#>  40 record(s) parsed, 40 new surface cover observation(s) added.

# Examine results
head(showElementTable(x, "surfaceCoverObservation"))
#>   plotName obsStartDate surfaceName    cover_method cover_value
#> 1      6 4   1980-02-07  Vegetation Surface cover/%          20
#> 2     17 3   1980-02-07  Vegetation Surface cover/%          20
#> 3     14 2   1980-02-07  Vegetation Surface cover/%          20
#> 4     12 1   1980-02-07  Vegetation Surface cover/%          20
#> 5      6 4   1980-02-07        Moss Surface cover/%          20
#> 6     14 2   1980-02-07        Moss Surface cover/%          20


# Another example with different surface types
data(takitimu)
head(taki_groundcover)
#>    PlotGroundCoverID            Plot Subplot                      Project
#> 26            396242 R3 1 (R3 1_TRA)      NA TAKITIMU GRASSLAND 1968-1969
#> 27            396243 R3 1 (R3 1_TRA)      NA TAKITIMU GRASSLAND 1968-1969
#> 28            396244 R3 1 (R3 1_TRA)      NA TAKITIMU GRASSLAND 1968-1969
#> 31            396210 R1 1 (R1 1_TRA)      NA TAKITIMU GRASSLAND 1968-1969
#> 32            396211 R1 1 (R1 1_TRA)      NA TAKITIMU GRASSLAND 1968-1969
#> 33            396212 R1 1 (R1 1_TRA)      NA TAKITIMU GRASSLAND 1968-1969
#>     PlotGroundCover                  TechniqueName           MeasureName Value
#> 26           Litter Standard Ground Cover Estimate Ground Cover Category    25
#> 27             Rock Standard Ground Cover Estimate Ground Cover Category    25
#> 28       Vegetation Standard Ground Cover Estimate Ground Cover Category    25
#> 31 Erosion Pavement Standard Ground Cover Estimate Ground Cover Category    25
#> 32           Litter Standard Ground Cover Estimate Ground Cover Category    25
#> 33             Rock Standard Ground Cover Estimate Ground Cover Category    25
#>    ParentPlotID ParentPlotObsID PlotObsID ProjectID PlotObsStartDate
#> 26       781860         1153882   1153882       500       1968-02-07
#> 27       781860         1153882   1153882       500       1968-02-07
#> 28       781860         1153882   1153882       500       1968-02-07
#> 31       781853         1153875   1153875       500       1968-02-07
#> 32       781853         1153875   1153875       500       1968-02-07
#> 33       781853         1153875   1153875       500       1968-02-07

unique(taki_groundcover$PlotGroundCover)
#> [1] "Litter"           "Rock"             "Vegetation"       "Erosion Pavement"
#> [5] "Soil"            
surfaceTypes = defineSurfaceTypes(name = "Default surface types",
                  description = "Five surface categories",
                  surfaceNames = c("Vegetation", "Soil", "Erosion Pavement", "Litter","Rock"))

x = addSurfaceCoverObservations(newVegX(), taki_groundcover, mapping,
                                coverMethod, surfaceTypes)
#>  Measurement method 'Surface cover/%' added for 'coverMeasurement'.
#>  Surface type definition method 'Default surface types' added.
#>  5 new surface type definitions added.
#>  5 plot(s) parsed, 5 new added.
#>  5 plot observation(s) parsed, 5 new added.
#>  17 record(s) parsed, 17 new surface cover observation(s) added.

head(showElementTable(x, "surfaceCoverObservation"))
#>          plotName obsStartDate      surfaceName    cover_method cover_value
#> 1 R3 1 (R3 1_TRA)   1968-02-07           Litter Surface cover/%          25
#> 2 R3 1 (R3 1_TRA)   1968-02-07             Rock Surface cover/%          25
#> 3 R3 1 (R3 1_TRA)   1968-02-07       Vegetation Surface cover/%          25
#> 4 R1 1 (R1 1_TRA)   1968-02-07 Erosion Pavement Surface cover/%          25
#> 5 R1 1 (R1 1_TRA)   1968-02-07           Litter Surface cover/%          25
#> 6 R1 1 (R1 1_TRA)   1968-02-07             Rock Surface cover/%          25

Arguments

Value

Details

References

See also

Examples