Quick Reference · explicit-rating recommenders · scikit-learn-style API

Surprise cheat sheet

A scikit-learn for recommenders. Load ratings into a Dataset, pick one of a dozen Algorithms, and the same fit → test → predict loop and cross-validation tooling works for every one of them. One caveat to hold onto: Surprise handles explicit ratings only — no implicit feedback, no content features.

data & I/O algorithms fit / predict evaluate / search options / params gotcha ★ most common

Distilled & cross-checked across: surprise.readthedocs.io · github.com/NicolasHug/Surprise · surpriselib.com · PyPI scikit-surprise · Koren 2010 (baseline estimates)

The workflow — from a ratings table to scored predictions
cross_validate() · GridSearchCV() Dataset Reader + ratings load_from_df / builtin user · item · rating Split train_test_split KFold iterator trainset + testset Algorithm SVD · KNN · NMF .fit(trainset) learns r̂ₕᵢ Predictions & score .test(testset) → list accuracy.rmse / mae (uid, iid, r_ui, est, ...) split fit test deploy → build_full_trainset · predict(uid, iid) build_anti_testset · top-N ranking INPUT OUTPUT
01Install & Importonce per env
02Load Your DataReader + Dataset
0330-Second Workflowthe whole loop
04Pick an Algorithmthe built-in zoo
05Matrix FactorizationSVD · SVD++ · NMF
06k-NN Neighborhoodsimilar users/items
07Baseline & Simplestrong floors
08Fit / Test / Predictthe three verbs
09Split & Cross-Validatescikit-learn-style
10Grid & Random Searchtune params
11Accuracy Metricson predictions
12Similarity Optionssim_options dict
13Baseline Optionsbsl_options dict
14Top-N Recommendationsthe ranking recipe
15Persist & Inspectdump + Trainset
16Gotchasread before you fit
★Prediction anatomywhat test() returns

How the pieces fit

Four views of the same library: the three core verbs, the algorithm family, the one toggle that reshapes k-NN, and the trick for turning a rating predictor into a top-N ranker.

fit · test · predict

Three verbs, three shapes of input and output. Everything else in Surprise is built on these.

trainset all ratings fit trained algo testset [(u,i), ...] test [Prediction, Prediction, ...] one (u, i) raw ids predict one Prediction .est = r̂ₕᵢ

Algorithm family

Every algorithm subclasses AlgoBase, so they're interchangeable. They fall into four camps.

AlgoBase baseline NormalPredictor BaselineOnly neighborhood KNNBasic KNNWithMeans KNNWithZScore KNNBaseline factorization SVD SVD++ NMF other SlopeOne CoClustering green = the strong default in its group

user-based vs item-based

One flag in sim_options decides whether neighbors are similar users (rows) or similar items (columns).

user_based=True user_based=False rows = users "find similar users" columns = items "find similar items" same data, opposite axis — and very different speed/accuracy

Top-N via anti-testset

Surprise predicts ratings, not rankings. The blanks a user hasn't rated become the anti-testset you score and sort.

one user's row 5 3 green = rated (trainset) white = blanks (anti-testset) test 4.6 4.9 2.1 predicted est for blanks sort by est per user → keep top-N no built-in ranker — a short DIY helper rating prediction → recommendation list

Worth memorizing

fit ≠ testfit trains on a Trainset; test scores a list of pairs
raw vs inner idspredict() takes raw ids — the strings from your file
explicit onlyno implicit feedback, no content features
GridSearchCV(SVD)pass the class, not an instance SVD()
SVD ≠ sklearn SVDit's Funk MF; biased=False gives PMF
user_based flips costitem-based is often faster & more accurate
KNNBaseline > KNNBasicbaseline-corrected neighbors win
build_anti_testsetthe blanks → test() → sort → top-N