def explain_recommendation(self, seed_song, recommendation, max_reasons=3):
"""Explain the recommendation you got.
**Usage Example:**
>>> explain_recommendation(seed_song, recommendation)
(~0.4, [
('genre', 0.1), # Very similar common attribute
('moodbar', 0.2), # Quite similar
('lyrics', 0.5) # Well, that's okay.
])
:param seed_song: The seed song used.
For ``_heuristic`` and ``_attribute`` this is the first song.
:param recommendation: The recommendation you want to have explained.
:param max_reasons: How many reasons to yield at a maximum.
:retruns: Tuple of the total distance to each other and a list of pairs
that consist of (attribute_name: subdistance_float)
"""
seed_song = song_or_uid(self.database, seed_song)
recommend = song_or_uid(self.database, recommendation)
return munin.graph.explain_recommendation(
self,
seed_song,
recommend,
max_reasons
)
def modify(self, song, sub_value_mapping):
"""Modify an existing and known song by the attributes mentioned
in ``sub_value_mapping``.
This should be run during the ``fix_graph`` contextmanager.
Usage example:
.. code-block:: python
>>> with session.fix_graph():
... session.modify(some_song, {'rating': 5})
One usecase is shown in the example, the adjustment of the rating.
.. note::
This is **not a cheap function**. The song is removed and all
distances to it are recalculated under the hood.
.. seealso::
:meth:`munin.session.Session.insert`
.. warning::
Attention! The returned uid is the same as before, but the underlying
song is different. Do not compare by reference!
:param song: The song to modify, either an uid or a :class:`munin.song.Song`
:param sub_value_mapping: A mapping of attributes in values.
:returns: ``song.uid``
"""
song = song_or_uid(self.database, song)
return self.database.modify(song, sub_value_mapping)
def feed_history(self, song):
"""Feed a single song to the history.
If the feeded song is not yet in the database,
it will be added automatically.
:param song: The song to feed in the history.
"""
self.database.feed_history(song_or_uid(self.database, song))
def playcount(self, song):
"""Get the playcount of a song.
If no playcount is known for it, 0 will be returned.
:returns: Number of times this song was played.
:rtype: int
"""
song = song_or_uid(self.database, song)
return self.database.playcount(song)
def remove(self, song):
"""Remove a single song (or *UID*) from the Graph.
This function will try to close the hole. If :meth:`insert`
is called afterwards the *UID* of the deleted song will be re-used.
:returns: The *UID* of the deleted song.
"""
song = song_or_uid(self.database, song)
return self.database.remove(song.uid)
def recommend_from_seed(self, song, number=20):
"""Recommend songs based on a certain attribute.
For example you can search by a certain genre by calling it like this: ::
>>> recommend_from_attributes({'genre', 'death metal'}, ...)
The value passed must match fully, no fuzzy matching is performed.
:returns: Recommendations like the others or None if no suitable song found.
"""
song = song_or_uid(self.database, song)
return self._recom_sieve(munin.graph.recommendations_from_seed(
self.database,
self.rule_index,
song
), number)
