utils_math

utils_math

Numerical and mathy utilities like math function that can be used for parametrisation of otherwise constant parameters. .

Functions

Name Description
asym_trapezoidal Specify an asymmetric trapezoidal ‘wave’ profile like the one used
box_gamma Generate a time signal which is 0 up to a ‘start’ time; 1 from
double_sigmoid_exp Calculate a stair-like function with 3 steps using two exponential
double_sigmoid_tanh This function simulates a stair-like function with 3 steps
gompertz_dfun Compute the derivative of the Gompertz function with respect to x for a
gompertz_fun Compute the Gompertz function for a given set of parameters.
sigmoid Compute a sigmoid-like function. The range of x is between [0, max_x].

asym_trapezoidal

utils_math.asym_trapezoidal(
    x,
    period=365.0,
    peak_start_doy=45.0,
    ramp_up_dur=15.0,
    ramp_dw_dur=25.0,
    cutoff_dur=0.0,
    max_amp=1.0,
)

Specify an asymmetric trapezoidal ‘wave’ profile like the one used in Gauld et al 2018 and Kraay et al 2024. Args: x (array-like): The array of x values at which the function is evaluated, usually time (in days). period (float): The period, in days, over which the seasonal pattern repeats. peak_start_doy (float): The day of the year (doy) at which the environmental exposure reaches its peak/plateau. ramp_up_dur (float): Duration, in days, of the period over which the environmental exposure route increases seasonally. ramp_dw_dur (float): Duration, in days, of the period over which the environmental exposure route descreases seasonally. cutoff_dur (float): Duration, in days, in which environmental exposure halts during the low season max_amp (float): usually a number between 0 and 1 with the maximum modulating scaling factor of exposure to the environment Returns: (ndarray): An array of values corresponding to the input asym_trapezoidal(x) values.

box_gamma

utils_math.box_gamma(x, start, box_duration, shape, rate)

Generate a time signal which is 0 up to a ‘start’ time; 1 from ‘start’ until ‘start + box_duration’, and from ‘start + box_duration’ decays as a gamma function.

Reverts to box exponential if shape = 1, where rate = 1/dur

Parameters

Name Type Description Default
x numpy.ndarray The array of points at which we calculate the signal, usually time. required
start numpy.ndarray The start time of the box_duration in the signal. required
box_duration numpy.ndarray The duration for which the signal remains at 1. required
shape numpy.ndarray the shape parameter for gamma decay required
rate numpy.ndarray the rate parameter for gamma decay required

Returns

Name Type Description
numpy.ndarray: The resulting signal as an array.

double_sigmoid_exp

utils_math.double_sigmoid_exp(x, l1, l2, l3, x_12, x_23, s12, s23)

Calculate a stair-like function with 3 steps using two exponential sigmoid functions.

This function simulates a stair-like characteristic with 3 steps (l1, l2, l3). The transition from l1 to l2 occurs around the point x_12, and from l2 to l3 around point x_23.

The steepness between any two levels is governed independently by s12 and s23 respectively.

Parameters

Name Type Description Default
x float or numpy.array Input data. required
l1, l2, l3 float y-levels for each step. required
x_12, x_23 float x-points that indicate halfway between two levels. required
s12, s23 float Steepness of the curve between l1 and l2, and l2 and l3, required

Returns

Name Type Description
float or numpy.array: the function evaluated at x

double_sigmoid_tanh

utils_math.double_sigmoid_tanh(x, l1, l2, l3, x_12, x_23, s=1.0)

This function simulates a stair-like function with 3 steps (l1, l2, l3), using a single specified steepness value (s) for the hyperbolic tangent.

l1> l2 > l3 or l1 < l2 < l3

Parameters

Name Type Description Default
x float or numpy.array Input data. required
l1, l2, l3 float y-levels for each step. required
x_12, x_23 float x-points that indicate halfway between two levels. required
s float Steepness of the curve between two levels. The larger s is, the closer to a step-like stair function we get. 1.0

Returns

Name Type Description
float or numpy.array: y-values.

Example

import numpy as np import typhoidsim.utils_math as tyum x = np.arange(1_000_000, 60_000_000, 1024) tyum.double_sigmoid_tanh(x, 2.235, 2.002, 1.5487, 5_050_000, 55_000_000, 1)

gompertz_dfun

utils_math.gompertz_dfun(x, a, b, c)

Compute the derivative of the Gompertz function with respect to x for a given set of parameters.

This function is used in ecology for modelling ageing processes.

The derivative of the Gompertz function is defined as: f’(x) = a * b * c * exp(-(b / exp(c * x)) - c * x)

Arguments x (array-like): The array of x values at which the function is evaluated a (float): The asymptote of the Gompertz function as x approaches infinity. b (float): Displacement along the x-axis c (float): The growth rate

Returns

Name Type Description
ndarray An array of derivative values corresponding to the input x values.

gompertz_fun

utils_math.gompertz_fun(x, a, b, c)

Compute the Gompertz function for a given set of parameters. This function is used for describing mortality and ageing-like processes.

See: https://en.wikipedia.org/wiki/Gompertz_function

The Gompertz function is defined as: f(x) = a * exp(-b * exp(-c * x))

Arguments x (array-like): The array of x values at which the function is evaluated a (float): The asymptote of the function as x approaches infinity. b (float): Displacement along the x-axis c (float): The growth rate

Returns

Name Type Description
ndarray An array of y values corresponding to the gomeprtz function
evaluated at the input x values.

sigmoid

utils_math.sigmoid(x, max_x, slope)

Compute a sigmoid-like function. The range of x is between [0, max_x]. The values of returned by the function are always between 0-1, as they often represent probabilities.

This function is used in the age-based exposure mechanism in typhoid.

Parameters

Name Type Description Default
x array - like The array of x values at which the function is evaluated required
max_x float The asymptote of the function as x approaches infinity. required
slope float The slope parameter that controls how ‘fast’ we reach required

Returns

Name Type Description
ndarray An array of y values corresponding to the sigmoid-like function evaluated at the input x values – which are expected to represent age.