BioDynaMo  v1.03.58-27764645
Classes | Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | List of all members
bdm::experimental::TimeSeries Class Reference

#include <time_series.h>

Classes

struct  Data
 

Public Member Functions

 TimeSeries ()
 
 TimeSeries (const TimeSeries &other)
 
 TimeSeries (TimeSeries &&other) noexcept
 
TimeSeriesoperator= (TimeSeries &&other) noexcept
 
TimeSeriesoperator= (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 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, Datadata_
 

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 33 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 227 of file time_series.cc.

◆ TimeSeries() [3/3]

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

Definition at line 230 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 346 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 382 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 362 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 324 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 246 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 258 of file time_series.cc.

◆ BDM_CLASS_DEF_NV()

bdm::experimental::TimeSeries::BDM_CLASS_DEF_NV ( TimeSeries  ,
 
)
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 78 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 400 of file time_series.cc.

◆ GetXValues()

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

Definition at line 408 of file time_series.cc.

◆ GetYErrorHigh()

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

Definition at line 424 of file time_series.cc.

◆ GetYErrorLow()

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

Definition at line 418 of file time_series.cc.

◆ GetYValues()

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

Definition at line 413 of file time_series.cc.

◆ ListEntries()

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

Print all time series entry names to stdout.

Definition at line 430 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 128 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;
&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 133 of file time_series.cc.

◆ operator=() [1/2]

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

Definition at line 240 of file time_series.cc.

◆ operator=() [2/2]

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

Definition at line 234 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 437 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 442 of file time_series.cc.

◆ Size()

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

Definition at line 405 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 270 of file time_series.cc.

Member Data Documentation

◆ data_

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

Definition at line 198 of file time_series.h.


The documentation for this class was generated from the following files:
bdm::experimental::TimeSeries::TimeSeries
TimeSeries()
bdm::real_t
double real_t
Definition: real_t.h:21
bdm::experimental::TimeSeries::Merge
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)
Definition: time_series.cc:133
bdm::experimental::TimeSeries::Load
static void Load(const std::string &full_filepath, TimeSeries **restored)
Definition: time_series.cc:128