dates interface documentation

[stuckyb]

We've recently overhauled the interface for specifying dates, and the new system needs to be explained in the user documentation. Here is an outline of all key details:

• Single dates and simple date ranges are specified with the parameter dates. This parameter can express:
  • one or more individual dates in "YYYY", "YYYY-MM", or "YYYY-MM-DD" format: 1980-01-12, 1980-01-12,1990-02-14, 1980,1982,1990
  • simple date ranges: 1980:1990, 1980-01-12:1981-01-12
  • combinations of single dates and simple ranges: 2000-1,2005-1,2010-1:2010-6
• More complicated date patterns are specified with the parameters years, months, and days (YMD). These parameters can express:
  • single values: 1980, 4, 1980,1981, 4,8,10
  • ranges: 1980:1990, 4:20
  • ranges with a custom increment: 1980:1990+5, 4:20+2
  • combinations of the above: 1,10:20+2,28

If dates is provided, the YMD date parameters will be ignored.

For the dates interface, leading 0s are optional in "MM" and "DD" strings. For example, 1980-01-01 and 1980-1-1 are both valid.

For the YMD interface, the last day in a month or year can be specified by using N instead of an integer. For example: 1,10,N, 1:N, 20:N.

Ranges are inclusive of their endpoints unless the endpoint does not correspond with the step size increment.

Date grain is inferred from the specificity of dates or, for the YMD parameters, as follows:

• If years is used by itself, the grain is annual.
• If years and months are used together, the grain is monthly.
• If years and days are used together, the grain is daily and days is interpreted as day of year.
• If years, months, and days are used together, the grain is daily and days is interpreted as day of month.
• All other YMD parameter combinations are invalid.

[HeatherSavoy-USDA]

Note: current documentation is still listing the '-' instead of ':' format for ranges