#include <time_series.h>

Classes
struct	Data

Public Member Functions
	TimeSeries ()

	TimeSeries (const TimeSeries &other)

	TimeSeries (TimeSeries &&other) noexcept

TimeSeries &	operator= (TimeSeries &&other) noexcept

TimeSeries &	operator= (const TimeSeries &other)

void	AddCollector (const std::string &id, real_t(ycollector)(Simulation ), real_t(xcollector)(Simulation )=nullptr)

void	AddCollector (const std::string &id, Reducer< real_t > y_reducer_collector, real_t(xcollector)(Simulation *)=nullptr)

void	Add (const std::string &id, const std::vector< real_t > &x_values, const std::vector< real_t > &y_values)

void	Add (const std::string &id, const std::vector< real_t > &x_values, const std::vector< real_t > &y_values, const std::vector< real_t > &y_error)

void	Add (const std::string &id, const std::vector< real_t > &x_values, const std::vector< real_t > &y_values, const std::vector< real_t > &y_error_low, const std::vector< real_t > &y_error_high)

void	Add (const TimeSeries &ts, const std::string &suffix)

void	AddTransformedData (const std::string &old_id, const std::string &transformed_id, const DataTransformer &transformer)

void	Update ()
	Adds a new data point to all time series with a collector. More...

bool	Contains (const std::string &id) const
	Returns whether a times series with given id exists in this object. More...

uint64_t	Size () const

const std::vector< real_t > &	GetXValues (const std::string &id) const

const std::vector< real_t > &	GetYValues (const std::string &id) const

const std::vector< real_t > &	GetYErrorLow (const std::string &id) const

const std::vector< real_t > &	GetYErrorHigh (const std::string &id) const

void	ListEntries () const
	Print all time series entry names to stdout. More...

void	Save (const std::string &full_filepath) const
	Saves a root file to disk. More...

void	SaveJson (const std::string &full_filepath) const
	Saves a json representation to disk. More...

Static Public Member Functions
static void	Load (const std::string &full_filepath, TimeSeries **restored)

static void	Merge (TimeSeries merged, const std::vector< TimeSeries > &time_series, const std::function< void(const std::vector< real_t > &, real_t , real_t , real_t )> &merger)

static real_t	ComputeError (const TimeSeries &ts1, const TimeSeries &ts2)
	Computes the mean squared error between `ts1` and `ts2` More...

Private Member Functions
	BDM_CLASS_DEF_NV (TimeSeries, 1)

Private Attributes
std::unordered_map< std::string, Data >	data_

Detailed Description

This class simplifies the collection of time series data during a simulation. Every entry has an id and data arrays storing x-values, y-values, y-error-low, and y-error-high.

Definition at line 123 of file time_series.h.

Constructor & Destructor Documentation

◆ TimeSeries() [1/3]

bdm::experimental::TimeSeries::TimeSeries ( )

default

◆ TimeSeries() [2/3]

bdm::experimental::TimeSeries::TimeSeries ( const TimeSeries & other )

Definition at line 292 of file time_series.cc.

◆ TimeSeries() [3/3]

bdm::experimental::TimeSeries::TimeSeries ( TimeSeries && other )

noexcept

Definition at line 295 of file time_series.cc.

Member Function Documentation

◆ Add() [1/4]

void bdm::experimental::TimeSeries::Add	(	const std::string &	id,
		const std::vector< real_t > &	x_values,
		const std::vector< real_t > &	y_values
	)

Add new entry with data that is not collected during a simulation. This function can for example be used to add experimental data which can be later plotted together with the simulation results using a LineGraph.

time_series.Add("experimental-data", {0, 1, 2}, {3, 4, 5});

Definition at line 444 of file time_series.cc.

◆ Add() [2/4]

void bdm::experimental::TimeSeries::Add	(	const std::string &	id,
		const std::vector< real_t > &	x_values,
		const std::vector< real_t > &	y_values,
		const std::vector< real_t > &	y_error
	)

Definition at line 480 of file time_series.cc.

◆ Add() [3/4]

void bdm::experimental::TimeSeries::Add	(	const std::string &	id,
		const std::vector< real_t > &	x_values,
		const std::vector< real_t > &	y_values,
		const std::vector< real_t > &	y_error_low,
		const std::vector< real_t > &	y_error_high
	)

Definition at line 460 of file time_series.cc.

◆ Add() [4/4]

void bdm::experimental::TimeSeries::Add	(	const TimeSeries &	ts,
		const std::string &	suffix
	)

Add the entries of another TimeSeries instance to this one. Let's assume that ts contains the entries: "entry1" and "entry2" and that suffix is set to "-from-ts". In this scenario the following entries will be added to this object: "entry1-from-ts", "entry2-from-ts"

Definition at line 422 of file time_series.cc.

◆ AddCollector() [1/2]

void bdm::experimental::TimeSeries::AddCollector	(	const std::string &	id,
		real_t()(Simulation )	ycollector,
		real_t()(Simulation )	xcollector = `nullptr`
	)

Adds a new collector which is executed at each iteration. e.g. to track the number of agents in the simulation:

auto* ts = simulation.GetTimeSeries();
auto get_num_agents = [](Simulation* sim) {
  return static_cast<real_t>(sim->GetResourceManager()->GetNumAgents());
};
ts->AddCollector("num-agents", get_num_agents);

The optional x-value collector allows to modify the x-values. If no x-value collector is given, x-values will correspond to the simulation time.

Definition at line 311 of file time_series.cc.

◆ AddCollector() [2/2]

void bdm::experimental::TimeSeries::AddCollector	(	const std::string &	id,
		Reducer< real_t > *	y_reducer_collector,
		real_t()(Simulation )	xcollector = `nullptr`
	)

Adds a reducer collector which is executed at each iteration.
The benefit (in comparison with AddCollector using a function pointer to collect y-values) is that multiple reducers can be combined. This mechanism is more cache-friendly and calculates the result much faster.
Update calculates the values for reducers before function pointers. Thus, a function pointer collector can use the result of a reducer collector. This is illustrated in the example below. Let's assume we want to track the fraction of infected agents in an epidemiological simulation.

auto is_infected = [](Agent* a) {
  return bdm_static_cast<Person*>(a)->state_ == State::kInfected;
};
ts->AddCollector("infected", new Counter<real_t>(is_infected);
 
auto infected_rate = [](Simulation* sim) {
  auto num_agents = sim->GetResourceManager()->GetNumAgents();
  auto count = ts->GetYValues("infected").back();
  return count / static_cast<real_t>(num_agents);
};
ts->AddCollector("infected_rate", infected_rate);

Definition at line 323 of file time_series.cc.

◆ AddTransformedData()

void bdm::experimental::TimeSeries::AddTransformedData	(	const std::string &	old_id,
		const std::string &	transformed_id,
		const DataTransformer &	transformer
	)

Copies the data of an existing entry and adds it to this object. During the copy process, the data is transformed using the given transformer. This allows to e.g. convert the x-values from simulation time to simulation steps, or vice versa. A common use case are linear or log scaling of the x-axis.

Definition at line 335 of file time_series.cc.

◆ BDM_CLASS_DEF_NV()

bdm::experimental::TimeSeries::BDM_CLASS_DEF_NV	(	TimeSeries	,
		1
	)

private

◆ ComputeError()

real_t bdm::experimental::TimeSeries::ComputeError	(	const TimeSeries &	ts1,
		const TimeSeries &	ts2
	)

static

Computes the mean squared error between ts1 and ts2

Definition at line 143 of file time_series.cc.

◆ Contains()

bool bdm::experimental::TimeSeries::Contains ( const std::string & id ) const

Returns whether a times series with given id exists in this object.

Definition at line 498 of file time_series.cc.

◆ GetXValues()

const std::vector< real_t > & bdm::experimental::TimeSeries::GetXValues ( const std::string & id ) const

Definition at line 506 of file time_series.cc.

◆ GetYErrorHigh()

const std::vector< real_t > & bdm::experimental::TimeSeries::GetYErrorHigh ( const std::string & id ) const

Definition at line 522 of file time_series.cc.

◆ GetYErrorLow()

const std::vector< real_t > & bdm::experimental::TimeSeries::GetYErrorLow ( const std::string & id ) const

Definition at line 516 of file time_series.cc.

◆ GetYValues()

const std::vector< real_t > & bdm::experimental::TimeSeries::GetYValues ( const std::string & id ) const

Definition at line 511 of file time_series.cc.

◆ ListEntries()

void bdm::experimental::TimeSeries::ListEntries ( ) const

Print all time series entry names to stdout.

Definition at line 528 of file time_series.cc.

◆ Load()

void bdm::experimental::TimeSeries::Load	(	const std::string &	full_filepath,
		TimeSeries **	restored
	)

static

Restore a saved TimeSeries object. Usage example:

TimeSeries* ts_restored;

TimeSeries::Load("path/ts.root", &ts_restored);

Definition at line 193 of file time_series.cc.

◆ Merge()

void bdm::experimental::TimeSeries::Merge	(	TimeSeries *	merged,
		const std::vector< TimeSeries > &	time_series,
		const std::function< void(const std::vector< real_t > &, real_t , real_t , real_t *)> &	merger
	)

static

This function combines several time series into one. All time series in parameter time_series must have the same entries. All entries must have the exact same x values. The parameter merger takes a function which describes how each data point should be combined. Let's assume the following example: We take the median of each value and define error_low = mean - minimum, and error_high = maximum - mean. All time series objects have one entry called "entry-0" with the same x-values.

std::vector<TimeSeries> tss(3);
tss[0].Add("entry-0", {1, 2}, {2, 5});
tss[1].Add("entry-0", {1, 2}, {4, 8});
tss[2].Add("entry-0", {1, 2}, {1, 13});
TimeSeries merged;
TimeSeries::Merge(
    &merged, tss,
    [](const std::vector<real_t>& all_y_values, real_t* y, real_t* el,
       real_t* eh) {
      *y = TMath::Median(all_y_values.size(), all_y_values.data());
      *el = *y - *TMath::LocMin(all_y_values.begin(), all_y_values.end());
      *eh = *TMath::LocMax(all_y_values.begin(), all_y_values.end()) - *y;
    });

After these operations, merged will contain one entry with id "entry-0" with the following arrays:
x-values: {1, 2}
y-values: {2, 8}
y-error-low: {1, 3}
y-error-high: {2, 5}
Of course any other merger can be used too: e.g. mean + stddev

See also: https://root.cern/doc/master/namespaceTMath.html

Definition at line 198 of file time_series.cc.

◆ operator=() [1/2]

TimeSeries & bdm::experimental::TimeSeries::operator= ( const TimeSeries & other )

Definition at line 305 of file time_series.cc.

◆ operator=() [2/2]

TimeSeries & bdm::experimental::TimeSeries::operator= ( TimeSeries && other )

noexcept

Definition at line 299 of file time_series.cc.

◆ Save()

void bdm::experimental::TimeSeries::Save ( const std::string & full_filepath ) const

Saves a root file to disk.

Definition at line 535 of file time_series.cc.

◆ SaveJson()

void bdm::experimental::TimeSeries::SaveJson ( const std::string & full_filepath ) const

Saves a json representation to disk.

Definition at line 540 of file time_series.cc.

◆ Size()

uint64_t bdm::experimental::TimeSeries::Size ( ) const

Definition at line 503 of file time_series.cc.

◆ Update()

void bdm::experimental::TimeSeries::Update ( )

Adds a new data point to all time series with a collector.

Definition at line 368 of file time_series.cc.

Member Data Documentation

◆ data_

std::unordered_map<std::string, Data> bdm::experimental::TimeSeries::data_

private

Definition at line 297 of file time_series.h.

The documentation for this class was generated from the following files:

core/analysis/time_series.h
core/analysis/time_series.cc

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TimeSeries() [1/3]

◆ TimeSeries() [2/3]

◆ TimeSeries() [3/3]

Member Function Documentation

◆ Add() [1/4]

◆ Add() [2/4]

◆ Add() [3/4]

◆ Add() [4/4]

◆ AddCollector() [1/2]

◆ AddCollector() [2/2]

◆ AddTransformedData()

◆ BDM_CLASS_DEF_NV()

◆ ComputeError()

◆ Contains()

◆ GetXValues()

◆ GetYErrorHigh()

◆ GetYErrorLow()

◆ GetYValues()

◆ ListEntries()

◆ Load()

◆ Merge()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Save()

◆ SaveJson()

◆ Size()

◆ Update()

Member Data Documentation

◆ data_