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
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
Pytorch domain library for recommendation systems

TorchRec (Experimental Release) TorchRec is a PyTorch domain library built to provide common sparsity & parallelism primitives needed for large-scale

Meta Research 1.3k Jan 05, 2023
Recommendation System to recommend top books from the dataset

recommendersystem Recommendation System to recommend top books from the dataset Introduction The recom.py is the main program code. The dataset is als

Vishal karur 1 Nov 15, 2021
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
大规模推荐算法库,包含推荐系统经典及最新算法LR、Wide&Deep、DSSM、TDM、MIND、Word2Vec、DeepWalk、SSR、GRU4Rec、Youtube_dnn、NCF、GNN、FM、FFM、DeepFM、DCN、DIN、DIEN、DLRM、MMOE、PLE、ESMM、MAML、xDeepFM、DeepFEFM、NFM、AFM、RALM、Deep Crossing、PNN、BST、AutoInt、FGCNN、FLEN、ListWise等

(中文文档|简体中文|English) 什么是推荐系统? 推荐系统是在互联网信息爆炸式增长的时代背景下,帮助用户高效获得感兴趣信息的关键; 推荐系统也是帮助产品最大限度吸引用户、留存用户、增加用户粘性、提高用户转化率的银弹。 有无数优秀的产品依靠用户可感知的推荐系统建立了良好的口碑,也有无数的公司依

3.6k Dec 30, 2022
Knowledge-aware Coupled Graph Neural Network for Social Recommendation

KCGN AAAI-2021 《Knowledge-aware Coupled Graph Neural Network for Social Recommendation》 Environments python 3.8 pytorch-1.6 DGL 0.5.3 (https://github.

xhc 22 Nov 18, 2022
RecList is an open source library providing behavioral, "black-box" testing for recommender systems.

RecList is an open source library providing behavioral, "black-box" testing for recommender systems.

Jacopo Tagliabue 375 Dec 30, 2022
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
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
Global Context Enhanced Social Recommendation with Hierarchical Graph Neural Networks

SR-HGNN ICDM-2020 《Global Context Enhanced Social Recommendation with Hierarchical Graph Neural Networks》 Environments python 3.8 pytorch-1.6 DGL 0.5.

xhc 9 Nov 12, 2022
A Python implementation of LightFM, a hybrid recommendation algorithm.

LightFM Build status Linux OSX (OpenMP disabled) Windows (OpenMP disabled) LightFM is a Python implementation of a number of popular recommendation al

Lyst 4.2k Jan 02, 2023
The source code for "Global Context Enhanced Graph Neural Network for Session-based Recommendation".

GCE-GNN Code This is the source code for SIGIR 2020 Paper: Global Context Enhanced Graph Neural Networks for Session-based Recommendation. Requirement

98 Dec 28, 2022
Jointly Learning Explainable Rules for Recommendation with Knowledge Graph

Jointly Learning Explainable Rules for Recommendation with Knowledge Graph

57 Nov 03, 2022
The official implementation of "DGCN: Diversified Recommendation with Graph Convolutional Networks" (WWW '21)

DGCN This is the official implementation of our WWW'21 paper: Yu Zheng, Chen Gao, Liang Chen, Depeng Jin, Yong Li, DGCN: Diversified Recommendation wi

FIB LAB, Tsinghua University 37 Dec 18, 2022
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
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
Temporal Meta-path Guided Explainable Recommendation (WSDM2021)

Temporal Meta-path Guided Explainable Recommendation (WSDM2021) TMER Code of paper "Temporal Meta-path Guided Explainable Recommendation". Requirement

Yicong Li 13 Nov 30, 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

1 Jul 14, 2022
Respiratory Health Recommendation System

Respiratory-Health-Recommendation-System Respiratory Health Recommendation System based on Air Quality Index Forecasts This project aims to provide pr

Abhishek Gawabde 1 Jan 29, 2022
Recommender System Papers

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

RUCAIBox 704 Jan 06, 2023