VisualApp

class rectools.visuals.visual_app.VisualApp(data_storage: AppDataStorage, auto_display: bool = True, formatters: Optional[Dict[str, Callable]] = None, rows_limit: int = 20, min_width: int = 50)[source]

Bases: VisualAppBase

Jupyter widgets app for user-to-item recommendations visualization and models comparison. Do not create instances of this class directly. Use VisualApp.construct method instead.

Inherited-members

Parameters

  • data_storage (AppDataStorage) –

  • auto_display (bool) –

  • formatters (Optional[Dict[str, Callable]]) –

  • rows_limit (int) –

  • min_width (int) –

Methods

construct(reco, interactions, item_data[, ...])

Construct visualization app for classic user-to-item recommendations.

display()

Display full VisualApp widget

load(folder_name[, auto_display, ...])

Create widgets from data that was processed and saved earlier.

save(folder_name[, overwrite])

Save stored data to re-create widgets when necessary.
classmethod construct(reco: Union[DataFrame, Dict[Hashable, DataFrame]], interactions: DataFrame, item_data: DataFrame, selected_users: Optional[Dict[Hashable, Hashable]] = None, n_random_users: int = 0, auto_display: bool = True, formatters: Optional[Dict[str, Callable]] = None, rows_limit: int = 20, min_width: int = 100) → VisualApp[source]

Construct visualization app for classic user-to-item recommendations.

This will process raw data and create Jupyter widgets for visual analysis and comparison of different models. Created app outputs both interactions history of the selected users and their recommended items from different models along with explicit items data.

Model names for comparison will be listed from the reco dictionary keys or reco dataframe Columns.Model values depending on the format provided.

Users for comparison can be predefined or random. For predefined users pass selected_users dict with user “names” as keys and user ids as values. For random users pass n_random_users number greater then 0. You must specify at least one of the above or provide both.

Optionally provide formatters to process dataframe columns values to desired html outputs.

Parameters

  • reco (tp.Union[pd.DataFrame, TablesDict]) –

    Recommendations from different models in a form of a pd.DataFrame or a dict. In the dict form model names are supposed to be dict keys, and recommendations from different models are supposed to be pd.DataFrames as dict values. In the DataFrame form all recommendations must be specified in one DataFrame with Columns.Model column to separate different models. Other required columns for both forms are:

    • Columns.User - user id

    • Columns.Item - recommended item id

    • Any other columns that you wish to display in widgets (e.g. rank or score)

    The original order of the rows will be preserved. Keep in mind to sort the rows correctly before visualizing. The most intuitive way is to sort by rank in ascending order.

  • interactions (pd.DataFrame) –

    Table with interactions history for users. Only needed for u2i case. Supposed to be in form of pandas DataFrames with columns:

    • Columns.User - user id

    • Columns.Item - item id

    The original order of the rows will be preserved. Keep in mind to sort the rows correctly before visualizing. The most intuitive way is to sort by date in descending order. If user has too many interactions the lest ones may not be displayed.

  • item_data (pd.DataFrame) –

    Data for items that is used for visualisation in both interactions and recommendations widgets. Supposed to be in form of a pandas DataFrame with columns:

    • Columns.Item - item id

    • Any other columns with item data (e.g. name, category, popularity, image link)

  • selected_users (tp.Optional[tp.Dict[tp.Hashable, ExternalId]], default None) – Predefined users that will be displayed in widgets. User names must be specified as keys of the dict and user ids as values of the dict. Must be provided if n_random_users = 0.

  • n_random_users (int, default 0) – Number of random users to add for visualization from users in recommendation tables. Must be greater then 0 if selected_users are not specified.

  • auto_display (bool, optional, default True) – Display widgets right after initialization.

  • formatters (tp.Optional[tp.Dict[str, tp.Callable]], optional, default None) – Formatter functions to apply to columns elements in the sections of interactions and recommendations. Keys of the dict must be columns names (item_data, interactions and recommendations columns can be specified here). Values bust be functions that will be applied to corresponding columns elements. The result of each function must be a unicode string that represents html code. Formatters can be used to format text, create links and display images with html.

  • rows_limit (int, optional, default 20) – Maximum number of rows to display in the sections of interactions and recommendations.

  • min_width (int, optional, default 100) – Minimum column width in pixels for dataframe columns in widgets output. Must be greater then 10.

Return type

VisualApp

Examples

Providing reco as TablesDict

>>> reco = {
...     "model_1": pd.DataFrame({Columns.User: [1, 2], Columns.Item: [3, 4], Columns.Score: [0.99, 0.9]}),
...     "model_2": pd.DataFrame({Columns.User: [1, 2], Columns.Item: [5, 6], Columns.Rank: [1, 1]})
... }
>>>
>>> item_data = pd.DataFrame({
...     Columns.Item: [3, 4, 5, 6, 7, 8],
...     "feature_1": ["one", "two", "three", "five", "one", "two"]
... })
>>>
>>> interactions = pd.DataFrame({Columns.User: [1, 1, 2], Columns.Item: [3, 7, 8]})
>>> selected_users = {"user_one": 1}
>>>
>>> app = VisualApp.construct(
...     reco=reco,
...     item_data=item_data,
...     interactions=interactions,
...     selected_users=selected_users,
...     auto_display=False
... )

Providing reco as pd.DataFrame and adding formatters

>>> reco = pd.DataFrame({
...     Columns.User: [1, 2, 1, 2],
...     Columns.Item: [3, 4, 5, 6],
...     Columns.Model: ["model_1", "model_1", "model_2", "model_2"]
... })
>>>
>>> item_data = pd.DataFrame({
...     Columns.Item: [3, 4, 5, 6, 7, 8],
...     "feature_1": ["one", "two", "three", "five", "one", "two"]
... })
>>>
>>> interactions = pd.DataFrame({Columns.User: [1, 1, 2], Columns.Item: [3, 7, 8]})
>>> selected_users = {"user_one": 1}
>>>
>>> formatters = {"item_id": lambda x: f"<b>{x}</b>"}
>>>
>>> app = VisualApp.construct(
...     reco=reco,
...     item_data=item_data,
...     interactions=interactions,
...     selected_users=selected_users,
...     formatters=formatters,
...     auto_display=False
... )