Get Started

Follow the guide below to start making explainable recommendations with Recsplain.

Start with:

Then start searching by:

Note

Learn more about the methods in the Reference πŸ¦–.

Installation

Import the package using the following import statement.

import recsplain as rx

Note

Learn more about the method in the Installation reference.

Configuration

First, you need to do is to configure the user recommendation strategy by using:

rec_strategy = rx.AvgUserStrategy()

Note

More strategies to come.

Use the init_schema method to configure the system so that it knows how to partition and compare feature vectors.

Here is an example of how to call the init_schema method.

import recsplain as rx

config_data = {
  "filters": [{ "field": "country", "values": ["US", "EU"] }],
  "encoders": [
    {
      "field": "price",
      "values": ["low", "mid", "high"],
      "type": "onehot",
      "weight": 1
    },
    {
      "field": "category",
      "values": ["dairy", "meat"],
      "type": "onehot",
      "weight": 2
    }
  ],
  "metric": "l2"
}

rec_strategy = rx.AvgUserStrategy()
rec_strategy.init_schema(**config_data)

Weights are used to set the relative importance the system should attribute to this feature in the similarity check.

This is the response from init_schema. The first element is an array of the filters created and the second element is a dictionary of the features and their corresponding vector size.

[('US',), ('EU',)], {'price': 4, 'category': 3}

Note

Encoder type one-hot save one spot for unknown feature_sizes so the size is N + 1.

Note

Learn more about the method in the configuration reference.

Index

Use the index method to add items to the Recsplain system so that it has items to partition and compare.

Here is an example of how to call the index method.

import recsplain as rx

config_data = {
  "filters": [{ "field": "country", "values": ["US", "EU"] }],
  "encoders": [
    {
      "field": "price",
      "values": ["low", "mid", "high"],
      "type": "onehot",
      "weight": 1
    },
    {
      "field": "category",
      "values": ["dairy", "meat"],
      "type": "onehot",
      "weight": 2
    }
  ],
  "metric": "l2"
}

index_data = [
  {
    "id": "1",
    "price": "low",
    "category": "meat",
    "country": "US"
  },
  {
    "id": "2",
    "price": "mid",
    "category": "meat",
    "country": "US"
  },
  {
    "id": "3",
    "price": "low",
    "category": "dairy",
    "country": "US"
  },
  {
    "id": "4",
    "price": "high",
    "category": "meat",
    "country": "EU"
  }
]

rec_strategy = rx.AvgUserStrategy()
rec_strategy.init_schema(config_data)
rec_strategy.index(index_data)

This is the response from index. The first element is a list of errors and the second elemnt is the number of partitions affected by the indexing.

[], 2

Note

If you do not index items, when you search there will be nothing to check the search against for similarity.

Note

When reusing the index method, using the same id twice creates duplicate entries in the index. In the example below the index method is called twice with the same entry. In the index table both entries are created.

_images/reusing_index.png

Note

Learn more about the method in the index reference.

Item Similarity

Use the query method to search by item.

The method returns explainable recommendations for indexed items that are similar to the search item.

Here is an example of how to call the query method.

import recsplain as rx

item_query_data = {
  "k": 2,
  "data": {
    "price": "low",
    "category": "meat",
    "country": "US"
  },
  "explain": 1
}

rec_strategy.query(**item_query_data)

This is the response from query. The first element is the ids of the recommended items, the second element is the distances of each of the recommended items and the third element is the explanation of how much each feature contributed to the overall distance.

('1', '2') (0.0, 2.0) [{'price': 0.0, 'category': 0.0}, {'price': 2.0, 'category': 0.0}]

Note

Learn more about the method in the item similarity reference.

User Preference

Use the user_query method to search by user.

The method returns explainable recommendations for indexed items that the user likely prefers.

Here is an example of how to call the user_query method.

import recsplain as rx

user_query_data = {
  "k": 2,
  "item_history": ["1", "3", "3"],
  "user_data": {
    "country": "US"
  }
}

rec_strategy.user_query(**user_query_data)

This is the response from user_query. The first element is the ids of the recommended items and the second element is the distance of each of these items from the user’s representation (as given by the items history).

['3', '1'] [2.0, 2.0]

Note

Learn more about the method in the user preference reference.