## Using Templates

GrADS allows you use a single data descriptor file to aggregate multiple data files and handle them as if they were one individual file. The individual data files must be identical in all dimensions except time and in a format GrADS can read. The time range of each individual file must be indicated it its filename.

First, the DSET entry has a substitution template instead of a filename. See below for a description of all the possible components of the template. Second, the OPTIONS entry contains the `template` keyword. Third, the TDEF entry describes the time range for the entire set of data files.

Templating works on any GrADS data type for which you can write a descriptor file. If you specify any additional OPTIONS keywords in the data descriptor file, make sure the options apply equally to each file included in the template.

Valid components of the substitution template are as follows:

`%x1` 1 digit decade
`%x3` 3 digit decade
`%y2` 2 digit year
`%y4` 4 digit year
`%m1` 1 or 2 digit month
`%m2` 2 digit month (leading zero if needed)
`%mc` 3 character month abbreviation
`%d1` 1 or 2 digit day
`%d2` 2 digit day (leading zero if needed)
`%h1` 1 or 2 digit hour
`%h2` 2 digit hour
`%h3` 3 digit hour (e.g., 120 or 012)
`%f2` 2 or 3 digit forecast hour
`%f3` 3 digit forecast hour
`%n2` 2 digit minute (leading zero if needed)

When specifying the initial time (e.g., NWP model output from NMC and FNMOC), use these substitutions:

`%ix1` initial 1 digit decade
`%ix3` initial 3 digit decade
`%iy2` initial 2 digit year
`%iy4` initial 4 digit year
`%im1` initial 1 or 2 digit month
`%im2` initial 2 digit month (leading zero if needed)
`%imc` initial 3 character month abbreviation
`%id1` initial 1 or 2 digit day (leading zero if needed)
`%id2` initial 2 digit day
`%ih1` initial 1 or 2 digit hour
`%ih2` initial 2 digit hour
`%ih3` initial 3 digit hour
`%in2` initial 2 minute (leading zero if needed)

Starting with version 1.9b4, a new template option has been added that allows for any user-specified string substitution, instead of only date string substitution. This is useful when none of the above template options match the time ranges in the files you wish to aggregate, or if the files are located on different disks. The syntax is as follows:

`%ch` substitute string

If you put the `%ch` template in your DSET entry, then you also need to put additional CHSUB entries in the descriptor file that contain two integers (t1 and t2) followed by a string which will be substituted for `%ch` in the data file names for the time steps beginning with
t1 and ending with t2. The CHSUB descriptor file entries have the following syntax:

`chsub t1 t2 string`

### Examples

1. Here's a set of binary files spanning a single month, where each day's worth of hourly data is contained in individual files:
   `1may92.dat
   2may92.dat
   ...
   31may92.dat`
   Three records must be modified in the data descriptor file. Note that the TDEF entry reflects the entire month's worth of data:
   `DSET ^%d1may92.dat
   OPTIONS template
   TDEF 744 linear 0z1may1992 1hr`
2. If your data set expanded, and there were more files containing hourly data for other months and years:
   `1jun92.dat
   2jun92.dat
   ...
   1jan93.dat`
   Then you would add a template for month and year in your DSET entry and extend the length of your TDEF:
   `DSET ^%d1%mc%y2.dat
   OPTIONS template
   TDEF 6624 linear 0z1may1992 1hr
   `
3. Suppose you have a set of seven netcdf files, each containing monthly data spanning a decade:
   `pr.1880_1889.nc`
   `pr.1890_1899.nc`
   `pr.1900_1909.nc`
   `pr.1910_1919.nc`
   `pr.1920_1929.nc`
   `pr.1930_1939.nc`
   `pr.1940_1949.nc`
   Then your descriptor file would include the following entries:
   `DSET ^pr.%x30_%x39.nc`
   `OPTIONS template`
   `DTYPE netcdf`
   `TDEF 840 linear jan1880 1mo`
4. Here are two netcdf files, one containing 50 years of monthly data (600 time steps), the other 100 years (1200 time steps):
   `pr.1851-1900.nc`
   `pr.1901-2000.nc`
   Your descriptor file should include the following entries:
   `DSET ^pr.%ch.nc`
   `CHSUB 1 600 1851-1900`
   `CHSUB 601 1800 1901-2000`
   `OPTIONS template`
   `DTYPE netcdf`
   `TDEF 1800 linear jan1851 1mo`
   If these two data files were located on different disks, you could write out the relevant descriptor file entries this way instead:
   `DSET %ch`
   `CHSUB 1 600 /disk1/pr.1851-1900.nc`
   `CHSUB 601 1800 /disk2/pr.1901-2000.nc`