compareLayers: Compare layers to each other

In MagicForrest/DGVMTools: DGVM Processing, Analysis and Plotting Tools

Compare layers to each other

Description

Compare two layers (each from a Field) to calculated various statistic metric and also the error (at every spatial/temporal locality) which is returned as a Comparison object. Usually this only acts on a single layer from each Field, but see the special case for "relative abundance" in details below.

Usage

compareLayers(
  field1,
  field2 = field1,
  layers1,
  layers2 = layers1,
  do.seasonality = FALSE,
  keepall1 = FALSE,
  keepall2 = FALSE,
  override.quantity = FALSE,
  verbose = FALSE,
  match.NAs = FALSE,
  show.stats = TRUE,
  area = TRUE,
  custom.metrics = list(),
  tolerance = NULL
)

Arguments

field1	A Field from which to get the first Layer for comparison. For the normalised metrics, this is the *modelled* values.
field2	A Field from which to get the second Layer for comparison. For the normalised metrics, this is the *observed* values.
layers1	The name of the Layer to be compared from field1 (character string). In general this should only be a *single* Layer, only in the special case of a "relative abundance" style comparison should this be multiple layers.
layers2	The name of the Layer to be compared from field2 (character string). If not defined taken to the be the same as layers1. In general this should only be a *single* Layer, only in the special case of a "relative abundance" style comparison should this be multiple layers.
do.seasonality	Logical, if TRUE use monthly values to calculate the seasonal concentration and phase, and then return NME/NSME of the concentration and MPD (mean phase difference) on the phase.
keepall1	Logical, if TRUE keep all data points in layers1 even if there is not corresponding data in layers2
keepall2	Logical, if TRUE keep all data points in layers2 even if there is not corresponding data in layers2
override.quantity	Logical, if TRUE ignore situation where field1 and field2 have non-identical Quantities and use the Quantity from field1 for the returned Comparison
verbose	Logical, if TRUE print some informative output
match.NAs	Logical, if TRUE copy NAs from one layer to the other. This is mostly to make sure that when you later plot the data in the final Comparison side-by-side, that the both have 'no data' (typically grey areas) plotted on both maps.
show.stats	Logical, if TRUE print the summary statistics
area	Logical, if TRUE (default) weight the comparison metrics by gridcell area (not yet implemented for seasonal, proportions or categorical comparisons)
custom.metrics	A named list of functions (defined by the user) to calculate additional custom metrics. The functions must take a data.table and two character vectors of layer names to be compared (in order in the case of multi-layer comparisons). Spatial-temporal-annual column names of Lon, Lat, Year, Month and Day can be assumed in the data.table. The name of the item in the list is used as the metric name.
tolerance	Numeric, passed to copyLayers. Defines how close the longitudes and latitudes of the gridcells in field1 and field2 need to be to the coordinates in order to get a match. Can be a single numeric (for the same tolerance) or a vector of two numerics (for lon and lat separately). Default is no rounding (value is NULL) and so is fine for most regular spaced grids. However, setting this can be useful to force matching of coordinates with many decimal places which may have lost a small amount of precision and so don't match exactly.

Value

A Comparison object, which includes points only where *both* input Field object have data.

The returned Comparison object has the same dimensions as the input Field objects (if they don't have the same dimensions as each other the code will fail). Depending on these dimensions, the Comparison can be plotted using plotSpatialComparison (to give the absolute difference, original values side-by-side and percentage difference, also the NME spatially - to be implemented) or plotTemporalComparison (again, absolute difference, percentage difference or original values). The stats slot (which contains list) holds information such as RSME, NME, Nash-Sutcliffe Model Efficiency, etc. between the datasets in the case of a continuous data. In the case of comparing categorical data (ie Layers which hold factors) it contains Cohen's Kappa.

There are two further special cases. In the case of monthly data, one can instead compare the seasonal cycles (enable with the "do.seasonality argument). In this case the metrics reported are the Mean Phase Difference and the NME calculation is done on seasonal concentration (derived from the monthly values) instead of each data point.

The second special case allows comparison of the "relative abundance" of multiple layers via the Manhattan Metric or the Square Chord Difference. In this case you can specify multiple layers (same number from each Field) and for each Field the provided layers should sum to 1.0 (this is not checked by DGVMTools so please check this yourself).

For definitions, details and applicability of metrics such as Normalised Mean Error, Manhattan Metric, Mean Phase Difference, etc. please see:

Kelley, D. I., Prentice, I. C., Harrison, S. P., Wang, H., Simard, M., Fisher, J. B., and Willis, K. O.: A comprehensive benchmarking system for evaluating global vegetation models, Biogeosciences, 10, 3313–3340, https://doi.org/10.5194/bg-10-3313-2013, 2013.

A Comparison object

Author(s)

Matthew Forrest [e-mail]

See Also

plotSpatialComparison, plotTemporalComparison

Examples

#' 

 
##### Continuous (single-layer) comparison

# Load Saatchi data and LPJ-GUESS data over Africa

africa.dir <- system.file("extdata", "LPJ-GUESS_Runs", "CentralAfrica", package = "DGVMTools")
africa.Source <- defineSource(name = "LPJ-GUESS", dir = africa.dir,  format = GUESS)
model.cmass <- getField(source = africa.Source, quant = "cmass", year.aggregate.method="mean")

Saatchi.dir <- system.file("extdata", "NetCDF", "Saatchi2011", "HD", package = "DGVMTools")
Saatchi.Source <- defineSource(name = "Saatchi Biomass", dir = Saatchi.dir,  format = NetCDF)
Saatchi.cmass <- getField(source = Saatchi.Source , quant = "vegC_std") #' 

## Calculate veg C of trees in model, compare layers, and print the statistics 
model.cmass <- layerOp(model.cmass, "+", ".Tree", "Tree")
vegC.comp <- compareLayers(field1 = model.cmass, 
                           field2 = Saatchi.cmass, 
                           layers1 = "Tree", 
                           layers2 = "vegC_std")
print(vegC.comp@stats)

# plot maps with plotSpatialComparison
print(plotSpatialComparison(vegC.comp)) 
print(plotSpatialComparison(vegC.comp, type = "values"))

##### Categorical (single-layer) comparison
# classification is by Smith et al 2014
# Load Haxeltine and Prentice PNV biomes data and calculate LPJ-GUESS biomes over Europe

europe.dir <- system.file("extdata", "LPJ-GUESS_Runs", "CentralEurope", package = "DGVMTools")
europe.Source <- defineSource(name = "LPJ-GUESS", dir = europe.dir,  format = GUESS)
model.biomes <- getScheme(source = europe.Source, 
                          scheme = Smith2014BiomeScheme, 
                          year.aggregate.method="mean")

PNV.dir <- system.file("extdata", "NetCDF", "HandP_PNV", "HD", package = "DGVMTools")
PNV.Source <- defineSource(name = "H and P PNV", dir = PNV.dir,  format = NetCDF)
PNV.biomes <- getField(source = PNV.Source , quant = "Smith2014")

## Compare biomes, print the statistics
biomes.comparison <- compareLayers(field1 = model.biomes, 
                                   field2 = PNV.biomes, 
                                   layers1 = "Smith2014")
print(biomes.comparison@stats)

# plotSpatialComparisons
print(plotSpatialComparison(biomes.comparison))
print(plotSpatialComparison(biomes.comparison, type = "values"))


##### Seasonal comparison

# Load monthly LPJ-GUESS LAI data over Europe for two periods

mlai.2000_2005 <-  getField(source = europe.Source, 
                            quant = "mlai", 
                            year.aggregate.method = "mean", 
                            first.year = 2000, last.year = 2005)
                            
mlai.2006_2010 <-  getField(source = europe.Source, 
                            quant = "mlai", 
                            year.aggregate.method = "mean", 
                            first.year = 2006, last.year = 2010)

# make comparison and show stats
seasonal.comparison <- compareLayers(field1 = mlai.2000_2005, 
                                     field2 = mlai.2006_2010, 
                                     layers1 = "mlai", 
                                     do.seasonality = TRUE, 
                                     verbose = TRUE, 
                                     show.stats = TRUE)
print(seasonal.comparison@stats)


# plotSpatialComparisons
print(plotSpatialComparison(seasonal.comparison))
print(plotSpatialComparison(seasonal.comparison, type = "values")) 

MagicForrest/DGVMTools documentation built on Aug. 23, 2024, 8:05 a.m.