"""This module contains the Reader class."""
from .builtin_datasets import BUILTIN_DATASETS
[docs]class Reader:
"""The Reader class is used to parse a file containing ratings.
Such a file is assumed to specify only one rating per line, and each line
needs to respect the following structure: ::
user ; item ; rating ; [timestamp]
where the order of the fields and the separator (here ';') may be
arbitrarily defined (see below). brackets indicate that the timestamp
field is optional.
For each built-in dataset, Surprise also provides predefined readers which
are useful if you want to use a custom dataset that has the same format as
a built-in one (see the ``name`` parameter).
Args:
name(:obj:`string`, optional): If specified, a Reader for one of the
built-in datasets is returned and any other parameter is ignored.
Accepted values are 'ml-100k', 'ml-1m', and 'jester'. Default
is ``None``.
line_format(:obj:`string`): The fields names, in the order at which
they are encountered on a line. Please note that ``line_format`` is
always space-separated (use the ``sep`` parameter). Default is
``'user item rating'``.
sep(char): the separator between fields. Example : ``';'``.
rating_scale(:obj:`tuple`, optional): The rating scale used for every
rating. Default is ``(1, 5)``.
skip_lines(:obj:`int`, optional): Number of lines to skip at the
beginning of the file. Default is ``0``.
"""
def __init__(
self,
name=None,
line_format="user item rating",
sep=None,
rating_scale=(1, 5),
skip_lines=0,
):
if name:
try:
self.__init__(**BUILTIN_DATASETS[name].reader_params)
except KeyError:
raise ValueError(
"unknown reader "
+ name
+ ". Accepted values are "
+ ", ".join(BUILTIN_DATASETS.keys())
+ "."
)
else:
self.sep = sep
self.skip_lines = skip_lines
self.rating_scale = rating_scale
lower_bound, higher_bound = rating_scale
splitted_format = line_format.split()
entities = ["user", "item", "rating"]
if "timestamp" in splitted_format:
self.with_timestamp = True
entities.append("timestamp")
else:
self.with_timestamp = False
# check that all fields are correct
if any(field not in entities for field in splitted_format):
raise ValueError("line_format parameter is incorrect.")
self.indexes = [splitted_format.index(entity) for entity in entities]
def parse_line(self, line):
"""Parse a line.
Ratings are translated so that they are all strictly positive.
Args:
line(str): The line to parse
Returns:
tuple: User id, item id, rating and timestamp. The timestamp is set
to ``None`` if it does no exist.
"""
line = line.split(self.sep)
try:
if self.with_timestamp:
uid, iid, r, timestamp = (line[i].strip() for i in self.indexes)
else:
uid, iid, r = (line[i].strip() for i in self.indexes)
timestamp = None
except IndexError:
raise ValueError(
"Impossible to parse line. Check the line_format" " and sep parameters."
)
return uid, iid, float(r), timestamp