fims_math.hpp File Reference

A collection of mathematical functions used in FIMS. More...

#include <cmath>
#include <random>
#include <sstream>
#include "../interface/interface.hpp"
#include "fims_vector.hpp"
#include "def.hpp"

Go to the source code of this file.

Functions
template<class Type>
const Type	fims_math::logistic (const Type &inflection_point, const Type &slope, const Type &x)
	The general logistic function.
template<class Type>
const Type	fims_math::logit (const Type &a, const Type &b, const Type &x)
	A logit function for bounding of parameters.
template<class Type>
const Type	fims_math::inv_logit (const Type &a, const Type &b, const Type &logit_x)
	An inverse logit function for bounding of parameters.
template<class Type>
const Type	fims_math::double_logistic (const Type &inflection_point_asc, const Type &slope_asc, const Type &inflection_point_desc, const Type &slope_desc, const Type &x)
	The general double logistic function.
template<class Type>
const Type	fims_math::ad_fabs (const Type &x, Type C=1e-5)
template<typename Type>
const Type	fims_math::ad_min (const Type &a, const Type &b, Type C=1e-5)
template<typename Type>
const Type	fims_math::ad_max (const Type &a, const Type &b, Type C=1e-5)
template<typename Type>
fims::Vector< Type >	fims_math::apply_ageing_error (const fims::Vector< Type > &proportion_at_true_age, const fims::Vector< Type > &ageing_error, size_t year=0)
	Converts values at true age, proportions or expected numbers, to values at observed age using an ageing error matrix.
template<class T>
T	fims_math::sum (const std::vector< T > &v)
template<class T>
T	fims_math::sum (const fims::Vector< T > &v)

Detailed Description

A collection of mathematical functions used in FIMS.

Copyright

This file is part of the NOAA, National Marine Fisheries Service Fisheries Integrated Modeling System project. See LICENSE in the source folder for reuse information.

Function Documentation

ad_fabs()

template<class Type>

const Type fims_math::ad_fabs	(	const Type &	x,
		Type	C = 1e-5 )

Used when x could evaluate to zero, which will result in a NaN for derivative values.

Evaluates:

\( (x^2+C)^.5 \)

The result is never below \( \sqrt{C} \), so ad_fabs(0) is about 0.0032 with the default C.

Parameters

x	value to keep positive
C	default = 1e-5

Returns

A smooth approximation of the absolute value of x.

ad_max()

template<typename Type>

const Type fims_math::ad_max ( const Type & a, const Type & b, Type C = 1e-5 )

inline

Returns the maximum between a and b in a continuous manner using:

(a + b + fims_math::ad_fabs(a - b, C)) *.5; Reference: fims_math::ad_fabs()

The result is never below the true maximum. The error is largest, \( \sqrt{C} / 2 \), when a = b. It is about \( C / (4|a - b|) \) when \( |a - b| \) is much larger than \( \sqrt{C} \). With the default C, ad_max(x, 1e-8) is about 0.0016 at x = 0, not 1e-8, and is 2.4% above x at x = 0.01. Use a smaller C when values near the floor matter.

Parameters

a	The first value.
b	The second value.
C	A positive constant that sets how smooth the result is. A smaller C gives a smaller error but a sharper bend at a = b. Default is 1e-5.

Returns

A smooth approximation of the maximum of a and b.

ad_min()

template<typename Type>

const Type fims_math::ad_min ( const Type & a, const Type & b, Type C = 1e-5 )

inline

Returns the minimum between a and b in a continuous manner using:

(a + b - fims_math::ad_fabs(a - b, C))*.5; Reference: fims_math::ad_fabs()

The result is never above the true minimum. The error is largest, \( \sqrt{C} / 2 \), when a = b. It is about \( C / (4|a - b|) \) when \( |a - b| \) is much larger than \( \sqrt{C} \). Use a smaller C when a and b can be close.

Parameters

a	The first value.
b	The second value.
C	A positive constant that sets how smooth the result is. A smaller C gives a smaller error but a sharper bend at a = b. Default is 1e-5.

Returns

A smooth approximation of the minimum of a and b.

apply_ageing_error()

template<typename Type>

fims::Vector< Type > fims_math::apply_ageing_error ( const fims::Vector< Type > & proportion_at_true_age, const fims::Vector< Type > & ageing_error, size_t year = 0 )

inline

Converts values at true age, proportions or expected numbers, to values at observed age using an ageing error matrix.

Ageing error spreads fish of one true age across several observed ages, so the expected composition of observed ages is

\( p^{obs}_{a'} = \sum_{a} p_{a} E_{a,a'} \)

where \( E_{a,a'} \) is the probability that a fish of true age \( a \) is read as age \( a' \). Each row of \( E \) sums to 1, so the total is unchanged. The caller checks the length of ageing_error.

Template Parameters

Type	The scalar type, a TMB AD type or double.

Parameters

proportion_at_true_age	Values at true age, 1 per model age.
ageing_error	1 matrix for all years or 1 per year, with true age as rows and observed age varying fastest.
year	Year index, used only when there is 1 matrix per year.

Returns

Values at observed age, 1 per model age.

double_logistic()

template<class Type>

const Type fims_math::double_logistic ( const Type & inflection_point_asc, const Type & slope_asc, const Type & inflection_point_desc, const Type & slope_desc, const Type & x )

inline

The general double logistic function.

\( \frac{1.0}{ 1.0 + exp(-1.0 * slope_{asc} (x - inflection_point_{asc}))} \frac{1.0}{ 1.0 + exp(slope_{desc} (x - inflection_point_{desc}))}\)

The descending limb is written as \(1 / (1 + exp(z))\), with \( z = slope_desc (x - inflection_point_desc) \), so it stays above 0 in double precision until \( exp(z) \) overflows.

Parameters

inflection_point_asc	the inflection point of the ascending limb of the double logistic function
slope_asc	the slope of the ascending limb of the double logistic function
inflection_point_desc	the inflection point of the descending limb of the double logistic function, where inflection_point_desc > inflection_point_asc
slope_desc	the slope of the descending limb of the double logistic function
x	the index the logistic function should be evaluated at

Returns

inv_logit()

template<class Type>

const Type fims_math::inv_logit ( const Type & a, const Type & b, const Type & logit_x )

inline

An inverse logit function for bounding of parameters.

\( a+\frac{b-a}{1+\mathrm{exp}(-\mathrm{logit}(x))}\)

Parameters

a	lower bound
b	upper bound
logit_x	the parameter in real space

Returns

the parameter in bounded space

logistic()

template<class Type>

const Type fims_math::logistic ( const Type & inflection_point, const Type & slope, const Type & x )

inline

The general logistic function.

The logistic function can range from zero to one or one to zero, depending on the slope parameter, but it is not normalized to force values to reach those ranges.

\( \frac{1.0}{ 1.0 + exp(-1.0 * slope (x - inflection_point))} \)

Parameters

inflection_point	the inflection point of the logistic function
slope	the slope of the logistic function. A positive slope results in an ascending logistic curve (0 to 1), while a negative slope results in a descending logistic curve (1 to 0).
x	the index the logistic function should be evaluated at

Returns

logit()

template<class Type>

const Type fims_math::logit ( const Type & a, const Type & b, const Type & x )

inline

A logit function for bounding of parameters.

\( -\mathrm{log}(b-x) + \mathrm{log}(x-a) \)

Parameters

a	lower bound
b	upper bound
x	the parameter in bounded space

Returns

the parameter in real space

sum() [1/2]

template<class T>

T fims_math::sum

(

const fims::Vector< T > &

v

)

Sum elements of a vector

Parameters

v	A vector of constants.

Returns

A single numeric value.

sum() [2/2]

template<class T>

T fims_math::sum

(

const std::vector< T > &

v

)

Sum elements of a vector

Parameters

v	A vector of constants.

Returns

A single numeric value.