Struct cmb_timeseries

Struct Documentation

struct cmb_timeseries

A time series with a conveniently resizing sample array. The parent class cmb_dataset provides the xa array.

Public Functions

struct cmb_timeseries *cmb_timeseries_create(void)

Allocate memory for a time series.

Remember to call a matching cmb_timeseries_destroy when done to avoid memory leakage.

Returns:

A freshly allocated time series object.

void cmb_timeseries_initialize(struct cmb_timeseries *tsp)

Initialize the time series, clearing any data values.

Parameters:

  • tsp – Pointer to an already allocated time series object.

void cmb_timeseries_reset(struct cmb_timeseries *tsp)

Re-initialize it, returning it to a newly initialized state.

Parameters:

  • tsp – Pointer to an already allocated time series object.

void cmb_timeseries_terminate(struct cmb_timeseries *tsp)

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

Parameters:

  • tsp – Pointer to an already allocated time series object.

void cmb_timeseries_destroy(struct cmb_timeseries *tsp)

Free memory allocated by cmb_timeseries_create for the time series and its arrays.

Do not call unless the time series was created on the heap by cmb_timeseries_create. Otherwise, use cmb_timeseries_terminate to free the data array only.

Parameters:

  • tsp – Pointer to a previously allocated time series object.

uint64_t cmb_timeseries_copy(struct cmb_timeseries *tgt, const struct cmb_timeseries *src)

Copy tgt into src, overwriting whatever was in tgt.

Parameters:

  • tgt – Pointer to the target time series object.

  • src – Pointer to the source time series object.

Returns:

Number of data points copied.

uint64_t cmb_timeseries_add(struct cmb_timeseries *tsp, double x, double t)

Add a single value to a time series, resizing the array as needed.

Parameters:

  • tsp – Pointer to a time series object.

  • x – The new sample x-value to add.

  • t – The t-value (timestamp) for the new sample.

Returns:

The new number of data values in the array.

uint64_t cmb_timeseries_finalize(struct cmb_timeseries *tsp, double t)

Add a final data point at the given time t with the same x-value as the last recorded value. Used to ensure that the last value gets weighted by its correct duration from the event time to the end of the data collection period.

Typically called as cmb_timeseries_finalize(tsp, cmb_time()) during the simulation closing ceremonies. The closing time is left as an explicit argument for user flexibility in any other use cases and for better separation between Cimba modules.

Parameters:

  • tsp – Pointer to a time series object.

  • t – The t-value (timestamp) for the final value, usually cmb_time().

void cmb_timeseries_sort_x(struct cmb_timeseries *tsp)

Sort timeseries in ascending order by x-value. The time stamps and weights in the ta and wa arrays follow the xa values.

Caution: Changes the sequence of data points, no longer a timeseries after this call.

Parameters:

  • tsp – Pointer to a time series object.

void cmb_timeseries_sort_t(struct cmb_timeseries *tsp)

An “undo” function for cmb_timeseries_sort_x(), sorting the time series back to an ascending time sequence.

Parameters:

  • tsp – Pointer to a time series object.

uint64_t cmb_timeseries_summarize(const struct cmb_timeseries *tsp, struct cmb_wtdsummary *wsp)

Calculate summary statistics of the time series.

Parameters:

  • tsp – Pointer to a time series object.

  • wsp – Pointer to a weighted data summary object.

Returns:

The number of data points in the summary.

double cmb_timeseries_median(const struct cmb_timeseries *tsp)

Calculate and return the median of the time series, sample values weighted by duration. Uses linear interpolation for the median value at 50 % of the summed weights.

Call cmb_dataset_median((struct cmb_dataset *)tsp, ...) for unweighted.

Parameters:

  • tsp – Pointer to a time series object.

Returns:

The median value in the time series.

void cmb_timeseries_fivenum_print(const struct cmb_timeseries *tsp, FILE *fp, bool lead_ins)

Calculate and print the “five-number” summary of timeseries quantiles, weighted by duration (the holding time from one sample to the next).

Call cmb_dataset_fivenum_print((struct cmb_dataset *)tsp, ...) to get unweighted quantiles.

Parameters:

  • tsp – Pointer to a time series object.

  • fp – A file pointer for the output, possibly stdout.

  • lead_ins – A flag indicating whether to add explanatory text (if true) or not (if false).

void cmb_timeseries_histogram_print(const struct cmb_timeseries *tsp, FILE *fp, uint16_t num_bins, double low_lim, double high_lim)

Print a simple character-based histogram. Like cmb_dataset_print_histogram() but weighted by the time interval until the next sample.

Call cmb_dataset_histogram((struct cmb_dataset *)tsp, ...) for unweighted.

Parameters:

  • tsp – Pointer to a time series object.

  • fp – A file pointer for the output, possibly stdout.

  • num_bins – Number of histogram bins to use. Will add one more on either side to catch overflow values.

  • low_lim – The lower limit of the histogram bin values.

  • high_lim – The upper limit of the histogram bin values. Will autoscale to actual sample value range if low_lim == high_lim.

void cmb_timeseries_print(const struct cmb_timeseries *tsp, FILE *fp)

Print the raw data in the timeseries.

Parameters:

  • tsp – Pointer to a time series object.

  • fp – A file pointer for the output, possibly stdout.

Public Members

struct cmb_dataset ds

Parent class providing the xa array

double *ta

The array of time stamps for the samples

double *wa

The weighting (duration) of each sample value

Public Static Functions

static inline uint64_t cmb_timeseries_count(const struct cmb_timeseries *tsp)

Count the number of samples in the time series.

Parameters:

  • tsp – Pointer to a time series object.

Returns:

The number of samples in the time series.

static inline double cmb_timeseries_min(const struct cmb_timeseries *tsp)

Find the smallest sample (x) value in the time series.

Parameters:

  • tsp – Pointer to a time series object.

Returns:

The smallest sample (x) value in the time series.

static inline double cmb_timeseries_max(const struct cmb_timeseries *tsp)

Find the largest sample (x) value in the time series.

Parameters:

  • tsp – Pointer to a time series object.

Returns:

The largest sample (x) value in the time series.

static inline void cmb_timeseries_ACF(const struct cmb_timeseries *tsp, const uint16_t n, double *acf)

Calculate the n first autocorrelation coefficients between individual samples, only considering the sequence, disregarding the time duration between samples.

Parameters:

  • tsp – Pointer to a time series object.

  • n – The number of coefficients to calculate.

  • acf – The array to store the autocorrelation coefficients, size n + 1

static inline void cmb_timeseries_PACF(const struct cmb_timeseries *tsp, const uint16_t n, double *pacf, double *acf)

Calculate the n first partial autocorrelation coefficients, again only considering sequence, not interval durations.

The first and most time-consuming step in the algorithm is to calculate the ACFs. If these already have been calculated, they can be given as the last argument acf[]. If this argument is NULL, they will be calculated directly from the dataset.

Parameters:

  • tsp – Pointer to a time series object.

  • n – The number of coefficients to calculate.

  • pacf – The array to store the partial autocorrelation coefficients, size n + 1.

  • acf – Array of autocorrelation coefficients, if already available, size n + 1.

static inline void cmb_timeseries_correlogram_print(const struct cmb_timeseries *tsp, FILE *fp, const uint16_t n, double *acf)

Print a simple correlogram of the autocorrelation coefficients previously calculated, either ACFs or PACFs.

If the data vector acf[] is NULL, ACFs will be calculated directly from the dataset by calling cmb_dataset_ACF().

To print PACFs, give a vector of already calculated PACFs as the acf argument.

Parameters:

  • tsp – Pointer to a time series object.

  • fp – A file pointer for the output, possibly stdout.

  • n – The number of coefficients to calculate.

  • acf – Array of (partial) autocorrelation coefficients, if already available, size n + 1.