NcML Cookbook Examples

General

Rename the variable lflx to LavaFlow:

<?xml version="1.0" encoding="UTF-8"?>
<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2" location="nc/cldc.mean.nc">
  <variable name="LavaFlow" orgName="lflx" />
  ...
</netcdf>

Remove the variable LavaFlow from the dataset.

<?xml version="1.0" encoding="UTF-8"?>
<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2" location="nc/cldc.mean.nc">
  <remove name="LavaFlow" type="variable" />
</netcdf>

Union Aggregation

Create union of datasets cldc.mean.nc and lflx.mean.nc located in the directory nc reletive to where the NcML file is found:

<?xml version="1.0" encoding="UTF-8"?>
<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">     
 <attribute name="title" type="string" value="Union cldc and lflx"/>
 <aggregation type="union">
   <netcdf location="nc/cldc.mean.nc"/>
   <netcdf location="nc/lflx.mean.nc"/>
  </aggregation>
</netcdf>

Create union of all datasets ending in mean.nc located in the directory nc reletive to where the NcML file is found:

<?xml version="1.0" encoding="UTF-8"?>
<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">     
  <attribute name="title" type="string" value="Union all mean.nc files"/>
  <aggregation type="union">
    <scan location="file:src/test/data/ncml/nc/" suffix="mean.nc"/> 
  </aggregation>
</netcdf>

See Dataset URLS for more information on the location attribute.

JoinNew Aggregation

Name each dataset in a netcdf element and assign coordinate values there:

<?xml version="1.0" encoding="UTF-8"?>
<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">

 <variable name="time" type="int">
   <attribute name="units" value="months since 2000-6-16 6:00"/>
 </variable>

 <aggregation  dimName="time" type="joinNew">
   <variableAgg name="T"/>
   <netcdf location="file:src/test/data/ncml/nc/time0.nc" coordValue="0"/>
   <netcdf location="file:src/test/data/ncml/nc/time1.nc" coordValue="10"/>
   <netcdf location="file:src/test/data/ncml/nc/time2.nc" coordValue="99"/>
 </aggregation>
</netcdf>

Assign coordinate values in the coordinate variable:

<?xml version="1.0" encoding="UTF-8"?>
<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">

 <variable name="time" type="int">
   <attribute name="units" value="months since 2000-6-16 6:00"/>
   <values>0 10 99</values>
 </variable>

 <aggregation  dimName="time" type="joinNew">
   <variableAgg name="T"/>
   <netcdf location="file:src/test/data/ncml/nc/time0.nc"/>
   <netcdf location="file:src/test/data/ncml/nc/time1.nc"/>
   <netcdf location="file:src/test/data/ncml/nc/time2.nc"/>
 </aggregation>
</netcdf>

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.

<?xml version="1.0" encoding="UTF-8"?>
<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">

 <variable name="time" type="int" shape="time">
   <attribute name="long_name" type="string" value="time coordinate" />
   <attribute name="units" type="string" value="days since 2001-8-31 00:00:00 UTC" />
   <values start="0" increment="1" />
 </variable>

 <aggregation  dimName="time" type="joinNew">
   <variableAgg name="T"/>
   <scan location="src/test/data/ncml/nc/" suffix="Dir.nc"/>
 </aggregation>
</netcdf>

Scan directory, assign date coordinate value from filename. The date coordinate must be derivable from the filename, using the dateFormatMark attribute.

<?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" />
  </aggregation>
</netcdf>

JoinExisting Aggregation

Name each dataset in a netcdf element and read coordinate values from the files. A coordinate variable named time must exist in each file.

<?xml version="1.0" encoding="UTF-8"?>
<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">

 <aggregation dimName="time" type="joinExisting">
   <netcdf location="file:src/test/data/ncml/nc/jan.nc"/>
   <netcdf location="file:src/test/data/ncml/nc/feb.nc"/>
 </aggregation>
   
</netcdf>

Name each dataset in a netcdf element and assign coordinate values explicitly. Overrides existing coordinate variable, if any.

<?xml version="1.0" encoding="UTF-8"?>
<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">

 <variable name="time">
   <attribute name="long_name" value="climatological time"/>
   <attribute name="units" value="days since 000-00-00 0:00"/>
   <attribute name="_CoordinateAxisType" value="Time" />
 </variable>

 <aggregation dimName="time" type="joinExisting">
   <netcdf location="file:src/test/data/ncml/nc/jan.nc"
      coordValue="0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30"/>
   <netcdf location="file:src/test/data/ncml/nc/feb.nc"
      coordValue="31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58"/>
 </aggregation>

</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 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. Also works for Fmrc.

<?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>

New Features in Netcdf-Java 4.0

Global Attributes to Variables (OuterDimension Aggregations only: JoinExisting, JoinNew, Fmrc)

The value(s) of the attribute in each file are placed into the named Variable. In the following, the Variable is given a different name ("times") than the global attribute ("time_coverage_end"):

<?xml version="1.0" encoding="UTF-8"?>
<netcdf xmlns="http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2">
  <aggregation dimName="time" type="joinExisting" recheckEvery="4 sec">
    <promoteGlobalAttribute name="times" orgName="time_coverage_end" />
    <scan dateFormatMark="CG#yyyyDDD_HHmmss" location="src/test/data/ncml/nc/cg/" suffix=".nc" subdirs="false" />
  </aggregation>
</netcdf>

Each file has a global attribute of type String:

 :time_coverage_end = "2006-06-07T13:00:00Z";

In the aggregation dataset, a String variable is created using the aggregation dimension:

  String times(time=3);
  data:
   "2006-06-07T12:00:00Z",   "2006-06-07T13:00:00Z",   "2006-06-07T14:00:00Z"

This document is maintained by John Caron and was last updated on November 2009

			Unidata is a member of the UCAR Community Programs, is managed by the University Corporation for Atmospheric Research, and is sponsored by the National Science Foundation.
			P.O. Box 3000 • Boulder, CO 80307-3000 USA • Tel: 303-497-8643 • Fax: 303-497-8690