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.
This is just to use the internal of the tabular application, don't worry about it.
This class should not be used directly, one of the factory methods should be preferred instead. All those factory methods accept as arguments:
valid_pct: the random percentage of the dataset to set aside for validation (with an optionalseed)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 workbs: the batch sizeval_bs: the batch size for the validationDataLoader(defaults tobs)shuffle_train: if we shuffle the trainingDataLoaderor notdevice: the PyTorch device to use (defaults todefault_device())
Let's see how this works on an example:
path = untar_data(URLs.ML_SAMPLE)
ratings = pd.read_csv(path/'ratings.csv')
ratings.head()
dls = CollabDataLoaders.from_df(ratings, bs=64)
dls.show_batch()
dls = CollabDataLoaders.from_csv(path/'ratings.csv', bs=64)
fastai provides two kinds of models for collaborative filtering: a dot-product model and a neural net.
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.
x,y = dls.one_batch()
model = EmbeddingDotBias(50, len(dls.classes['userId']), len(dls.classes['movieId']), y_range=(0,5)
).to(x.device)
out = model(x)
assert (0 <= out).all() and (out <= 5).all()
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
Let's see how it can be used in practice:
model = EmbeddingDotBias.from_classes(50, dls.classes, y_range=(0,5)
).to(x.device)
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:
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])))
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])))
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)
).to(x.device)
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.
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 inferred 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)