recnexteval 0.1.0__py3-none-any.whl

recnexteval/datasets/config/amazon.py

@@ -0,0 +1,188 @@
+from dataclasses import dataclass
+
+from .base import DatasetConfig, MetadataConfig
+
+
+@dataclass
+class AmazonDatasetConfig(DatasetConfig):
+    """Amazon dataset base configuration."""
+
+    user_ix: str = "user_id"
+    item_ix: str = "parent_asin"
+    timestamp_ix: str = "timestamp"
+    rating_ix: str = "rating"
+    helpful_vote_ix: str = "helpful_vote"
+    dataset_url: str = ""  # Set per subclass
+    remote_filename: str = ""  # Set per subclass
+    default_base_path: str = DatasetConfig.default_base_path + "/amazon"
+
+    @property
+    def default_filename(self) -> str:
+        """Return just the filename for Amazon datasets (no zipname prefix)."""
+        return self.remote_filename
+
+
+@dataclass
+class AmazonMusicDatasetConfig(AmazonDatasetConfig):
+    """Amazon Music dataset configuration."""
+
+    remote_filename: str = "Digital_Music.jsonl.gz"
+    dataset_url: str = "https://mcauleylab.ucsd.edu/public_datasets/data/amazon_2023/raw/review_categories/Digital_Music.jsonl.gz"
+
+
+@dataclass
+class AmazonMovieDatasetConfig(AmazonDatasetConfig):
+    """Amazon Movie dataset configuration."""
+
+    remote_filename: str = "Movies_and_TV.jsonl.gz"
+    dataset_url: str = "https://mcauleylab.ucsd.edu/public_datasets/data/amazon_2023/raw/review_categories/Movies_and_TV.jsonl.gz"
+
+
+@dataclass
+class AmazonSubscriptionBoxesDatasetConfig(AmazonDatasetConfig):
+    """Amazon Subscription Boxes dataset configuration."""
+
+    remote_filename: str = "Subscription_Boxes.jsonl.gz"
+    dataset_url: str = "https://mcauleylab.ucsd.edu/public_datasets/data/amazon_2023/raw/review_categories/Subscription_Boxes.jsonl.gz"
+
+
+@dataclass
+class AmazonBookDatasetConfig(AmazonDatasetConfig):
+    """Amazon Books dataset configuration."""
+
+    remote_filename: str = "Books.jsonl.gz"
+    dataset_url: str = "https://mcauleylab.ucsd.edu/public_datasets/data/amazon_2023/raw/review_categories/Books.jsonl.gz"
+
+
+@dataclass
+class AmazonItemMetadataConfig(MetadataConfig, AmazonDatasetConfig):
+    """
+    Amazon Item Metadata Base Configuration.
+
+    Handles configuration for Amazon product metadata including:
+    - Product identifiers (ASIN)
+    - Product information (title, category, price, rating)
+    - Rich content (features, description, images, videos)
+    - Relational data (store, details, bought together)
+
+    All properties are computed from base fields to ensure consistency.
+    """
+
+    item_ix: str = "parent_asin"
+    """Name of the column containing product identifiers (parent ASIN)."""
+    main_category_ix: str = "main_category"
+    """Name of the column containing the main product category."""
+    title_ix: str = "title"
+    """Name of the column containing product title."""
+    average_rating_ix: str = "average_rating"
+    """Name of the column containing average product rating (0-5)."""
+    rating_number_ix: str = "rating_number"
+    """Name of the column containing number of ratings received."""
+    features_ix: str = "features"
+    """Name of the column containing product features (list)."""
+    description_ix: str = "description"
+    """Name of the column containing product description (list)."""
+    price_ix: str = "price"
+    """Name of the column containing product price."""
+    images_ix: str = "images"
+    """Name of the column containing product images URLs (list)."""
+    videos_ix: str = "videos"
+    """Name of the column containing product videos URLs (list)."""
+    store_ix: str = "store"
+    """Name of the column containing store/seller information."""
+    categories_ix: str = "categories"
+    """Name of the column containing category hierarchy (list)."""
+    details_ix: str = "details"
+    """Name of the column containing product details (dict)."""
+    bought_together_ix: str = "bought_together"
+    """Name of the column containing products bought together (list)."""
+
+    @property
+    def column_names(self) -> list[str]:
+        return [
+            self.main_category_ix,
+            self.title_ix,
+            self.average_rating_ix,
+            self.rating_number_ix,
+            self.features_ix,
+            self.description_ix,
+            self.price_ix,
+            self.images_ix,
+            self.videos_ix,
+            self.store_ix,
+            self.categories_ix,
+            self.details_ix,
+            self.item_ix,
+            self.bought_together_ix,
+        ]
+
+    @property
+    def dtype_dict(self) -> dict:
+        return {
+            self.main_category_ix: str,
+            self.title_ix: str,
+            self.average_rating_ix: "float32",
+            self.rating_number_ix: "int64",
+            self.features_ix: list,
+            self.description_ix: list,
+            self.price_ix: "float32",
+            self.images_ix: list,
+            self.videos_ix: list,
+            self.store_ix: str,
+            self.categories_ix: list,
+            self.details_ix: dict,
+            self.item_ix: str,
+            self.bought_together_ix: list,
+        }
+
+
+@dataclass
+class AmazonDigitalMusicItemMetadataConfig(AmazonItemMetadataConfig):
+    """Amazon Digital Music metadata configuration."""
+
+    remote_filename: str = "meta_Digital_Music.jsonl.gz"
+    """Filename for Digital Music metadata."""
+
+    dataset_url: str = (
+        "https://mcauleylab.ucsd.edu/public_datasets/data/amazon_2023/"
+        "raw/meta_categories/meta_Digital_Music.jsonl.gz"
+    )
+
+
+@dataclass
+class AmazonMoviesAndTVItemMetadataConfig(AmazonItemMetadataConfig):
+    """Amazon Movies and TV metadata configuration."""
+
+    remote_filename: str = "meta_Movies_and_TV.jsonl.gz"
+    """Filename for Movies and TV metadata."""
+
+    dataset_url: str = (
+        "https://mcauleylab.ucsd.edu/public_datasets/data/amazon_2023/"
+        "raw/meta_categories/meta_Movies_and_TV.jsonl.gz"
+    )
+
+
+@dataclass
+class AmazonSubscriptionBoxesItemMetadataConfig(AmazonItemMetadataConfig):
+    """Amazon Subscription Boxes metadata configuration."""
+
+    remote_filename: str = "meta_Subscription_Boxes.jsonl.gz"
+    """Filename for Subscription Boxes metadata."""
+
+    dataset_url: str = (
+        "https://mcauleylab.ucsd.edu/public_datasets/data/amazon_2023/"
+        "raw/meta_categories/meta_Subscription_Boxes.jsonl.gz"
+    )
+
+
+@dataclass
+class AmazonBooksItemMetadataConfig(AmazonItemMetadataConfig):
+    """Amazon Books metadata configuration."""
+
+    remote_filename: str = "meta_Books.jsonl.gz"
+    """Filename for Books metadata."""
+
+    dataset_url: str = (
+        "https://mcauleylab.ucsd.edu/public_datasets/data/amazon_2023/"
+        "raw/meta_categories/meta_Books.jsonl.gz"
+    )

recnexteval/datasets/config/base.py

@@ -0,0 +1,72 @@
+from dataclasses import dataclass
+
+from recnexteval.utils import get_data_dir
+
+
+@dataclass
+class DatasetConfig:
+    """Base configuration for datasets."""
+
+    user_ix: str = "user_id"
+    """Name of the column in the DataFrame with user identifiers"""
+    item_ix: str = "item_id"
+    """Name of the column in the DataFrame with item identifiers"""
+    timestamp_ix: str = "timestamp"
+    """Name of the column in the DataFrame that contains time of interaction in seconds since epoch."""
+    dataset_url: str = "http://example.com"
+    """URL to fetch the dataset from."""
+    default_base_path: str = str(get_data_dir())
+    """Default base path where the dataset will be stored."""
+    remote_zipname: str = ""
+    remote_filename: str = ""
+    """Name of the file containing user interaction."""
+
+    @property
+    def default_filename(self) -> str:
+        """Derived filename from remote components."""
+        if not self.remote_zipname or not self.remote_filename:
+            return "dataset.csv"
+        return f"{self.remote_zipname}_{self.remote_filename}"
+
+
+@dataclass
+class MetadataConfig(DatasetConfig):
+    sep: str = "|"
+    """Column separator in the data file."""
+
+    def __post_init__(self) -> None:
+        self.default_base_path = super().default_base_path + "/metadata"
+
+    @property
+    def column_names(self) -> list[str]:
+        """
+        Ordered list of column names for pd.read_table.
+
+        Returns:
+            list[str]: Column names in file order [user_id, age, gender, ...]
+
+        Example:
+            ["userId", "age", "gender", "occupation", "zipcode"]
+        """
+        return []
+
+    @property
+    def dtype_dict(self) -> dict:
+        """
+        Data type mapping for all columns.
+
+        Used in pd.read_table() dtype parameter to ensure correct
+        column types are loaded from file.
+
+        Returns:
+            dict: Mapping of column names to numpy dtypes
+
+        Example:
+            {
+                "age": "int64",
+                "gender": "<U1",  # string
+                "occupation": "object",
+                "zipcode": "object"
+            }
+        """
+        return {}

recnexteval/datasets/config/lastfm.py

@@ -0,0 +1,105 @@
+from dataclasses import dataclass
+
+from .base import DatasetConfig, MetadataConfig
+
+
+@dataclass
+class LastFMDatasetConfig(DatasetConfig):
+    """LastFM dataset configuration."""
+
+    user_ix: str = "userID"
+    item_ix: str = "artistID"
+    timestamp_ix: str = "timestamp"
+    tag_ix: str = "tagID"
+    """Name of the column in the DataFrame that contains the tag a user gave to the item."""
+    dataset_url: str = "https://files.grouplens.org/datasets/hetrec2011"
+    remote_zipname: str = "hetrec2011-lastfm-2k"
+    remote_filename: str = "user_taggedartists-timestamps.dat"
+    default_base_path: str = DatasetConfig.default_base_path + "/lastfm"
+
+
+@dataclass
+class LastFMUserMetadataConfig(MetadataConfig, LastFMDatasetConfig):
+    """LastFM User Metadata Configuration."""
+
+    user_ix: str = "userID"
+    """Name of the column containing user identifiers."""
+    friend_ix: str = "friendID"
+    """Name of the column containing friend identifiers."""
+
+    remote_filename: str = "user_friends.dat"
+    remote_zipname: str = "hetrec2011-lastfm-2k"
+    dataset_url: str = "https://files.grouplens.org/datasets/hetrec2011"
+    sep: str = "\t"
+
+    @property
+    def column_names(self) -> list[str]:
+        return [
+            self.user_ix,
+            self.friend_ix,
+        ]
+
+
+@dataclass
+class LastFMItemMetadataConfig(MetadataConfig, LastFMDatasetConfig):
+    """LastFM Item Metadata Configuration."""
+
+    item_ix: str = "id"
+    """Name of the column containing item identifiers."""
+    name_ix: str = "name"
+    """Name of the column containing item names."""
+    url_ix: str = "url"
+    """Name of the column containing item URLs."""
+    picture_url_ix: str = "pictureURL"
+    """Name of the column containing item picture URLs."""
+
+    remote_filename: str = "artists.dat"
+    remote_zipname: str = "hetrec2011-lastfm-2k"
+    dataset_url: str = "https://files.grouplens.org/datasets/hetrec2011"
+    sep: str = "\t"
+
+    @property
+    def column_names(self) -> list[str]:
+        return [
+            self.item_ix,
+            self.name_ix,
+            self.url_ix,
+            self.picture_url_ix,
+        ]
+
+    @property
+    def dtype_dict(self) -> dict:
+        return {
+            self.name_ix: str,
+            self.url_ix: str,
+            self.picture_url_ix: str,
+        }
+
+
+@dataclass
+class LastFMTagMetadataConfig(MetadataConfig, LastFMDatasetConfig):
+    """LastFM Tag Metadata Configuration."""
+
+    tag_ix: str = "tagID"
+    """Name of the column containing tag identifiers."""
+    name_ix: str = "tagValue"
+    """Name of the column containing tag names."""
+
+    remote_filename: str = "tags.dat"
+    remote_zipname: str = "hetrec2011-lastfm-2k"
+    dataset_url: str = "https://files.grouplens.org/datasets/hetrec2011"
+    sep: str = "\t"
+
+    @property
+    def column_names(self) -> list[str]:
+        return [
+            self.tag_ix,
+            self.name_ix,
+        ]
+
+    @property
+    def dtype_dict(self) -> dict:
+        return {
+            self.tag_ix: str,
+            self.name_ix: str,
+        }

recnexteval/datasets/config/movielens.py

@@ -0,0 +1,169 @@
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from .base import DatasetConfig, MetadataConfig
+
+
+@dataclass
+class MovieLensDatasetConfig(DatasetConfig):
+    """MovieLens base configuration."""
+
+    user_ix: str = "userId"
+    item_ix: str = "movieId"
+    timestamp_ix: str = "timestamp"
+    rating_ix: str = "rating"
+    """Name of the column in the DataFrame that contains the rating a user gave to the item."""
+    dataset_url: str = "https://files.grouplens.org/datasets/movielens"
+    remote_zipname: str = "ml-100k"
+    """Name of the zip-file on the MovieLens server."""
+    remote_filename: str = "ratings.csv"
+    """Name of the file containing user ratings on the MovieLens server."""
+    default_base_path: str = DatasetConfig.default_base_path + "/movielens"
+
+
+@dataclass
+class MovieLens100KDatasetConfig(MovieLensDatasetConfig):
+    """MovieLens 100K specific configuration."""
+
+    remote_filename: str = "u.data"
+
+
+@dataclass
+class MovieLens100kUserMetadataConfig(MetadataConfig, MovieLensDatasetConfig):
+    """
+    MovieLens 100K User Metadata Configuration.
+
+    Handles configuration for user demographic data:
+    - User ID mapping
+    - Age information
+    - Gender information
+    - Occupation information
+    - Zipcode information
+
+    All properties are computed from base fields to ensure consistency.
+    """
+    user_ix: str = "userId"
+    """Name of the column containing user identifiers."""
+    age_ix: str = "age"
+    """Name of the column containing user age."""
+    gender_ix: str = "gender"
+    """Name of the column containing user gender."""
+    occupation_ix: str = "occupation"
+    """Name of the column containing user occupation."""
+    zipcode_ix: str = "zipcode"
+    """Name of the column containing user zipcode."""
+
+    remote_filename: str = "u.user"
+    """Filename of user metadata file in remote zip."""
+    remote_zipname: str = "ml-100k"
+    """Name of the zip file on remote server."""
+    dataset_url: str = "https://files.grouplens.org/datasets/movielens"
+    """URL to fetch the metadata from."""
+
+    @property
+    def column_names(self) -> list[str]:
+        return [
+            self.user_ix,
+            self.age_ix,
+            self.gender_ix,
+            self.occupation_ix,
+            self.zipcode_ix,
+        ]
+
+    @property
+    def dtype_dict(self) -> dict:
+        return {
+            self.age_ix: np.int64,
+            self.gender_ix: str,
+            self.occupation_ix: str,
+            self.zipcode_ix: str,
+        }
+
+
+@dataclass
+class MovieLens100kItemMetadataConfig(MetadataConfig, MovieLensDatasetConfig):
+    """
+    MovieLens 100K Item Metadata Configuration.
+
+    Handles configuration for movie metadata including:
+    - Movie ID mapping
+    - Title, release date, IMDB URL
+    - 19 binary genre indicator columns
+
+    All properties are computed from base fields to ensure consistency.
+    """
+
+    item_ix: str = "movieId"
+    """Name of the column containing movie identifiers."""
+    title_ix: str = "title"
+    """Name of the column containing movie title."""
+    release_date_ix: str = "releaseDate"
+    """Name of the column containing movie release date."""
+    video_release_date_ix: str = "videoReleaseDate"
+    """Name of the column containing video release date."""
+    imdb_url_ix: str = "imdbUrl"
+    """Name of the column containing IMDB URL."""
+    genres: tuple[str, ...] = (
+        "unknown",
+        "action",
+        "adventure",
+        "animation",
+        "children",
+        "comedy",
+        "crime",
+        "documentary",
+        "drama",
+        "fantasy",
+        "filmNoir",
+        "horror",
+        "musical",
+        "mystery",
+        "romance",
+        "sciFi",
+        "thriller",
+        "war",
+        "western",
+    )
+    """Tuple of 19 genre names in canonical order."""
+
+    remote_filename: str = "u.item"
+    remote_zipname: str = "ml-100k"
+    dataset_url: str = "https://files.grouplens.org/datasets/movielens"
+    encoding: str = "ISO-8859-1"
+    """File encoding (ISO-8859-1 needed for special characters)."""
+
+    @property
+    def non_genre_columns(self) -> list[str]:
+        """
+        Column names for non-genre metadata.
+
+        Returns:
+            list[str]: [movie_id, title, release_date, video_release_date, imdb_url]
+
+        Example:
+            ["movieId", "title", "releaseDate", "videoReleaseDate", "imdbUrl"]
+        """
+        return [
+            self.item_ix,
+            self.title_ix,
+            self.release_date_ix,
+            self.video_release_date_ix,
+            self.imdb_url_ix,
+        ]
+
+    @property
+    def column_names(self) -> list[str]:
+        return self.non_genre_columns + list(self.genres)
+
+    @property
+    def dtype_dict(self) -> dict:
+        dtype_dict: dict[str, Any] = {
+            self.title_ix: str,
+            self.release_date_ix: str,
+            self.video_release_date_ix: str,
+            self.imdb_url_ix: str,
+        }
+        dtype_dict.update({genre: np.int64 for genre in self.genres})
+        return dtype_dict

recnexteval/datasets/config/yelp.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+
+from .base import DatasetConfig
+
+
+@dataclass
+class YelpDatasetConfig(DatasetConfig):
+    """Yelp dataset configuration.
+
+    Note: Yelp dataset must be manually downloaded from https://www.yelp.com/dataset/download
+    as it requires acceptance of a license agreement. The dataset should be converted
+    from JSON to CSV and placed in the data directory.
+    """
+
+    user_ix: str = "user_id"
+    item_ix: str = "business_id"
+    timestamp_ix: str = "date"
+    rating_ix: str = "stars"
+    dataset_url: str = "https://www.yelp.com/dataset/download"
+    remote_filename: str = "yelp_academic_dataset_review.csv"
+
+    @property
+    def default_filename(self) -> str:
+        """Return the default filename for Yelp dataset."""
+        return self.remote_filename

recnexteval/datasets/datasets/__init__.py

@@ -0,0 +1,24 @@
+from .amazon import (
+    AmazonBookDataset,
+    AmazonMovieDataset,
+    AmazonMusicDataset,
+    AmazonSubscriptionBoxesDataset,
+)
+from .base import Dataset
+from .lastfm import LastFMDataset
+from .movielens import MovieLens100K
+from .test import TestDataset
+from .yelp import YelpDataset
+
+
+__all__ = [
+    "AmazonBookDataset",
+    "AmazonMovieDataset",
+    "AmazonMusicDataset",
+    "AmazonSubscriptionBoxesDataset",
+    "LastFMDataset",
+    "MovieLens100K",
+    "YelpDataset",
+    "TestDataset",
+    "Dataset",
+]