Template Resources
Template Resources are Data Package Resources that contain one or more references(service paths) with parametrisable URLs. This means, URLs of such resources contain variables like ${time_period} that are replaced by actual values that are either taken from a selected scenario in CSIS or from a permutation of all possible values that have been added as as tags to the resource. Those two usages of Template Resources are called scenario-based resource parametrisation and parameter-based resource expansion.
As the name suggests, scenario based resource parametrisation does only work in combination with a scenario (formerly called 'study preset'. In CSIS, a scenario is understood as combination of the scenario parameters time period, emissions scenario, event frequency and optionally variation (with / without adaption). A study in CSIS may be assigned different scenarios.
Instead of creating distinct resources for each possible combination of the scenario parameters like time period and emissions scenario, only one Template Resources with an URL that contains placeholders ($parameter_name) for the predefined scenario parameters (e.g. ${time_period}, ${emissions_scenario}, ...) has to be created. Interestingly, one resource can be assigned multiple template URLs by means of the so called references.
The Template Resource Consecutive wet-days for example, contains two references: one for ENSMEAN and for ENSSTD. Note that the download paths property of the resource is not interpreted by CSIS visualisation components like Map and Table, only the references are recognized by those components. The reason for this is, that only references contain a type property, which tells the visualisation component how to handle the response (data obtained from a web service) of the requested reference URL. The reason for the distinction between paths and references is explained in this issue. For the end users creating new Data Packages and Resources it's mainly import to know that data that shall directly be visualised in CSIS tables, maps, etc. must be publicly accessible, e.g. from a WMS, through the service path (references) URLs.
The two references mentioned above contain the actual template URLs with variables for ${emissions_scenario} and ${time_period}. The template URL of reference Consecutive wet days ENSMEAN looks like:
The property type = @mapview:ogc:wms indicates, that this particular URI is understood by the Map Component, thus a respective layer will be shown on the map. Variables in the URI are replaced by the respective values (e.g. time_period = 19710101-20001231 and emissions_scenario = historical) taken from the selected scenario:
Currently selected Study scenario: Baseline Scenario, Frequent
- Time Period: 1971 to 2000 (historical)
- Emissions Scenario: Historical
- Event Frequency: Frequent (yearly)
- Study Variant: no Adaptation Options
Accordingly, the template URL ...?service=WMS&version=1.1.0&request=GetMap&layers=europe:PI_consecutive-wet-days_${emissions_scenario}_${time_period}_ensstd&srs=EPSG%3A3035&format=image/png%3B%20mode%3D8bit of Consecutive wet days ENSMEAN is parametrised as layer URL:
But why is ENSMEAN and ENSSTD and not part of the template URI, e.g. by including a third variable {$ensemble}? The reason is, that it is not part of the scenario definition. As already mentioned, a scenario consist currently of the following variables and supported values:
| variable name | variable values |
|---|---|
| STUDY_VARIANT | 'BASELINE' |
| TIME_PERIOD | 'Baseline', '20110101-20401231', '20410101-20701231', '20710101-21001231' |
| EMISSIONS_SCENARIO | Baseline', 'rcp26', 'rcp45', 'rcp85' |
| EVENT_FREQUENCY | 'Rare', 'Occasional', 'Frequent' |
Both variable names and values are fixed, supporting new variables is currently not foreseen.
Important: Variable names and respective values that shall be supported by the Template Resource have to be included as tags in the resource meta-data, in order to let CSIS visualisation components properly substitute ${variable} placeholders in the request URL. When creating or editing a Resource, the respective existing tags from the "Variables" Taxonomy have to be added as shown in the list below (screenshot from resource editor form in CSIS) :
In the list above, the tags for supported variables are rendered as follows:
- Format:
${variable}:value(Meaning) - Example: e.g.
time_period:19710101-20001231(Time Period: 1971 to 2000 (historical))
Meaning is only a workaround to resolve ambiguity that could not resolved at the level of the original actual dataset, e.g. by changing the resource URL. In some original dataset URL, the time period '1971 to 2000 (historical)' is represented by 19710101-20001231 in others as Baseline. Although it is possible to use different values for the same "meaning", it is not recommended, though. Such ambiguities should be resolved at the level of the original data source, e.g. by aligning the resource name and service request parameters (e.g. WMS getMap layers query parameter) to variable values of the "Variables" Taxonomy.
Also important to note is, that Template Resources can only be visualised, e.g. as map layer, in the context of a study that has at least one scenario defined. This means, that source resources cannot be shown a Data Package Preview Map.
Parameter-based resource expansion does not need a scenario to be selected. This experimental feature is currently supported by the Map Component only. Basically, this feature can be used to create n maps layer from one Template Resource.
Unless scenario-based resource parametrisation, which will only create one parametrised map layer where the parameter values are taken from the selected scenario, parameter-based resource expansion creates map layer for all possible combinations of parameters and their values. This is a powerful feature, but it has to be used with care: Too many parameters and allowed values per template resource will quickly fill up the Map Component's Layer Control Widget (layers list). Having dozens of layers in this list is not very user friendly. Although layers can be organised in categories by hazards, obviously this is not possible at the level of an individual template resource.
Example: A Template resource with the variables ${recurrence} and ${value} and the following allowed values for parametrising a template URL like http://.../stockholm_110_historic_O3-${recurrence}_${value}.nc
| variable name | variable values |
|---|---|
| RECURRENCE | 'yearly', 'monthly' |
| VALUE | 'mean', 'max' 'min' |
will be expanded into 6 distinct layers:
http://...&layers=stockholm_110_historic_O3-yearly_mean.nc&...http://...&layers=stockholm_110_historic_O3-monthly_mean.nc&...http://...&layers=stockholm_110_historic_O3-yearly_min.nc&...- etc.
In the example above, additional variables could be included in template resource URL like ${airquality_parameter} (O3, CO, CO2, ...) and ${period} (historic, present, future). This would further reduce the number of template resources that have to be created in CSIS data package tool. However, with only 5 different air quality parameters, already 90 layers would be added to the map layers list. Moreover, there is no check that the automatically generated layer URLs actually exists. If there is no data available for mean yearly CO2, still the layer URL http://...&layers=stockholm_110_historic_CO2-yearly_mean.nc&... would be generated and added to the map layers list.
Another disadvantage is, that there is no control on how the layer is named in the layer control list. While for "regular" resources either the name of the resource or the name of the reference is used, layers generated from expanded template resources will have automatically generated names.