Tools to quickly get the data and train models suitable for collaborative filtering

This module contains all the high-level functions you need in a collaborative filtering application to assemble your data, get a model and train it with a Learner. We will go other those in order but you can also check the collaborative filtering tutorial.

Gather the data

class TabularCollab[source]

TabularCollab(df, procs=None, cat_names=None, cont_names=None, y_names=None, y_block=None, splits=None, do_setup=True, device=None, inplace=False, reduce_memory=True) :: TabularPandas

Instance of TabularPandas suitable for collaborative filtering (with no continuous variable)

This is just to use the internal of the tabular application, don't worry about it.

class CollabDataLoaders[source]

CollabDataLoaders(*loaders, path='.', device=None) :: DataLoaders

Base DataLoaders for collaborative filtering.

This class should not be used directly, one of the factory methods should be prefered instead. All those factory methods accept as arguments:

  • valid_pct: the random percentage of the dataset to set aside for validation (with an optional seed)
  • user_name: the name of the column containing the user (defaults to the first column)
  • item_name: the name of the column containing the item (defaults to the second column)
  • rating_name: the name of the column containing the rating (defaults to the third column)
  • path: the folder where to work
  • bs: the batch size
  • val_bs: the batch size for the validation DataLoader (defaults to bs)
  • shuffle_train: if we shuffle the training DataLoader or not
  • device: the PyTorch device to use (defaults to default_device())

CollabDataLoaders.from_df[source]

CollabDataLoaders.from_df(ratings, valid_pct=0.2, user_name=None, item_name=None, rating_name=None, seed=None, path='.', bs=64, val_bs=None, shuffle_train=True, device=None)

Create a DataLoaders suitable for collaborative filtering from ratings.

Let's see how this works on an example:

path = untar_data(URLs.ML_SAMPLE)
ratings = pd.read_csv(path/'ratings.csv')
ratings.head()
userId movieId rating timestamp
0 73 1097 4.0 1255504951
1 561 924 3.5 1172695223
2 157 260 3.5 1291598691
3 358 1210 5.0 957481884
4 130 316 2.0 1138999234
dls = CollabDataLoaders.from_df(ratings, bs=64)
dls.show_batch()
userId movieId rating
0 15 480 3.0
1 111 380 4.5
2 382 6377 4.5
3 150 110 4.5
4 30 733 4.0
5 407 1617 5.0
6 220 1265 4.0
7 481 4306 3.5
8 128 367 3.0
9 577 1213 4.5

CollabDataLoaders.from_csv[source]

CollabDataLoaders.from_csv(csv, valid_pct=0.2, user_name=None, item_name=None, rating_name=None, seed=None, path='.', bs=64, val_bs=None, shuffle_train=True, device=None)

Create a DataLoaders suitable for collaborative filtering from csv.

dls = CollabDataLoaders.from_csv(path/'ratings.csv', bs=64)

Models

fastai provides two kinds of models for collaborative filtering: a dot-product model and a neural net.

class EmbeddingDotBias[source]

EmbeddingDotBias(n_factors, n_users, n_items, y_range=None) :: Module

Base dot model for collaborative filtering.

The model is built with n_factors (the length of the internal vectors), n_users and n_items. For a given user and item, it grabs the corresponding weights and bias and returns

torch.dot(user_w, item_w) + user_b + item_b

Optionally, if y_range is passed, it applies a SigmoidRange to that result.

model = EmbeddingDotBias(50, len(dls.classes['userId']), len(dls.classes['movieId']), y_range=(0,5)).cuda()
x,y = dls.one_batch()
out = model(x)
assert (0 <= out).all() and (out <= 5).all()

EmbeddingDotBias.from_classes[source]

EmbeddingDotBias.from_classes(n_factors, classes, user=None, item=None, y_range=None)

Build a model with n_factors by inferring n_users and n_items from classes

y_range is passed to the main init. user and item are the names of the keys for users and items in classes (default to the first and second key respectively). classes is expected to be a dictionary key to list of categories like the result of dls.classes in a CollabDataLoaders:

dls.classes
{'userId': (#101) ['#na#',15,17,19,23,30,48,56,73,77...],
 'movieId': (#101) ['#na#',1,10,32,34,39,47,50,110,150...]}

Let's see how it can be used in practice:

model = EmbeddingDotBias.from_classes(50, dls.classes,  y_range=(0,5)).cuda()
out = model(x)
assert (0 <= out).all() and (out <= 5).all()

Two convenience methods are added to easily access the weights and bias when a model is created with EmbeddingDotBias.from_classes:

EmbeddingDotBias.weight[source]

EmbeddingDotBias.weight(arr, is_item=True)

Weight for item or user (based on is_item) for all in arr

The elements of arr are expected to be class names (which is why the model needs to be created with EmbeddingDotBias.from_classes)

mov = dls.classes['movieId'][42] 
w = model.weight([mov])
test_eq(w, model.i_weight(tensor([42])))

EmbeddingDotBias.bias[source]

EmbeddingDotBias.bias(arr, is_item=True)

Bias for item or user (based on is_item) for all in arr

The elements of arr are expected to be class names (which is why the model needs to be created with EmbeddingDotBias.from_classes)

mov = dls.classes['movieId'][42] 
b = model.bias([mov])
test_eq(b, model.i_bias(tensor([42])))

class EmbeddingNN[source]

EmbeddingNN(emb_szs, layers, ps=None, embed_p=0.0, y_range=None, use_bn=True, bn_final=False, bn_cont=True) :: TabularModel

Subclass TabularModel to create a NN suitable for collaborative filtering.

emb_szs should be a list of two tuples, one for the users, one for the items, each tuple containing the number of users/items and the corresponding embedding size (the function get_emb_sz can give a good default). All the other arguments are passed to TabularModel.

emb_szs = get_emb_sz(dls.train_ds, {})
model = EmbeddingNN(emb_szs, [50], y_range=(0,5)).cuda()
out = model(x)
assert (0 <= out).all() and (out <= 5).all()

Create a Learner

The following function lets us quickly create a Learner for collaborative filtering from the data.

collab_learner[source]

collab_learner(dls, n_factors=50, use_nn=False, emb_szs=None, layers=None, config=None, y_range=None, loss_func=None, opt_func='Adam', lr=0.001, splitter='trainable_params', cbs=None, metrics=None, path=None, model_dir='models', wd=None, wd_bn_bias=False, train_bn=True, moms=(0.95, 0.85, 0.95))

Create a Learner for collaborative filtering on dls.

If use_nn=False, the model used is an EmbeddingDotBias with n_factors and y_range. Otherwise, it's a EmbeddingNN for which you can pass emb_szs (will be infered from the dls with get_emb_sz if you don't provide any), layers (defaults to [n_factors]) y_range, and a config that you can create with tabular_config to customize your model.

loss_func will default to MSELossFlat and all the other arguments are passed to Learner.

learn = collab_learner(dls, y_range=(0,5))
learn.fit_one_cycle(1)
epoch train_loss valid_loss time
0 2.526475 2.530848 00:00