# The History¶

This module implements the history mechanism of libmunin.

class munin.history.History(maxlen=100, time_threshold_sec=1200, max_group_size=5)[source]

A History implements a mechanism to store groups of songs together that were listened in a certain order.

Songs can be feeded to the history. Songs that were feeded at the same time get into the same group, after some time threshold has passed, a new group is opened. A group may only have a certain size, if the size is exceeded a new group is opened.

The whole history can be set to store only a certain amount of groups. If new groups are added, the oldest ones are removed.

Instance a new History object with these settings:

Parameters: maxlen – Max. number of groups that may be fed to the history. time_threshold_sec – Time after which a new group is opened, even if the current group is not yet full. max_group_size – Max. size of a single group.
clear()[source]

Clear the history fully.

Will be as freshly instantiated afterwards.

count_keys()[source]

Count the key distribution of the songs in the history

Not all songs have all keys set. This can be helpful to find often missing data.

Returns: A collections.Counter object with each attribute and their count.
count_listens()[source]

Count the listens of the songs in the history

Returns: A collections.Counter object with each song and their count.
feed(song)[source]

Feed a single song to the History.

Parameters: song (A munin.song.Song) – The song to add to the listen history. True if a new group was started.
groups()[source]

Return an iterator to iterate over all groups in the History.

Returns: an iterator that yields a list of iteralbes with songs in it.
last_time()[source]

Gives the last inserted timestamp, or if empty, the current time

class munin.history.ListenHistory(maxlen=10000, max_group_size=5, time_threshold_sec=1200)[source]

A History that holds all recently listened Songs.

Sane defaults are chosen for History.__init__

find_rules(itemsets=None, min_support=2, **kwargs)[source]

Find frequent itemsets and try to find association rules in them.

Parameters: itemsets – A itemset-mapping, as returned by frequent_itemsets(). If None, the current history will be mined.

This function takes the same finetuning parameters as :funcassociation_rules.

Returns: An iterable of rules, each rule being a tuple. [(left, right, support, confidence, kulc, ir), ...]
frequent_itemsets(min_support=2)[source]

Mine frequent item sets (FIM) using the RELIM algorithm.

Parameters: min_support – Minimum count of occurences an itemset must have to be returned. A mapping of itemsets to their supportcount. dict(set=int)
class munin.history.RecommendationHistory(penalty_map={'album': 5, 'artist': 3}, **kwargs)[source]

bad shall be defined as follows: If a recommendation with e.g. the same artist is repeated, even though, the previous recommendation was from this artist it’s called bad. The same applies for the album or even for the genre.

In this case we might consider to give a penalty to those, so that the same artist only might be recommended within the range of, say, 3 recommendations, and the same album might only be recommended in the range of 5 recommendations.

The RecommendationHistory can do this for any attribute you might think of.

Note

This takes the same keyword arguments as History, but maxlen will be silenty ignored.

Parameters: penalty_map – A mapping from attribute s to a penalty count i.e. the number of recommendations to wait before allowing it again.
allowed(recommendation)[source]

Check if a recommendation is allowed, i.e. if it someting similar was not recently recommended.

Parameters: recommendation (munin.song.Song) – The recommendation to check for forbidden attributes. True if it is allowed, i.e. all possibly forbidden attributes are long enough ago.
class munin.history.RuleIndex(maxlen=1000)[source]

A Manager for all known and usable rules.

This class offers an Index for all rules, so one can ask for all rules that affect a certain song. Additionally the number of total rules are limited by specifying a maxlen. If more rules are added they become invalid and get deleted on the next add or once all adds were done (with begin_add_many()).

Duplicated rules are silently ignored.

This class implements the contains operator to check if a rule tuple is in the index. Also __iter__ is supported, and will yield the rules in the index sorted by their Kulczynski measure multiplied by their imbalance ratio.

Create a new Index with a certain maximal length:

Parameters: maxlen – Max. number of rules to save, or 0 for no limit.

>>> with rule_index.begin_add_many():
...    rule_index.insert_rule(...)


Calls drop_invalid() after being done.

best()[source]

Return the currently best rule (the one with the highest rating)

Requires linear complexity. This could be optimized.

Returns: A ruletuple or None if no rule yet in the index.
clear()[source]

Clear all known rules.

This really does what it says. Be careful.

drop_invalid()[source]

Delete invalid rules from the cache.

Often, a large number of rules is added at once. For maintaining a valid index, rules that are no longer valid need to be deleted from the cache, which takes linear time.

With this, the cache is checked for consistenct only once all rules were added, which might be a lot faster for many rules.

insert_rule(rule_tuple, drop_invalid=False)[source]

Add a new rule to the index.

Parameters: rule_tuple – The rule to add, coming from association_rules(). drop_invalid – If True, delete the first element immediately if index is too large.
insert_rules(rule_tuples)[source]

Convienience function for adding many rules at once.

Calls drop_invalid() when done inserting.

Parameters: rule_tuples – a list of rule tuples.
lookup(song)[source]

Lookup all rules that would affect a certain song.

Parameters: song (munin.song.Song) – The song to lookup. An iterable with all rule_tuples affecting this song.
munin.history.append_rule(data, visited, rules, known_rules, support, left, right, min_confidence, min_kulc, max_ir)[source]

Internal Function. Append a rule if it’s good enoguh to rules.

Parameters: visited – Set of visited pairs. known_rules – Rules that are known, and do not need to be recaclulated. support – Support count for this rule.
munin.history.association_rules(data, min_confidence=0.5, min_support=2, min_kulc=0.66, max_ir=0.35)[source]

Compute strong association rules from the itemset_to_support dict in data.

Inspiration for some tricks in this function were take from:

The rating of a rule is defined as: (1 - imbalance_ratio) * kulczynski

Parameters: data (dict(set=int)) – Mapping between itemsets and support counts

Fine grained finetuning is possible with the following parameters:

Parameters: min_confidence (float) – Minimal confidence a rule must have (from 0 to 1, higher is better) min_support (int) – Minimal support an itemset must have. Lowers ones are filtered out and only used for lookup. min_kulc (float) – Minimum Kulczynski measure (from 0 to 1, higher is better) max_ir (float) – Maximum Imbalance Ratio (from 0 to 1, lower is better) An iterable with rules. [(left, right, support, rating), ...]