Deep recommender models using PyTorch.

Overview

docs/_static/img/spotlight.png


https://travis-ci.org/maciejkula/spotlight.svg?branch=master https://ci.appveyor.com/api/projects/status/jq5e76a7a08ra2ji/branch/master?svg=true https://badges.gitter.im/gitterHQ/gitter.png https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat

Spotlight uses PyTorch to build both deep and shallow recommender models. By providing both a slew of building blocks for loss functions (various pointwise and pairwise ranking losses), representations (shallow factorization representations, deep sequence models), and utilities for fetching (or generating) recommendation datasets, it aims to be a tool for rapid exploration and prototyping of new recommender models.

See the full documentation for details.

Installation

conda install -c maciejkula -c pytorch spotlight

Usage

Factorization models

To fit an explicit feedback model on the MovieLens dataset:

from spotlight.cross_validation import random_train_test_split
from spotlight.datasets.movielens import get_movielens_dataset
from spotlight.evaluation import rmse_score
from spotlight.factorization.explicit import ExplicitFactorizationModel

dataset = get_movielens_dataset(variant='100K')

train, test = random_train_test_split(dataset)

model = ExplicitFactorizationModel(n_iter=1)
model.fit(train)

rmse = rmse_score(model, test)

To fit an implicit ranking model with a BPR pairwise loss on the MovieLens dataset:

from spotlight.cross_validation import random_train_test_split
from spotlight.datasets.movielens import get_movielens_dataset
from spotlight.evaluation import mrr_score
from spotlight.factorization.implicit import ImplicitFactorizationModel

dataset = get_movielens_dataset(variant='100K')

train, test = random_train_test_split(dataset)

model = ImplicitFactorizationModel(n_iter=3,
                                   loss='bpr')
model.fit(train)

mrr = mrr_score(model, test)

Sequential models

Recommendations can be seen as a sequence prediction task: given the items a user has interacted with in the past, what will be the next item they will interact with? Spotlight provides a range of models and utilities for fitting next item recommendation models, including

from spotlight.cross_validation import user_based_train_test_split
from spotlight.datasets.synthetic import generate_sequential
from spotlight.evaluation import sequence_mrr_score
from spotlight.sequence.implicit import ImplicitSequenceModel

dataset = generate_sequential(num_users=100,
                              num_items=1000,
                              num_interactions=10000,
                              concentration_parameter=0.01,
                              order=3)

train, test = user_based_train_test_split(dataset)

train = train.to_sequence()
test = test.to_sequence()

model = ImplicitSequenceModel(n_iter=3,
                              representation='cnn',
                              loss='bpr')
model.fit(train)

mrr = sequence_mrr_score(model, test)

Datasets

Spotlight offers a slew of popular datasets, including Movielens 100K, 1M, 10M, and 20M. It also incorporates utilities for creating synthetic datasets. For example, generate_sequential generates a Markov-chain-derived interaction dataset, where the next item a user chooses is a function of their previous interactions:

from spotlight.datasets.synthetic import generate_sequential

# Concentration parameter governs how predictable the chain is;
# order determins the order of the Markov chain.
dataset = generate_sequential(num_users=100,
                              num_items=1000,
                              num_interactions=10000,
                              concentration_parameter=0.01,
                              order=3)

Examples

  1. Rating prediction on the Movielens dataset.
  2. Using causal convolutions for sequence recommendations.
  3. Bloom embedding layers.

How to cite

Please cite Spotlight if it helps your research. You can use the following BibTeX entry:

@misc{kula2017spotlight,
  title={Spotlight},
  author={Kula, Maciej},
  year={2017},
  publisher={GitHub},
  howpublished={\url{https://github.com/maciejkula/spotlight}},
}

Contributing

Spotlight is meant to be extensible: pull requests are welcome. Development progress is tracked on Trello: have a look at the outstanding tickets to get an idea of what would be a useful contribution.

We accept implementations of new recommendation models into the Spotlight model zoo: if you've just published a paper describing your new model, or have an implementation of a model from the literature, make a PR!

Comments
  • I ran this command but met problems

    I ran this command but met problems

    I ran this command:conda install -c maciejkula -c pytorch -c peterjc123 spotlight=0.1.4 but showed the error
    conda install -c maciejkula -c pytorch -c peterjc123 spotlight=0.1.3 Fetching package metadata ........... Solving package specifications:

    PackageNotFoundError: Packages missing in current channels:

    • spotlight 0.1.3* -> pytorch 0.3.0 -> mkl >=2018
    opened by swan815 12
  • [WIP] FIX Unit tests on Windows

    [WIP] FIX Unit tests on Windows

    This PR aims to fix https://github.com/maciejkula/spotlight/issues/82

    It includes,

    • an Appveyor CI setup
    • a fix of the randint overflow issue
    • an attempt to fix dtype mismatch between IntTensor and LongTensor by casting them in forward as suggested here https://github.com/pytorch/pytorch/issues/145#issuecomment-255355000 . I must be missing something though as I still don't understand why this not an issue on Linux but only on Windows..

    The latest Appveyor output can be seen here some of the failures will go away once https://github.com/maciejkula/spotlight/pull/83 is merged..

    opened by rth 10
  • Segmentation Fault with Pandas

    Segmentation Fault with Pandas

    I ran into a very odd segmentation fault error. This could very well be a PyTorch bug, but I thought I'd bring it up here, first. I've produced a minimal example at the bottom of this issue.

    So far, I know that the fault happens at the loss.backward() call in model.fit(). The fault only seems to happen under the combination of two conditions (that I can find, so far):

    1. When sparse=True.
    2. Pandas is imported at the top of the file

    (BTW, I pass in an SGD optimizer because that seems to be the only one that works right now with sparse embeddings)

    I'm using pandas version 0.20.3 from conda, the latest spotlight from master, and PyTorch 0.2.0 from conda. I'd love to know if others can reproduce this.

    As I said, this could very well be a PyTorch bug, but, if others run into this, it'll be helpful to have this issue as a reference.

    import pandas as pd
    import numpy as np
    import torch
    
    from spotlight.interactions import Interactions
    from spotlight.factorization.implicit import ImplicitFactorizationModel
    
    user_ids = [2471, 5808, 3281, 4086, 6293, 8970, 11828, 3281]
    item_ids = [1583, 57, 6963, 867, 8099, 10991, 24, 800]
    num_users = 15274
    num_items = 25655
    
    train = Interactions(np.array(user_ids, dtype=np.int64),
                         np.array(item_ids, dtype=np.int64),
                         num_users=num_users,
                         num_items=num_items)
    
    def optimizer_func(params, lr=0.01):
        return torch.optim.SGD(params, lr=lr)
      
    RANDOM_STATE = np.random.RandomState(42)
    model = ImplicitFactorizationModel(loss='bpr',
                                       embedding_dim=32,
                                       batch_size=4,
                                       n_iter=1,
                                       use_cuda=False,
                                       optimizer_func=optimizer_func,
                                       sparse=True,
                                       random_state=RANDOM_STATE)
    # Fault
    model.fit(train, verbose=True)
    
    opened by EthanRosenthal 6
  • Cannot install spotlight via pip

    Cannot install spotlight via pip

    Hi,

    I am using an environment where conda install is not possible. I have tried installing via pip but it doesn't work. Has anyone tried this? Would appreciate any tips.

    opened by mexangel 5
  • Roadmap: Hybrid Recommender?

    Roadmap: Hybrid Recommender?

    Hi, I was looking at LightFM and saw item and user metadata being used for recommendations. This is really cool. Just wondering if such functionality is in the roadmap for spotlight?

    opened by RAbraham 5
  • Formulation and usage questions

    Formulation and usage questions

    I have a few questions about using Spotlight for an item-item problem involving graded implicit feedback, pardon me if there is a better forum for such questions, I wasn't able to find one.

    I work on a system with feedback in the form of clicks (aka page view), likes and purchases. In this case obviously a purchase is substantially more desirable than a simple click.

    Is there an obvious way to achieve this with Spotlight? Should I treat it as pure implicit and use the weights parameter to assign a greater weight to purchases than clicks? Or is it more appropriate to treat it as a ratings prediction problem where the "ratings" are really pseudo-ratings assigned by me?

    Also, does Spotlight have any support for cold-start? Or support for predicting for a new user in production based on that user's (previously unseen) history of implicit feedback? Or would lightfm maybe be a better fit for all of this?

    Finally, if deployed in production can Spotlight models predict at reasonably low latency? Perhaps <100ms?

    thanks very much for Spotlight. It's well-documented and the code is a joy to read.

    opened by travisbrady 5
  • Install Error

    Install Error

    Using python 3.6 in conda environment. Getting the following error

    conda install -c maciejkula -c soumith spotlight=0.1.2 Fetching package metadata .............

    PackageNotFoundError: Package missing in current osx-64 channels:

    • spotlight 0.1.2*
    opened by navacron 5
  • Negative sampling

    Negative sampling

    @maciejkula I guess we should remove the items found the training dataset before the negative sampling. Otherwise, it might make the learning less effective?

    opened by nonamestreet 5
  • ModuleNotFoundError

    ModuleNotFoundError

    When i try to import some modules:

    from spotlight.datasets.movielens import get_movielens_dataset Traceback (most recent call last): File "", line 1, in ModuleNotFoundError: No module named 'spotlight.datasets'

    from spotlight.factorization.explicit import ExplicitFactorizationModel Traceback (most recent call last): File "", line 1, in ModuleNotFoundError: No module named 'spotlight.factorization'

    opened by blancyin 5
  • Install Spotlight on win 64 using conda

    Install Spotlight on win 64 using conda

    I have created a py 3.6 env.

    Please let me know how to install it .

    conda install -c maciejkula -c pytorch spotlight=0.1.4 is not working

    conda install -c maciejkula -c pytorch -c peterjc123 spotlight=0.1.4 even this fails

    opened by vikrant-sahu 4
  • Conda Install Issue (Windows 10)

    Conda Install Issue (Windows 10)

    Hi! Thank you for Spotlight.

    I have a similar problem to the issue #80

    My OS is Windows 10 x64.

    First, i must admit i am new with Anaconda. I have a 'portable' installation Anaconda (with Anaconda3-5.1.0-Windows-x86_64.exe).

    When i try:

    conda install -c maciejkula -c pytorch spotlight=0.1.4

    i get;

    u:\Python\Anaconda3>conda install -c maciejkula -c pytorch spotlight=0.1.4
    Solving environment: failed
    
    PackagesNotFoundError: The following packages are not available from current channels:
    
      - spotlight=0.1.4
      - pytorch=0.3.1
    
    Current channels:
    
      - https://conda.anaconda.org/maciejkula/win-64
      - https://conda.anaconda.org/maciejkula/noarch
      - https://conda.anaconda.org/pytorch/win-64
      - https://conda.anaconda.org/pytorch/noarch
      - https://repo.continuum.io/pkgs/main/win-64
      - https://repo.continuum.io/pkgs/main/noarch
      - https://repo.continuum.io/pkgs/free/win-64
      - https://repo.continuum.io/pkgs/free/noarch
      - https://repo.continuum.io/pkgs/r/win-64
      - https://repo.continuum.io/pkgs/r/noarch
      - https://repo.continuum.io/pkgs/pro/win-64
      - https://repo.continuum.io/pkgs/pro/noarch
      - https://repo.continuum.io/pkgs/msys2/win-64
      - https://repo.continuum.io/pkgs/msys2/noarch
    
    u:\Python\Anaconda3>
    

    I have not created an environment... Is it necessary?

    Perhaps, is it necessary to add channels or so?

    opened by DJuego 4
  • docs: fix simple typo, imcompatible -> incompatible

    docs: fix simple typo, imcompatible -> incompatible

    There is a small typo in tests/factorization/test_explicit.py.

    Should read incompatible rather than imcompatible.

    Semi-automated pull request generated by https://github.com/timgates42/meticulous/blob/master/docs/NOTE.md

    opened by timgates42 0
  • ModuleNotFoundError: No module named

    ModuleNotFoundError: No module named "spotlight.interactions"

    I need to migrate a code that is using spotlight to Azure Machine Learning.

    When calling the module I am constantly getting these type of errors.

    My python version is 3.6.9 in Azure Machine Learning and I tried to call the module on my local pc as well, but I am getting the same error.

    Any news on how to fix this?

    opened by NomiDomi 1
  • How can I train a model when adding a new user or item?

    How can I train a model when adding a new user or item?

    After training the model, I add a new user or item to the Interactions dataset and then try to train the model, but I get the following error:ValueError: Maximum user id greater than number of users in model. Is there any way to add users and item to the dataset and train the model online after that?

    opened by artyomche9 0
  • Error in BPR loss function

    Error in BPR loss function

    Hello! Thank you for your great work! In your realisation of bpr loss you use the following formula:

    loss = (1.0 - torch.sigmoid(positive_predictions - negative_predictions)).

    In the original publication (bpr paper) the authors propose loss = log(sigmoid(positive - negative)) + regularisation. Is it okay?

    opened by PeterZaidel 0
  • why don't we need to take logarithm in pointwise_loss?

    why don't we need to take logarithm in pointwise_loss?

    My question is I'm thinking is there any reason we can simplify cross entropy loss into the below way instead of what [1] used in cross-entropy.

    def pointwise_loss(positive_predictions, negative_predictions, mask=None):
        """
        Logistic loss function.
        Parameters
        ----------
        positive_predictions: tensor
            Tensor containing predictions for known positive items.
        negative_predictions: tensor
            Tensor containing predictions for sampled negative items.
        mask: tensor, optional
            A binary tensor used to zero the loss from some entries
            of the loss tensor.
        Returns
        -------
        loss, float
            The mean value of the loss function.
        """
    
        positives_loss = (1.0 - torch.sigmoid(positive_predictions))
        negatives_loss = torch.sigmoid(negative_predictions)
    
        loss = (positives_loss + negatives_loss)
    
        if mask is not None:
            mask = mask.float()
            loss = loss * mask
            return loss.sum() / mask.sum()
    
        return loss.mean()
    
    

    [1].https://ml-cheatsheet.readthedocs.io/en/latest/logistic_regression.html

    opened by liyunrui 0
Releases(v0.1.6)
  • v0.1.6(Sep 8, 2019)

  • v0.1.3(Dec 14, 2017)

  • v0.1.2(Sep 19, 2017)

    Added

    • spotlight.layers.BloomEmbedding: bloom embedding layers that reduce the number of parameters required by hashing embedding indices into some fixed smaller dimensionality, following Serrà, Joan, and Alexandros Karatzoglou. "Getting deep recommenders fit: Bloom embeddings for sparse binary input/output networks."
    • sequence_mrr_score now accepts an option that excludes previously seen items from scoring.

    Changed

    • optimizer arguments is now optimizer_func. It accepts a function that takes a single argument (list of model parameters) and return a PyTorch optimizer (thanks to Ethan Rosenthal).
    • fit calls will resume from previous model state when called repeatedly (Ethan Rosenthal).
    • Updated to work with PyTorch v0.2.0.

    Fixed

    • Factorization predict APIs now work as advertised in the documentation.
    Source code(tar.gz)
    Source code(zip)
Owner
Maciej Kula
Maciej Kula
Recommender System Papers

Included Conferences: SIGIR 2020, SIGKDD 2020, RecSys 2020, CIKM 2020, AAAI 2021, WSDM 2021, WWW 2021

RUCAIBox 704 Jan 6, 2023
Graph Neural Networks for Recommender Systems

This repository contains code to train and test GNN models for recommendation, mainly using the Deep Graph Library (DGL).

null 217 Jan 4, 2023
RecSim NG: Toward Principled Uncertainty Modeling for Recommender Ecosystems

RecSim NG, a probabilistic platform for multi-agent recommender systems simulation. RecSimNG is a scalable, modular, differentiable simulator implemented in Edward2 and TensorFlow. It offers: a powerful, general probabilistic programming language for agent-behavior specification;

Google Research 110 Dec 16, 2022
NVIDIA Merlin is an open source library designed to accelerate recommender systems on NVIDIA’s GPUs.

NVIDIA Merlin is an open source library providing end-to-end GPU-accelerated recommender systems, from feature engineering and preprocessing to training deep learning models and running inference in production.

null 420 Jan 4, 2023
Collaborative variational bandwidth auto-encoder (VBAE) for recommender systems.

Collaborative Variational Bandwidth Auto-encoder The codes are associated with the following paper: Collaborative Variational Bandwidth Auto-encoder f

Yaochen Zhu 14 Dec 11, 2022
QRec: A Python Framework for quick implementation of recommender systems (TensorFlow Based)

QRec is a Python framework for recommender systems (Supported by Python 3.7.4 and Tensorflow 1.14+) in which a number of influential and newly state-of-the-art recommendation models are implemented. QRec has a lightweight architecture and provides user-friendly interfaces. It can facilitate model implementation and evaluation.

Yu 1.4k Dec 27, 2022
E-Commerce recommender demo with real-time data and a graph database

?? E-Commerce recommender demo ?? This is a simple stream setup that uses Memgraph to ingest real-time data from a simulated online store. Data is str

g-despot 3 Feb 23, 2022
Movie Recommender System

Movie-Recommender-System Movie-Recommender-System is a web application using which a user can select his/her watched movie from list and system will r

null 1 Jul 14, 2022
Mutual Fund Recommender System. Tailor for fund transactions.

Explainable Mutual Fund Recommendation Data Please see 'DATA_DESCRIPTION.md' for mode detail. Recommender System Methods Baseline Collabarative Fiilte

JHJu 2 May 19, 2022
Movies/TV Recommender

recommender Movies/TV Recommender. Recommends Movies, TV Shows, Actors, Directors, Writers. Setup Create file API_KEY and paste your TMDB API key in i

Aviem Zur 3 Apr 22, 2022
6002project-rl - An implemention of offline RL on recommender system

An implemention of offline RL on recommender system @author: misajie @update: 20

Tzay Lee 3 May 24, 2022
Plex-recommender - Get movie recommendations based on your current PleX library

plex-recommender Description: Get movie/tv recommendations based on your current

null 5 Jul 19, 2022
ToR[e]cSys is a PyTorch Framework to implement recommendation system algorithms

ToR[e]cSys is a PyTorch Framework to implement recommendation system algorithms, including but not limited to click-through-rate (CTR) prediction, learning-to-ranking (LTR), and Matrix/Tensor Embedding. The project objective is to develop a ecosystem to experiment, share, reproduce, and deploy in real world in a smooth and easy way (Hope it can be done).

LI, Wai Yin 90 Oct 8, 2022
Deep recommender models using PyTorch.

Spotlight uses PyTorch to build both deep and shallow recommender models. By providing both a slew of building blocks for loss functions (various poin

Maciej Kula 2.8k Dec 29, 2022
A library for preparing, training, and evaluating scalable deep learning hybrid recommender systems using PyTorch.

collie_recs Collie is a library for preparing, training, and evaluating implicit deep learning hybrid recommender systems, named after the Border Coll

ShopRunner 97 Jan 3, 2023
A library for preparing, training, and evaluating scalable deep learning hybrid recommender systems using PyTorch.

collie Collie is a library for preparing, training, and evaluating implicit deep learning hybrid recommender systems, named after the Border Collie do

ShopRunner 96 Dec 29, 2022
StackRec: Efficient Training of Very Deep Sequential Recommender Models by Iterative Stacking

StackRec: Efficient Training of Very Deep Sequential Recommender Models by Iterative Stacking Datasets You can download datasets that have been pre-pr

null 25 May 29, 2022
NVIDIA Merlin is an open source library providing end-to-end GPU-accelerated recommender systems, from feature engineering and preprocessing to training deep learning models and running inference in production.

NVIDIA Merlin NVIDIA Merlin is an open source library designed to accelerate recommender systems on NVIDIA’s GPUs. It enables data scientists, machine

null 419 Jan 3, 2023
An efficient PyTorch implementation of the evaluation metrics in recommender systems.

recsys_metrics An efficient PyTorch implementation of the evaluation metrics in recommender systems. Overview • Installation • How to use • Benchmark

Xingdong Zuo 12 Dec 2, 2022
Book Recommender System Using Sci-kit learn N-neighbours

Model-Based-Recommender-Engine I created a book Recommender System using Sci-kit learn's N-neighbours algorithm for my model and the streamlit library

null 1 Jan 13, 2022