---

name: data-features description: "Build LightFM Dataset mappings, sparse interactions, weights, user/item feature matrices, built-in data loads, and cold-start feature inputs." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

LightFM data-features

Use this sub-skill when the task is to turn external user/item ids, interaction records, sample weights, or user/item metadata into LightFM-ready sparse matrices and mappings.

Route map

Need	Go to
Build Dataset mappings, interactions, weights, user/item feature matrices, or cold-start feature rows	This sub-skill; start with API reference and data formats.
Convert tiny local JSONL records without network access	build_lightfm_dataset.py.
Choose loss, learning schedule, regularization, epochs, or LightFM.fit strategy	model-training.
Create train/test splits, compute precision/AUC, or reason about check_intersections	evaluation-splitting.
Build, install, Cythonize, or maintain the repository itself	repo-development.

Short matrix-building workflow

1. Collect the complete user id set, item id set, and stable user/item feature vocabulary needed for the current model run. Namespace metadata labels such as genre:comedy or country:gb so they cannot collide with raw ids.
2. Choose Dataset(user_identity_features=..., item_identity_features=...). Defaults add one identity feature per known user and item; disable the relevant identity flag for true cold-start generalization from metadata only.
3. Call fit(users, items, user_features=None, item_features=None) once to create fresh mappings, or fit_partial(...) only when intentionally extending mappings before model training.
4. Call build_interactions(records) to get (interactions, weights) as aligned COO matrices. Call build_user_features(records) and/or build_item_features(records) when passing explicit feature matrices to LightFM.
5. Check interactions_shape(), user_features_shape(), item_features_shape(), model_dimensions(), and mapping() before handing matrices to training, prediction, or evaluation.
6. Pass the same feature matrices, with the same number and order of feature columns, to every model operation that needs them.

Read next

• API reference for exact methods, return keys, shapes, dtypes, and mapping semantics.
• Data formats for accepted interaction/feature records, built-in dataset dictionaries, custom conversion, and cold-start workflows.
• Troubleshooting for unknown ids/features, normalization failures, feature dimension mismatches, download/cache errors, and identity-feature tradeoffs.