igt_stats_init ()

void
igt_stats_init (igt_stats_t *stats);

Initializes an igt_stats_t instance. igt_stats_fini() must be called once finished with stats .

igt_stats_init_with_size ()

void
igt_stats_init_with_size (igt_stats_t *stats,
                          unsigned int capacity);

Like igt_stats_init() but with a size to avoid reallocating the underlying array(s) when pushing new values. Useful if we have a good idea of the number of data points we want stats to hold.

igt_stats_fini() must be called once finished with stats .

igt_stats_fini ()

void
igt_stats_fini (igt_stats_t *stats);

Frees resources allocated in igt_stats_init().

igt_stats_is_population ()

bool
igt_stats_is_population (igt_stats_t *stats);

igt_stats_set_population ()

void
igt_stats_set_population (igt_stats_t *stats,
                          bool full_population);

In statistics, we usually deal with a subset of the full data (which may be a continuous or infinite set). Data analysis is then done on a sample of this population.

This has some importance as only having a sample of the data leads to biased estimators. We currently used the information given by this method to apply Bessel's correction to the variance.

Note that even if we manage to have an unbiased variance by multiplying a sample variance by the Bessel's correction, n/(n - 1), the standard deviation derived from the unbiased variance isn't itself unbiased. Statisticians talk about a "corrected" standard deviation.

When giving true to this function, the data set in stats is considered a full population. It's considered a sample of a bigger population otherwise.

When newly created, stats defaults to holding sample data.

igt_stats_push ()

void
igt_stats_push (igt_stats_t *stats,
                uint64_t value);

Adds a new value to the stats dataset and converts the igt_stats from an integer collection to a floating point one.

igt_stats_push_float ()

void
igt_stats_push_float (igt_stats_t *stats,
                      double value);

igt_stats_push_array ()

void
igt_stats_push_array (igt_stats_t *stats,
                      const uint64_t *values,
                      unsigned int n_values);

Adds an array of values to the stats dataset.

igt_stats_get_min ()

uint64_t
igt_stats_get_min (igt_stats_t *stats);

Retrieves the minimal value in stats

igt_stats_get_max ()

uint64_t
igt_stats_get_max (igt_stats_t *stats);

Retrieves the maximum value in stats

igt_stats_get_range ()

uint64_t
igt_stats_get_range (igt_stats_t *stats);

Retrieves the range of the values in stats . The range is the difference between the highest and the lowest value.

The range can be a deceiving characterization of the values, because there can be extreme minimal and maximum values that are just anomalies. Prefer the interquatile range (see igt_stats_get_iqr()) or an histogram.

igt_stats_get_quartiles ()

void
igt_stats_get_quartiles (igt_stats_t *stats,
                         double *q1,
                         double *q2,
                         double *q3);

Retrieves the quartiles of the stats dataset.

igt_stats_get_iqr ()

double
igt_stats_get_iqr (igt_stats_t *stats);

Retrieves the interquartile range (IQR) of the stats dataset.

igt_stats_get_iqm ()

double
igt_stats_get_iqm (igt_stats_t *stats);

Retrieves the interquartile mean (IQM) of the stats dataset.

The interquartile mean is a "statistical measure of central tendency". It is a truncated mean that discards the lowest and highest 25% of values, and calculates the mean value of the remaining central values.

It's useful to hide outliers in measurements (due to cold cache etc).

igt_stats_get_mean ()

double
igt_stats_get_mean (igt_stats_t *stats);

Retrieves the mean of the stats dataset.

igt_stats_get_trimean ()

double
igt_stats_get_trimean (igt_stats_t *stats);

Retrieves the trimean of the stats dataset.

The trimean is a the most efficient 3-point L-estimator, even more robust than the median at estimating the average of a sample population.

igt_stats_get_median ()

double
igt_stats_get_median (igt_stats_t *stats);

Retrieves the median of the stats dataset.

igt_stats_get_variance ()

double
igt_stats_get_variance (igt_stats_t *stats);

Retrieves the variance of the stats dataset.

igt_stats_get_std_deviation ()

double
igt_stats_get_std_deviation (igt_stats_t *stats);

Retrieves the standard deviation of the stats dataset.

igt_mean_init ()

void
igt_mean_init (struct igt_mean *m);

Initializes or resets m .

igt_mean_add ()

void
igt_mean_add (struct igt_mean *m,
              double v);

Adds a new value v to m .

igt_mean_get ()

double
igt_mean_get (struct igt_mean *m);

Computes the current mean of the samples tracked in m .

igt_mean_get_variance ()

double
igt_mean_get_variance (struct igt_mean *m);

Computes the current variance of the samples tracked in m .

igt_stats_t

typedef struct {
	unsigned int n_values;
	unsigned int is_float : 1;
	union {
		uint64_t *values_u64;
		double *values_f;
	};
} igt_stats_t;

struct igt_mean

struct igt_mean {
};

Structure to compute running statistical numbers. Needs to be initialized with igt_mean_init(). Read out data using igt_mean_get() and igt_mean_get_variance().