# 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'})`