Struct cmb_datasummary

Struct Documentation

struct cmb_datasummary

A running tally of basic statistics. The cmb_datasummary does not keep individual data values, just the summary statistics. Use cmb_dataset instead if you need individual values and then cmb_dataset_summarize to extract the summary statistics from a collected data set.

Public Functions

struct cmb_datasummary *cmb_datasummary_create(void)

Allocate a data summary on the heap.

Note that this does not allocate from a thread local memory pool, since it may be passed back outside the current replication.

Returns:

A pointer to a newly allocated data summary.

void cmb_datasummary_destroy(struct cmb_datasummary *dsp)

Deallocate (free) the allocated memory for a data summary.

Parameters:

  • dsp – Pointer to a data summary previously created by cmb_datasummary_create.

void cmb_datasummary_reset(struct cmb_datasummary *dsp)

Reset a previously used data summary to a newly initialized state.

Parameters:

  • dsp – Pointer to a data summary.

void cmb_datasummary_terminate(struct cmb_datasummary *dsp)

Un-initialize the data summary, returning it to a newly created state.

Parameters:

  • dsp – Pointer to a data summary.

uint64_t cmb_datasummary_add(struct cmb_datasummary *dsp, double y)

Add a single value to a data summary, updating running statistics.

Parameters:

  • dsp – Pointer to a data summary.

  • y – Sample value to be added.

Returns:

The updated sample count.

uint64_t cmb_datasummary_merge(struct cmb_datasummary *tgt, const struct cmb_datasummary *dsp1, const struct cmb_datasummary *dsp2)

Merge two data summaries s1 and s2 into the given target. The target can be one of the sources, merging the other source into this.

Use case: Partition a simulation across several pthreads and CPU cores, assemble the final results by merging the data summaries returned by each.

Parameters:

  • tgt – Pointer to data summary to receive the merge. Any previous content will be overwritten.

  • dsp1 – Pointer to a data summary.

  • dsp2 – Pointer to a data summary.

Returns:

The combined sample count.

double cmb_datasummary_skewness(const struct cmb_datasummary *dsp)

The sample skewness of the samples in the data summary.

Parameters:

  • dsp – Pointer to a data summary.

Returns:

The sample skewness of the samples in the data summary.

double cmb_datasummary_kurtosis(const struct cmb_datasummary *dsp)

The sample excess kurtosis of the samples in the data summary.

Parameters:

  • dsp – Pointer to a data summary

Returns:

The sample excess kurtosis of the samples in the data summary.

void cmb_datasummary_print(const struct cmb_datasummary *dsp, FILE *fp, bool lead_ins)

Print a line of basic statistics for the data summary.

Parameters:

  • dsp – Pointer to a data summary.

  • fp – A file pointer for where to print, possibly stdout

  • lead_ins – Flag to control if explanatory text is printed. If false, only prints a tab-separated line of numeric values.

Public Members

uint64_t cookie

A “magic cookie” to catch uninitialized objects

uint64_t count

The number of samples seen

double min

The smallest sample seen, initially DBL_MAX

double max

The largest sample seen, initially -DBL_MAX

double m1

First raw moment

double m2

Second raw moment

double m3

Third raw moment

double m4

Fourth raw moment

Public Static Functions

static inline uint64_t cmb_datasummary_count(const struct cmb_datasummary *dsp)

The number of samples in the data summary.

Parameters:

  • dsp – Pointer to a data summary.

Returns:

The number of samples included in the data summary.

static inline double cmb_datasummary_max(const struct cmb_datasummary *dsp)

The largest sample in the data summary.

Parameters:

  • dsp – Pointer to a data summary.

Returns:

The largest sample included in the data summary.

static inline double cmb_datasummary_min(const struct cmb_datasummary *dsp)

The smallest sample in the data summary.

Parameters:

  • dsp – Pointer to a data summary.

Returns:

The smallest sample included in the data summary.

static inline double cmb_datasummary_mean(const struct cmb_datasummary *dsp)

The mean of the samples in the data summary.

Parameters:

  • dsp – Pointer to a data summary.

Returns:

The mean of the samples included in the data summary.

static inline double cmb_datasummary_variance(const struct cmb_datasummary *dsp)

The sample variance of the samples in the data summary.

Parameters:

  • dsp – Pointer to a data summary.

Returns:

The sample variance of the samples included in the data summary.

static inline double cmb_datasummary_stddev(const struct cmb_datasummary *dsp)

The sample standard deviation of the samples in the data summary.

Parameters:

  • dsp – Pointer to a data summary.

Returns:

The sample standard deviation of the samples in the data summary.