Reels
Loading...
Searching...
No Matches
Public Member Functions | List of all members
reels::Targets Class Reference

A container class to hold target events and do predictions based on clips. More...

#include <reels.h>

Inheritance diagram for reels::Targets:
Inheritance graph
[legend]
Collaboration diagram for reels::Targets:
Collaboration graph
[legend]

Public Member Functions

 Targets (pClipMap p_clips, TargetMap target)
 Construct a Targets object from a Clips object and a TargetMap.
 
bool insert_target (pChar p_c, pChar p_t)
 Utility to fill the internal TargetMap target.
 
bool fit (Transform x_form, Aggregate agg, double p, int depth, bool as_states)
 Fit the prediction model.
 
TimesToTarget predict ()
 Predict time to target for all the clients in the Clips object used to fit the model.
 
TimesToTarget predict (Clients clients)
 Predict time to target for all the clients in a given Clients object whose clips have been used to fit the model.
 
TimesToTarget predict (pClipMap p_clips)
 Predict time to target for a set of clients whose clips are given in a ClipMap.
 
void verbose_predict_clip (const ElementHash &client, Clip &clip, TimePoint &obs_time, bool &target_yn, int &longest_seq, uint64_t &n_visits, uint64_t &n_targets, double &targ_mean_t)
 Predict time for a single Clip returning all kind of prediction related information.
 
bool load (pBinaryImage &p_bi)
 Load the state of an object from a base64 mercury-dynamics serialization using image_get()
 
bool save (pBinaryImage &p_bi)
 Save the state of an object into a base64 mercury-dynamics serialization using image_put()
 
int update_node (int idx_parent, uint64_t code, bool target, ExtFloat time_d)
 Update (fit) the CodeTree inserting new nodes as necessary.
 
double normal_pdf (double x)
 Density (pdf) for the normal distribution with mean 0 and standard deviation 1.
 
double normal_cdf (double x)
 Cumulative distribution (cdf) for the normal distribution with mean 0 and standard deviation 1.
 
double agresti_coull_upper_bound (uint64_t n_hits, uint64_t n_total)
 Upper bound of the Agresti-Coull confidence interval for a binomial proportion.
 
double agresti_coull_lower_bound (uint64_t n_hits, uint64_t n_total)
 Lower bound of the Agresti-Coull confidence interval for a binomial proportion.
 
double predict_time (CodeTreeNode &node)
 Predict the time to target for a sub-clip that starts at a node.
 
double predict_clip (Clip clip)
 Predict the time to target for a clip.
 
bool recurse_tree_stats (int depth, int idx, int parent_idx, uint64_t code, CodeInTreeStatMap &codes_stat)
 Recursive tree exploration updating a CodeInTreeStatMap map.
 
int num_targets ()
 Return the size of the internal TargetMap.
 
int tree_size ()
 Return the size of the internal CodeTree.
 
pClipMap clip_map ()
 The address of the internal ClipMap.
 
pCodeTree p_tree ()
 The address of the internal CodeTree.
 
pTargetMap p_target ()
 The address of the internal TargetMap.
 
- Public Member Functions inherited from reels::TimeUtil
TimePoint get_time (pChar p_t)
 Convert time as a string to a TimePoint (using the object's time_format).
 
void set_time_format (pChar fmt)
 Sets the public property time_format to simplify the python interface.
 

Additional Inherited Members

- Public Attributes inherited from reels::TimeUtil
char time_format [128] = "%Y-%m-%d %H:%M:%S"
 Date and time format for insert_row() and define_event()
 

Detailed Description

A container class to hold target events and do predictions based on clips.

Constructor & Destructor Documentation

◆ Targets()

reels::Targets::Targets ( pClipMap  p_clips,
TargetMap  target 
)
inline

Construct a Targets object from a Clips object and a TargetMap.

Parameters
p_clipsThe address of a Clips object initialized with the clips of a set of clients.
targetA TargetMap with the even times for a subset of the same clients (those who experienced the target).

Member Function Documentation

◆ agresti_coull_lower_bound()

double reels::Targets::agresti_coull_lower_bound ( uint64_t  n_hits,
uint64_t  n_total 
)
inline

Lower bound of the Agresti-Coull confidence interval for a binomial proportion.

The confidence level is passed as an argument to the fit() method, the fit method computes some "binomial_z.*" variables used in this function.

Parameters
n_hitsThe number of successes.
n_totalThe number of independent trials.
Returns
The upper bound of the AC confidence interval.

◆ agresti_coull_upper_bound()

double reels::Targets::agresti_coull_upper_bound ( uint64_t  n_hits,
uint64_t  n_total 
)
inline

Upper bound of the Agresti-Coull confidence interval for a binomial proportion.

The confidence level is passed as an argument to the fit() method, the fit method computes some "binomial_z.*" variables used in this function.

Parameters
n_hitsThe number of successes.
n_totalThe number of independent trials.
Returns
The upper bound of the AC confidence interval.

◆ clip_map()

pClipMap reels::Targets::clip_map ( )
inline

The address of the internal ClipMap.

Returns
The address.

◆ fit()

bool reels::Targets::fit ( Transform  x_form,
Aggregate  agg,
double  p,
int  depth,
bool  as_states 
)

Fit the prediction model.

Parameters
x_formA possible transformation of the times. (Currently "log" or "linear".)
aggThe mechanism used for the aggregation. (Currently "minimax", "mean" or "longest".)
pThe width of the confidence interval for the binomial proportion used to calculate the lower bound. (E.g., p = 0.5 will estimate a lower bound of a symmetric CI with coverage of 0.5.)
depthThe maximum depth of the tree (maximum sequence length learned).
as_statesTreat events as states by removing repeated ones from the ClipMap keeping the time of the first instance only. When used, the ClipMap passed to the constructor by reference will be converted to states as a side effect.

Fit can only be called once in the life of a Targets object and predict() cannot be called before fit().

Returns
True on success. Error is already fitted or wrong arguments.

◆ insert_target()

bool reels::Targets::insert_target ( pChar  p_c,
pChar  p_t 
)

Utility to fill the internal TargetMap target.

The TargetMap can be initialized and given to the constructor, or an empty TargetMap can be given to the constructor ans initialized by this method.

Parameters
p_cThe "client". A C/Python string representing "the actor".
p_tThe "time". A timestamp of the event as a C/Python string. (The format is given via set_time_format().)
Returns
True on new clients. False if the client is already in the TargetMap or the time is in the wrong format.

◆ load()

bool reels::Targets::load ( pBinaryImage p_bi)

Load the state of an object from a base64 mercury-dynamics serialization using image_get()

Parameters
p_biThe address of a BinaryImage stream containing a previously save()-ed image at the cursor position.
Returns
True on success (Most likely error is a wrong stream).

◆ normal_cdf()

double reels::Targets::normal_cdf ( double  x)
inline

Cumulative distribution (cdf) for the normal distribution with mean 0 and standard deviation 1.

Parameters
xThe quantile.
Returns
The cumulative probability.

◆ normal_pdf()

double reels::Targets::normal_pdf ( double  x)
inline

Density (pdf) for the normal distribution with mean 0 and standard deviation 1.

Parameters
xThe quantile.
Returns
The density.

◆ num_targets()

int reels::Targets::num_targets ( )
inline

Return the size of the internal TargetMap.

Returns
Size of the internal TargetMap.

◆ p_target()

pTargetMap reels::Targets::p_target ( )
inline

The address of the internal TargetMap.

Returns
The address.

◆ p_tree()

pCodeTree reels::Targets::p_tree ( )
inline

The address of the internal CodeTree.

Returns
The address.

◆ predict() [1/3]

TimesToTarget reels::Targets::predict ( )

Predict time to target for all the clients in the Clips object used to fit the model.

predict() cannot be called before fit() and can be called any number of times in all overloaded forms after that.

Returns
A vector with the times.

◆ predict() [2/3]

TimesToTarget reels::Targets::predict ( Clients  clients)

Predict time to target for all the clients in a given Clients object whose clips have been used to fit the model.

It will predict the prediction of the zero-length clip (accumulated in the root node) if the client is not found.

Parameters
clientsA Clients object with a subset of the clients used to fit the model.

predict() cannot be called before fit() and can be called any number of times in all overloaded forms after that.

Returns
A vector with the times.

◆ predict() [3/3]

TimesToTarget reels::Targets::predict ( pClipMap  p_clips)

Predict time to target for a set of clients whose clips are given in a ClipMap.

Parameters
p_clipsA ClipMap of clients and clips to be used in prediction.

predict() cannot be called before fit() and can be called any number of times in all overloaded forms after that.

Returns
A vector with the times.

◆ predict_clip()

double reels::Targets::predict_clip ( Clip  clip)
inline

Predict the time to target for a clip.

Parameters
clipA clip containing a sequence of event codes.
Returns
The predicted time to the target event.

◆ predict_time()

double reels::Targets::predict_time ( CodeTreeNode node)
inline

Predict the time to target for a sub-clip that starts at a node.

This method assumes uniform distribution over time of the events (like Poisson distribution) but weighted by evidence.

Basically, we assume that the observed maximum likelihood time (mu_hat) is the mean (therefore the half) of a uniform distribution U(0, 2*mu_hat) and the whole "event space", if estimated without bias, would be U(0, 2*mu_hat*n_seen/n_target).

Caveat 1. We don't want it unbiased, but biased by evidence, because many estimates will be done, "lucky paths" are a real thing, especially with low number of visits. That is why we use agresti_coull_lower_bound() and not n_seen/n_target. Note that, of course, as you reduce the confidence (the p argument of fit), you will make it approach n_seen/n_target.

Caveat 2. We, intentionally bias towards underestimating the urgency. With much evidence, it will be close to unbiased, but with little evidence, if will underrepresent the urgency (proximity of the event happening). This is why minimax will select the most urgent (min) of the biased up values (max).

Caveat 3. mu_hat is numerically more stable if the transformation is log (although the aggregation it is computed in 128 bit floating point arithmetic which should be stable either way) but, in that case mu_hat will not be the mean time, but its geometric mean (since adding logs is multiplying).

Parameters
nodeThe node in the tree defining the sub-clip.
Returns
The predicted time to the target event.

◆ recurse_tree_stats()

bool reels::Targets::recurse_tree_stats ( int  depth,
int  idx,
int  parent_idx,
uint64_t  code,
CodeInTreeStatMap codes_stat 
)

Recursive tree exploration updating a CodeInTreeStatMap map.

Parameters
depthThe recursion depth
idxThe index of the current node
parent_idxThe index of the parent node
codeThe current code
codes_statThe CodeInTreeStatMap being updated
Returns
False on error.

◆ save()

bool reels::Targets::save ( pBinaryImage p_bi)

Save the state of an object into a base64 mercury-dynamics serialization using image_put()

Parameters
p_biThe address of a BinaryImage stream that is either empty or has been used only for writing.
Returns
True on success (Most likely error is allocation).

◆ tree_size()

int reels::Targets::tree_size ( )
inline

Return the size of the internal CodeTree.

Returns
Size of the internal CodeTree.

◆ update_node()

int reels::Targets::update_node ( int  idx_parent,
uint64_t  code,
bool  target,
ExtFloat  time_d 
)
inline

Update (fit) the CodeTree inserting new nodes as necessary.

Parameters
idx_parentThe index of the parent node. For the first insertion, root == 0. For more, returned values of this.
codeThe node will be the child of the parent node whose code is this code.
targetThe target was matched in the clip or not.
time_dThe time difference from the code to the target (when there is a target, must be 0 otherwise).
Returns
The index of the current node.

◆ verbose_predict_clip()

void reels::Targets::verbose_predict_clip ( const ElementHash client,
Clip clip,
TimePoint obs_time,
bool &  target_yn,
int &  longest_seq,
uint64_t &  n_visits,
uint64_t &  n_targets,
double &  targ_mean_t 
)

Predict time for a single Clip returning all kind of prediction related information.

Parameters
clientThe client hash (needed to see if he fits the target).
clipThe clip we want to predict
obs_timeA variable to store the time between the last even and the target when the target is hit.
target_ynA variable to store if the target was hit (true) or not (false).
longest_seqA variable to store the longest aligned matching sequence stored in the tree.
n_visitsA variable to store the number of visits for the longest sequence.
n_targetsA variable to store the number of target hits for the longest sequence.
targ_mean_tA variable to store average observed time for hits in the longest sequence.

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