Datasets API

See Datasets for each dataset’s metadata, precomputed feature availability, timestamps, sources, and checkpoint examples. Dataset citations are listed in Datasets.

class compresso_recsys.datasets.RecSysDataset(data_dir='data')[source]

Thin base class for interaction datasets used in example pipelines.

Canonical interactions schema: - user_id: str - item_id: str - value: float - timestamp: int | float | None

Parameters:

data_dir (str | Path)

static preprocess_interactions_for_recsys(df, *, min_value_to_keep=4.0, user_min_support=5, item_min_support=1, set_all_values_to=1.0, max_steps=0)[source]

Paper-style preprocessing: threshold, binarize, iterative pruning, categorical cleanup.

Return type:

DataFrame

Parameters:

  • df (DataFrame)

  • min_value_to_keep (float | None)

  • user_min_support (int)

  • item_min_support (int)

  • set_all_values_to (float | None)

  • max_steps (int)

to_hf_dataset(df=None)[source]

Convert interactions to HuggingFace Dataset.

Import is optional so core library does not hard-depend on datasets.

Parameters:

df (DataFrame | None)

static to_sparse_matrix(df)[source]

Return (X, user_ids, item_ids) where X is user x item CSR.

Parameters:

df (DataFrame)

class compresso_recsys.datasets.SplitBundle(train, val, test)[source]
Parameters:

  • train (DataFrame)

  • val (DataFrame)

  • test (DataFrame)

class compresso_recsys.datasets.MovieLens1M(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0)[source]
Parameters:

  • data_dir (str)

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

class compresso_recsys.datasets.MovieLens20M(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0)[source]
Parameters:

  • data_dir (str)

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

class compresso_recsys.datasets.Goodbooks(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0)[source]
Parameters:

  • data_dir (str)

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

class compresso_recsys.datasets.AmazonReviews2023(data_dir='data', *, category='Toys_and_Games', metadata_text_fields=None, min_entity_text_words=0, include_image_urls=False, show_progress=True)[source]

Amazon Reviews 2023 category dataset loaded from McAuley’s files.

The recommender pipeline only needs compact rating-only interactions plus item metadata. Reviews are intentionally not downloaded.

Parameters:

  • data_dir (str)

  • category (str)

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

  • include_image_urls (bool)

  • show_progress (bool)

load_source_dataframe(config, *, split='full')

Load a McAuley Amazon 2023 config into a DataFrame.

Kept under its historical name for compatibility with tests and subclasses, but this no longer uses Hugging Face datasets. Recent datasets releases reject repositories that still expose loading scripts, so we read direct Hugging Face/McAuley data files instead.

Return type:

DataFrame

Parameters:

  • config (str)

  • split (str)

load_timestamp_splits_with_history()[source]

Load McAuley’s timestamp split with per-row history fields.

Return type:

dict[str, DataFrame]

class compresso_recsys.datasets.Steam(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0, show_progress=True)[source]

Raw McAuley Steam reviews with original product IDs and game metadata.

Every review is an interaction, including negative reviews (BERT4Rec’s convention). Dates have day precision; equal dates retain source order. Metadata does not have to exist for every reviewed game.

Parameters:

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

  • show_progress (bool)

class compresso_recsys.datasets.NetflixPrize(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0, show_progress=True)[source]

Netflix Prize ratings with dates, movie titles and release years.

Downloads the original-format archive from Internet Archive. No Kaggle dependency. Original Netflix terms apply; Compresso does not redistribute it.

Parameters:

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

  • show_progress (bool)

class compresso_recsys.datasets.TasteProfile(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0, show_progress=True)[source]

MSD Taste Profile triplets: play counts, no timestamps or item text.

The original source currently serves this archive over HTTP. Additional MSD metadata and mismatch lists are not part of this interaction adapter.

Parameters:

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

  • show_progress (bool)

timestamp_precision = None
class compresso_recsys.datasets.Gowalla(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0, show_progress=True)[source]

Raw SNAP check-ins with timestamps and location coordinates.

Repeated check-ins are retained. This is not the remapped LightGCN split. Coordinates are taken from the first source occurrence of each location. The social graph is not required or downloaded.

Parameters:

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

  • show_progress (bool)

class compresso_recsys.datasets.DBbook(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0, show_progress=True)[source]

DBbook binary feedback; retains the upstream train/test label per row.

Parameters:

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

  • show_progress (bool)

timestamp_precision = None
get_official_split()[source]

Return the supplied train/test frames without merging or resplitting.

class compresso_recsys.datasets.LastFM2K(data_dir='data', *, metadata_text_fields=None, min_entity_text_words=0, show_progress=True)[source]

Artist listening counts; tagging dates are not listening timestamps.

Parameters:

  • metadata_text_fields (Iterable[str] | None)

  • min_entity_text_words (int)

  • show_progress (bool)

timestamp_precision = None