Merge pull request #68 from MagicForrest/Format-NetCDF-devel

Merge all v0.10 changes to master ready for release.

Author: MagicForrest

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: DGVMTools
 Type: Package
-Version: 0.9.0
+Version: 0.10.0
 Title: DGVM Processing, Analysis and Plotting Tools
 Date: 2019-11-01
 Authors@R: c(person("Matthew", "Forrest", role=c("aut", "cre"), email="[email protected]"),
@@ -41,14 +41,14 @@ License: GPL | file LICENSE
 URL: https://www.bik-f.de
 BugReports: https://github.com/MagicForrest/DGVMTools/issues
 NeedsCompilation: no
-RoxygenNote: 7.1.0
+RoxygenNote: 7.1.1
 VignetteBuilder: knitr
 Encoding: UTF-8
 Collate:
     'classes.R'
     'colour-palettes.R'
-    'Format-DGVMData.R'
     'Format-GUESS.R'
+    'Format-NetCDF.R'
     'Format-aDGVM.R'
     'Format-aDGVM2.R'
     'Standard-Quantities.R'
@@ -95,6 +95,7 @@ Collate:
     'plotTemporal.R'
     'plotTemporalComparison.R'
     'plotting-framework-functions.R'
+    'read-netcdf-utility-functions.R'
     'renameLayers.R'
     'selectDays.R'
     'selectGridcells.R'

NAMESPACE

@@ -4,7 +4,6 @@ S3method(as.data.frame,Comparison)
 S3method(as.data.frame,Field)
 S3method(as.data.table,Comparison)
 S3method(as.data.table,Field)
-export(DGVMData)
 export(DevMegaBiomeScheme)
 export(FPCMegaBiomeScheme)
 export(FireMIPBiomeScheme)
@@ -14,6 +13,7 @@ export(GrowthFormAdgvm2BiomeScheme)
 export(Hickler2012BiomeScheme)
 export(LondonCentre)
 export(MeditBiomeScheme)
+export(NetCDF)
 export(PhenologyAdgvm2BiomeScheme)
 export(SimpleAdgvm2BiomeScheme)
 export(SimpleHeightAdgvm2BiomeScheme)

NEWS.md

@@ -1,3 +1,49 @@
+#  DGVMTools v0.10.0 (2021-04-09) 
+
+Feature release, and a good one!  A new flexible netCDF file reader is now included! This completely supersedes the previous "DGVMData"" Format (which has been removed), please now use the "NetCDF"" Format instead (it should also read any old DGVMData file without problems). For further details of this and other features and bugfixes, see below.
+
+## Main Feature
+
+* New 'NetCDF' Format is implemented and completely replaces the old 'DGVMData' Format.  This new Format will attempt to read any netCDF file, with the following considerations:
+  - Time axes (if present) can be relative (units "days/months/years/seconds since...") or absolute (units "years/months").
+  - Longitude and latitude dimensions must be present in the netCDF files with a (single) corresponding variable defined i.e. no rotated grids (CDO will regrid a properly-defined rotated grid to a normal) or "land_id"-style 1D index of points.   
+  - Aside from lon, lat and time, variables can have only *one* further dimension (to represent, say, PFT or carbon pool, etc).    Correspondingly, DGVMTools interprets this dimension as a Layer dimensison .
+  These limitation can be addressed if there is user demand for more flexibility. So if you want something, reach out to the author by raising an Issue on Github. 
+This new Format has been well-tested and works with ISIMIP biome sector output, TRENDY/FireMIP2019 output and a broad sample of netCDF files found "in the wild".  However, if you have problems with your, again please just get in touch and raise an Issue.
+
+## Minor features/improvements
+
+* aggregateXXXX() functions now accept "mode" and "median" to their method argument. 
+* plotTrend argument set to FALSE by default in plotTemporal().
+* Added "global.extent" as an argument to writeNetCDF() to automatically make a netCDF file that covers the whole globe.
+* All possible factor levels are included in the return from getScheme() (even if not all levels are present in the data).
+* Implemented "gap-making" in writeNetCDF() to ensure ocean-only bands are present with NAs (and not just missing).
+* plotSubannual() aesthetics now consistent with plotTemporal().
+* Legend order now matches input order of Fields in plotTemporal(). 
+
+## Breaking changes
+
+* DGVMData Format removed, NetCDF Format should be a drop in replacement.  Any problems, let me know.
+* The 'file.name' argument has been moved higher in the argument list for getField().  This is to reflect its new importance when 
+  using the NetCDF Format.
+
+## Bug fixes
+
+* Minor corrections to the logic of Smith2014 and Forrest2015 biome schemes (now strictly based on the original Lund script and logic).
+* Unused 'facet.labels' argument remove from plotSpatial().  Please pass in standard ggplot arguments to control facetting.
+* Bug fix to plotSubannual where function failed if Year had been averaged away.
+* Corrected dimension ordering when writing "Layer" dimension in netCDF files.
+
+## Under the hood
+
+* When writing netCDF files, arguments to ncdf4 functions are passed through automatically with "...".
+* FieldToArray reworked for efficiency, clarity and consistency.  Labelling of time axis of arrays now of form "days since". 
+* Much netCDF reading code has been factored out into read-netcdf-utility-functions.R, for clarity and re-usability.
+
+*Thank you to everyone for your bug reports and feature requests!  Keep 'em coming :-)*
+
+
+
 #  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.