Skip to content

Commit

Permalink
Merge pull request #23 from BBVA/feature/doc_issues
Browse files Browse the repository at this point in the history 
Feature/doc issues
  • Loading branch information
@sbasaldua
sbasaldua authored Mar 14, 2024
2 parents 1d5895a + 0e7f666 commit 152ca84
Show file tree
Hide file tree
Showing 12 changed files with 365 additions and 370 deletions.
2 changes: 1 addition & 1 deletion notebooks/reels_event_optimization_colab.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1714,7 +1714,7 @@
"\n",
"The next two, `sum_dep` and `n_dep` provide an idea of how deep the code is found on average (== sum_dep/n_dep) in the sequence and can be used in the score when exponential decay is not zero.\n",
"\n",
"The next is `edf` (exponential decay factor) and multiplies the final score. E.g. If we set `exponential_decay` to 0.00693 it decays to approx 0.5 in 100 steps because (1- 0.00693)^100 is 0.4988.\n",
"The next is `edf` (exponential decay factor) and multiplies the final score. E.g. If we set `exp_decay` to 0.00693 it decays to approx 0.5 in 100 steps because (1- 0.00693)^100 is 0.4988.\n",
"\n",
"The next two are the proportion (or lower bound for the confidence interval) of target/seen for both \"incl\" and \"succ\" as explained above.\n",
"\n",
Expand Down
2 changes: 1 addition & 1 deletion src/Doxyfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -499,7 +499,7 @@ NUM_PROC_THREADS = 1
# normally produced when WARNINGS is set to YES.
# The default value is: NO.

EXTRACT_ALL = NO
EXTRACT_ALL = YES

# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
# be included in the documentation.
Expand Down
33 changes: 16 additions & 17 deletions src/reels/Clients.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,6 @@ def __next__(self):


class Clients:

"""Interface to the c++ container object to hold clients.
The purpose of this object is to be filled (via successive add_client_id()
Expand All @@ -62,9 +61,8 @@ class Clients:
for size and iterated by calling client_hashes().
Args:
binary_image: An optional binary image (returned by save_as_binary_image())
to initialize the object with data copied from another Clients
object.
binary_image (list): An optional binary image (returned by save_as_binary_image())
to initialize the object with data copied from another Clients object.
"""

def __init__(self, binary_image=None):
Expand Down Expand Up @@ -98,38 +96,39 @@ def hash_client_id(self, client):
"""Convert a client id into a hash (as stored buy the internal C** Clients object).
Args:
client: The "client". A string representing "the actor".
client (str): The "client". A string representing "the actor".
Returns:
The hash as a decimal python string starting with 'h' to prevent numeric conversion.
(str): The hash as a decimal python string starting with 'h' to prevent numeric conversion.
"""
return clients_hash_client_id(self.cl_id, client)

def add_client_id(self, client):
"""Define clients explicitly.
Args:
client: The "client". A string representing "the actor".
client (str): The "client". A string representing "the actor".
Returns:
True on success.
(bool): True on success.
"""
return clients_add_client_id(self.cl_id, client)

def client_hashes(self):
"""Return an iterator to iterate over all the hashed client ids.
Returns:
An iterator (a ClientsHashes object)
(ClientsHashes): An iterator (a ClientsHashes object)
"""
return ClientsHashes(self.cl_id, self.num_clients())

def num_clients(self):
"""Return the number of clients in the object.
The container will add one client per add_client_id() call and keep the order.
Returns:
The number of clients stored in the object which may include repeated ids.
The container will add one client per add_client_id() call and keep the order.
(int): The number of clients stored in the object which may include repeated ids.
"""
return clients_num_clients(self.cl_id)

Expand All @@ -138,10 +137,10 @@ def save_as_binary_image(self):
list of strings referred to a binary_image.
Returns:
The binary_image containing the state of the Clients. There is
not much you can do with it except serializing it as a Python
(e.g., pickle) object and loading it into another Clients object.
Pass it to the constructor to create an initialized object,
(list): The binary_image containing the state of the Clients. There is
not much you can do with it except serializing it as a Python
(e.g., pickle) object and loading it into another Clients object.
Pass it to the constructor to create an initialized object,
"""
bi_idx = clients_save(self.cl_id)
if bi_idx == 0:
Expand All @@ -161,10 +160,10 @@ def load_from_binary_image(self, binary_image):
returned by a previous save_as_binary_image() call.
Args:
binary_image: A list of strings returned by save_as_binary_image()
binary_image (list): A list of strings returned by save_as_binary_image()
Returns:
True on success, destroys, initializes and returns false on failure.
(bool): True on success, destroys, initializes and returns false on failure.
"""
failed = False

Expand Down
38 changes: 18 additions & 20 deletions src/reels/Clips.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,6 @@ def __next__(self):


class Clips:

"""Interface to the c++ container object to hold clips.
The purpose of this object is to be filled (via successive scan_event()
Expand All @@ -81,7 +80,7 @@ class Clips:
"""

def __init__(
self, clients: Clients, events: Events, time_format=None, binary_image=None
self, clients: Clients, events: Events, time_format: str=None, binary_image: list=None
):
self.cp_id = new_clips(clients.cl_id, events.ev_id)

Expand Down Expand Up @@ -109,7 +108,7 @@ def __setstate__(self, state):
self.cp_id = new_clips(new_clients(), new_events())
self.load_from_binary_image(state)

def scan_event(self, emitter, description, weight, client, time):
def scan_event(self, emitter: str, description: str, weight: float, client: str, time: str):
"""Process a row from a transaction file, to add the event to the client's timeline in a Clips object.
Args:
Expand All @@ -121,44 +120,43 @@ def scan_event(self, emitter, description, weight, client, time):
is given via the time_format argument to the constructor.)
Returns:
True on insertion. False usually just means, the event is not in events
or the client is not in clients. It may be a time parsing error too.
(bool): True on insertion. False usually just means, the event is not in events
or the client is not in clients. It may be a time parsing error too.
"""
return clips_scan_event(self.cp_id, emitter, description, weight, client, time)

def clips_client_hashes(self):
"""Return an iterator to iterate over all the hashed client ids.
Returns:
An iterator (a ClipsHashes object)
(ClipsHashes): An iterator (a ClipsHashes object)
"""
return ClipsHashes(self.cp_id)

def num_clips(self):
"""Return the number of clips in the object.
Returns:
The number of clips stored in the object. Clips are indexed by unique
client hash.
(int): The number of clips stored in the object. Clips are indexed by unique client hash.
"""
return clips_num_clips(self.cp_id)

def num_events(self):
"""Return the number of events counting all the clips stored by the object.
Returns:
The number of events stored in the object.
(int): The number of events stored in the object.
"""
return clips_num_events(self.cp_id)

def describe_clip(self, client):
"""Return a list ot the codes in chronological order for a given client.
Args:
client: Either a client identifier or the hash of a client identifier returned by Clients.hash_client_id().
client (str): Either a client identifier or the hash of a client identifier returned by Clients.hash_client_id().
Returns:
A list of integer codes on success or None on failure.
(list): A list of integer codes on success or None on failure.
"""
s = clips_describe_clip(self.cp_id, client)

Expand All @@ -170,10 +168,10 @@ def save_as_binary_image(self):
list of strings referred to a binary_image.
Returns:
The binary_image containing the state of the Clips. There is
not much you can do with it except serializing it as a Python
(e.g., pickle) object and loading it into another Clips object.
Pass it to the constructor to create an initialized object,
(list): The binary_image containing the state of the Clips. There is
not much you can do with it except serializing it as a Python
(e.g., pickle) object and loading it into another Clips object.
Pass it to the constructor to create an initialized object,
"""
bi_idx = clips_save(self.cp_id)
if bi_idx == 0:
Expand All @@ -193,10 +191,10 @@ def load_from_binary_image(self, binary_image):
returned by a previous save_as_binary_image() call.
Args:
binary_image: A list of strings returned by save_as_binary_image()
binary_image (list): A list of strings returned by save_as_binary_image()
Returns:
True on success, destroys, initializes and returns false on failure.
(bool): True on success, destroys, initializes and returns false on failure.
"""
failed = False

Expand All @@ -220,11 +218,11 @@ def test_sequence(self, seq_num, target):
This returns one of the 500 non target sequences or one of the 500 target sequences.
Args:
seq_num: The sequence id (in range 0.499).
target: True for one of the target sequences, false for non target.
seq_num (int): The sequence id (in range 0.499).
target (bool): True for one of the target sequences, false for non target.
Returns:
A sequence of integer codes list or None if seq_num is out of range.
(list): A sequence of integer codes list or None if seq_num is out of range.
"""

s = clips_test_sequence(seq_num, target)
Expand Down
61 changes: 30 additions & 31 deletions src/reels/Events.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,6 @@ def __next__(self):


class Events:

"""Interface to the c++ container object to hold events.
The purpose of this object is to be filled (either via successive
Expand All @@ -67,11 +66,11 @@ class Events:
methods exist.
Args:
max_num_events: The maximum number of events to limit the discovery via
insert_row() to the max_num_events more frequent/recent.
binary_image: An optional binary image (returned by save_as_binary_image())
to initialize the object with data copied from another Events
object.
max_num_events (int): The maximum number of events to limit the discovery via
insert_row() to the max_num_events more frequent/recent.
binary_image (bool): An optional binary image (returned by save_as_binary_image())
to initialize the object with data copied from another Events
object.
"""

def __init__(self, max_num_events=1000, binary_image=None):
Expand Down Expand Up @@ -111,12 +110,12 @@ def insert_row(self, emitter, description, weight):
either one way or the other.
Args:
emitter: The "emitter". A C/Python string representing "owner of event".
description: The "description". A C/Python string representing "the event".
weight: The "weight". A double representing a weight of the event.
emitter (str): The "emitter". A C/Python string representing "owner of event".
description (str): The "description". A C/Python string representing "the event".
weight (float): The "weight". A double representing a weight of the event.
Returns:
True on success.
(bool): True on success.
"""
return events_insert_row(self.ev_id, emitter, description, weight)

Expand All @@ -128,29 +127,29 @@ def define_event(self, emitter, description, weight, code):
either one way or the other.
Args:
emitter: The "emitter". A C/Python string representing "owner of event".
description: The "description". A C/Python string representing "the event".
weight: The "weight". A double representing a weight of the event.
code: A unique code number identifying the event.
emitter (str): The "emitter". A C/Python string representing "owner of event".
description (str): The "description". A C/Python string representing "the event".
weight (float): The "weight". A double representing a weight of the event.
code (int): A unique code number identifying the event.
Returns:
True on success.
(bool): True on success.
"""
return events_define_event(self.ev_id, emitter, description, weight, code)

def num_events(self):
"""Return the number of events in the object.
Returns:
The number of events stored in the object.
(int): The number of events stored in the object.
"""
return events_num_events(self.ev_id)

def describe_events(self):
"""Return an iterator of (emitter, description, weight, code) tuples describing all events.
Returns:
An iterator of (emitter, description, weight, code) tuple on success or None on failure.
(EventTuples): An iterator of (emitter, description, weight, code) tuple on success or None on failure.
"""
return EventTuples(self.ev_id)

Expand All @@ -159,10 +158,10 @@ def save_as_binary_image(self):
list of strings referred to a binary_image.
Returns:
The binary_image containing the state of the Events. There is
not much you can do with it except serializing it as a Python
(e.g., pickle) object and loading it into another Events object.
Pass it to the constructor to create an initialized object,
(list): The binary_image containing the state of the Events. There is
not much you can do with it except serializing it as a Python
(e.g., pickle) object and loading it into another Events object.
Pass it to the constructor to create an initialized object,
"""
bi_idx = events_save(self.ev_id)
if bi_idx == 0:
Expand All @@ -182,10 +181,10 @@ def load_from_binary_image(self, binary_image):
returned by a previous save_as_binary_image() call.
Args:
binary_image: A list of strings returned by save_as_binary_image()
binary_image (list): A list of strings returned by save_as_binary_image()
Returns:
True on success, destroys, initializes and returns false on failure.
(bool): True on success, destroys, initializes and returns false on failure.
"""
failed = False

Expand All @@ -204,9 +203,9 @@ def load_from_binary_image(self, binary_image):

return True

def optimize_events(self, clips, targets, num_steps=10, codes_per_step=5, threshold=0.0001, force_include='',
force_exclude='', x_form='linear', agg='longest', p=0.5, depth=1000, as_states=True,
exp_decay=0.00693, lower_bound_p=0.95, log_lift=True):
def optimize_events(self, clips: int, targets: int, num_steps: int=10, codes_per_step: int=5, threshold: float=0.0001,
force_include: str='', force_exclude: str='', x_form: str='linear', agg: str='longest', p: float=0.5,
depth: int=1000, as_states: bool=True, exp_decay: float=0.00693, lower_bound_p: float=0.95, log_lift: bool=True):
"""Events optimizer.
Optimizes the events to maximize prediction signal. (F1 score over same number of positives.)
Expand Down Expand Up @@ -245,7 +244,7 @@ def optimize_events(self, clips, targets, num_steps=10, codes_per_step=5, thresh
log_lift: A boolean to set if lift (= LB(included)/LB(after inclusion)) is log() transformed or not.
Returns:
A tuple (success, dictionary, top_codes, log)
(tuple): A tuple (success, dictionary, top_codes, log)
"""

ret = events_optimize_events(self.ev_id, clips.cp_id, targets.tr_id, num_steps, codes_per_step, threshold, force_include,
Expand Down Expand Up @@ -281,12 +280,12 @@ def copy(self, dictionary = None):
with either optimize_events() or a Targets object, not to continue populating it with events via insert_row().
Args:
dictionary: A dictionary to be applied during the copy. The dictionary must be returned by a previous optimize_events()
of an identical object in order to have the same codes defined. Otherwise, the codes not present in the dictionary
will not be translated into events.
dictionary (dict): A dictionary to be applied during the copy. The dictionary must be returned by a previous optimize_events()
of an identical object in order to have the same codes defined. Otherwise, the codes not present in the dictionary
will not be translated into events.
Returns:
A new Events object
(Events): A new Events object
"""

ret = Events(max_num_events = self.max_num_events)
Expand Down
Loading

0 comments on commit 152ca84

Please sign in to comment.