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.