API

Previous Next

Typedefs

malloc_fn

typedef void *(* malloc_fn) (__SIZE_TYPE__)

malloc_fn is a pointer to a malloc-type function i.e. with prototype: void * malloc(size_t)

free_fn

typedef void(* free_fn) (void *)

free_fn is a pointer to a free-type function i.e. with prototype: void free(void*)

frexp_fn

typedef double(* frexp_fn) (double, int *)

frexp_fn is a pointer to a frexp-type function i.e. with prototype: double frexp_fn(double, int*)

math_fn

typedef double(* math_fn) (double)

math_fn is a pointer to a generic real math function like log, exp...

math2_fn

typedef double(* math2_fn) (double, double)

math_fn is a pointer to a generic two parameters math function like pow

ldexp_fn

typedef double(* ldexp_fn) (double, int)

ldexp_fn is a pointer to a ldexp-type function i.e. with prototype: double ldexp_fn(double, int*)

real_function

typedef double(* real_function) (double, void *)

real_function defines a pointer to a univariate function that can require extra paramaters (second argument)

Enum

LibspotError

enum LibspotError {
    ERR_MEMORY_ALLOCATION_FAILED = 1000,
    ERR_LEVEL_OUT_OF_BOUNDS,
    ERR_Q_OUT_OF_BOUNDS,
    ERR_EXCESS_THRESHOLD_IS_NAN,
    ERR_ANOMALY_THRESHOLD_IS_NAN,
    ERR_DATA_IS_NAN,
};

Constants to store libspot errors.

Name Description
ERR_MEMORY_ALLOCATION_FAILED Allocation of the backing array failed.
ERR_LEVEL_OUT_OF_BOUNDS The level parameter must between 0 and 1.
ERR_Q_OUT_OF_BOUNDS The q parameter must be between 0 and 1-level.
ERR_EXCESS_THRESHOLD_IS_NAN The excess threshold has not been initialized.
ERR_ANOMALY_THRESHOLD_IS_NAN The anomaly threshold has not been initialized.
ERR_DATA_IS_NAN The input data is NaN.

SpotResult

enum SpotResult {
    NORMAL = 0,
    EXCESS = 1,
    ANOMALY = 2,
};

Possible outputs of a Spot step.

Name Description
NORMAL Data is normal.
EXCESS Data is in the tail (so the model has been updated)
ANOMALY Data is beyond the anomaly threshold.

Structures

Ubend

struct Ubend {
    unsigned long cursor;
    unsigned long capacity;
    double last_erased_data;
    int filled;
    double * data;
};

This container is a kind of circular vector.

First it is empty. Then we feed it with data until its max capacity is reached (transitory state). When it is full, the earlier data erase the older one (cruise state).

Member Description
cursor Current position inside the container.
capacity Max storage.
last_erased_data Last erased value (i.e. replaced by a new one)
filled Container fill status (1 = filled, 0 = not filled)
data Data container.

Peaks

struct Peaks {
    double e;
    double e2;
    double min;
    double max;
    struct Ubend container;
};

Stucture that computes stats about the peaks.

Member Description
e Sum of the elements.
e2 Sum of the square of the elements.
min Minimum of the elements.
max Maximum of the elements.
container Underlying data container.

Tail

struct Tail {
    double gamma;
    double sigma;
    struct Peaks peaks;
};

Stucture that embeds GPD parameter (GPD tail actually)

Member Description
gamma GPD gamma parameter.
sigma GPD sigma parameter.
peaks Underlyning Peaks structure.

Spot

struct Spot {
    double q;
    double level;
    int discard_anomalies;
    int low;
    double __up_down;
    double anomaly_threshold;
    double excess_threshold;
    unsigned long Nt;
    unsigned long n;
    struct Tail tail;
};

Main structure to run the SPOT algorithm.

Member Description
q Probability of an anomaly.
level Location of the tail (high quantile)
discard_anomalies Flag anomalies (1 = flag, 0 = don't flag)
low Upper/Lower tail choice (1 = lower tail, 0 = upper tail)
__up_down Internal constant (+/- 1.0)
anomaly_threshold Normal/abnormal threshold.
excess_threshold Tail threshold.
Nt Total number of excesses.
n Total number of seen data.
tail GPD Tail.

Functions

spot_init

int spot_init(struct Spot * spot, double q, int low, int discard_anomalies, double level, unsigned long max_excess)

Initialize the Spot structure.

Parameter Description
spot Spot instance
q Decision probability (Spot will flag extreme events that will have a probability lower than q)
low Lower tail mode (0 by defaut for upper tail and 1 for lower tail)
discard_anomalies Do not include anomalies in the model (default: 1, 0 otherwise)
level Excess level (it is a high quantile that delimits the tail)
max_excess Maximum number of data that are kept to analyze the tail

spot_free

void spot_free(struct Spot * spot)

Free the tail data.

Parameter Description
spot Spot instance

spot_fit

int spot_fit(struct Spot * spot, double const * data, unsigned long size)

Compute the first excess and anomaly thresholds based on training data.

Parameter Description
spot Spot instance
data Buffer of input data
size Size of the buffer

spot_step

int spot_step(struct Spot * spot, double x)

fit-predict step

Parameter Description
spot Spot instance
x new value

spot_quantile

double spot_quantile(struct Spot const * spot, double q)

Compute the value zq such that P(X>zq) = q.

Parameter Description
spot Spot instance
q Low probability (it must be within the tail)

spot_probability

double spot_probability(struct Spot const * spot, double z)

Compute the probability p such that P(X>z) = p.

Parameter Description
spot Spot instance
z High quantile (it must be within the tail)

set_allocators

void set_allocators(malloc_fn m, free_fn f)

Set the allocators object (malloc and free)

Parameter Description
m pointer to a "malloc" function
f pointer to a "free" function

set_float_utils

void set_float_utils(ldexp_fn l, frexp_fn f)

Set the ldexp/frexp functions.

By default these functions are provided but the API allows to change them. It is low level, you might rather use set_math_functions to provide optimized math functions.

Parameter Description
l pointer to a "ldexp" function (nil if you do not want to change it)
f pointer to a "frexp" function (nil if you do not want to change it)

set_math_functions

void set_math_functions(math_fn lo, math_fn ex, math2_fn po)

Set the log, exp and pow functions. It is recommended when you have access to optimized versions (e.g., from the standard library).

Parameter Description
lo pointer to a "log" function (nil if you do not want to change it)
ex pointer to an "exp" function (nil if you do not want to change it)
po pointer to a "pow" function (nil if you do not want to change it)

libspot_version

void libspot_version(char * buffer, unsigned long size)

Return the version of libspot.

Parameter Description
buffer input buffer to fill with
size size of the input buffer

libspot_license

void libspot_license(char * buffer, unsigned long size)

Return the license of the library.

Parameter Description
buffer input buffer to fill with
size size of the input buffer

libspot_error

void libspot_error(enum LibspotError err, char * buffer, unsigned long size)

Return a string related to an error code.

Parameter Description
err error code
buffer input buffer to fill with
size size of the input buffer
Parameters Python