cmfrec Cheat Sheet

01Install & Importonce per env

pip install cmfrec★
Ships both float32 & float64 builds; needs a C compiler.
pip install --no-use-pep517 cmfrec
Fallback if the standard build fails.
from cmfrec import CMF, CMF_implicit★
The two workhorse classes.
export DONT_SET_MARCH=1
Portable wheel: drop -march=native before install.
brew install libomp
macOS: enable multi-threading, then reinstall.

02Pick a Model7 classes, one idea

CMF★
Explicit ratings (1–5). Most flexible; add U/I side info.
CMF_implicit★
Implicit clicks/plays. Weighted-binary; no biases.
ContentBased
Pure content model — factors are a direct map of attributes.
OMF_explicit / OMF_implicit
Offsets model: attributes + a free offset. Better cold-start.
MostPopular
Non-personalized baseline (biases only). Sanity benchmark.
CMF_imputer / CMF_embedder
scikit-learn subclasses for imputation / embeddings.

03Prepare Your Datashapes & missing

X = df["UserId","ItemId","Rating"]★
Explicit long-format table; IDs may be strings.
X = df["UserId","ItemId","Value"]
Implicit uses a Value column (counts/weights).
X = scipy.sparse.coo_matrix(...)
Fastest input; skips internal reindexing.
U, I = user_df, item_df
Side info; carry a UserId/ItemId column if X is a DF.
arr[i, j] = np.nan
Dense inputs: unobserved entries must be NaN.
W = weights
Optional per-observation weights (explicit models).

04Fit the Modellearn A,B,C,D

05Predict & Scorerating for a pair

m.predict(user=[3,3], item=[2,4])★
Existing user/item, element-wise pairs.
m.predict_warm(items, X_col=, X_val=)
Warm: new user defined by fresh ratings.
m.predict_cold(items, U=u)
Cold: new user from attributes only, no X.
m.predict_new(user, I=i)
New items scored from item attributes.
m.predict_warm_multiple(X, item)
Batch version across many new users.

06Top-N Recommendationsranked lists

m.topN(user=3, n=10)★
Best n items for an existing user.
m.topN_warm(n=, X_col=, X_val=)★
Rank for a new user from their new ratings.
m.topN_cold(n=, U=u)
Rank for a new user from attributes alone.
m.topN_new(user, I=i, n=)
Rank a set of brand-new items for a user.
m.topN(3, exclude=seen, output_score=True)
Drop already-seen items; also return scores.
m.topN(3, include=candidates)
Rank only within a candidate shortlist.

07Latent Factorsembed new rows

m.factors_warm(X_col=, X_val=)
Factor vector for a new user from ratings.
m.factors_cold(U=u)
Factor vector from attributes only.
m.factors_multiple(X=, U=)
Batch factors for many rows at once.
m.factors_warm(..., return_bias=True)
Also hand back the estimated user bias.
m.item_factors_cold(I=i)slow
Item factors are un-precomputed — prefer swapping.

08Core Hyperparameterstune these first

09Implicit-Feedback KnobsCMF_implicit

alpha=1.0★
Confidence weight on positives: W = 1 + alpha·X.
lambda_=1.0
Higher default than explicit; e.g. ~5 for LastFM-360K.
w_user=10., w_item=10.
Up-weight side info — X's dense zeros dominate otherwise.
apply_log_transf=True
Log-scale raw counts before fitting.
from recometrics import ...
Companion lib for P@K / MAP / hit-rate metrics.

10Shared vs Split Factorsthe collective trick

11Advanced Optionsreshape the objective

scale_lam=True
Per-row regularization — then use a much smaller lambda_ (~0.05).
add_implicit_features=True
Free implicit signal from the same X; helps small data.
nonneg=True
NMF-style non-negative factors (turn off centering).
NA_as_zero=True
Treat sparse missing as 0 — for dim-reduction / speed.
l1_lambda=0.0
L1 sparsity (coordinate descent — slower).
use_float=True
float32: faster & leaner, less precise.

12Impute & Pipelinesbeyond recsys

m.transform(X)
Reconstruct all missing entries of X (imputation).
CMF_imputer()
Drop-in scikit-learn imputer step.
CMF_embedder()
Emit the A-factors as features for a Pipeline.
m.user_mapping_, m.item_mapping_
Internal↔original ID maps (DataFrame inputs).
m.get_params() / m.set_params()
sklearn-compatible — set_params resets the fit.

13Production & Servingship it lean

m.drop_nonessential_matrices()
Shrink for serving; keeps factors_* / topN_*.
m.swap_users_and_items()★
Make item-side ops (item cold-start) fast.
CMF.from_model_matrices(A, B)
Wrap externally-trained factors into a cmfrec model.
precompute_for_predictions=False
Faster/leaner fit; recompute later on demand.
# ANN over A · B
For big catalogs, serve top-N via hnsw / Milvus.

14Gotchasread before you fit

df = df.copy()mutates
fit reindexes input in place — copy first.
CMF on click datawrong
Use CMF_implicit for implicit feedback & P@K.
lambda_ like other libsoff-scale
cmfrec's lambda_ is absolute — often 10–100× larger.
U_bin with method="als"n/a
Binary side info + sigmoid need method="lbfgs".
topN on huge catalogfull scan
topN scores every item — use ANN in production.

★warm · cold · newthe naming key

cmfrec cheat sheet