Components

Basic Concepts

Columns

Names of columns are fixed. They are user_id, item_id, weight (numerical value of interaction’s importance), datetime (date and time of interaction), rank (rank of recommendation according to score) and score (numeric value estimating how good recommendation it is). Column names are fixed in order to not constantly require mapping of columns in data and their actual meaning. So you’ll need to rename your columns.

rectools.columns.Columns()

Fixed column names for tables that contain interactions and recommendations.

Identifiers

Mappings of external identifiers of users or items to internal ones. Recommendation systems always require to have a mapping between external item ids in data sources and internal ids in interaction matrix. Managing such mapping requires a lot of diligence. RecTools does it for you. Every user and item must have a unique id. External ids may be any unique hashable values, internal - always integers from 0 to n_objects-1.

Interactions

This table stores history of interactions between users and items. It carries the most importance. Interactions table might also contain column describing importance of an interaction. Also timestamp of interaction. If no such column is provided, all interactions are assumed to be of equal importance.

User Features

This table stores data about users. It might include age, gender or any other features which may prove to be important for a recommender model.

Item Features

This table stores data about items. It might include category, price or any other features which may prove to be important for a recommender model.

Hot, warm, cold

There is a concept of a temperature we’re using for users and items:

hot - the ones that are present in interactions used for training (they may or may not have features);
warm - the ones that are not in interactions, but have some features;
cold - the ones we don’t know anything about (they are not in interactions and don’t have any features).

All the models are able to generate recommendations for the hot users (items). But as for warm and cold ones, there may be all possible combinations (neither of them, only cold, only warm, both). The important thing is that if model is able to recommend for cold users (items), but not for warm ones (see table below), it is still able to recommend for warm ones, but they will be considered as cold (no personalisation should be expected).

All of the above concepts are combined in Dataset. Dataset is used to build recommendation models and infer recommendations.

Dataset

Details of RecTools Dataset

See the API documentation for further details on Dataset:

`rectools.dataset.dataset.Dataset`(...[, ...])	Container class for all data for a recommendation model.
`rectools.dataset.features.DenseFeatures`(...)	Storage for dense features.
`rectools.dataset.identifiers.IdMap`(external_ids)	Mapping between external and internal object ids.
`rectools.dataset.interactions.Interactions`(df)	Structure to store info about user-item interactions.
`rectools.dataset.features.SparseFeatures`(...)	Storage for sparse features.

Models

Details of RecTools Models

Model	Supports features	Recommends for warm	Recommends for cold
DSSMModel	Yes	Yes	No
EASEModel	No	No	No
ImplicitALSWrapperModel	Yes	No	No
ImplicitItemKNNWrapperModel	No	No	No
LightFMWrapperModel	Yes	Yes	Yes
PopularModel	No	No	Yes
PopularInCategoryModel	No	No	Yes
PureSVDModel	No	No	No
RandomModel	No	No	Yes

See the API documentation for further details on Models:

`rectools.models.dssm.DSSMModel`(...)	Wrapper for rectools.models.dssm.DSSM
`rectools.models.ease.EASEModel`([...])	Embarrassingly Shallow Autoencoders for Sparse Data model.
`rectools.models.implicit_als.ImplicitALSWrapperModel`(model)	Wrapper for implicit.als.AlternatingLeastSquares with possibility to use explicit features and GPU support.
`rectools.models.implicit_knn.ImplicitItemKNNWrapperModel`(model)	Wrapper for implicit.nearest_neighbours.ItemItemRecommender and its successors.
`rectools.models.lightfm.LightFMWrapperModel`(model)	Wrapper for lightfm.LightFM.
`rectools.models.popular_in_category.PopularInCategoryModel`(...)	Model generating recommendations based on popularity of items.
`rectools.models.popular.PopularModel`([...])	Model generating recommendations based on popularity of items.
`rectools.models.pure_svd.PureSVDModel`([...])	PureSVD matrix factorization model.
`rectools.models.random.RandomModel`([...])	Model generating random recommendations.

What are you waiting for? Train and apply them!

Recommendation Table

Recommendation table contains recommendations for each user. It has a fixed set of columns, though they are different for i2i and u2i recommendations. Recommendation table can also be used for calculation of metrics.

Metrics

Details of RecTools Metrics

See the API documentation for further details on Dataset:

`rectools.metrics.classification.Accuracy`(k)	Ratio of correctly recommended items among all items.
`rectools.metrics.popularity.AvgRecPopularity`(k)	Average Recommendations Popularity metric.
`rectools.metrics.classification.F1Beta`(k[, beta])	Fbeta score for k first recommendations.
`rectools.metrics.classification.HitRate`(k)	HitRate calculates the fraction of users for which the correct answer is included in the recommendation list.
`rectools.metrics.diversity.IntraListDiversity`(k, ...)	Intra-List Diversity metric.
`rectools.metrics.ranking.MAP`(k[, divide_by_k])	Mean Average Precision at k (MAP@k).
`rectools.metrics.classification.MCC`(k)	Matthew correlation coefficient calculates correlation between actual and predicted classification.
`rectools.metrics.ranking.MRR`(k)	Mean Reciprocal Rank at k (MRR@k).
`rectools.metrics.novelty.MeanInvUserFreq`(k)	Mean Inverse User Frequency metric.
`rectools.metrics.ranking.NDCG`(k[, log_base])	Normalized Discounted Cumulative Gain at k (NDCG@k).
`rectools.metrics.distances.PairwiseDistanceCalculator`()	Base pairwise distance calculator class
`rectools.metrics.distances.PairwiseHammingDistanceCalculator`(...)	Class for computing Hamming distance between a pair of items.
`rectools.metrics.classification.Precision`(k)	Ratio of relevant items among top-k recommended items.
`rectools.metrics.classification.Recall`(k)	Ratio of relevant recommended items among all items user interacted with after recommendations were made.
`rectools.metrics.serendipity.Serendipity`(k)	Serendipity metric.
`rectools.metrics.distances.SparsePairwiseHammingDistanceCalculator`(...)	Class for computing Hamming distance between multiple pairs of elements represented in features matrix in sparse form.
`rectools.metrics.scoring.calc_metrics`(...[, ...])	Calculate metrics.

Oops, yeah, can’t forget about them.

Model selection

Details of RecTools Model selection

See the API documentation for further details on Model selection:

`rectools.model_selection.last_n_split.LastNSplitter`(n)	Splitter for cross-validation by leave-one-out / leave-k-out scheme (recent activity).
`rectools.model_selection.random_split.RandomSplitter`(...)	Slitter for cross-validation by random.
`rectools.model_selection.splitter.Splitter`([...])	Base class to construct data splitters.
`rectools.model_selection.time_split.TimeRangeSplitter`(...)	Splitter for cross-validation by leave-time-out scheme.
`rectools.model_selection.cross_validate.cross_validate`(...)	Run cross validation on multiple models with multiple metrics.

Tools

Details of RecTools Tools

See the API documentation for further details on Tools:

`rectools.tools.ann.ItemToItemAnnRecommender`(...)	Class implements item-to-item ANN recommender.
`rectools.tools.ann.UserToItemAnnRecommender`(...)	Class implements user to item ANN recommender.

Visuals

Details of RecTools Visuals

See the API documentation for further details on Visuals:

`rectools.visuals.visual_app.ItemToItemVisualApp`(...)	Jupyter widgets app for item-to-item recommendations visualization and models comparison.
`rectools.visuals.visual_app.VisualApp`(...[, ...])	Jupyter widgets app for user-to-item recommendations visualization and models comparison.