Document new numericTimeSettings NcML scan attribute

Author: lesserwhirls

docs/src/site/pages/netcdfJava/NcmlCookbook.md

@@ -190,7 +190,7 @@ See [Dataset URLs](dataset_urls.html) for more information on the location attri
 
 ### Assign coordinate values to unknown number of datasets.
 
-You dont have to know the number of files found in the scan, but they must be evenly spaced, and they must be in alphabetic order.
+You don't have to know the number of files found in the scan, but they must be evenly spaced, and they must be in alphabetic order.
 
 ~~~xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -207,7 +207,7 @@ You dont have to know the number of files found in the scan, but they must be ev
 </netcdf>
 ~~~
 
-### Scan directory, assign date coordinate value from filename.
+### Scan directory, assign date coordinate value (ISO time strings) from filename.
 
 The date coordinate must be derivable from the filename, using the dateFormatMark attribute.
 
@@ -221,6 +221,23 @@ The date coordinate must be derivable from the filename, using the dateFormatMar
 </netcdf> 
 ~~~
 
+### Scan directory, assign date coordinate value (numeric, UDUNITS compatible) from filename.
+
+The date coordinate must be derivable from the filename, using the dateFormatMark attribute.
+The numericTimeSettings consists of a data type plus a UDUNITS time unit.
+These should be chosen carefully, as truncation can occur.
+
+~~~xml
+<?xml version="1.0" encoding="UTF-8"?>
+<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">
+  <aggregation dimName="time" type="joinNew">
+    <variableAgg name="T"/>
+    <scan location="/data/goes/" suffix=".gini" dateFormatMark="SUPER-NATIONAL_1km_SFC-T_#yyyyMMdd_HHmm"
+      numericTimeSettings="int minutes since 2015-06-07T12:00:00Z"/>
+  </aggregation>
+</netcdf> 
+~~~
+
 ## JoinExisting Aggregation
 
 ### Name each dataset in a netcdf element and read coordinate values from the files.
@@ -258,30 +275,6 @@ Overrides existing coordinate variable, if any.
 </netcdf>
 ~~~
 
-### Scan directory, assign date coordinate value from filename.
-
-Each file must have exactly one time slice.
-The date coordinate must be derivable from the filename, using the `dateFormatMark` attribute.
-
-~~~xml
-<?xml version="1.0" encoding="UTF-8"?>
-<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">
-  <aggregation dimName="time" type="joinExisting">
-    <scan dateFormatMark="CG#yyyyDDD_HHmmss" location="src/test/data/ncml/nc/cg/" suffix=".nc" subdirs="false" />
-  </aggregation>
-</netcdf>
-
-<?xml version="1.0" encoding="UTF-8"?>
-<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">
- <aggregation dimName="time" type="joinExisting" timeUnitsChange="true"> 
-  <netcdf location="20060925_0600.nc" ncoords="2"/>
-  <netcdf location="20060925_1200.nc" ncoords="2"/>
-  <netcdf location="20060925_1800.nc" ncoords="2"/>
-  <netcdf location="20060926_0000.nc" ncoords="2"/>
- </aggregation>
-</netcdf>
-~~~
-
 ### Name each dataset in a netcdf element and read coordinate values from the files, whose units change.
 
 Add the `timeUnitsChange` attribute.

docs/src/site/pages/netcdfJava/ncmlschema.md

@@ -27,7 +27,8 @@ Aggregation specific elements are listed in <font color="darkred">red. The forec
 <xsd:schema targetNamespace="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2"
-  elementFormDefault="qualified">
+  elementFormDefault="qualified"
+  version="2.2.1">
 ~~~
 
 ### netcdf Element
@@ -446,30 +447,31 @@ The aggregation element allows multiple datasets to be combined into a single lo
 (11)   <xsd:attribute name="olderThan" type="xsd:string" />
 (12)   <xsd:attribute name="dateFormatMark" type="xsd:string" />
 (13)   <xsd:attribute name="enhance" type="xsd:string"/>
+(14)   <xsd:attribute name="numericTimeSettings" type="xsd:string"/>
       </xsd:complexType>
      </xsd:element>
 
-(14) <xsd:element name="scanFmrc" minOccurs="0" maxOccurs="unbounded">
+(15) <xsd:element name="scanFmrc" minOccurs="0" maxOccurs="unbounded">
       <xsd:complexType>
 (7)    <xsd:attribute name="location" type="xsd:string" 
 (8)    <xsd:attribute name="regExp" type="xsd:string" />use="required"/>
 (9)    <xsd:attribute name="suffix" type="xsd:string" />
 (10)   <xsd:attribute name="subdirs" type="xsd:boolean" default="true"/>
 (11)   <xsd:attribute name="olderThan" type="xsd:string" />
-(15)   <xsd:attribute name="runDateMatcher" type="xsd:string" />
+(16)   <xsd:attribute name="runDateMatcher" type="xsd:string" />
        <xsd:attribute name="forecastDateMatcher" type="xsd:string" />
        <xsd:attribute name="forecastOffsetMatcher" type="xsd:string" />
       </xsd:complexType>
      </xsd:element>
     </xsd:sequence>
     
-(16) <xsd:attribute name="type" type="AggregationType" use="required"/>
-(17) <xsd:attribute name="dimName" type="xsd:token" />
-(18) <xsd:attribute name="recheckEvery" type="xsd:string" />
-(19) <xsd:attribute name="timeUnitsChange" type="xsd:boolean"/>
+(17) <xsd:attribute name="type" type="AggregationType" use="required"/>
+(18) <xsd:attribute name="dimName" type="xsd:token" />
+(19) <xsd:attribute name="recheckEvery" type="xsd:string" />
+(20) <xsd:attribute name="timeUnitsChange" type="xsd:boolean"/>
 
       <!-- fmrc only  -->
-(20) <xsd:attribute name="fmrcDefinition" type="xsd:string" />
+(21) <xsd:attribute name="fmrcDefinition" type="xsd:string" />
 
 </xsd:complexType>
 </xsd:element>
@@ -482,7 +484,7 @@ The aggregation element allows multiple datasets to be combined into a single lo
  **promoteGlobalAttribute** element.
 4. Specify which variables should be cached (outer aggregation only) with a **cacheVariable** element.
 5. Nested **netcdf** datasets can be explicitly listed.
-6. Nested netcdf datasets can be implictly specified with a **scan** element.
+6. Nested netcdf datasets can be implicitly specified with a **scan** element.
 7. The scan directory **location**.
 8. If you specify a **regExp**, only files with whose full pathnames match the regular expression will be included.
 9. If you specify a **suffix**, only files with that ending will be included. A regExp attribute will override, that is, 
@@ -495,17 +497,18 @@ The aggregation element allows multiple datasets to be combined into a single lo
 13. You can optionally specify that the files should be opened in **enhance** mode (default is *None*).
  Generally you should do this if the ncml needs to operate on the dataset after the CoordSysBuilder has augmented it. 
  Otherwise, you should not enhance.
-14. A specialized **scanFmrc** element can be used for a forecastModelRunSingleCollection aggregation, where forecast 
+14. **numericTimeSettings** is used in conjunction with **dateFormatMark** to create a numeric, UDUNITS compatible aggregated time variable. See more below.
+15. A specialized **scanFmrc** element can be used for a forecastModelRunSingleCollection aggregation, where forecast 
  model run data is stored in multiple files, with one forecast time per file.
-15. For scanFmrc, the run date and the forecast date is extracted from the file pathname using a **runDateMatcher** and 
+16. For scanFmrc, the run date and the forecast date is extracted from the file pathname using a **runDateMatcher** and 
  either a **forecastDateMatcher** or a **forecastOffsetMatcher** attribute. See more below.
-16. You must specify an **aggregation type**.
-17. For all types except joinUnion, you must specify the **dimension name** to join.
-18. The **recheckEvery** allows you to rescan periodically to see if the set of files has changed.
-19. Only for *joinExisting* and *forecastModelRunCollection* types: if **timeUnitsChange** is set to true, the units of the 
+17. You must specify an **aggregation type**.
+18. For all types except joinUnion, you must specify the **dimension name** to join.
+19. The **recheckEvery** allows you to rescan periodically to see if the set of files has changed.
+20. Only for *joinExisting* and *forecastModelRunCollection* types: if **timeUnitsChange** is set to true, the units of the 
  joined coordinate variable may change, so examine them and do any appropriate conversion so that the aggregated 
  coordinate values have consistent units.
-20. Experimental, do not use.
+21. Experimental, do not use.
 
 ##### DateFormatMark
 A **dateFormatMark** is used on joinNew types to create date coordinate values out of the filename. It consists of a 
@@ -521,6 +524,16 @@ A **dateFormatMark** is used on joinNew types to create date coordinate values o
  in which case the coordinate values of the time can be created from the filename, instead of having to open each file
  and read it.
 
+##### numericTimeSettings
+**numericTimeSettings** can be combined with a **dateFormatMark** to produce a numeric, UDUNITS compatible time variable.
+**numericTimeSettings** consists of a data type plus a UDUNITS compatible time unit.
+Care must be taken when choosing these parameters to prevent truncation.
+ ```
+            Filename: SUPER-NATIONAL_1km_SFC-T_20051206_2300.gini 
+      DateFormatMark: SUPER-NATIONAL_1km_SFC-T_#yyyyMMdd_HHmm
+ numericTimeSettings: int minutes since 2005-12-01T00:00:00Z"
+ ```
+
 ##### ScanFmrc
 
 The run date and the forecast date is extracted from the file pathname using a **runDateMatcher** and 

docs/src/site/pages/netcdfJava_tutorial/ncml/NcmlAggregation.md

@@ -235,6 +235,7 @@ These are the ways that coordinate values may be assigned to a `joinExisting` co
   </aggregation>
   ~~~
 * If there is exactly one time slice in each file of the `joinExisting` aggregation, and you are using a scan element to dynamically scan the files in a directory, then you can use the `dateFormatMark` attribute to derive the date from the filename.
+  * You can combine `dateFormatMark` with `numericTimeSettings` to produce a time variable with numeric values and a UDUNITS compatible unit.
 * If you do not specify a coordinate variable, one must exist in each of the nested datasets, and the coordinate values will be read from it, just like any other aggregation variable.
   In this case, when the units of the aggregation coordinate change on the existing coordinate variables, you must add **timeUnitsChange=\"true\"** on the aggregation element:
   ~~~xml