README.md

---
license: other
language:
- en
tags:
- recommender-system
- collaborative-filtering
- matrix-factorization
- movielens
- implicit-feedback
- implicit-als
metrics:
- recall
- ndcg
model-index:
- name: ml32m-als128-v1
  results:
  - task:
      type: top-n-recommendation
      name: Top-N recommendation
    dataset:
      name: MovieLens ml-32m
      type: MovieLens
    metrics:
    - type: recall_at_10
      value: 0.08418674438152764
      name: Recall@10
    - type: ndcg_at_10
      value: 0.06680269709374106
      name: NDCG@10
---

# ml32m-als128-v1

This repository contains an implicit-feedback ALS recommender artifact trained from MovieLens ml-32m interactions.

## Model Details

- Model type: implicit ALS
- Factors: 128
- Iterations: 20
- Regularization: 0.05
- Alpha: 40.0
- Users: 200,948
- Movies after filtering: 43,884
- Minimum movie ratings filter: 5
- Training positives: 12,979,522
- Saved user factors: false
- Saved at UTC: 2026-07-02T15:18:10.162757+00:00

## Evaluation

Evaluation metrics were taken from `train/ml-32m-train.ipynb`.

Protocol:

- Held-out relevance: test-set ratings `>= 4.0`.
- Seen-item filtering: movies present in each user's training history were excluded from the ranked list.
- Ranking sample: 10,000 users sampled with seed `0` from 187,278 users with at least one relevant test item.
- Cutoff: `K=10`.

| Model | Recall@10 | NDCG@10 | Users |
| --- | ---: | ---: | ---: |
| ALS implicit | 0.0842 | 0.0668 | 10,000 |
| Popularity baseline | 0.0489 | 0.0430 | 10,000 |
| Explicit MF baseline | 0.0005 | 0.0005 | 10,000 |

The ALS model is optimized for implicit-feedback ranking, so rating-prediction RMSE/MAE is not reported for this artifact.

## Repository Files

- `als_model.npz`: ALS artifact containing saved item factors and training parameters.
- `user_ids.npy`: MovieLens user id mapping aligned to training user indices.
- `movie_ids.npy`: MovieLens movie id mapping aligned to model movie indices.
- `config.json`: Hub-compatible model configuration and artifact metadata.
- `meta.json`: Legacy copy of the model metadata, retained for backwards compatibility.

The saved NPZ contains:

- `item_factors`: shape `(43884, 128)`, `float32`
- `user_factors`: shape `(1, 128)`, `float32`
- scalar ALS parameters including `regularization`, `factors`, `iterations`, `alpha`, and related solver settings

Because full user factors were not saved, this artifact is primarily useful for item/movie factor analysis, item similarity, and workflows that recompute or supply user representations.

## Dataset

The model was trained using MovieLens ml-32m, a GroupLens dataset containing 32,000,204 ratings and 2,000,072 tag applications across 87,585 movies from 200,948 users. The original dataset was generated on October 13, 2023 and contains user activity from January 09, 1995 through October 12, 2023.

MovieLens users are anonymized and no demographic information is included. Ratings use a 0.5 to 5.0 star scale. This model artifact includes model factors and id mappings, not the raw MovieLens CSV files.

## Dataset Source

The raw MovieLens ml-32m dataset is not included in this repository. Download and review the dataset from the official GroupLens sources:

- Official MovieLens 32M page: https://grouplens.org/datasets/movielens/32m/
- MovieLens datasets page: https://grouplens.org/datasets/movielens/
- Dataset README and usage license: https://files.grouplens.org/datasets/movielens/ml-32m-README.html

## Basic Loading Example

```python
import json
from pathlib import Path

import numpy as np
from huggingface_hub import snapshot_download

repo_dir = Path(snapshot_download(repo_id="mskayacioglu/ml32m-als128-v1"))

with (repo_dir / "config.json").open("r", encoding="utf-8") as f:
    config = json.load(f)

movie_ids = np.load(repo_dir / config["mappings"]["movie_ids"])
user_ids = np.load(repo_dir / config["mappings"]["user_ids"])
als = np.load(repo_dir / config["path"])

item_factors = als["item_factors"]
```

Use `movie_ids.npy` to translate between MovieLens movie ids and item factor rows.

## Intended Use

This artifact is intended for research and experimentation with recommender systems, implicit-feedback collaborative filtering, item embeddings, and movie similarity workflows based on MovieLens ml-32m.

## Limitations

- Full user factors are not included in this artifact.
- The model inherits biases, sparsity, temporal coverage, and quality limitations from MovieLens ml-32m.
- MovieLens data is anonymized but still represents historical user interaction behavior.
- The model should not be presented as endorsed by the University of Minnesota or GroupLens.
- Commercial or revenue-bearing use is restricted by the MovieLens data terms below.

## License and Data Terms

This model is derived from MovieLens ml-32m and is distributed under the same MovieLens dataset conditions. Key conditions from the MovieLens usage license:

- Do not state or imply endorsement from the University of Minnesota or the GroupLens Research Group.
- Acknowledge use of the dataset in publications.
- Redistribute the dataset or transformations only under the same license conditions.
- Do not use this information for commercial or revenue-bearing purposes without first obtaining permission from a faculty member of the GroupLens Research Project at the University of Minnesota.
- The dataset and executable scripts are provided as-is, without warranty.

For questions about MovieLens data terms, contact `grouplens-info@umn.edu`.

## Citation

If you use this model or the underlying MovieLens ml-32m dataset in a publication, cite:

Paper DOI: https://doi.org/10.1145/2827872

```bibtex
@article{harper2015movielens,
  title = {The MovieLens Datasets: History and Context},
  author = {Harper, F. Maxwell and Konstan, Joseph A.},
  journal = {ACM Transactions on Interactive Intelligent Systems},
  volume = {5},
  number = {4},
  pages = {19:1--19:19},
  year = {2015},
  doi = {10.1145/2827872}
}
```