rfscorer 0.5.4

Recency-Frequency based recommendation scoring

RFscorer

日本語 README

rfscorer is a Python package for Recency-Frequency based recommendation scoring.

Note: In this package, RF stands for Recency-Frequency, not Random Forest.

It estimates a recommendation score (product-choice probability) — how likely each previously interacted item is to be chosen — from two behavioral signals:

• Recency: time since the last interaction. More recently viewed items tend to attract more interest.
• Frequency: number of interactions. More frequently viewed items tend to attract more interest.

You can set any event as the prediction target (revisits, purchases, conversions, etc.).

Product recommendation comes down to deciding which previously interacted items to prioritize. For example:

• [By frequency] Item A viewed once 🆚 Item B viewed twice ▶ recommend B, viewed more often
• [By recency] Item A viewed 1 day ago 🆚 Item C viewed 2 days ago ▶ recommend A, viewed more recently
• [Trade-off] Item A viewed once 1 day ago 🆚 Item D viewed twice 2 days ago ▶ hard to judge by intuition

For such non-trivial cases, rfscorer uses mathematical optimization to estimate scores that capture the recency–frequency interaction while satisfying their natural monotonicity, giving a data-driven, natural recommendation order over previously interacted items (Iwanaga et al., KBS (2016)).

rfscorer's scores also serve as input to downstream models — a rating matrix for collaborative filtering or features for ML models. These features capture the recency–frequency interaction and can help improve downstream accuracy (Iwanaga et al., ECRA (2019)).

Recommendation system architecture using RF scoring

Slides

Overview slides (PDF) (CC BY 4.0)

Target Users

rfscorer is designed for both practitioners and researchers.

• Practitioners
  • Data scientists / ML engineers
  • Marketers / analysts
  • Recommendation system owners on EC / content platforms
• Researchers
  • Recommender systems / information retrieval
  • Marketing science / consumer behavior
  • Operations research / mathematical optimization
  • Cognitive psychology (memory / mere-exposure effect)

Features

Feature	Description
scikit-learn style	fit() / transform() interface
Minimal data	works with any behavior history with three columns: user, item, datetime
Explainable	scores are estimated by mathematical optimization under RF monotonicity, making the reasoning behind each recommendation easy to explain
Stable probability estimation	product-choice probabilities are estimated directly from recency and frequency, avoiding the instability of converting ML model outputs to a probability scale
Downstream use	usable not only as a standalone recommendation score but also as a rating matrix for collaborative filtering or as features for ML models
Rich diagnostics & visualization	extensive statistical outputs and visualization features let practitioners explain results in their work and researchers report them in papers

Installation

pip install rfscorer

Usage

Below is a minimal example of building a model and scoring recommendations from a behavior history (for complete, runnable code, see Examples).

Minimal Example

import pandas as pd
from rfscorer import RecencyFrequencyScorer, split_by_date

# Load your behavior history
df = ...  # columns: user, item, datetime

# Split by target date
target_date = "2026-07-07"
df_obs, df_gt = split_by_date(df, target_date, 7, 1)  # observation: 7 days, ground truth: 1 day

# Fit and optimize
scorer = RecencyFrequencyScorer()
scorer.fit(df_obs, df_gt)
scorer.optimize(kind="mono")

# Score recommendations (on test data)
df_test = ...  # test data (columns: user, item, datetime)
df_test_obs, _ = split_by_date(df_test, target_date, 7, 1)
df_scores = scorer.transform(df_test_obs, target_date, kind="mono")

Input data (behavior history)

The input is a behavior history with three columns: user, item, datetime.

user	item	datetime
u_001	i_032	2026-07-06
u_001	i_032	2026-07-05
u_001	i_017	2026-07-05
u_002	i_011	2026-07-06
...	...	...

Output data (recommendation scores)

transform() returns a table that adds recency, frequency, product-choice probability, and recommendation order to each user × item.

user	item	recency	frequency	probability	order
u_001	i_032	1	4	0.1167	1
u_001	i_017	2	3	0.0789	2
u_001	i_045	3	1	0.0248	3
u_002	i_011	1	2	0.0621	1
u_002	i_058	4	1	0.0182	2

Recommend items to each user from highest to lowest probability. Since scores are probabilities, expected value calculations are straightforward (e.g., expected revenue per recommendation). Use the order column to apply business rules (e.g., recommend the top 2 items per user).

Visualization: Comparing Optimization Approaches

The package supports many optimization approaches. Here we visualize three representative methods:

scorer.plot_probability_surface(kind="emp")  # empirical (raw rates)

scorer.optimize(kind="mono")  # RF monotonicity
scorer.plot_probability_surface(kind="mono")

scorer.optimize(kind="mcc")   # convex in R, concave in F
scorer.plot_probability_surface(kind="mcc")

Empirical	Monotonicity	Monotonicity-Convex-Concave

Each surface clearly captures how the product-choice probability behaves with respect to recency (time since last interaction) and frequency (number of interactions):

• Empirical: Raw probabilities without constraints. Noisy and may violate monotonicity, sometimes recommending items in unnatural order.
• Monotonicity: Probabilities with RF monotonicity constraints. Guarantees items are recommended in natural order.
• Monotonicity-Convex-Concave: Probabilities with RF monotonicity and convexity-concavity constraints. Produces the smoothest surface.

Examples

• examples/tutorial_beginner_en.ipynb — end-to-end walkthrough: load data, fit, optimize, visualize, transform, and evaluate
• examples/tutorial_practical_en.ipynb — practical workflow: chronological train/test split, build the various models, compare accuracy, and save/load the model
• examples/tutorial_advanced_fit_rolling_en.ipynb — advanced workflow: time-series rolling training with fit_rolling() to stabilize empirical probabilities across multiple reference dates

For the complete list of tutorials, see examples/.

API Reference

Show API reference

API	Description
split_by_date(df, date, obs, gt)	Split a behavior history into observation and ground-truth data chronologically
RecencyFrequencyScorer()	Create a scorer
.fit(df_obs, df_gt)	Aggregate empirical product-choice probabilities per recency × frequency
.fit_rolling(...)	Stabilize empirical probabilities by rolling aggregation over multiple reference dates
.optimize(kind="mono")	Estimate scores satisfying constraints such as monotonicity via mathematical optimization
.transform(df_obs, date, kind)	Compute recommendation scores (probability / order)
.predict(r, f, kind)	Return the product-choice probability for a given (recency, frequency)
.evaluate(df_rec, df_gt)	Evaluate recommendation accuracy
.plot_probability_surface(kind)	Visualize the 3D surface of product-choice probabilities
.save(path) / .load(path)	Save / load the model

References

Show references

• Jiro Iwanaga, Naoki Nishimura, Noriyoshi Sukegawa, and Yuichi Takano, “Estimating product-choice probabilities from recency and frequency of page views,” Knowledge-Based Systems, Volume 99, 2016, Pages 157–167.

• Jiro Iwanaga, Kyota Ishihara, Naoki Nishimura, and Ikki Tanaka, Pythonではじめる数理最適化 ―ケーススタディでモデリングのスキルを身につけよう―(in Japanese), Ohmsha, 2021.

  • Chapter 7: 商品推薦のための興味のスコアリング(in Japanese)

• Jiro Iwanaga, Naoki Nishimura, Noriyoshi Sukegawa, and Yuichi Takano, “Improving collaborative filtering recommendations by estimating user preferences from clickstream data,” Electronic Commerce Research and Applications, Volume 37, Article 100877, 2019.

Citation

Show citation & BibTeX

If you use rfscorer in academic work, you can cite it as follows in the body of your paper:

We used rfscorer (Iwanaga et al., 2016), a Python library for Recency-Frequency-based recommendation scoring.¹

¹ https://github.com/jiro-iwanaga/rfscorer

The full reference is:

• Jiro Iwanaga, Naoki Nishimura, Noriyoshi Sukegawa, and Yuichi Takano, “Estimating product-choice probabilities from recency and frequency of page views,” Knowledge-Based Systems, Volume 99, 2016, Pages 157–167.

@article{Iwanaga2016,
  author  = {Jiro Iwanaga and Naoki Nishimura and Noriyoshi Sukegawa and Yuichi Takano},
  title   = {Estimating product-choice probabilities from recency and frequency of page views},
  journal = {Knowledge-Based Systems},
  volume  = {99},
  pages   = {157--167},
  year    = {2016},
  url     = {https://www.sciencedirect.com/science/article/abs/pii/S0950705116000848}
}

If you also use the probability matrix as input to a collaborative filtering model or as ML features, please also cite:

• Jiro Iwanaga, Naoki Nishimura, Noriyoshi Sukegawa, and Yuichi Takano, “Improving collaborative filtering recommendations by estimating user preferences from clickstream data,” Electronic Commerce Research and Applications, Volume 37, Article 100877, 2019.

@article{Iwanaga2019,
  author  = {Jiro Iwanaga and Naoki Nishimura and Noriyoshi Sukegawa and Yuichi Takano},
  title   = {Improving collaborative filtering recommendations by estimating user preferences from clickstream data},
  journal = {Electronic Commerce Research and Applications},
  volume  = {37},
  pages   = {100877},
  year    = {2019},
  url     = {https://www.sciencedirect.com/science/article/abs/pii/S1567422319300547}
}

License

MIT License

---

RFscorer (日本語README)

English README

rfscorer は、最新度（Recency）と頻度（Frequency）に基づいて、ユーザーが過去に接触した商品の推薦スコア（商品選択確率）を推定する Python パッケージです。

本パッケージでは RF は Recency-Frequency（最新度-頻度） を表します

ユーザーの行動履歴から、各商品の 選択されやすさ を表す推薦スコア（商品選択確率）を推定します。スコアは、次の2つの行動シグナルに基づいて計算されます。

• 最新度（recency）：最後に接触してからの経過時間。最近接触した商品ほど関心が高い傾向。
• 頻度（frequency）：商品への接触回数。何度も接触した商品ほど関心が高い傾向。

予測対象は、再閲覧、購買、コンバージョンなど用途に応じて自由に設定できます。

商品推薦は、過去の行動履歴を用いて、ユーザーが過去に接触した商品の中でどれを優先して推薦するかを決める問題と捉えられます。 たとえば、次のような比較です。

• 【頻度で判断】 1回閲覧した商品A　🆚　2回閲覧した商品B　▶　たくさん閲覧した 商品B を推薦
• 【最新度で判断】 1日前に閲覧した商品A　🆚　2日前に閲覧した商品C　▶　最近閲覧した 商品A を推薦
• 【トレードオフ】 1日前に1回閲覧した商品A　🆚　2日前に2回閲覧した商品D　▶　直感では判断できない

rfscorer は、このような非自明な比較に対して、数理最適化により、最新度と頻度の交互作用を考慮しつつ、自然な単調性を満たす推薦スコアを推定します。 これにより、ユーザーが過去に接触した商品に対して、データに基づく自然な推薦順位を与えることができます(Iwanaga et al., KBS (2016))。

また、rfscorer が出力する商品選択確率は、下流のモデルの入力（協調フィルタリングの評価値行列・機械学習モデルの特徴量）としても有効です。最新度と頻度の交互作用が反映された有用な特徴量によるモデル構築ができます(Iwanaga et al., ECRA (2019))。

RFスコアリングを用いた推薦システム構成

紹介スライド

rfscorer 紹介スライド（PDF・日本語）（CC BY 4.0）

想定ユーザー

rfscorer は実務家と研究者が利用することを想定しています。

• 実務家
  • データサイエンティスト・ML エンジニア
  • マーケター・アナリスト
  • EC・コンテンツ基盤の推薦システム担当者
• 研究者
  • 推薦システム・情報検索
  • マーケティングサイエンス・消費者行動論
  • オペレーションズリサーチ・数理最適化
  • 認知心理学（記憶・単純接触効果）

パッケージの特徴

特徴	説明
scikit‑learn ラ⁠イ⁠ク	fit() / transform() によるインターフェースを提供
最⁠小⁠限⁠の⁠デ⁠ー⁠タ⁠要⁠件	入力データは、user、item、datetime の３カラムをもつ行動履歴
説⁠明⁠可⁠能⁠性	数理最適化によりRF単調性を満たすスコアを推定するため、推薦理由を説明しやすい
安⁠定⁠し⁠た⁠確⁠率⁠推⁠定	最新度と頻度から商品選択確率を直接推定するため、機械学習モデルの出力を確率スケールへ変換する際の不安定さを回避できる
下⁠流⁠モ⁠デ⁠ル⁠へ⁠の⁠活⁠用	単独の推薦スコアとしてだけでなく、協調フィルタリングの評価値行列や機械学習モデルの特徴量としても利用可能
豊⁠富⁠な⁠診⁠断⁠と⁠可⁠視⁠化	各種統計量の出力や可視化機能が充実。実務家は業務で説明しやすく、研究者は分析報告をしやすい

インストール

pip install rfscorer

使い方

以下は、行動履歴からモデル構築と推薦スコア（商品選択確率）算出までを行う最小限の例です（実行可能な完全版はサンプルを参照）。

最小限の例

import pandas as pd
from rfscorer import RecencyFrequencyScorer, split_by_date

# 行動履歴の読み込み
df = ...  # カラム: user, item, datetime

# 基準日で観測データ・正解データに分割
target_date = "2026-07-07"
df_obs, df_gt = split_by_date(df, target_date, 7, 1) # 観測データ7日間・正解データ1日間

# モデル構築と最適化
scorer = RecencyFrequencyScorer()
scorer.fit(df_obs, df_gt)
scorer.optimize(kind="mono")

# 推薦スコアを算出(テストデータ)
df_test = ...  # テストデータ（カラム: user, item, datetime）
df_test_obs, _ = split_by_date(df_test, target_date, 7, 1)
df_scores = scorer.transform(df_test_obs, target_date, kind="mono")

入力データ（行動履歴）

入力は user・item・datetime の3カラムを持つ行動履歴です。

user	item	datetime
u_001	i_032	2026-07-06
u_001	i_032	2026-07-05
u_001	i_017	2026-07-05
u_002	i_011	2026-07-06
...	...	...

出力データ（推薦スコア）

各 user × item に最新度・頻度・商品選択確率・推薦順位を付与したテーブルを返します。

user	item	recency	frequency	probability	order
u_001	i_032	1	4	0.1167	1
u_001	i_017	2	3	0.0789	2
u_001	i_045	3	1	0.0248	3
u_002	i_011	1	2	0.0621	1
u_002	i_058	4	1	0.0182	2

各ユーザーに対して、商品選択確率（probability ）の高い順に商品を推薦します。推薦スコアが確率値であるため、期待値計算(例：推薦結果に対する期待収益の計算)が容易です。order 列を使えば、業務ルール(例：「各ユーザーに上位2個の商品を推薦する」)を簡単に実装できます。

可視化：最適化手法の比較

本パッケージは多くの最適化アプローチをサポートしています。ここでは代表的な3つの手法を可視化します。

scorer.plot_probability_surface(kind="emp")  # empirical (raw rates)

scorer.optimize(kind="mono")  # RF monotonicity
scorer.plot_probability_surface(kind="mono")

scorer.optimize(kind="mcc")   # convex in R, concave in F
scorer.plot_probability_surface(kind="mcc")

Empirical	Monotonicity	Monotonicity-Convex-Concave

各グラフは、最新度（recency）（ユーザーが商品に接触してからの経過時間）と 頻度（frequency）（接触回数）に基づく商品選択確率の特徴をよく表しています：

• Empirical（経験確率）: 制約を課していない商品選択確率。ノイズにより単調性を満たさないため不自然な順序で商品を推薦する場合がある。
• Monotonicity（単調性）: RF単調性制約を課した商品選択確率。商品を自然な順序で推薦することを保証する。
• Monotonicity-Convex-Concave（単調性＋凸凹）: RF単調性制約と凹凸性制約を課した商品選択確率。最も滑らかなグラフを生成する

サンプル

• examples/tutorial_beginner_ja.ipynb — 初級編では、最小限の利用方法を紹介します。データロード、モデル構築・最適化・可視化、推薦スコア算出、精度評価までのコードを紹介します。
• examples/tutorial_practical_ja.ipynb — 実践編では、主要機能を紹介します。具体的には、時系列での訓練・テスト分割、各種モデル構築と精度比較、モデルの保存・ロードを紹介します。
• examples/tutorial_advanced_fit_rolling_ja.ipynb — 応用編では、fit_rolling() を用いたローリング集計を扱います。複数の基準日にわたって集計することで経験的商品選択確率を安定させる方法を紹介します。

全チュートリアルの一覧は examples/ を参照してください。

APIリファレンス

APIリファレンスを表示

API	説明
split_by_date(df, date, obs, gt)	行動履歴を観測データ・正解データに時系列分割
RecencyFrequencyScorer()	スコアラーを生成
.fit(df_obs, df_gt)	最新度×頻度ごとに経験的な商品選択確率を集計
.fit_rolling(...)	複数の基準日でローリング集計し経験的商品選択確率を安定化
.optimize(kind="mono")	数理最適化で単調性などの制約を満たすスコアを推定
.transform(df_obs, date, kind)	推薦スコア（probability / order）を算出
.predict(r, f, kind)	指定した (recency, frequency) の商品選択確率を返す
.evaluate(df_rec, df_gt)	推薦結果の精度を評価
.plot_probability_surface(kind)	商品選択確率の3D曲面を可視化
.save(path) / .load(path)	モデルの保存・読み込み

参考文献

参考文献を表示

• Jiro Iwanaga, Naoki Nishimura, Noriyoshi Sukegawa, and Yuichi Takano, "Estimating product-choice probabilities from recency and frequency of page views," Knowledge-Based Systems, Volume 99, 2016, Pages 157–167.

• 岩永二郎・石原響太・西村直樹・田中一樹『Pythonではじめる数理最適化 ―ケーススタディでモデリングのスキルを身につけよう―』, オーム社, 2021.

  • 第7章: 商品推薦のための興味のスコアリング

• Jiro Iwanaga, Naoki Nishimura, Noriyoshi Sukegawa, and Yuichi Takano, "Improving collaborative filtering recommendations by estimating user preferences from clickstream data," Electronic Commerce Research and Applications, Volume 37, Article 100877, 2019.

引用について

引用方法と BibTeX を表示

学術論文等で rfscorer を利用する場合は、論文の引用と本Githubへのリンクを脚注を加え、本文中で以下のように引用できます：

We used rfscorer (Iwanaga et al., 2016), a Python library for Recency-Frequency-based recommendation scoring.¹

¹ https://github.com/jiro-iwanaga/rfscorer

参考文献とBibTexは以下のとおりです：

• Jiro Iwanaga, Naoki Nishimura, Noriyoshi Sukegawa, and Yuichi Takano, "Estimating product-choice probabilities from recency and frequency of page views," Knowledge-Based Systems, Volume 99, 2016, Pages 157–167.

@article{Iwanaga2016,
  author  = {Jiro Iwanaga and Naoki Nishimura and Noriyoshi Sukegawa and Yuichi Takano},
  title   = {Estimating product-choice probabilities from recency and frequency of page views},
  journal = {Knowledge-Based Systems},
  volume  = {99},
  pages   = {157--167},
  year    = {2016},
  url     = {https://www.sciencedirect.com/science/article/abs/pii/S0950705116000848}
}

さらに、商品選択確率行列を協調フィルタリングモデルの入力として利用する場合や機械学習の特徴量として利用する場合には、以下の文献も併せて引用してください：

• Jiro Iwanaga, Naoki Nishimura, Noriyoshi Sukegawa, and Yuichi Takano, "Improving collaborative filtering recommendations by estimating user preferences from clickstream data," Electronic Commerce Research and Applications, Volume 37, Article 100877, 2019.

@article{Iwanaga2019,
  author  = {Jiro Iwanaga and Naoki Nishimura and Noriyoshi Sukegawa and Yuichi Takano},
  title   = {Improving collaborative filtering recommendations by estimating user preferences from clickstream data},
  journal = {Electronic Commerce Research and Applications},
  volume  = {37},
  pages   = {100877},
  year    = {2019},
  url     = {https://www.sciencedirect.com/science/article/abs/pii/S1567422319300547}
}

ライセンス

MIT License