# Maths functions ## `pow` Arguments: `[x: Floating, exp: Floating]` Returns: `Floating` Raise a number by a specific power ## `log` Arguments: `[x: Floating, base: Floating]` Returns: `Floating` Return the logarithm of a number for a particular base, defaulting to natural log if none given ## `log10` Arguments: `[Floating]` Returns: `Floating` Returns the base-10 logarithm of the given value ## `exp` Arguments: `[Floating]` Returns: `Floating` Returns Euler's number (e) raised to the power of the value given. The inverse of log() ## `square_root` Arguments: `[Floating]` Returns: `Floating` Get the square root of the given number ## `abs` Arguments: `[Floating]` Returns: `Floating` Gives the absolute value of a number ## `min` Arguments: `[Anything, Anything]` Returns: `Anything` Returns the smaller of two values given ## `max` Arguments: `[Anything, Anything]` Returns: `Anything` Returns the largest of two values given. Also works as an aggregate function for computing the largest value across a set of values ## `round` Arguments: `[number: Floating, ndigits: Nullable[Integer]]` Returns: `Integer` Rounds a number to the closest integer, or the number of digits (decimal places) specified ## `ceil` Arguments: `[Floating]` Returns: `Integer` Round number up to the closest integer ## `floor` Arguments: `[Floating]` Returns: `Integer` Round number down to the closest integer ## `float` Arguments: `[Anything]` Returns: `Floating` Convert input to a floating point number ## `int` Arguments: `[Anything]` Returns: `Integer` Convert input to a integer number ## `maxint` Arguments: `[]` Returns: `Integer` Returns the largest positive number (maximum) that the integer type is capable of representing. ## `minint` Arguments: `[]` Returns: `Integer` Returns the largest negative number (minimum) that the integer type is capable of representing. ## `maxfloat` Arguments: `[]` Returns: `Floating` Returns the largest positive number (maximum) that the floating (point) type is capable of representing. ## `minfloat` Arguments: `[]` Returns: `Floating` Returns the largest negative number (minimum) that the floating (point) type is capable of representing. ## `inf` Arguments: `[]` Returns: `Floating` Returns a floating point number that can be used to represent infinity. ## `negative_inf` Arguments: `[]` Returns: `Floating` Returns a floating point number that can be used to represent negative infinity ## `norm_cdf` Arguments: `[x: Floating, mean: Floating, stddev: Floating]` Returns: `Floating` Cumulative probability distribution function from a normal curve The equivalent of this function in Excel is: NORM.DIST(x, scale, shape, 1) Or in Python: `scipy.stats.norm(mean, stddev).cdf(x)` Implementation uses `org.apache.commons.math3.distribution.NormalDistribution cumulativeProbability()` (Javadoc available online) ## `norm_pdf` Arguments: `[x: Floating, mean: Floating, stddev: Floating]` Returns: `Floating` Probability Density Function (`PDF`) for a given point in a normal distribution The equivalent of this function in Excel is: NORM.DIST(x, scale, shape, 0) Or in Python: `scipy.stats.norm(mean, stddev).pdf(x)` Implementation uses `org.apache.commons.math3.distribution.NormalDistribution density()` (Javadoc available online) ## `norm_ppf` Arguments: `[x: Floating, mean: Floating, stddev: Floating]` Returns: `Floating` Percent Point Function (`PPF`). Returns the inverse Cumulative Distribution Function from a normal curve, where x is the desired probability between 0.0 and 1.0 For example, to find the value in a standard normal distribution that 97.72% of values are less than or equal to, use: `norm_ppf(0.9772, 0, 1)` The equivalent of this function in Python is: `scipy.stats.norm(mean, stddev).ppf(x)` Implementation uses `org.apache.commons.math3.distribution.NormalDistribution inverseCumulativeProbability()` (Javadoc available online) ## `lognorm_cdf` Arguments: `[x: Floating, scale: Floating, shape: Floating]` Returns: `Floating` Cumulative probability distribution function from a log-normal curve. Where shape is σ (standard deviation) and scale is μ (mean), both as the log of the distribution. The equivalent of this function in Excel is: `LOGNORM.DIST(x, scale, shape, 1)` Or in Python: `scipy.stats.lognorm(s=shape, scale=exp(scale)).cdf(x)` Implementation uses `org.apache.commons.math3.distribution.LogNormalDistribution cumulativeProbability()` (Javadoc available online) ## `lognorm_pdf` Arguments: `[x: Floating, scale: Floating, shape: Floating]` Returns: `Floating` Probability Density Function (PDF) for a given point in a normal distribution. Where shape is σ (standard deviation) and scale is μ (mean), both as the log of the distribution. The equivalent of this function in Excel is: `LOGNORM.DIST(x, scale, shape, 0)` Or in Python: `scipy.stats.lognorm(s=shape, scale=exp(scale)).pdf(x)` Implementation uses `org.apache.commons.math3.distribution.LogNormalDistribution density()` (Javadoc available online) ## `lognorm_ppf` Arguments: `[x: Floating, scale: Floating, shape: Floating]` Returns: `Floating` Percent Point Function (`PPF`). Returns the inverse Cumulative Distribution Function from a log normal curve, where x is the desired probability between 0.0 and 1.0 For example, to find the value in a standard log-normal distribution that 97.72% of values are less than or equal to, use: `lognorm_ppf(0.9772, 0, 1)` The equivalent of this function in Python is: `scipy.stats.lognorm(s=shape, scale=exp(scale)).ppf(x)` Implementation uses `org.apache.commons.math3.distribution.LogNormalDistribution inverseCumulativeProbability()` (Javadoc available online) ## `polynomial` Arguments: `[x: Floating, c: List[Floating]]` Returns: `Floating` Computes a polynomial expression, denoted by the set of coefficients 'c' (starting at x⁰, x, x², etc) For example, 'polynomial(x: 4, c: [7.0, -5.0, 0.0, 1.0])' will calculate: 7 - 5x + x³ where x=4. The equivalent of this function in Python is: numpy.polynomial.polynomial.polyval(x, c) Implementation uses org.apache.commons.math3.analysis.polynomials.PolynomialFunction (Javadoc available online) ## `random_uniform` Arguments: `[start: Floating, stop: Floating]` Returns: `Floating` Returns a uniformly distributed random number between start (inclusive) and stop (exclusive). For comparison, the equivalent of this function in Python is `random.uniform(start, stop)`. However, note the actual implementation uses `java.util.Random.nextDouble()`. Use the `random-seed` RiskScape parameter to make the randomness reproducibly consistent. ## `random_norm` Arguments: `[mean: Floating, stddev: Floating]` Returns: `Floating` Returns a random number from the given normal distribution The equivalent of this function in Python is: `random.normalvariate(mean, stddev)` Use the `random-seed` RiskScape parameter to make the randomness reproducibly consistent ## `modulo` Arguments: `[dividend: Floating, divisor: Floating]` Returns: `Floating` Compute the remainder when the `dividend` is divided by the given `divisor` ## `random_choice` Arguments: `[items: List[Nullable[Anything]], weights: Nullable[List[Floating]]]` Returns: `Nullable[Anything]` Picks an item from the list at random, or with an optional weighted probability This function is similar to the random.choice() variants in Python Use the `random-seed` RiskScape parameter to make the randomness reproducibly consistent ## `scale` Arguments: `[input_value: Anything, scale_factor: Floating]` Returns: `Anything` Scales the numeric `input_value` by multiplying it by the `scale_factor` argument. If the `input_value` is a struct it will scale the numeric members of the struct and leave other members untouched. ## `mean` Arguments: `[List[Nullable[Anything]]]` Returns: `Nullable[Anything]` Aggregate function for calculating a mean value across a group, e.g. `group(mean(damage), by: region)`. Can also be used in a normal expression to calculate the mean value of numeric items in a list. ## `count` Arguments: `[List[Nullable[Anything]]]` Returns: `Nullable[Anything]` Aggregate function for counting all non-null elements in a group. The exception to this is for boolean values where only those that are true are counted. Can also be used with a list in a normal expression. ## `sum` Arguments: `[List[Nullable[Anything]]]` Returns: `Nullable[Anything]` Aggregate function for calculating a sum of all non-null values in a group. Also works on lists of numbers in a normal expression. ## `median` Arguments: `[List[Nullable[Anything]]]` Returns: `Nullable[Anything]` Aggregate function for calculating the median value across a group, e.g. `group(median(damage), by: region)`. Can also be used in a normal expression to calculate the median value of numeric items in a list. ## `mode` Arguments: `[List[Nullable[Anything]]]` Returns: `Nullable[Anything]` Aggregate function for calculating the mode (most observed value) across a group, e.g. `group(mode(damage), by: region)`. Can also be used in a normal expression to calculate the mode from a list. ## `percentiles` Arguments: `[items: List[Nullable[Anything]], percentiles: List[Integer]]` Returns: `Nullable[Anything]` Aggregate function that returns the values at the desired percentiles across a group, e.g. `group(percentiles(damage, percentiles: [50, 90]), by: region)` will return the 50th and 90th percentiles. Can also be used in a normal expression to return the percentiles of numeric items in a list. Uses the nearest-rank exclusive method. ## `percentile` Arguments: `[items: List[Nullable[Anything]], percentile: Integer]` Returns: `Nullable[Anything]` Aggregate function that returns the value at the desired percentile across a group, e.g. `group(percentile(damage, percentile: 90), by: region)` will return the 90th percentile. Can also be used in a normal expression to return the percentile of numeric items in a list. Uses the nearest-rank exclusive method. ## `stddev` Arguments: `[List[Nullable[Anything]]]` Returns: `Nullable[Anything]` Aggregate function for calculating the standard deviation across a group, e.g. `group(stddev(damage), by: region)`. Can also be used in a normal expression to calculate the median value of numeric items in a list. ## `create_continuous` Arguments: `[x-values: List[Anything], apply-to: λ(x-value), apply-log-to-x: Bool]` Returns: `ContinuousCurve(xvalues=[], returnType=Anything)` Creates a 'continuous curve' that will more efficiently evaluate a computationally expensive loss function for probabilistic modelling. Pass the curve result to `apply_continuous()` where you would normally call your loss function, e.g. `apply_continuous(curve, hazard_value)`. This is useful when there are a large number of hazard intensity values to process, and they all fall into a similar range of values. Instead of executing the loss function for every single hazard intensity value, the function is executed at most once for each of the `x-values`. For example, `create_continuous([0.1, 0.2, 0.3], x -> my_loss_function(exposure, x)` will only execute `my_loss_function` at most three times, once each for 0.1, 0.2, 0.3. Any hazard intensities that fall between 0.1 and 0.3 will be interpolated based on the function's return values. Be careful that the `x-values` you specify accurately reflect the range of hazard intensities you expect. The min or max x-values will be used if the hazard intensity falls outside this range. ## `apply_continuous` Arguments: `[function: ContinuousCurve(returnType=Anything), x-value: Floating, y-value: Nullable[Floating]]` Returns: `Floating` Apply an x-value to a pre-computed curve using interpolation. Used alongside `create_continuous` to perform large probabilistic analysis with a computationally expensive loss function. ## `stack_continuous` Arguments: `[List[Nullable[Anything]]]` Returns: `Nullable[Anything]` Aggregate function for 'stacking' a set of continuous curves in to a single one. Can be used as an optimization for probabilistic modelling to cut down on the number of function calls - the function can be called once per hazard site (instead of once per exposure) by grouping all the exposures by site and then stacking their consequence curves using this function. ## `apply` Arguments: `[function: Function(ƒ()=Anything), args...: Anything]` Returns: `Anything` Call a function that is part of the expression scope (rather than by name), e.g. `apply(function, x_value)`. Used for calling functions that have been created by another function, such as with mathematical modelling functions like curve fitting. The first argument, `function` is the function that you wish to call. This is not the identifier of a function from the your project, but a part of the expression scope, i.e. a member of a tuple. These are typically returned from some other function creating function. This function is just a generic way to call any function when it is part of your data. Any extra arguments given to the apply function are taken to be arguments to the function `apply` calls. These arguments must match the calling function's types exactly. ## `fit_curve` Arguments: `[x-value: Floating, y-value: Floating, fitters: Nullable[{}]]` Returns: `{function=>Function(ƒ(Floating)=Floating), fit=>Text, score=>Floating}` Aggregate function for fitting a mathematical curve to a set of two dimensional data points (i.e. X, Y values). This function attempts to fit a curve to these points, picking the best-scoring curve from all curve types that have been registered. The return value contains the details of the best-fitting curve, which includes: the curve 'function', the 'fit' ID (i.e. `continuous`, `linear`, `powerlaw`, etc), and the r² 'score' for this curve against the original data points. Passing the returned function to the `apply` function will sample the curve, i.e. determine the Y value for a given X value. For example, use the expression `fit_curve(x-value: loss, y-value: probability) as loss_curve` to fit a curve to a set of probabilistic losses. You can then use `apply(loss_curve.function, threshold)` to determine the probability (Y value) of the given `threshold` loss (X value) being reached. The optional 'fitters' argument describes specific curves(s) that should be used. For example, using `fit_curve(loss, probability, fitters: {'continuous'})` would only attempt to fit a continuous curve to the given data points. The default is to attempt to fit all possible curves. Note that when selecting from multiple curves (the default), you can refer to the 'fit' ID in the return value to verify the best-fit that was actually chosen. ## `trapz` Arguments: `[function: Function(ƒ()=Anything), a: Floating, b: Floating, intervals: Integer]` Returns: `Floating` Estimates the area under the curve provided by `function` between points `a` and `b`. Estimation is performed using the trapezoidal rule (https://en.wikipedia.org/wiki/Trapezoidal_rule) The provided function should accept a single floating argument and also return a floating result. Note that for average annual loss (AAL) calculations, it is simpler to use the `aal_trapz` function. ## `aal_trapz` Arguments: `[loss: Floating, ep: Floating]` Returns: `Floating` Aggregate function for calculating an Average Annual Loss (AAL) for hazard-based probabilistic data using trapezoid integration Aggregates a series of event loss data-points to calculate the AAL. The event loss data points are plotted as piecewise linear x,y coordinates, where x is the exceedance probability (EP) and y is the loss. The AAL is then the area under the loss/EP curve, which is determined using trapezoid integration. This function produces a similar result to `numpy.trapz(x=[0.0]+EPs, y=[max(losses)]+losses)`. The extra EP=0.0 data-point represents the area under the loss/EP curve beyond the maximum known loss (these losses can be inferred to be greater than or equal to the max loss). Note that any null loss values are treated as zero. Probability values must fall between 0.0 and 1.0 and cannot be duplicated. This function can also be used outside of aggregate 'group' steps by passing it the losses and exceedance probabilities as lists. This approach is more memory-efficient when calculating a large number of AAL calculations, such as a per-property AAL.