Skip to content

Targets

reels.Targets

Result(iter_id)

Container holding the results of time predictions. It behaves, basically, like an iterator.

Source code in reels/Targets.py
54
55
def __init__(self, iter_id):
    self.iter_id = iter_id

Targets(clips, time_format=None, binary_image=None)

Interface to the c++ container object to hold clips.

This object fits the model for a set of targets defined via insert_target(). Once .

Parameters:

Name Type Description Default
clips Clips

A Clips object containing the clips defining the events for a set of clients.

required
time_format

An optional definition of the time format that will affect how time is parsed by insert_target() the default is "%Y-%m-%d %H:%M:%S" https://www.gnu.org/software/libc/manual/html_node/Formatting-Calendar-Time.html

None
binary_image

An optional binary image (returned by save_as_binary_image()) to initialize the object with data copied from another Clips object. You have to pass empty clips to use this.

None
Source code in reels/Targets.py
87
88
89
90
91
92
93
94
95
def __init__(self, clips: Clips, time_format=None, binary_image=None):
    self.tr_id = new_targets(clips.cp_id)
    self.cp_id = clips.cp_id

    if time_format is not None:
        targets_set_time_format(self.tr_id, time_format)

    if binary_image is not None:
        self.load_from_binary_image(binary_image)

__getstate__()

Used by pickle.dump() (See https://docs.python.org/3/library/pickle.html)

Source code in reels/Targets.py
113
114
115
def __getstate__(self):
    """Used by pickle.dump() (See https://docs.python.org/3/library/pickle.html)"""
    return self.save_as_binary_image()

__setstate__(state)

Used by pickle.load() (See https://docs.python.org/3/library/pickle.html)

Source code in reels/Targets.py
117
118
119
120
def __setstate__(self, state):
    """Used by pickle.load() (See https://docs.python.org/3/library/pickle.html)"""
    self.tr_id = new_targets(new_clips(new_clients(), new_events()))
    self.load_from_binary_image(state)

describe_tree()

Describes some statistics of a fitted tree inside a Targets object.

Returns:

Type Description

On success, it will return a descriptive text with node count numbers for different node content.

Source code in reels/Targets.py
241
242
243
244
245
246
247
248
def describe_tree(self):
    """Describes some statistics of a fitted tree inside a Targets object.

    Returns:
        On success, it will return a descriptive text with node count numbers for different node content.
    """

    return targets_describe_tree(self.tr_id)

describe_tree_node(idx)

Return a tuple (n_seen, n_target, sum_time_d, num_codes) describing a node in the tree by index.

Parameters:

Name Type Description Default
idx

The zero-based index identifying the node (0 for root or a value returned by tree_node_idx()).

required

Returns:

Type Description

A tuple (n_seen, n_target, sum_time_d, num_codes) on success or None on failure.

Source code in reels/Targets.py
226
227
228
229
230
231
232
233
234
235
236
237
238
239
def describe_tree_node(self, idx):
    """Return a tuple (n_seen, n_target, sum_time_d, num_codes) describing a node in the tree by index.

    Args:
        idx: The zero-based index identifying the node (0 for root or a value returned by tree_node_idx()).

    Returns:
        A tuple (n_seen, n_target, sum_time_d, num_codes) on success or None on failure.
    """
    s = targets_describe_tree_node(self.tr_id, idx)

    if len(s) != 0:
        ns, nt, sd, nc = tuple(s.split('\t'))
        return int(ns), int(nt), float(sd), int(nc)

fit(x_form='log', agg='minimax', p=0.5, depth=8, as_states=False)

Fit the prediction model in the object stored after calling insert_target() multiple times.

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

Parameters:

Name Type Description Default
x_form

A possible transformation of the times. (Currently "log" or "linear".)

'log'
agg

The mechanism used for the aggregation. (Currently "minimax", "mean" or "longest".)

'minimax'
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.)

0.5
depth

The maximum depth of the tree (maximum sequence length learned).

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

False

Returns:

Type Description

True on success. Error if already fitted, wrong arguments or the id is not found.

Source code in reels/Targets.py
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def fit(self, x_form="log", agg="minimax", p=0.5, depth=8, as_states=False):
    """Fit the prediction model in the object stored after calling insert_target() multiple times.

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

    Args:
        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.

    Returns:
        True on success. Error if already fitted, wrong arguments or the id is not found.
    """
    return targets_fit(self.tr_id, x_form, agg, p, depth, as_states)

insert_target(client, time)

Define the targets before calling fit() by calling this method once for each client.

Parameters:

Name Type Description Default
client

The "client". A string representing "the actor".

required
time

The "time". A timestamp of the target event as a string. (The format is given via the time_format argument to the constructor.)

required

Returns:

Type Description

True on new clients. False if the client is already in the object or the time

is in the wrong format.

Source code in reels/Targets.py
122
123
124
125
126
127
128
129
130
131
132
133
134
def insert_target(self, client, time):
    """Define the targets before calling fit() by calling this method once for each client.

    Args:
        client: The "client". A string representing "the actor".
        time:   The "time". A timestamp of the target event as a string. (The format
                is given via the time_format argument to the constructor.)

    Returns:
        True on new clients. False if the client is already in the object or the time
        is in the wrong format.
    """
    return targets_insert_target(self.tr_id, client, time)

load_from_binary_image(binary_image)

Load the state of the c++ Targets object from a binary_image returned by a previous save_as_binary_image() call.

Parameters:

Name Type Description Default
binary_image

A list of strings returned by save_as_binary_image()

required

Returns:

Type Description

True on success, destroys, initializes and returns false on failure.

Source code in reels/Targets.py
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
def load_from_binary_image(self, binary_image):
    """Load the state of the c++ Targets object from a binary_image
        returned by a previous save_as_binary_image() call.

    Args:
        binary_image: A list of strings returned by save_as_binary_image()

    Returns:
        True on success, destroys, initializes and returns false on failure.
    """
    failed = False

    for binary_image_block in binary_image:
        if not targets_load_block(self.tr_id, binary_image_block):
            failed = True
            break

    if not failed:
        failed = not targets_load_block(self.tr_id, "")

    if failed:
        destroy_targets(self.tr_id)
        self.tr_id = new_targets(new_clips(new_clients(), new_events()))
        return False

    return True

num_targets()

Number of target point that have been given to the object.

This mostly for debugging, verifying that the number of successful insert_target() is as expected.

Returns:

Type Description

The number of target points stored in the internal target object.

Source code in reels/Targets.py
190
191
192
193
194
195
196
197
198
def num_targets(self):
    """Number of target point that have been given to the object.

        This mostly for debugging, verifying that the number of successful insert_target() is as expected.

    Returns:
        The number of target points stored in the internal target object.
    """
    return targets_num_targets(self.tr_id)

predict_clients(clients)

Predict time to target for all the clients in clients whose clips have been 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.

The model can only predict clips, so this will only work for those clients whose clips are stored in the object,
unlike predict_clips() which is completely general.

Parameters:

Name Type Description Default
clients Clients

The Clients object containing the ids of the clients you want to predict or a list of client ids.

required

Returns:

Type Description

An iterator object containing the results. (Empty on error.)

Source code in reels/Targets.py
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def predict_clients(self, clients: Clients):
    """Predict time to target for all the clients in clients whose clips have been 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.

        The model can only predict clips, so this will only work for those clients whose clips are stored in the object,
        unlike predict_clips() which is completely general.

    Args:
        clients: The Clients object containing the ids of the clients you want to predict or a list of client ids.

    Returns:
        An iterator object containing the results. (Empty on error.)
    """
    if type(clients) == list:
        cli = Clients()
        for c in clients:
            cli.add_client_id(c)
        return Result(targets_predict_clients(self.tr_id, cli.cl_id))

    return Result(targets_predict_clients(self.tr_id, clients.cl_id))

predict_clips(clips)

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

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

Parameters:

Name Type Description Default
clips Clips

The clips you want to predict.

required

Returns:

Type Description

An iterator object containing the results. (Empty on error.)

Source code in reels/Targets.py
177
178
179
180
181
182
183
184
185
186
187
188
def predict_clips(self, clips: Clips):
    """Predict time to target for a set of clients whose clips are given in a Clips object.

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

    Args:
        clips: The clips you want to predict.

    Returns:
        An iterator object containing the results. (Empty on error.)
    """
    return Result(targets_predict_clips(self.tr_id, clips.cp_id))

save_as_binary_image()

Saves the state of the c++ Targets object as a Python list of strings referred to a binary_image.

Returns:

Type Description

The binary_image containing the state of the Targets. There is

not much you can do with it except serializing it as a Python

(e.g., pickle) object and loading it into another Targets object.

Pass it to the constructor to create an initialized object,

Source code in reels/Targets.py
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
def save_as_binary_image(self):
    """Saves the state of the c++ Targets object as a Python
        list of strings referred to a binary_image.

    Returns:
        The binary_image containing the state of the Targets. There is
        not much you can do with it except serializing it as a Python
        (e.g., pickle) object and loading it into another Targets object.
        Pass it to the constructor to create an initialized object,
    """
    bi_idx = targets_save(self.tr_id)
    if bi_idx == 0:
        return None

    bi = []
    bi_size = size_binary_image_iterator(bi_idx)
    for t in range(bi_size):
        bi.append(next_binary_image_iterator(bi_idx))

    destroy_binary_image_iterator(bi_idx)

    return bi

tree_node_children(idx)

Return a list ot the codes of the children of a node in the tree by index.

Parameters:

Name Type Description Default
idx

The zero-based index identifying the node (0 for root or a value returned by tree_node_idx()).

required

Returns:

Type Description

A list of integer codes on success or None on failure.

Source code in reels/Targets.py
212
213
214
215
216
217
218
219
220
221
222
223
224
def tree_node_children(self, idx):
    """Return a list ot the codes of the children of a node in the tree by index.

    Args:
         idx: The zero-based index identifying the node (0 for root or a value returned by tree_node_idx()).

    Returns:
        A list of integer codes on success or None on failure.
    """
    s = targets_tree_node_children(self.tr_id, idx)

    if len(s) != 0:
        return [int(i) for i in s.split('\t')]

tree_node_idx(parent_idx, code)

Returns the index of a tree node by parent node and code.

Parameters:

Name Type Description Default
parent_idx

The index of the parent node which is either 0 for root or returned from a previous tree_node_idx() call.

required
code

The code that leads in the tree from the parent node to the child node.

required

Returns:

Type Description

On success, i.e, if both the parent index exists and contains the code, it will return the index of the child (-1 otherwise).

Source code in reels/Targets.py
200
201
202
203
204
205
206
207
208
209
210
def tree_node_idx(self, parent_idx, code):
    """Returns the index of a tree node by parent node and code.

    Args:
        parent_idx: The index of the parent node which is either 0 for root or returned from a previous tree_node_idx() call.
        code:       The code that leads in the tree from the parent node to the child node.

    Returns:
        On success, i.e, if both the parent index exists and contains the code, it will return the index of the child (-1 otherwise).
    """
    return targets_tree_node_idx(self.tr_id, parent_idx, code)