Time dimension(s) handling in Petascope

In this page we will describe how time can be embedded in the definition of a spatio-temporal coverage for WCS and WCPS web services, by means of temporal Coordinate Reference Systems (CRSs). Attachment(s) are also included for further insights on the matter.

Temporal CRSs

Thanks to the [SecoreUserGuide SECORE] resolver, time can be embedded in the n-dimensional CRS space just as another dimension: temporal CRS definitions can be used in composition with geodetic ones to create a unique space-time aquarium for the coverage.

Temporal CRSs (gml:TemporalCRS) are always 1D and are rather simple entities: in a few words, they count the amount of a certain time step from an epoch. No stratigraphic calendars, leap seconds, eras and eons are involved here: simple linear counting of time units. Time units are the Unit of Measure (UoM) of the reference system.

Like geodetic datums bind the set of geographic coordinates to an absolute position on Earth (or planetary object), temporal datums link the temporal axis to an absolute moment in time. Indeed a temporal datum is essentially an "origin" (the epoch) expressed through an ​ISO:8601 datetime representation. Technically, this representation is of type ​xsd:dateTime, which says:

The type xsd:dateTime represents a specific date and time in the format CCYY-MM-DDThh:mm:ss.sss, which is a concatenation of the date and time forms, separated by a literal letter T. All of the same rules that apply to the date and time types are applicable to xsd:dateTime as well. An optional time zone expression may be added at the end of the value. The letter Z is used to indicate Coordinated Universal Time (UTC). All other time zones are represented by their difference from Coordinated Universal Time in the format +hh:mm, or -hh:mm. These values may range from -14:00 to 14:00. For example, US Eastern Standard Time, which is five hours behind UTC, is represented as -05:00. If no time zone value is present, it is considered unknown; it is not assumed to be UTC.

At the time being, ​we provide a first basic set of Temporal CRSs (T-CRSs) which (among others) are under review process by the OGC-NA authority and represents part of the effort of the newly born (public) OGC ​Temporal Domain Working Group. These definitions are:

• ​ANSI date (OGC:AnsiDate) : linear count of days (labelled 'ansi') since 1^st of January 1601, 00h00 UTC (note that decimal coordinates are possible to reference fraction of the day).
• ​parametrized temporal CRS (OGC:Temporal) : parametrized CRS for the user-friendly definition of a custom T-CRS: it resolves to a concrete definition of T-CRS as long as the epoch and the UoM are explicitly set in the query of the URI (and optionally an axis label and an axis direction: defaults are 't' and 'future'). UoMs can be defined as either i) ​UCUM c/s codes, ii) actionable URIs pointing to valid GML definition of UoMs or iii) URIs like http://www.opengis.net/def/uom/UCUM/0/<code> (which the OGC SISSVoc resolver redirects to the UCUM web page and from which Petascope extracts the <code>); please note that our ISO timestamp parser relies on UCUM codes, so using unconventional abbreviations or definitions is not recommended here.

For a full list of time resources under review by OGC-NA please visit ​this page (active participation is also appreciated via ​mailing list). After official acknowledgment of such resources, all of them will be provided by our resolver and additionally by the official ​opengis servers.

Still, especially thanks to our customizable OGC:Temporal CRS, it is possible to start deploying spatio-temporal (but also purely temporal) coverages via rasdaman/Petascope.

While all kinds of T-CRS are possible with OGC:Temporal, you might decide to create your own definition so to have a more meaningful URI. This can be achieved relatively easily in spite of the verbose GML representation. What is actually important for Petascope in a T-CRS is:

• the datum origin (gml:origin) (we assume UTC as default time zone if that is not specified)
• the axis time step (gml:CoordinateSystemAxis/@uom)
• the axis label (gml:axisAbbrev)

After defining it, then you might want to replace your OGC:Temporal parametrized URI of, say, Unix time, with your URI:

• ​http://rasdaman.org:8080/def/crs/OGC/0/Temporal?epoch="1970-01-01T00:00:00Z"&uom="s"&label="unix_time"
• ​http://mydomain.com/def/crs/MYAUTHORITY/<version>/UnixTime

Parametrizations are also useful when one needs to compound together more than one T-CRS of the same kind: this can happen especially e.g. when numerical models are applied daily (real time axis) targeting a set of future days (simulation time axis). Using the same T-CRS makes sense here (let's pick OGC:AnsiDate for example), but in order to avoid a clash in the labels of the axes we need to actually use two different URIs in the composition of the CRS, for instance:

• real-time : ​http://rasdaman.org:8080/def/crs/OGC/0/AnsiDate?axis-label="real_time"
• simulation-time : ​http://rasdaman.org:8080/def/crs/OGC/0/AnsiDate?axis-label="simulation_time"

In case you want to exploits the parametrizations of 'OGC:Temporal' CRS or you want to create a new one, you can adopt the following UCUM-compliant time units:

    // Standard codes for supported temporal Unit of Measures (which provide ISO8601 interface to the user)
    // http://unitsofmeasure.org/ucum.html
    public static final String UCUM_MILLIS               = "ms";
    public static final String UCUM_SECOND               = "s";
    public static final String UCUM_MINUTE               = "min";
    public static final String UCUM_HOUR                 = "h";
    public static final String UCUM_DAY                  = "d";
    public static final String UCUM_WEEK                 = "wk";
    public static final String UCUM_MEAN_JULIAN_MONTH    = "mo_j";
    public static final String UCUM_MEAN_GREGORIAN_MONTH = "mo_g";
    public static final String UCUM_SYNODAL_MONTH        = "mo_s";
    public static final String UCUM_MONTH                = "mo";
    public static final String UCUM_MEAN_JULIAN_YEAR     = "a_j";
    public static final String UCUM_MEAN_GREGORIAN_YEAR  = "a_g";
    public static final String UCUM_TROPICAL_YEAR        = "a_t";
    public static final String UCUM_YEAR                 = "a";

Due to the characteristics of the ​'Duration' Joda-time class, the highest time resolution achievable now is milliseconds ![ms]. For further info on CRS parametrization and composition, see the SECORE [SecoreUserGuide user guide] and also this section.

Using and understanding time in WCS/WCPS

Once a T-CRS has been successfully embedded in the overall native CRS of a coverage, the WCS/WCPS services will accept both numerical and alphanumerical time coordinates on the time axis/axes.

In the first place, one should be aware of the difference between the time resolution (UoM) of the T-CRS and the adopted offset vector ruling the spacing along time for the coverage: with 1-norm vectors there is no such difference, however it is perfectly possible to use either a bigger vector (e.g. equal to 7 on a day-resolution T-CRS for weekly data) or a fractional one. For more on offset vectors please refer to the Petascope [PetascopeUserGuide user guide].

As with normal spatial axes, a WCS/WCPS subsets shall define numeric trimming and slicings on a CRS dimension. The ​standard additionally adhere to EBNF syntax [IETF 2616], allowing tokens inside double-quotes: on time dimensions then ​ISO:8601 datetime representations can be used in place of the usually less friendly numeric time coordinates:

...&service=WCS&request=GetCoverage&subset=ansi(150905)&...

...&service=WCS&request=GetCoverage&subset=ansi("2014-02-28")&...

Implementation-wise, the support for ISO datetime is extended by Petascope thanks to the ​Joda-Time Java library. The datetime formatter used to convert literal to numeric time representations is the official ISO date formatter with optional time, which then permits dates only or dates plus time (plus time zone shifts). When a time zone is not defined, the library takes the default time zone of the underlying JVM, hence it was decided to force a UTC default time zone instead, to avoid platform-dependent behaviors.

Formally, the allowed input datetime strings are (taken from ​Joda-Time API):

date-opt-time     = date-element ['T' [time-element] [offset]]
date-element      = std-date-element | ord-date-element | week-date-element
std-date-element  = yyyy ['-' MM ['-' dd]]
ord-date-element  = yyyy ['-' DDD]
week-date-element = xxxx '-W' ww ['-' e]
time-element      = HH [minute-element] | [fraction]
minute-element    = ':' mm [second-element] | [fraction]
second-element    = ':' ss [fraction]
fraction          = ('.' | ',') digit+

For practical examples see our related unit tests or our WCS systemtest queries n.{27-28, 35-37}.

Regarding the responses to a WCS request, time is encoded in its numerical form. The T-CRS definition is the key to decode the meaning of such numbers: while sometimes well-known T-CRS can be used (as Unix time), the general principle is that the time coordinate T' is the representation of (v_t*T') time steps (i.e. T-CRS UoMs) from the epoch of the T-CRS, being v_t the scalar norm of the offset vector of the coverage along time. In order to ease the understanding of a GML response, it is foreseen the use of gml:EnvelopeWithTimePeriod (see #678) to additionally provide literals of time in the bbox of a coverage.

Irregular time series

In addition to the inclusion of time in the compound CRS where a coverage is located, importing irregular time series in [PetascopeUserGuide Petascope] is also possible, although this not connected to the definition of perhaps a different T-CRS. The topology of a coverage (along the time dimension in this case) is independent of the way time is measured.

To import irregular time series you can either manually insert in petascopedb the so-called vector weighting coefficients of the offset vector along time (see the Petascope [PetascopeDevGuide dev-guide]) or use the mechanism provided by GeneralGridCoverage in OGC CIS 1.1.

To better understand the meaining of (GML) weighting vector ​coefficients, the general principle to decode numeric time coordinates is that the time coordinate T' is the representation of (c_T' * v_t) time steps (T-CRS UoM) from the epoch of the T-CRS, being v_t the scalar norm of the offset vector of the coverage along time and c_T' the coefficient associated to T'.