Merge Veg-X documents

Merges two Veg-X documents while considering that some of their entities may be shared.

mergeVegX(
  x,
  y,
  allowMergePlots = FALSE,
  allowMergeOrganismIdentities = FALSE,
  verbose = TRUE
)

Arguments

x, y

The objects of class VegX to be merged.

allowMergePlots

If TRUE plots should be merged when sharing the same plotName and, if defined, plotUniqueIdentifier. If FALSE plots are never merged (i.e. the two VegX documents are considered as coming from different vegetation data sources).

allowMergeOrganismIdentities

If TRUE, allows organism identities sharing the same organismName to be merged. If FALSE organism identities are never merged (i.e. the two VegX documents are considered as coming from different vegetation data sources).

verbose

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

Value

An object of class VegX with the pooled data

Details

Some entities are attempted to be merged or are kept as separate entities depeding on their definition:

  • projects are merged when their element title has the same value.

  • plots are merged, if allowMergePlots = TRUE, when they have the same value for element plotName and, if defined, plotUniqueIdentifier are also equal.

  • plotObservations are merged when both their plotID and obsStartDate elements have the same value

  • organismIdentities are merged if they share the same organismName and allowMergeOrganismIdentities = TRUE because one can have the same name used in different data sets but referring to different concepts.

  • methods are merged when their element name has the same value.

  • strata are merged when their element stratumName has the same value and the corresponding method has the same name.

  • stratumObservations are merged when both their stratumID and plotObservationID elements have the same value.

  • aggregateOrganismObservations are merged when their plotObservationID and organismIdentityID (and stratumObservationID, if defined) have the same value

  • individualOrganisms are merged when both their plotID and individualOrganismLabel have the same value.

  • individualOrganismObservations are merged when both their plotObservationID and individualOrganismID have the same value.

  • surfaceTypes are merged when their element surfaceName has the same value and the corresponding method has the same name.

  • surfaceCoverObservations are merged when both their surfaceTypeID and plotObservationID elements have the same value

  • siteObservations are merged into the same element when their element plotObservationID has the same value, but particular measurements are always added as if they were distinct pieces of information.

Merging to these entities may cause interruption of the process if the two entities to be merged have different value for the same element. Other entities (e.g., attributes of a method) are always considered as distinct entities between the two data sets to be merged and hence are simply copied to the result.

See also

VegX

Examples


data(mokihinui)

# Create document 'x' with aggregate taxon observations
taxmapping = list(plotName = "Plot", obsStartDate = "PlotObsStartDate",
              taxonName = "NVSSpeciesName",
              stratumName = "Tier", cover = "Category")
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%"))
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")
x = addAggregateOrganismObservations(newVegX(), moki_tcv, taxmapping,
               methods = c(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.

# Create document 'y' with tree observations
treemapping = list(plotName = "Plot", subPlotName = "Subplot", obsStartDate = "PlotObsStartDate",
                   taxonName = "NVSSpeciesName", diameterMeasurement = "Diameter")
diamMeth = predefinedMeasurementMethod("DBH/cm")
y = addIndividualOrganismObservations(newVegX(), moki_dia, treemapping,
                   methods = c(diameterMeasurement = diamMeth))
#>  Measurement method 'DBH/cm' added for 'diameterMeasurement'.
#>  23 plot(s) parsed, 23 new added.
#>  18 plot observation(s) parsed, 18 new added.
#>  28 organism names(s) parsed, 28 new added.
#>  0 taxon concept(s) parsed, 0 new added.
#>  28 organism identitie(s) parsed, 28 new added.
#>  0 individual organism(s) parsed, 643 new added.
#>  643 record(s) parsed, 643 new individual organism observation(s) added.

# Merge 'x' and 'y' while keeping plots of the same name separate and
# organism identities that have the same name separated. This default behaviour
# is set assuming that 'x' and 'y' come from different data sources.
z1 = mergeVegX(x,y)
#>  Final number of party(ies): 0. Data pooled for 0 party(ies).
#>  Final number of literature citations: 2. Data pooled for 0 citation(s).
#>  Final number of methods: 3. Data pooled for 0 method(s).
#>  Final number of attributes: 9.
#>  Final number of strata: 7. Data pooled for 0 strata.
#>  Final number of surface types: 0. Data pooled for 0 surface types.
#>  Final number of organism names: 149. Data pooled for 27 organism name(s).
#>  Final number of taxon concepts: 0. Data pooled for 0 organism name(s).
#>  Final number of organism identities: 176. Data pooled for 0 organism identitie(s).
#>  Final number of projects: 0. Data pooled for 0 project(s).
#>  Final number of plots: 28. Data pooled for 0 plot(s).
#>  Final number of individual organisms: 643. Data pooled for 0 individual organism(s).
#>  Final number of plot observations: 23. Data pooled for 0 plot observation(s).
#>  Final number of stratum observations: 33. Data pooled for 0 stratum observation(s).
#>  Final number of individual organism observations: 643. Data pooled for 0 individual organism observation(s).
#>  Final number of aggregate organism observations: 582. Data pooled for 0 aggregate organism observation(s).
#>  Final number of site observations: 0. Data pooled for 0 site observation(s).
#>  Final number of community observations: 0. Data pooled for 0 community observation(s).
#>  Final number of surface cover observations: 0. Data pooled for 0 surface cover observation(s).
summary(z1)
#> ================================================================
#>                     Veg-X object (ver 2.0.0)                   
#> ----------------------------------------------------------------
#> 
#>    Projects: 0
#> 
#>    Plots: 28  [Parent plots: 10 Sub-plots: 18]
#> 
#>    Individual organisms: 643
#> 
#>    Organism names: 149
#> 
#>    Taxon concepts: 0
#> 
#>    Organism Identities: 176
#> 
#>    Vegetation strata: 7
#>       1. Tier 1 [1/Recce strata]
#>       2. Tier 2 [2/Recce strata]
#>       3. Tier 3 [3/Recce strata]
#>       4. Tier 4 [4/Recce strata]
#>       5. Tier 5 [5/Recce strata]
#>       6. Tier 6 [6/Recce strata]
#>       7. Tier 7 [7/Recce strata]
#> 
#>    Surface types: 0
#> 
#>    Parties: 0
#> 
#>    Literature citations: 2
#> 
#>    Methods: 3
#>       1. Recce cover scale [plant cover / 7 ordinal atts.]
#>       2. Recce strata [stratum mixed / 1 quantitative atts.]
#>       3. DBH/cm [stem diameter / 1 quantitative atts.]
#> 
#>    Plot observations: 23  [in parent plots: 5 in sub-plots: 18]
#> 
#>    Individual organism observations: 643
#> 
#>    Aggregated organism observations: 582
#> 
#>    Stratum observations: 33
#> 
#>    Community observations: 0
#> 
#>    Site observations: 0
#> 
#>    Surface cover observations: 0
#> 
#> ================================================================

# Merge 'x' and 'y' while allowing plots of the same name to be merged
# and organism identities that have the same name to be merged. This configuration
# should be used when merging two VegX objects that come from the same data source 
# (i.e. Mokihinui data)
z2 = mergeVegX(x,y, allowMergePlots = TRUE,
               allowMergeOrganismIdentities = TRUE)
#>  Final number of party(ies): 0. Data pooled for 0 party(ies).
#>  Final number of literature citations: 2. Data pooled for 0 citation(s).
#>  Final number of methods: 3. Data pooled for 0 method(s).
#>  Final number of attributes: 9.
#>  Final number of strata: 7. Data pooled for 0 strata.
#>  Final number of surface types: 0. Data pooled for 0 surface types.
#>  Final number of organism names: 149. Data pooled for 27 organism name(s).
#>  Final number of taxon concepts: 0. Data pooled for 0 organism name(s).
#>  Final number of organism identities: 149. Data pooled for 27 organism identitie(s).
#>  Final number of projects: 0. Data pooled for 0 project(s).
#>  Final number of plots: 23. Data pooled for 5 plot(s).
#>  Final number of individual organisms: 643. Data pooled for 0 individual organism(s).
#>  Final number of plot observations: 23. Data pooled for 0 plot observation(s).
#>  Final number of stratum observations: 33. Data pooled for 0 stratum observation(s).
#>  Final number of individual organism observations: 643. Data pooled for 0 individual organism observation(s).
#>  Final number of aggregate organism observations: 582. Data pooled for 0 aggregate organism observation(s).
#>  Final number of site observations: 0. Data pooled for 0 site observation(s).
#>  Final number of community observations: 0. Data pooled for 0 community observation(s).
#>  Final number of surface cover observations: 0. Data pooled for 0 surface cover observation(s).
summary(z2)
#> ================================================================
#>                     Veg-X object (ver 2.0.0)                   
#> ----------------------------------------------------------------
#> 
#>    Projects: 0
#> 
#>    Plots: 23  [Parent plots: 5 Sub-plots: 18]
#> 
#>    Individual organisms: 643
#> 
#>    Organism names: 149
#> 
#>    Taxon concepts: 0
#> 
#>    Organism Identities: 149
#> 
#>    Vegetation strata: 7
#>       1. Tier 1 [1/Recce strata]
#>       2. Tier 2 [2/Recce strata]
#>       3. Tier 3 [3/Recce strata]
#>       4. Tier 4 [4/Recce strata]
#>       5. Tier 5 [5/Recce strata]
#>       6. Tier 6 [6/Recce strata]
#>       7. Tier 7 [7/Recce strata]
#> 
#>    Surface types: 0
#> 
#>    Parties: 0
#> 
#>    Literature citations: 2
#> 
#>    Methods: 3
#>       1. Recce cover scale [plant cover / 7 ordinal atts.]
#>       2. Recce strata [stratum mixed / 1 quantitative atts.]
#>       3. DBH/cm [stem diameter / 1 quantitative atts.]
#> 
#>    Plot observations: 23  [in parent plots: 5 in sub-plots: 18]
#> 
#>    Individual organism observations: 643
#> 
#>    Aggregated organism observations: 582
#> 
#>    Stratum observations: 33
#> 
#>    Community observations: 0
#> 
#>    Site observations: 0
#> 
#>    Surface cover observations: 0
#> 
#> ================================================================