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.
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.