{"id":21995688,"url":"https://github.com/tohtsky/irspack","last_synced_at":"2025-04-30T17:27:43.855Z","repository":{"id":37048133,"uuid":"321234747","full_name":"tohtsky/irspack","owner":"tohtsky","description":"Train, evaluate, and optimize implicit feedback-based recommender systems.","archived":false,"fork":false,"pushed_at":"2023-06-03T05:41:32.000Z","size":751,"stargazers_count":29,"open_issues_count":1,"forks_count":9,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-15T16:53:58.437Z","etag":null,"topics":["eigen","evaluation-framework","hyperparameter-optimization","knn-algorithm","matrix-factorization","optuna","pybind11","recommender-systems"],"latest_commit_sha":null,"homepage":"https://irspack.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tohtsky.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-12-14T04:38:45.000Z","updated_at":"2024-11-19T11:50:16.000Z","dependencies_parsed_at":"2023-02-05T08:32:13.506Z","dependency_job_id":"7e20e903-bb9e-427f-8ac9-af30f2a3b285","html_url":"https://github.com/tohtsky/irspack","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tohtsky%2Firspack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tohtsky%2Firspack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tohtsky%2Firspack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tohtsky%2Firspack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tohtsky","download_url":"https://codeload.github.com/tohtsky/irspack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251750623,"owners_count":21637756,"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":["eigen","evaluation-framework","hyperparameter-optimization","knn-algorithm","matrix-factorization","optuna","pybind11","recommender-systems"],"created_at":"2024-11-29T21:18:10.339Z","updated_at":"2025-04-30T17:27:43.830Z","avatar_url":"https://github.com/tohtsky.png","language":"Python","readme":"# irspack - Implicit recommender systems for practitioners\n\n[![Python](https://img.shields.io/badge/python-3.7%20%7C%203.8%20%7C%203.9%20%7C%203.10-blue)](https://www.python.org)\n[![pypi](https://img.shields.io/pypi/v/irspack.svg)](https://pypi.python.org/pypi/irspack)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/tohtsky/irspack)\n[![Build](https://github.com/tohtsky/irspack/workflows/Build/badge.svg?branch=main)](https://github.com/tohtsky/irspack)\n[![Read the Docs](https://readthedocs.org/projects/irspack/badge/?version=stable)](https://irspack.readthedocs.io/en/stable/)\n[![codecov](https://codecov.io/gh/tohtsky/irspack/branch/main/graph/badge.svg?token=kLgOKTQqcV)](https://codecov.io/gh/tohtsky/irspack)\n\n[**Docs**](https://irspack.readthedocs.io/en/latest/)\n\n**irspack** is a Python package for recommender systems based on implicit feedback, designed to be used by practitioners.\n\nSome of its features include:\n\n- Efficient parameter tuning enabled by C++/Eigen implementations of core recommender algorithms and [optuna](https://github.com/optuna/optuna).\n  - In particular, if an early stopping scheme is available, optuna can prune out unpromising trial based on the intermediate validation scores.\n- Various utility functions, including\n  - ID/index mapping utilities\n  - Fast, multithreaded argsort for batch recommendation retrieval\n  - Efficient and configurable evaluation of recommender system performance\n\n# Installation \u0026 Optional Dependencies\n\nIn most cases, you can install the pre-build binaries via\n\n```sh\npip install irspack\n```\n\nThe binaries have been compiled to use AVX instruction. If you want to use AVX2/AVX512 or your environment does not support AVX (like Rosetta 2 on Apple M1), install it from source like\n\n```sh\nCFLAGS=\"-march=native\" pip install git+https://github.com/tohtsky/irspack.git\n```\n\nIn that case, you must have a decent version of C++ compiler (with C++11 support). If it doesn't work, feel free to make an issue!\n\n## Optional Dependencies\n\nI have also prepared a wrapper class (`BPRFMRecommender`) to train/optimize BPR/warp loss Matrix factorization implemented in [lightfm](https://github.com/lyst/lightfm). To use it you have to install `lightfm` separately, e.g. by\n\n```sh\npip install lightfm\n```\n\nIf you want to use Mult-VAE, you'll need the following additional (pip-installable) packages:\n\n- [jax](https://github.com/google/jax)\n- [jaxlib](https://github.com/google/jax)\n  - If you want to use GPU, follow the installation guide [https://github.com/google/jax#installation](https://github.com/google/jax#installation)\n- [dm-haiku](https://github.com/deepmind/dm-haiku)\n- [optax](https://github.com/deepmind/optax)\n\n# Basic Usage\n\n## Step 1. Train a recommender\n\nTo begin with, we represent the user/item interaction as a [scipy.sparse](https://docs.scipy.org/doc/scipy/reference/sparse.html) matrix. Then we can feed it into recommender classes:\n\n```Python\nimport numpy as np\nimport scipy.sparse as sps\nfrom irspack import IALSRecommender, df_to_sparse\nfrom irspack.dataset import MovieLens100KDataManager\n\ndf = MovieLens100KDataManager().read_interaction()\n\n# Convert pandas.Dataframe into scipy's sparse matrix.\n# The i'th row of `X_interaction` corresponds to `unique_user_id[i]`\n# and j'th column of `X_interaction` corresponds to `unique_movie_id[j]`.\nX_interaction, unique_user_id, unique_movie_id = df_to_sparse(\n  df, 'userId', 'movieId'\n)\n\nrecommender = IALSRecommender(X_interaction)\nrecommender.learn()\n\n# for user 0 (whose userId is unique_user_id[0]),\n# compute the masked score (i.e., already seen items have the score of negative infinity)\n# of items.\nrecommender.get_score_remove_seen([0])\n```\n\n## Step 2. Evaluation on a validation set\n\nTo evaluate the performance of a recommenderm we have to split the dataset to train and validation sets:\n\n```Python\nfrom irspack.split import rowwise_train_test_split\nfrom irspack.evaluation import Evaluator\n\n# Random split\nX_train, X_val = rowwise_train_test_split(\n    X_interaction, test_ratio=0.2, random_state=0\n)\n\nevaluator = Evaluator(ground_truth=X_val)\n\nrecommender = IALSRecommender(X_train)\nrecommender.learn()\nevaluator.get_score(recommender)\n```\n\nThis will print something like\n\n```Python\n{\n    'appeared_item': 435.0,\n    'entropy': 5.160409123151053,\n    'gini_index': 0.9198367595008214,\n    'hit': 0.40084835630965004,\n    'map': 0.013890322881619916,\n    'n_items': 1682.0,\n    'ndcg': 0.07867240014767263,\n    'precision': 0.06797454931071051,\n    'recall': 0.03327028758587522,\n    'total_user': 943.0,\n    'valid_user': 943.0\n}\n```\n\n## Step 3. Hyperparameter optimization\n\nNow that we can evaluate the recommenders' performance against the validation set, we can use [optuna](https://github.com/optuna/optuna)-backed hyperparameter optimization.\n\n```Python\nbest_params, trial_dfs  = IALSRecommender.tune(X_train, evaluator, n_trials=20)\n\n# maximal ndcg around 0.43 ~ 0.45\ntrial_dfs[\"ndcg@10\"].max()\n```\n\nOf course, we have to hold-out another interaction set for test, and measure the performance of tuned recommender against the test set.\n\nSee `examples/` for more complete examples.\n\n# TODOs\n\n- more benchmark dataset\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftohtsky%2Firspack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftohtsky%2Firspack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftohtsky%2Firspack/lists"}