Merge pull request #61 from MagicForrest/dev

*** Release v0.9.0 ***

Author: MagicForrest

DESCRIPTION

@@ -1,15 +1,16 @@
 Package: DGVMTools
 Type: Package
-Version: 0.8.2
+Version: 0.9.0
 Title: DGVM Processing, Analysis and Plotting Tools
-Date: 2019-02-27
+Date: 2019-11-01
 Authors@R: c(person("Matthew", "Forrest", role=c("aut", "cre"), email="[email protected]"),
              person("Simon", "Scheiter", role=c("aut"), email="[email protected]"),
-             person("Joerg", "Steinkamp", role=c("aut"), email="[email protected]"))
-Author: Matthew Forrest [aut, cre], Simon Scheiter [aut], Joerg Steinkamp [aut]
+             person("Joerg", "Steinkamp", role=c("aut"), email="[email protected]"),
+             person("Glenn", "Moncrieff", role=c("aut"), email="[email protected]"))
+Author: Matthew Forrest [aut, cre], Simon Scheiter [aut], Joerg Steinkamp [aut], Glenn Moncrieff [aut]
 Maintainer: Matthew Forrest <[email protected]>
 Description: Read, process, benchmark, analyse and plot output data produced by dynamic global vegetation
-    models (DGVMs) LPJ-GUESS(-SPITFIRE) and aDGVM2 and potentially soon others, for use in R. 
+    models (DGVMs): LPJ-GUESS(-SPITFIRE), aDGVM and aDGVM2 (and potentially soon others), for use in R. 
     Also reads many standard datasets as processed by companion 'DGVMData' package. 
     FireMIP model output is supported with an additional package (FireMIPTools).
 Depends:
@@ -21,10 +22,10 @@ Imports:
     sp,
     raster,
     compiler,
+    fields,
     maps,
     maptools,
     mapdata,
-    fields,
     RColorBrewer,
     reshape2,
     viridis,
@@ -40,7 +41,7 @@ License: GPL | file LICENSE
 URL: https://www.bik-f.de
 BugReports: https://github.com/MagicForrest/DGVMTools/issues
 NeedsCompilation: no
-RoxygenNote: 6.1.1
+RoxygenNote: 7.1.0
 VignetteBuilder: knitr
 Encoding: UTF-8
 Collate:
@@ -49,32 +50,35 @@ Collate:
     'Format-DGVMData.R'
     'Format-GUESS.R'
     'Format-aDGVM.R'
+    'Format-aDGVM2.R'
     'Standard-Quantities.R'
     'addArea.R'
     'addStandardSpatialAttributes.R'
+    'addTo.R'
     'aggregateSpatial.R'
     'aggregateSubannual.R'
     'aggregateYears.R'
     'availableQuantities.R'
     'averageFields.R'
     'benchmarking.R'
-    'biome-schemes.R'
     'byIDfromList.R'
     'calcNewField.R'
+    'classification-schemes.R'
     'commonSTAInfo.R'
     'compareLayers.R'
     'copyLayers.R'
     'crop-methods.R'
+    'defineLayer.R'
+    'defineQuantity.R'
     'defineSource.R'
     'determinePFTs.R'
     'export-methods.R'
     'extent-methods.R'
-    'getBiomes.R'
     'getDimInfo.R'
     'getField.R'
+    'getScheme.R'
     'is-methods.R'
     'layerOp.R'
-    'listPFTs.R'
     'lookupQuantity.R'
     'makeFieldID.R'
     'makePlotTitle.R'
@@ -89,6 +93,7 @@ Collate:
     'plotSpatialComparison.R'
     'plotSubannual.R'
     'plotTemporal.R'
+    'plotTemporalComparison.R'
     'plotting-framework-functions.R'
     'renameLayers.R'
     'selectDays.R'
@@ -100,5 +105,6 @@ Collate:
     'show-methods.R'
     'small-utility-functions.R'
     'summary-methods.R'
+    'whichLayers.R'
     'writeField-methods.R'
     'writeNetCDF-methods.R'

NAMESPACE

@@ -20,8 +20,11 @@ export(SimpleHeightAdgvm2BiomeScheme)
 export(Smith2014BiomeScheme)
 export(Standard.quantities)
 export(aDGVM)
+export(aDGVM2)
+export(aDGVMBiomeScheme)
 export(addArea)
 export(addStandardSpatialAttributes)
+export(addTo)
 export(aggregateSpatial)
 export(aggregateSubannual)
 export(aggregateYears)
@@ -38,33 +41,33 @@ export(commonSTAInfo)
 export(compareLayers)
 export(continuousComparison)
 export(copyLayers)
+export(defineLayer)
+export(defineQuantity)
 export(defineSource)
 export(determinePFTs)
 export(difference.palette)
 export(extract.seq)
 export(fire.palette)
-export(getBiomes)
 export(getDimInfo)
 export(getField)
-export(getStandardQuantity_LPJ)
+export(getScheme)
 export(gridarea1d)
 export(gridarea2d)
 export(is.Comparison)
 export(is.Field)
 export(is.Format)
-export(is.PFT)
+export(is.Layer)
 export(is.Quantity)
 export(is.STAInfo)
 export(is.Source)
 export(is.Statistics)
 export(is.leapyear)
 export(layerOp)
-export(listPFTs)
 export(lookupQuantity)
 export(makeFieldID)
 export(makePlotTitle)
 export(makeSPDFfromDT)
-export(matchPFTCols)
+export(matchLayerCols)
 export(periods)
 export(plotResidualsHisto)
 export(plotScatter)
@@ -74,6 +77,7 @@ export(plotSpatial)
 export(plotSpatialComparison)
 export(plotSubannual)
 export(plotTemporal)
+export(plotTemporalComparison)
 export(promoteToRaster)
 export(proportionsComparison)
 export(renameLayers)
@@ -91,16 +95,17 @@ export(selectMonths)
 export(selectSeasons)
 export(selectYears)
 export(setKeyDGVM)
-export(supported.biome.schemes)
+export(supported.classification.schemes)
 export(veg.palette)
-exportClasses(BiomeScheme)
+export(whichLayers)
 exportClasses(Comparison)
 exportClasses(Field)
 exportClasses(Format)
-exportClasses(PFT)
+exportClasses(Layer)
 exportClasses(Period)
 exportClasses(Quantity)
 exportClasses(STAInfo)
+exportClasses(Scheme)
 exportClasses(Source)
 exportMethods(as.Raster)
 exportMethods(as.array)

NEWS.md

@@ -1,3 +1,43 @@
+#  DGVMTools v0.9.0 (2020-08-04) 
+
+This is a feature release!  Main features are aDGVM1 support, the inclusion of plotTemporalComparison() and the change from PFT objects to the more flexible Layer objects.  However there have been many other bug-fixes and tweaks.
+
+## Main features
+
+* aDGVM1 now supported!  Thanks Glenn Moncrieff! The original aDGVM Format object, which referred to aDGVM2, has been renamed to ... drum roll please... aDGVM2.
+* Biome schemes have been included specifically for aDGVM1.
+* plotTemporalComparison() has been added.
+* The PFT object has been replaced with a Layer object which is designed to be much more flexible.  Where PFT objects had fixed slots to represent their properties, Layer objects feature an R list of properties, which can be user-defined and customised for each supported model.  PFTs are now simply defined as Layer objects, but Layers can also be other things (C pools, soils depths, whatever).
+* Sources now have slots "predefined.layers" to contain, yes you got it, their pre-defined Layers.
+* Facetting has been reworked for plotSpatial() and is now consistent with the other plotXXX() functions.  Note that an automatic calls to facet_grid() are no longer done in plotSpatial(), but of course they can be done afterwards by the user.  Number of rows or columns of facets in a spatial plot should be specified by suppling arguments "nrow" and "ncol" to plotSpatial() (or plotSpatialComparison()).  These are actually completely equivalent to the standard arguments to facet_wrap() in ggplot2.
+
+## Minor features/improvements
+
+* Can now use a map object for selecting gridcells with selectGridcells().
+* Functions defineLayer() and defineQuantity() added.
+* Added the addTo() function to add Layer or Quantity objects to Format or Source objects.  This is simply a user-friendly convience so that users don't need to explicitly access the slots in the S4 class structure, and is designed to work in conjunction with the nee defineLayer() and defineQuantity() function above.
+* Added the legend.title argument to plotSpatial().
+* Coefficient of variation is now a possible method when aggregating with aggregateSpatial(), aggregateSubannual() or aggregateYears().
+* Improved Field to Raster conversion.  It now supports multiple Layers, months and years.
+
+## Breaking changes
+
+* Using a string when specifying the format argument to defineSource() has been disabled.  Please specify the Format object, i.e. Guess instead of "GUESS" or "LPJ-GUESS".
+* BiomeScheme renamed to Scheme, getBiomes() renamed to getScheme().
+* Functions copyLayers() and compareLayers() now use a "tolerance" argument instead of "dec.places" which is more intuitive, efficient and reliable.
+* Function determinePFTs() has been removed as it was not particularly useful and PFT objects have now been generalised to Layer objects.
+* plotScatter() argument names changed to 'x' and 'y' instead of 'field1' and 'field2'
+* First argument to plotScatterComparision() and plotResidualComparison() is now called 'comparisons' instead of 'input.CLayers'.
+
+## Under the hood
+
+* In Format-GUESS, crop and aggregating is now done earlier to save memory.
+* Precision of Lon and Lat handled better in addArea().
+* plotSpatial() now correctly identifies different year periods and puts them in different panels (thanks to Peter Antoni for reporting).
+* Removed correct.map.offset internal function because it now seems unnecesary and just caused problems.
+
+
+
 #  DGVMTools v0.8.2 (2019-10-04) 
 
 This is a bug-fix and "feature tweaking" release - i.e. there is no new major functionality but enhanced useability and other tweaks.

R/Format-DGVMData.R

@@ -53,7 +53,7 @@ getField_DGVMData <- function(source,
 
 
   # Make the filename (if necessary) and check for the file, gunzip if necessary, fail if not present
-  if(!is.null(file.name)) file.path(source@dir, file.name)
+  if(!is.null(file.name)) file.name.nc <- file.path(source@dir, file.name)
   else file.name.nc <- file.path(source@dir, paste(quant@id, "nc", sep = "."))
   file.name.nc.gz <- paste(file.name.nc, "gz", sep = ".")
   zipped <- FALSE
@@ -403,7 +403,7 @@ getField_DGVMData <- function(source,
       dimnames(this.slice) <- dimension.names
 
       # prepare data.table from the slice (array)
-      this.slice.dt <- as.data.table(melt(this.slice))
+      this.slice.dt <- as.data.table(reshape2::melt(this.slice))
       rm(this.slice)
       gc()
       this.slice.dt <- stats::na.omit(this.slice.dt)
@@ -536,10 +536,11 @@ getField_DGVMData <- function(source,
   }
 
 
-  
-  # if london.centre is requested, shift to -180 to +180
-  if(length(all.lons) > 0) {
-    if(source@london.centre  && max(all.lons) >= 180){ dt[, Lon := vapply(dt[,Lon], 1, FUN = LondonCentre)] }
+  # if london.centre is requested, make sure all longitudes greater than 180 are shifted to negative
+  if(source@london.centre){
+    if(max(all.lons) > 180) {
+      dt[, Lon := LondonCentre(Lon)]
+    }
   }
 
   # set keys
@@ -611,21 +612,6 @@ availableQuantities_DGVMData <- function(source, names){
 }
 
 
-#' Detemine PFTs present in an DGVMData source 
-#' 
-#' @param x  A Source objects describing a DGVMData source
-#' @param variables Some variable to look for to detremine the PFTs present in the run.  Not the function automatically searches:
-#'  "lai", "cmass", "dens" and "fpc".  If they are not in your output you should define another per-PFT variable here.  Currently ignored.
-#' @author Matthew Forrest \email{matthew.forrest@@senckenberg.de}
-#' @keywords internal
-
-determinePFTs_DGVMData <- function(x, variables) {
-  
-  warning("Datasets don't normally have PFTs (or they are not likely to be defined consistently) so I am not looking for them.  Instead I am returning the source@[email protected] argument directly (in case you defined some yourself, which would be the way to go in this case)")
-  return(x@format@pft.set)
-  
-}
-
 
 ########################################################
 ########### DGVMData QUANTITIES ########################
@@ -756,17 +742,14 @@ DGVMData <- new("Format",
                 # UNIQUE ID
                 id = "DGVMData",
 
-                # FUNCTION TO LIST ALL PFTS APPEARING IN A RUN
-                determinePFTs = determinePFTs_DGVMData,
-                
                 # FUNCTION TO LIST ALL QUANTIES AVAILABLE IN A RUN
                 availableQuantities = availableQuantities_DGVMData,
 
                 # FUNCTION TO READ A FIELD 
                 getField = getField_DGVMData,
 
-                # DEFAULT GLOBAL PFTS  
-                default.pfts = list(),
+                # DEFAULT GLOBAL LAYERS  
+                predefined.layers = list(),
 
                 # QUANTITIES THAT CAN BE PULLED DIRECTLY FROM LPJ-GUESS RUNS  
                 quantities = DGVMData.quantities