1.2.1 JoinNew Aggregation

The JoinNew aggregation type joins variables along a new dimension. The dimension and a coordinate variable are created and values for the coordinates are specified in the aggregation element:

<aggregation serviceName="ISCCP" aggType="JoinNew" 
             varName="time">
  <fileAccess urlPath="cldfrc/isccp.8501.bin" coord="Jan"/>
  <fileAccess urlPath="cldfrc/isccp.8502.bin" coord="Feb"/>
  <variable name="cldfrc"/>
</aggregation>

This XML fragment will combine these two datasets:

Dataset {
  Float32 cldfrc[lat = 180][lon = 360];
} isccp_c2;

Dataset {
  Float32 cldfrc[lat = 180][lon = 360];
} isccp_c2;

into this one:

Dataset {
  String time[time = 2];
  Float32 cldfrc[time = 2][lat = 180][lon = 360];
} ISCCP/cldfrc;

The coordinate variable time has been assigned the values "Jan" for dataset 8501 and "Feb" for dataset 8502, as specified in the aggregation tag.

NOTE: JoinNew aggregations will automatically join all variables of type Grid. Variables of type Array may also be joined, but must be explicitly listed in a variable element. In the example here, the variable element specified that all arrays called cldfrc were to be joined.

There are several options for assigning values to the coordinate variable of the joined dimension of JoinNew aggregations; see a description of the varType and varUnit attributes of the aggregation element. The most common use of JoinNew aggregations is to add a time dimension. The dateFormat attribute is used to convert date/time strings into other units. In the following example:

<aggregation aggType="JoinNew" varName="time" varType="int" 
    varUnit="days since 0000-01-01 00:00:00" 
    dateFormat="yy/M/d:HH:mm:ss z">
<fileAccess 
    urlPath="20020101.dat" coord="2002/1/1:00:00:00 GMT"/>
<fileAccess 
    urlPath="20020102.dat" coord="2002/1/2:00:00:00 GMT"/>
<fileAccess 
    urlPath="20020103.dat" coord="2002/1/3:00:00:00 GMT"/>
</aggregation>

The time data strings are read in using the SimpleDateFormat string yyyy/M/d:HH:mm:ss z, then converted to the unit specified with the varUnit attribute:

  days since 0000-01-01 00:00:00

using the ucar.units package and stored in the dataset as an int32, so the time coordinate values will look like:

time[3]
0, 1, 2