Experimental functions (beta plugin)
sample_n_closest
Arguments: [geometry: Geom, coverage: Coverage[Anything], n: Integer]
Returns: List[{geometry=>Geom, sampled=>Anything}]
Returns a list of n values and geometries from a coverage, sorted closest first.
Each list item item contains a geometry attribute, which is the geometry of the underlying coverage (e.g. a point stored in a nearest-neighbour coverage), and a sampled attribute, which is the value returned from the coverage at that specific location.
triangulate
Arguments: [geometry: Geom, samples: List[{geometry=>Geom, sampled=>Floating}]]
Returns: Nullable[Floating]
Convert a list of samples into a single value using barycentric interpolation.
Works with sample_n_closest to interpolate sampled values from a coarse grid to increase accuracy, for example triangulate(sample_n_closest(building, shaking_data, 3)).
If the given list of samples is empty, the function returns null. If it contains a single item, that sample’s value is returned. If the list contains two samples, linear interpolation is performed. If the list contains more than three samples, only the first three are used - this function assumes the list is already sorted by distance, like sample_n_closest does.
switch
Arguments: [on: Anything, default: Anything, cases: List[{in=>List[Nullable[Anything]], return=>Anything}]]
Returns: Anything
Returns a result based on the on value. The given cases are searched for one that contains the on value in the in list. If the value is matched then return is returned else searching continues. The default value is returned if there are no matches.
Note that the cases argument must be constant.
E.g switch(on: 'bicycle', default: 'unknown', cases: [{in: ['bicycle', 'motorbike'], return: '2'},{in: ['car'], return: '4'}]) will return ‘2’.
list_to_tuple
Arguments: [list: Nullable[List[Nullable[Anything]]], upto: Integer, prefix: Nullable[Text]]
Returns: Anything
Returns a tuple containing an attribute for each item in the given list, until the upto limit is reached. This function has been deprecated. Please use list_to_columns instead.
The member names are formed from the prefix (defaults to empty string) and the list position. E.g the expression list_to_tuple(list, 2, 'prefix') will return the tuple {prefix0: item0, prefix1: item1}. If the given list does not contain enough items to fill the tuple then the missing attributes will have a null value.
losses_by_period
Arguments: [losses: List[Floating], return-periods: List[Floating], investigation-time: Integer, options: {mode=>WithinSet(type=Text, allowed=[percentile, ranked_closest])}]
Returns: List[Floating]
Calculates loss metrics, such as Probable Maximum Loss, Occurrence Exceedance Probability, or Aggregate Exceedance Probability for specific return periods. (beta)
The default mode is percentile. In this mode losses are interpolated using a percentile based approach where the percentile is (1 - 1/RP) * 100.
With the ranked_closest mode each loss is assigned an RP. Then the loss closest to the desired RP is returned. If there are not enough event losses for the requested return period, then zero is returned for the event loss.
The investigation-time argument specifies the effective time period that the losses cover. E.g. losses_by_period(losses, [1000, 250, 100, 50], investigation-time: 10000) as PML calculates metrics for a 10,000 year period. The first requested return-period (1000) corresponds to the 10th largest loss (i.e. a 10 in 10000-year event)
remove_attr
Arguments: [original: Anything, remove: Anything]
Returns: {}
Returns a copy of original with the attribute specified by remove removed. remove can be either a string or a struct containing the attributes to be removed.
For example: remove_attr(exposure, 'geom') returns a new struct with all the members of exposure except for geom, while remove_attr(exposure, {exposure.geom, exposure.area}) removes both the geom and area attributes.
to_relation
Arguments: [coverage: Coverage[Anything]]
Returns: Relation[{}]
Converts a coverage into a relation so that each data point in the coverage can be treated as a separate row of data. This can be useful when dynamically loading a series of rasters as exposure data, such as population rasters.
This function can be combined with the unnest pipeline step to turn the converted relation into individual rows of data. For example, select({*, to_relation(bookmark('my-raster')) as grid_cell}) -> unnest(grid_cell)
expression_text
Arguments: [expression: Nullable[Anything]]
Returns: Text
Returns the given expression almost verbatim as a text string. Useful if you need to display a pipeline parameter in a custom error or warning message
list_contains
Arguments: [list: List[Nullable[Anything]], item: Nullable[Anything]]
Returns: Bool
Returns true if the given list contains the given item.
reduce
Arguments: [values: List[Nullable[Anything]], combine: λ(lhs,rhs)]
Returns: Anything
Advanced function for transforming a list in to something else by performing a functional reduction, e.g. reduce([1, 2, 3], (memo, val) -> memo + val) performs a sum of elements in the list.
select_attr
Arguments: [struct: Anything, pattern: Text, replacements: Nullable[List[Text]]]
Returns: {}
Returns the subset of attributes that match the given pattern. This is useful when several attributes of interest have a similar naming pattern. See also get_attr(), which can be used to return a single exact attribute match.
For example, select_attr({building_loss: 100, building_damage: 0.1, contents_loss: 50, contents_damage: 0.2}, 'building') would return {building_loss=100, building_damage=0.1}
The pattern argument is a regular expression, so for example '^building' will only match attributes that start with ‘building’, whereas 'building$' will only match attributes that end with ‘building’. Refer to https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html for more information on supported regular expressions.
Advanced users can also rename the attributes using the optional replacements argument. Regular expression capture groups (denoted in brackets) are used to match the part(s) of the attribute name to replace. For example, select_attr({building_loss: 100, building_count: 2}, '(building)', ['total']) would replace ‘building’ with ‘total’ in the struct, and return {total_loss=100, total_count=2}. There should be a replacement for each capture group, for example: select_attr({total_commercial_building_loss: 100, total_residential_building_loss: 200}, '^(total_).*(loss)', ['', 'AAL']) would return {commercial_building_AAL=100, residential_building_AAL=200}
lazy_lookup
Arguments: [key-type: Text, mapping-function: λ(key), options: {maximum_size=>Integer, initial_capacity=>Integer}]
Returns: LookupTable(key=Anything, value=Anything)
Produces a lookup table that will accept the given key-type and use the mapping-function to derive the lookup value. The mapping-function is only called for key values that are requested and these values are cached in the lookup table should they be required again.
For example lazy_lookup('integer', key -> expensive_function(key)) will create a lookup table that is backed by the expensive_function.
Note that nullable types are not allowed for the key-type or the mapping-function return type.
The lazy_lookup function supports some advanced options for tuning caching behaviour:
maximum_size- limits how many entries can be stored in the cache. If exceeded, least recently used items are removed first.initial_capacity- a size for the cache when created. Setting it high will prevent expensive resizing operations during a model run, but setting it too high can waste memory.
call
Arguments: [function: Text, arguments: {}, options: {message=>Text}]
Returns: Text
Utility function for calling a function using its name (as text), which allows function calls to be parameterized.
For example call('my_loss_function', {exposure, hazard}) is the same as my_loss_function(exposure, hazard). This can be parameterized to allow users of the model to swap in a custom function without having to change the model pipeline, e.g call($loss_function, {exposure, hazard}). See the pipeline-parameters section in the documentation for more details.
Note that the only order of the attributes in the arguments struct determines how they will be passed to the target function. Any keyword arguments in the target function will be ignored. It does not matter what you name the attributes in the arguments struct, only the attribute order will be used.
The message option may be used to customize the error message users will be given if the given function is not compatible with the given arguments. For example call('my_loss_function', {exposure, hazard}, options: {message: 'requires exposure of the building type, and floating hazard'})