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
Code for ICML2019 Paper "Compositional Invariance Constraints for Graph Embeddings"

Dependencies NOTE: This code has been updated, if you were using this repo earlier and experienced issues that was due to an outaded codebase. Please

Avishek (Joey) Bose 43 Nov 25, 2022
fastFM: A Library for Factorization Machines

Citing fastFM The library fastFM is an academic project. The time and resources spent developing fastFM are therefore justified by the number of citat

1k Dec 24, 2022
Attentive Social Recommendation: Towards User And Item Diversities

ASR This is a Tensorflow implementation of the paper: Attentive Social Recommendation: Towards User And Item Diversities Preprint, https://arxiv.org/a

Dongsheng Luo 1 Nov 14, 2021
A PyTorch implementation of "Say No to the Discrimination: Learning Fair Graph Neural Networks with Limited Sensitive Attribute Information" (WSDM 2021)

FairGNN A PyTorch implementation of "Say No to the Discrimination: Learning Fair Graph Neural Networks with Limited Sensitive Attribute Information" (

31 Jan 04, 2023
Cross-Domain Recommendation via Preference Propagation GraphNet.

PPGN Codes for CIKM 2019 paper Cross-Domain Recommendation via Preference Propagation GraphNet. Citation Please cite our paper if you find this code u

Information Retrieval Group, Wuhan University, China 20 Dec 15, 2022
It is a movie recommender web application which is developed using the Python.

Movie Recommendation 🍿 System Watch Tutorial for this project Source IMDB Movie 5000 Dataset Inspired from this original repository. Features Simple

Kushal Bhavsar 10 Dec 26, 2022
Codes for AAAI'21 paper 'Self-Supervised Hypergraph Convolutional Networks for Session-based Recommendation'

DHCN Codes for AAAI 2021 paper 'Self-Supervised Hypergraph Convolutional Networks for Session-based Recommendation'. Please note that the default link

Xin Xia 124 Dec 14, 2022
Self-supervised Graph Learning for Recommendation

SGL This is our Tensorflow implementation for our SIGIR 2021 paper: Jiancan Wu, Xiang Wang, Fuli Feng, Xiangnan He, Liang Chen, Jianxun Lian,and Xing

151 Dec 20, 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

420 Jan 04, 2023
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
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 Python scikit for building and analyzing recommender systems

Overview Surprise is a Python scikit for building and analyzing recommender systems that deal with explicit rating data. Surprise was designed with th

Nicolas Hug 5.7k Jan 01, 2023
A movie recommender which recommends the movies belonging to the genre that user has liked the most.

Content-Based-Movie-Recommender-System This model relies on the similarity of the items being recommended. (I have used Pandas and Numpy. However othe

Srinivasan K 0 Mar 31, 2022
EXEMPLO DE SISTEMA ESPECIALISTA PARA RECOMENDAR SERIADOS EM PYTHON

exemplo-de-sistema-especialista EXEMPLO DE SISTEMA ESPECIALISTA PARA RECOMENDAR SERIADOS EM PYTHON Resumo O objetivo de auxiliar o usuário na escolha

Josue Lopes 3 Aug 31, 2021
Learning Fair Representations for Recommendation: A Graph-based Perspective, WWW2021

FairGo WWW2021 Learning Fair Representations for Recommendation: A Graph-based Perspective As a key application of artificial intelligence, recommende

lei 39 Oct 26, 2022
Price-aware Recommendation with Graph Convolutional Networks,

PUP This is the official implementation of our ICDE'20 paper: Yu Zheng, Chen Gao, Xiangnan He, Yong Li, Depeng Jin, Price-aware Recommendation with Gr

S4rawBer2y 3 Oct 30, 2022
Codes for CIKM'21 paper 'Self-Supervised Graph Co-Training for Session-based Recommendation'.

COTREC Codes for CIKM'21 paper 'Self-Supervised Graph Co-Training for Session-based Recommendation'. Requirements: Python 3.7, Pytorch 1.6.0 Best Hype

Xin Xia 43 Jan 04, 2023
Incorporating User Micro-behaviors and Item Knowledge 59 60 3 into Multi-task Learning for Session-based Recommendation

MKM-SR Incorporating User Micro-behaviors and Item Knowledge into Multi-task Learning for Session-based Recommendation Paper data and code This is the

ciecus 38 Dec 05, 2022
This library intends to be a reference for recommendation engines in Python

Crab - A Python Library for Recommendation Engines

Marcel Caraciolo 85 Oct 04, 2021
Code for KHGT model, AAAI2021

KHGT Code for KHGT accepted by AAAI2021 Please unzip the data files in Datasets/ first. To run KHGT on Yelp data, use python labcode_yelp.py For Movi

32 Nov 29, 2022