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

#include <reels.h>

Inheritance diagram for reels::Targets:

Collaboration diagram for reels::Targets:

Public Member Functions
	Targets (pClipMap p_clips, TargetMap target)
	Construct a Targets object from a Clips object and a TargetMap. More...

bool	insert_target (pChar p_c, pChar p_t)
	Utility to fill the internal TargetMap target. More...

bool	fit (Transform x_form, Aggregate agg, double p, int depth, bool as_states)
	Fit the prediction model. More...

TimesToTarget	predict ()
	Predict time to target for all the clients in the Clips object used to fit the model. More...

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. More...

TimesToTarget	predict (pClipMap p_clips)
	Predict time to target for a set of clients whose clips are given in a ClipMap. More...

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. More...

bool	load (pBinaryImage &p_bi)
	Load the state of an object from a base64 mercury-dynamics serialization using image_get() More...

bool	save (pBinaryImage &p_bi)
	Save the state of an object into a base64 mercury-dynamics serialization using image_put() More...

int	update_node (int idx_parent, uint64_t code, bool target, ExtFloat time_d)
	Update (fit) the CodeTree inserting new nodes as necessary. More...

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

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

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. More...

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. More...

double	predict_time (CodeTreeNode &node)
	Predict the time to target for a sub-clip that starts at a node. More...

double	predict_clip (Clip clip)
	Predict the time to target for a clip. More...

bool	recurse_tree_stats (int depth, int idx, int parent_idx, uint64_t code, CodeInTreeStatMap &codes_stat)
	Recursive tree exploration updating a CodeInTreeStatMap map. More...

int	num_targets ()
	Return the size of the internal TargetMap. More...

int	tree_size ()
	Return the size of the internal CodeTree. More...

pClipMap	clip_map ()
	The address of the internal ClipMap. More...

pCodeTree	p_tree ()
	The address of the internal CodeTree. More...

pTargetMap	p_target ()
	The address of the internal TargetMap. More...

Public Member Functions inherited from reels::TimeUtil
	TimeUtil ()

TimePoint	get_time (pChar p_t)
	Convert time as a string to a TimePoint (using the object's time_format). More...

void	set_time_format (pChar fmt)
	Sets the public property time_format to simplify the python interface. More...

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() More...

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_clips	The address of a Clips object initialized with the clips of a set of clients.
target	A 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_hits	The number of successes.
n_total	The 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_hits	The number of successes.
n_total	The 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_form	A possible transformation of the times. (Currently "log" or "linear".)
agg	The mechanism used for the aggregation. (Currently "minimax", "mean" or "longest".)
p	The 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.)
depth	The maximum depth of the tree (maximum sequence length learned).
as_states	Treat 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_c	The "client". A C/Python string representing "the actor".
p_t	The "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_bi	The 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

x	The 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

x	The 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

clients A 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_clips A 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

clip	A 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

node	The 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

depth	The recursion depth
idx	The index of the current node
parent_idx	The index of the parent node
code	The current code
codes_stat	The 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_bi	The 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_parent	The index of the parent node. For the first insertion, root == 0. For more, returned values of this.
code	The node will be the child of the parent node whose code is this code.
target	The target was matched in the clip or not.
time_d	The 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

client	The client hash (needed to see if he fits the target).
clip	The clip we want to predict
obs_time	A variable to store the time between the last even and the target when the target is hit.
target_yn	A variable to store if the target was hit (true) or not (false).
longest_seq	A variable to store the longest aligned matching sequence stored in the tree.
n_visits	A variable to store the number of visits for the longest sequence.
n_targets	A variable to store the number of target hits for the longest sequence.
targ_mean_t	A variable to store average observed time for hits in the longest sequence.

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

reels/reels.h
reels/reels.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Targets()

Member Function Documentation

◆ agresti_coull_lower_bound()

◆ agresti_coull_upper_bound()

◆ clip_map()

◆ fit()

◆ insert_target()

◆ load()

◆ normal_cdf()

◆ normal_pdf()

◆ num_targets()

◆ p_target()

◆ p_tree()

◆ predict() [1/3]

◆ predict() [2/3]

◆ predict() [3/3]

◆ predict_clip()

◆ predict_time()

◆ recurse_tree_stats()

◆ save()

◆ tree_size()

◆ update_node()

◆ verbose_predict_clip()