usersimcrs.items.ratings

Represents item ratings and provides access either based on items or users.

Ratings are normalized in the [-1,1] range, where -1 corresponds to (strong) dislike, 0 is neutral, and 1 is (strong) like.

Attributes

logger

Classes

Ratings

Initializes a ratings instance.

Functions

user_item_sampler(→ List[str])

Creates a random sample of items for a given user.

Module Contents

usersimcrs.items.ratings.logger
usersimcrs.items.ratings.user_item_sampler(item_ratings: Dict[str, float], historical_ratio: float) → List[str]

Creates a random sample of items for a given user.

Parameters:

  • item_ratings – Item ratings to sample.

  • historical_ratio – Ratio of items ratings to be used as historical data.

Returns:

List of sampled item ids.

class usersimcrs.items.ratings.Ratings(item_collection: usersimcrs.items.item_collection.ItemCollection = None)

Initializes a ratings instance.

Parameters:

item_collection (optional) – If provided, only ratings on items in ItemCollection are accepted.

load_ratings_csv(file_path: str, delimiter: str = ',', min_rating: float = 0.5, max_rating: float = 5.0) → None

Loads ratings from a csv file.

The file is assumed to have userID, itemID, and rating columns (following the MovieLens format). Additional columns that may be present are ignored. UserID and itemID are strings, rating is a float.

Ratings are assumed to be given in the [min_rating, max_rating] range, which gets normalized into the [-1,1] range. (Default min/max rating values are based on the MovieLens collection.)

If an ItemCollection is provided in the constructor, then ratings are filtered to items that are present in the collection.

Parameters:

  • file_path – Path to CSV file.

  • delimiter – Field separator (default: comma).

  • min_rating – Minimum rating (default: 0.5).

  • max_rating – Maximum rating (default: 5.0).

get_user_ratings(user_id: str) → Dict[str, float]

Returns all ratings of a given user.

Parameters:

user_id – User ID.

Returns:

Dictionary with item IDs as keys and ratings as values.

get_item_ratings(item_id: str) → Dict[str, float]

Returns all ratings given to a specific item.

Parameters:

item_id – Item ID.

Returns:

Dictionary with user IDs as keys and ratings as values.

add_user_item_rating(user_id: str, item_id: str, normalized_rating: float) → None

Adds the rating by a given user on a specific item.

Parameters:

  • user_id – User ID.

  • item_id – Item ID.

  • normalized_rating – Normalized rating.

get_user_item_rating(user_id: str, item_id: str) → float | None

Returns the rating by a given user on a specific item.

Parameters:

  • user_id – User ID.

  • item_id – Item ID.

Returns:

Rating as float or None.

get_random_user_id() → str

Returns a random user ID.

Returns:

User ID.

create_split(historical_ratio: float, sampler: Callable = user_item_sampler) → Tuple[Ratings, Ratings]

Splits ratings into historical and ground truth ratings.

Parameters:

  • historical_ratio – Ratio ([0..1]) of ratings to be used as historical data.

  • sampler – Callable performing the sampling of items per user.

Raises:

ValueError – if historical_ratio is not in the interval [0,1].

Returns:

Two Ratings objects, one corresponding to historical and another to ground truth ratings.