lenskit.knn#

k-NN recommender models.

class lenskit.knn.ItemKNNScorer(config=None, **kwargs)#

Bases: Component[ItemList, …], Trainable

Item-item nearest-neighbor collaborative filtering feedback. This item-item implementation is based on the description of item-based CF by Deshpande and Karypis [DK04] and hard-codes several design decisions found to work well in the previous Java-based LensKit code [ELKR11]. In explicit-feedback mode, its output is equivalent to that of the Java version.

Note

This component must be used with queries containing the user’s history, either directly in the input or by wiring its query input to the output of a user history component (e.g., UserTrainingHistoryLookup).

Stability:

Caller (see Stability Levels).

Parameters:

config (ItemKNNConfig)
kwargs (Any)

items_: Vocabulary#: Vocabulary of item IDs.

item_means_: ndarray[int, dtype[float32]] | None#: Mean rating for each known item.

item_counts_: ndarray[int, dtype[int32]]#: Number of saved neighbors for each item.

sim_matrix_: csr_array#: Similarity matrix (sparse CSR tensor).

users_: Vocabulary#: Vocabulary of user IDs.

train(data, options=TrainingOptions(retrain=True, device=None, rng=None))#

Train a model.

The model-training process depends on save_nbrs and min_sim, but not on other algorithm parameters.

Parameters:

ratings – (user,item,rating) data for computing item similarities.
data (Dataset)
options (TrainingOptions)

class lenskit.knn.ItemKNNConfig(*, max_nbrs=20, min_nbrs=1, min_sim=1e-06, save_nbrs=None, feedback='explicit', block_size=250)#

Bases: BaseModel

Configuration for ItemKNNScorer.

Parameters:

max_nbrs (Annotated[int, Gt(gt=0)])
min_nbrs (Annotated[int, Gt(gt=0)])
min_sim (Annotated[float, Gt(gt=0)])
save_nbrs (Annotated[int, Gt(gt=0)] | None)
feedback (Literal['explicit', 'implicit'])
block_size (int)

max_nbrs: PositiveInt#: The maximum number of neighbors for scoring each item.

min_nbrs: PositiveInt#: The minimum number of neighbors for scoring each item.

min_sim: PositiveFloat#: Minimum similarity threshold for considering a neighbor. Must be positive; if less than the smallest 32-bit normal (\(1.175 \times 10^{-38}\)), is clamped to that value.

save_nbrs: PositiveInt | None#: The number of neighbors to save per item in the trained model (None for unlimited).

feedback: FeedbackType#: The type of input data to use (explicit or implicit). This affects data pre-processing and aggregation.

block_size: int#: The block size for computing item similarity blocks in parallel. Only affects performance, not behavior.

property explicit: bool#: Query whether this is in explicit-feedback mode.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class lenskit.knn.UserKNNScorer(config=None, **kwargs)#

Bases: Component[ItemList, …], Trainable

User-user nearest-neighbor collaborative filtering with ratings. This user-user implementation is not terribly configurable; it hard-codes design decisions found to work well in the previous Java-based LensKit code.

Note

Stability:

Caller (see Stability Levels).

Parameters:

config (UserKNNConfig)
kwargs (Any)

users_: Vocabulary#: The index of user IDs.

items_: Vocabulary#: The index of item IDs.

user_means_: Tensor | None#: Mean rating for each known user.

user_vectors_: Tensor#: Normalized rating matrix (CSR) to find neighbors at prediction time.

user_ratings_: csc_array#: Centered but un-normalized rating matrix (COO) to find neighbor ratings.

train(data, options=TrainingOptions(retrain=True, device=None, rng=None))#

“Train” a user-user CF model. This memorizes the rating data in a format that is usable for future computations.

Parameters:

ratings (pandas.DataFrame) – (user, item, rating) data for collaborative filtering.
data (Dataset)
options (TrainingOptions)

class lenskit.knn.UserKNNConfig(*, max_nbrs=20, min_nbrs=1, min_sim=1e-06, feedback='explicit')#

Bases: BaseModel

Configuration for ItemKNNScorer.

Parameters:

max_nbrs (Annotated[int, Gt(gt=0)])
min_nbrs (Annotated[int, Gt(gt=0)])
min_sim (Annotated[float, Gt(gt=0)])
feedback (Literal['explicit', 'implicit'])

max_nbrs: PositiveInt#: The maximum number of neighbors for scoring each item.

min_nbrs: PositiveInt#: The minimum number of neighbors for scoring each item.

min_sim: PositiveFloat#: Minimum similarity threshold for considering a neighbor. Must be positive; if less than the smallest 32-bit normal (\(1.175 \times 10^{-38}\)), is clamped to that value.

feedback: FeedbackType#: The type of input data to use (explicit or implicit). This affects data pre-processing and aggregation.

property explicit: bool#: Query whether this is in explicit-feedback mode.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Modules

`item`	Item-based k-NN collaborative filtering.
`user`	User-based k-NN collaborative filtering.