[[TOC]] = 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. [[Image(temporalCrs.png, center, 70%)]] 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 [http://www.schemacentral.com/sc/xsd/t-xsd_dateTime.html 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, [http://rasdaman.org:8080/def/crs/OGC/0/ 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 [http://external.opengeospatial.org/twiki_public/TemporalDWG/WebHome Temporal Domain Working Group]. These definitions are: * [http://rasdaman.org:8080/def/crs/OGC/0/AnsiDate 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). * [http://rasdaman.org:8080/def/crs/OGC/0/Temporal?expand=none 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) [http://unitsofmeasure.org/ucum.html 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/`'' (which the OGC SISSVoc resolver redirects to the UCUM web page and from which ''Petascope'' extracts the ''``''); 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 [http://external.opengeospatial.org/twiki_public/TemporalDWG/TemporalCrsUris this page] (active participation is also appreciated via [https://lists.opengeospatial.org/mailman/listinfo/temporal mailing list]). After official acknowledgment of such resources, all of them will be provided by our resolver and additionally by the official [http://www.opengis.net/def/crs/ 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=%222013-02-20T00:00:00Z%22%26uom=%22min%22%26label=%22simulation_time%22 http://rasdaman.org:8080/def/crs/OGC/0/Temporal?epoch="1970-01-01T00:00:00Z"&uom="s"&label="unix_time"]~~ * [http://www.schemacentral.com/sc/niem21/e-gml32_TemporalCRS.html http://mydomain.com/def/crs/MYAUTHORITY//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=%22real_time%22 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=%22simulation_time%22 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 [http://www.joda.org/joda-time/apidocs/org/joda/time/Duration.html ''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 [wiki:IndexCrss#Changingaxislabels 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 [https://portal.opengeospatial.org/files/?artifact_id=50140 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: {{{ #!div style="background: GhostWhite; border: 5px ridge; text-align: center; width: 70%; margin-left: auto ; margin-right: auto ;" {{{ #!html

...&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 [http://www.joda.org/joda-time/ 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 [http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateOptionalTimeParser() 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 [browser:applications/petascope/src/test/java/petascope/util/TimeUtilTest.java unit tests] or our WCS [browser:systemtest/testcases_services/test_wcs/queries 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 otherwise use our ''rasgeo'' component to handle the irregular time series directly with absolute time coordinates via the `'--z-coords'` parameter of `rasimport` (see [RasgeoUserGuide user guide] for more details). To better understand the meaining of (GML) weighting vector [http://schemas.opengis.net/gml/3.3/referenceableGrid.xsd 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'.