{"id":17596013,"url":"https://github.com/shoprunner/collie","last_synced_at":"2025-04-09T12:04:42.268Z","repository":{"id":39740873,"uuid":"357336413","full_name":"ShopRunner/collie","owner":"ShopRunner","description":"A library for preparing, training, and evaluating scalable deep learning hybrid recommender systems using PyTorch. ","archived":false,"fork":false,"pushed_at":"2024-02-21T16:29:12.000Z","size":1059,"stargazers_count":111,"open_issues_count":11,"forks_count":20,"subscribers_count":30,"default_branch":"main","last_synced_at":"2025-04-09T12:04:38.037Z","etag":null,"topics":["datascience","deep-learning","hybrid","implicit","learning-to-rank","python","pytorch","recommendation-system","recommender-system"],"latest_commit_sha":null,"homepage":"https://collie.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ShopRunner.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-12T20:54:06.000Z","updated_at":"2025-03-04T17:04:50.000Z","dependencies_parsed_at":"2024-06-03T18:49:59.421Z","dependency_job_id":null,"html_url":"https://github.com/ShopRunner/collie","commit_stats":{"total_commits":193,"total_committers":14,"mean_commits":"13.785714285714286","dds":"0.39896373056994816","last_synced_commit":"739fad43c27695b3ca394b5cd4ec770a479a3c76"},"previous_names":["shoprunner/collie_recs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShopRunner%2Fcollie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShopRunner%2Fcollie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShopRunner%2Fcollie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShopRunner%2Fcollie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ShopRunner","download_url":"https://codeload.github.com/ShopRunner/collie/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036063,"owners_count":21037092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["datascience","deep-learning","hybrid","implicit","learning-to-rank","python","pytorch","recommendation-system","recommender-system"],"created_at":"2024-10-22T08:07:09.853Z","updated_at":"2025-04-09T12:04:42.237Z","avatar_url":"https://github.com/ShopRunner.png","language":"Python","readme":"# collie\n\n[![PyPI version](https://badge.fury.io/py/collie.svg)](https://badge.fury.io/py/collie)\n[![versions](https://img.shields.io/pypi/pyversions/collie.svg)](https://pypi.org/project/collie/)\n[![Workflows Passing](https://github.com/ShopRunner/collie/workflows/CI%2FCD/badge.svg)](https://github.com/ShopRunner/collie/actions/workflows/ci.yaml)\n[![Documentation Status](https://readthedocs.org/projects/collie/badge/?version=latest)](https://collie.readthedocs.io/en/latest/?badge=latest)\n[![codecov](https://codecov.io/gh/ShopRunner/collie/branch/main/graph/badge.svg)](https://codecov.io/gh/ShopRunner/collie)\n[![license](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://github.com/ShopRunner/collie/blob/main/LICENSE)\n\nCollie is a library for preparing, training, and evaluating implicit deep learning hybrid recommender systems, named after the Border Collie dog breed.\n\nCollie offers a collection of simple APIs for preparing and splitting datasets, incorporating item metadata directly into a model architecture or loss, efficiently evaluating a model's performance on the GPU, and so much more. Above all else though, Collie is built with flexibility and customization in mind, allowing for faster prototyping and experimentation.\n\nSee the [documentation](https://collie.readthedocs.io/en/latest/index.html) for more details.\n\n![](https://net-shoprunner-scratch-data-science.s3.amazonaws.com/njones/collie/collie-banner.png)\n\u003e \"We adopted 2 Border Collies a year ago and they are about 3 years old. They are completely obsessed with fetch and tennis balls and it's getting out of hand. They live in the fenced back yard and when anyone goes out there they instantly run around frantically looking for a tennis ball. If there is no ball they will just keep looking and will not let you pet them. When you do have a ball, they are 100% focused on it and will not notice anything else going on around them, like it's their whole world.\"\n\u003e\n\u003e -- *A Reddit thread on r/DogTraining*\n\n## Installation\n```bash\npip install collie\n```\n\nThrough July 2021, this library used to be under the name ``collie_recs``. While this version is still available on PyPI, it is no longer supported or maintained. All users of the library should use ``collie`` for the latest and greatest version of the code!\n\n## Quick Start\n\n### Implicit Data\n\nCreating and evaluating a matrix factorization model with _implicit_ MovieLens 100K data is simple with Collie:\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ShopRunner/collie/blob/main/tutorials/quickstart.ipynb)\n\n```python\nfrom collie.cross_validation import stratified_split\nfrom collie.interactions import Interactions\nfrom collie.metrics import auc, evaluate_in_batches, mapk, mrr\nfrom collie.model import MatrixFactorizationModel, CollieTrainer\nfrom collie.movielens import read_movielens_df\nfrom collie.utils import convert_to_implicit\n\n\n# read in explicit MovieLens 100K data\ndf = read_movielens_df()\n\n# convert the data to implicit\ndf_imp = convert_to_implicit(df)\n\n# store data as ``Interactions``\ninteractions = Interactions(users=df_imp['user_id'],\n                            items=df_imp['item_id'],\n                            allow_missing_ids=True)\n\n# perform a data split\ntrain, val = stratified_split(interactions)\n\n# train an implicit ``MatrixFactorization`` model\nmodel = MatrixFactorizationModel(train=train,\n                                 val=val,\n                                 embedding_dim=10,\n                                 lr=1e-1,\n                                 loss='adaptive',\n                                 optimizer='adam')\ntrainer = CollieTrainer(model, max_epochs=10)\ntrainer.fit(model)\nmodel.eval()\n\n# evaluate the model\nauc_score, mrr_score, mapk_score = evaluate_in_batches(metric_list=[auc, mrr, mapk],\n                                                       test_interactions=val,\n                                                       model=model)\n\nprint(f'AUC:          {auc_score}')\nprint(f'MRR:          {mrr_score}')\nprint(f'MAP@10:       {mapk_score}')\n```\n\nMore complicated examples of implicit pipelines can be viewed [for MovieLens 100K data here](https://github.com/ShopRunner/collie/blob/main/collie/movielens/run.py), [in notebooks here](https://github.com/ShopRunner/collie/tree/main/tutorials), and [documentation](https://collie.readthedocs.io/en/latest/index.html) here.\n\n### Explicit Data\n\nCollie also handles the situation when you instead have _explicit_ data, such as star ratings. Note how similar the pipeline and APIs are compared to the implicit example above:\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ShopRunner/collie/blob/main/tutorials/quickstart-explicit.ipynb)\n\n```python\nfrom collie.cross_validation import stratified_split\nfrom collie.interactions import ExplicitInteractions\nfrom collie.metrics import explicit_evaluate_in_batches\nfrom collie.model import MatrixFactorizationModel, CollieTrainer\nfrom collie.movielens import read_movielens_df\n\nfrom torchmetrics import MeanAbsoluteError, MeanSquaredError\n\n\n# read in explicit MovieLens 100K data\ndf = read_movielens_df()\n\n# store data as ``Interactions``\ninteractions = ExplicitInteractions(users=df['user_id'],\n                                    items=df['item_id'],\n                                    ratings=df['rating'])\n\n# perform a data split\ntrain, val = stratified_split(interactions)\n\n# train an implicit ``MatrixFactorization`` model\nmodel = MatrixFactorizationModel(train=train,\n                                 val=val,\n                                 embedding_dim=10,\n                                 lr=1e-2,\n                                 loss='mse',\n                                 optimizer='adam')\ntrainer = CollieTrainer(model, max_epochs=10)\ntrainer.fit(model)\nmodel.eval()\n\n# evaluate the model\nmae_score, mse_score = explicit_evaluate_in_batches(metric_list=[MeanAbsoluteError(),\n                                                                 MeanSquaredError()],\n                                                    test_interactions=val,\n                                                    model=model)\n\nprint(f'MAE: {mae_score}')\nprint(f'MSE: {mse_score}')\n```\n\n## Comparison With Other Open-Source Recommendation Libraries\n\n*On some smaller screens, you might have to scroll right to see the full table.* ➡️\n\n| Aspect Included in Library | \u003ca href=\"http://surpriselib.com\" target=\"_blank\"\u003eSurprise\u003c/a\u003e | \u003ca href=\"https://making.lyst.com/lightfm/docs/home.html\" target=\"_blank\"\u003eLightFM\u003c/a\u003e | \u003ca href=\"https://docs.fast.ai\" target=\"_blank\"\u003eFastAI\u003c/a\u003e | \u003ca href=\"https://maciejkula.github.io/spotlight/\" target=\"_blank\"\u003eSpotlight\u003c/a\u003e | \u003ca href=\"https://recbole.io\" target=\"_blank\"\u003eRecBole\u003c/a\u003e | \u003ca href=\"https://www.tensorflow.org/recommenders\" target=\"_blank\"\u003eTensorFlow Recommenders\u003c/a\u003e | Collie |\n| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |\n| **Implicit data support** for when we only know when a user interacts with an item or not, not the explicit rating the user gave the item |  | ✓ |  | ✓ | ✓ | ✓ | ✓ |\n| **Explicit data support** for when we know the explicit rating the user gave the item | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| Support for **side-data** incorporated directly into the models |  | ✓ |  |  | ✓ | ✓ | ✓ |\n| Support a **flexible framework for new model architectures** and experimentation |  |  | ✓ | ✓ | ✓ | ✓ | ✓ |\n| **Deep learning** libraries utilizing speed-ups with a GPU and able to implement new, cutting-edge deep learning algorithms  |  |  | ✓ | ✓ | ✓ | ✓ | ✓ |\n| **Automatic support for multi-GPU training**  |  |  |  |  |  |  | ✓ |\n| **Actively supported and maintained**  | ✓ | ✓ | ✓ |  | ✓ | ✓ | ✓ |\n| **Type annotations** for classes, methods, and functions  |  |  |  |  |  | ✓ | ✓ |\n| **Scalable for larger, out-of-memory datasets**  |  |  |  |  |  | ✓ | ✓ |\n| Includes **model zoo** with two or more model architectures implemented  |  |  |  | ✓ | ✓ |  | ✓ |\n| Includes **implicit loss functions** for training and **metric functions** for model evaluation  |  | ✓ |  | ✓ | ✓ |  | ✓ |\n| Includes **adaptive loss functions** for multiple negative examples  |  | ✓ |  | ✓ |  |  | ✓ |\n| Includes **loss functions with [partial credit for side-data](https://collie.readthedocs.io/en/latest/loss.html)**  |  |  |  |  |  |  | ✓ |\n\nThe following table notes shows the results of an experiment training and evaluating recommendation models in some popular implicit recommendation model frameworks on a common [MovieLens 10M](https://grouplens.org/datasets/movielens/10m/) dataset. The data was split via a 90/5/5 stratified data split. Each model was trained for a maximum of 40 epochs using an embedding dimension of 32. For each model, we used default hyperparameters (unless otherwise noted below).\n\n| Model | MAP@10 Score | Notes |\n| ----- | :----------: | :---: |\n| Randomly initialized, untrained model                                     | 0.0001     |                                       |\n| [Logistic MF](https://implicit.readthedocs.io/en/latest/lmf.html)         | 0.0128     | Using the CUDA implementation.        |\n| [LightFM](https://making.lyst.com/lightfm/docs/home.html) with BPR Loss   | 0.0180     |                                       |\n| [ALS](https://implicit.readthedocs.io/en/latest/als.html)                 | 0.0189     | Using the CUDA implementation.        |\n| [BPR](https://implicit.readthedocs.io/en/latest/bpr.html)                 | 0.0301     | Using the CUDA implementation.        |\n| [Spotlight](https://maciejkula.github.io/spotlight/index.html)            | 0.0376     | Using adaptive hinge loss.            |\n| [LightFM](https://making.lyst.com/lightfm/docs/home.html) with WARP Loss  | 0.0412     |                                       |\n| Collie ``MatrixFactorizationModel``                                       | **0.0425** | Using a separate SGD bias optimizer.  |\n\nAt ShopRunner, we have found Collie models outperform comparable LightFM models with up to **64% improved MAP@10 scores**.\n\n## Development\nTo run locally, begin by creating a data path environment variable:\n\n```bash\n# Define where on your local hard drive you want to store data. It is best if this\n# location is not inside the repo itself. An example is below\nexport DATA_PATH=$HOME/data/collie\n```\n\nRun development from within the Docker container:\n```bash\ndocker build -t collie .\n\n# run the container in interactive mode, leaving port ``8888`` open for Jupyter\ndocker run \\\n    -it \\\n    --rm \\\n    -v \"${DATA_PATH}:/collie/data/\" \\\n    -v \"${PWD}:/collie\" \\\n    -p 8888:8888 \\\n    collie /bin/bash\n```\n\n### Run on a GPU:\n```bash\ndocker build -t collie .\n\n# run the container in interactive mode, leaving port ``8888`` open for Jupyter\ndocker run \\\n    -it \\\n    --rm \\\n    --gpus all \\\n    -v \"${DATA_PATH}:/collie/data/\" \\\n    -v \"${PWD}:/collie\" \\\n    -p 8888:8888 \\\n    collie /bin/bash\n```\n\n### Start JupyterLab\nTo run JupyterLab, start the container and execute the following:\n```bash\njupyter lab --ip 0.0.0.0 --no-browser --allow-root\n```\nConnect to JupyterLab here: [http://localhost:8888/lab](http://localhost:8888/lab)\n\n### Unit Tests\nLibrary unit tests in this repo are to be run in the Docker container:\n\n```bash\n# execute unit tests\npytest --cov-report term --cov=collie\n```\n\nNote that a handful of tests require the [MovieLens 100K dataset](https://files.grouplens.org/datasets/movielens/ml-100k.zip) to be downloaded (~5MB in size), meaning that either before or during test time, there will need to be an internet connection. This dataset only needs to be downloaded a single time for use in both unit tests and tutorials.\n\n### Docs\nThe Collie library supports Read the Docs documentation. To compile locally,\n```bash\ncd docs\nmake html\n\n# open local docs\nopen build/html/index.html\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshoprunner%2Fcollie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshoprunner%2Fcollie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshoprunner%2Fcollie/lists"}