recnexteval 0.1.0__py3-none-any.whl

recnexteval/utils/json_to_csv_converter.py

@@ -0,0 +1,128 @@
+# Reference: https://github.com/Yelp/dataset-examples/blob/master/json_to_csv_converter.py
+
+# -*- coding: utf-8 -*-
+"""Convert the Yelp Dataset Challenge dataset from json format to csv.
+
+For more information on the Yelp Dataset Challenge please visit http://yelp.com/dataset_challenge
+
+"""
+
+import argparse
+import csv
+from collections.abc import MutableMapping
+
+import simplejson as json
+
+
+def read_and_write_file(json_file_path, csv_file_path, column_names) -> None:
+    """Read in the json dataset file and write it out to a csv file, given the column names."""
+    with open(csv_file_path, "w") as fout:
+        csv_file = csv.writer(fout)
+        csv_file.writerow(list(column_names))
+        with open(json_file_path, encoding="utf-8") as fin:
+            for line in fin:
+                line_contents = json.loads(line)
+                csv_file.writerow(get_row(line_contents, column_names))
+
+
+def get_superset_of_column_names_from_file(json_file_path):
+    """Read in the json dataset file and return the superset of column names."""
+    column_names = set()
+    with open(json_file_path, encoding="utf-8") as fin:
+        for line in fin:
+            line_contents = json.loads(line)
+            column_names.update(set(get_column_names(line_contents).keys()))
+    return column_names
+
+
+def get_column_names(line_contents, parent_key="") -> dict:
+    """Return a list of flattened key names given a dict.
+
+    Example:
+
+        line_contents = {
+            'a': {
+                'b': 2,
+                'c': 3,
+                },
+        }
+
+        will return: ['a.b', 'a.c']
+
+    These will be the column names for the eventual csv file.
+
+    """
+    column_names = []
+    for k, v in line_contents.items():
+        column_name = "{0}.{1}".format(parent_key, k) if parent_key else k
+        if isinstance(v, MutableMapping):
+            column_names.extend(get_column_names(v, column_name).items())
+        else:
+            column_names.append((column_name, v))
+    return dict(column_names)
+
+
+def get_nested_value(d, key):
+    """Return a dictionary item given a dictionary `d` and a flattened key from `get_column_names`.
+
+    Example:
+
+        d = {
+            'a': {
+                'b': 2,
+                'c': 3,
+                },
+        }
+        key = 'a.b'
+
+        will return: 2
+
+    """
+    if "." not in key:
+        if key not in d:
+            return None
+        return d[key]
+    base_key, sub_key = key.split(".", 1)
+    if base_key not in d:
+        return None
+    sub_dict = d[base_key]
+    return get_nested_value(sub_dict, sub_key)
+
+
+def get_row(line_contents, column_names):
+    """Return a csv compatible row given column names and a dict."""
+    row = []
+    for column_name in column_names:
+        line_value = get_nested_value(
+            line_contents,
+            column_name,
+        )
+        if isinstance(line_value, str):
+            row.append("{0}".format(line_value.encode("utf-8")))
+        elif line_value is not None:
+            row.append("{0}".format(line_value))
+        else:
+            row.append("")
+    return row
+
+
+if __name__ == "__main__":
+    """Convert a yelp dataset file from json to csv."""
+
+    parser = argparse.ArgumentParser(
+        description="Convert Yelp Dataset Challenge data from JSON format to CSV.",
+    )
+
+    parser.add_argument(
+        "json_file",
+        type=str,
+        help="The json file to convert.",
+    )
+
+    args = parser.parse_args()
+
+    json_file = args.json_file
+    csv_file = "{0}.csv".format(json_file.split(".json")[0])
+
+    column_names = get_superset_of_column_names_from_file(json_file)
+    read_and_write_file(json_file, csv_file, column_names)

recnexteval/utils/logging_tools.py

@@ -0,0 +1,159 @@
+import logging
+import logging.config
+import os
+import warnings
+from collections.abc import Generator
+from contextlib import contextmanager
+from enum import Enum
+
+import pyfiglet
+import yaml
+
+from recnexteval.utils.path import safe_dir
+from recnexteval.utils.yaml_tool import create_config_yaml
+
+
+class LogLevel(Enum):
+    CRITICAL = logging.CRITICAL
+    ERROR = logging.ERROR
+    WARNING = logging.WARNING
+    INFO = logging.INFO
+    DEBUG = logging.DEBUG
+    NOTSET = logging.NOTSET
+
+    @classmethod
+    def from_string(cls, level: str) -> "LogLevel":
+        """Return a LogLevel member from a case-insensitive string.
+
+        Args:
+            level: Name of the log level (case-insensitive).
+
+        Returns:
+            The corresponding :class:`LogLevel` enum member.
+        """
+        return cls[level.upper()]
+
+
+def log_level(level: int | str | LogLevel) -> None:
+    """Change the logging level for the root logger.
+
+    Args:
+        level: The logging level to set. May be a :class:`LogLevel` enum,
+            a level name (str, case-insensitive), or an integer logging level.
+
+    Returns:
+        None
+    """
+    if isinstance(level, str):
+        level = LogLevel.from_string(level)
+
+    numeric_level = level.value if isinstance(level, LogLevel) else level
+
+    logger = logging.getLogger()
+    logger.setLevel(numeric_level)
+    for handler in logger.handlers:
+        handler.setLevel(numeric_level)
+
+
+log_level_by_name = log_level  # Alias for convenience
+
+
+def suppress_warnings() -> None:
+    """Suppress all Python warnings.
+
+    This will disable warning output by filtering all warnings and
+    disabling logging's capture of warnings.
+
+    Returns:
+        None
+    """
+    logging.captureWarnings(False)
+    warnings.filterwarnings("ignore")
+
+
+def enable_warnings() -> None:
+    """Enable Python warnings (reset to default behavior).
+
+    This re-enables warning capture and resets any filters previously set.
+
+    Returns:
+        None
+    """
+    logging.captureWarnings(True)
+    warnings.resetwarnings()
+
+
+def suppress_specific_warnings(category: type[Warning]) -> None:
+    """Suppress warnings of a specific category.
+
+    Args:
+        category: Warning class/type to suppress (for example, :class:`DeprecationWarning`).
+
+    Returns:
+        None
+    """
+    warnings.filterwarnings("ignore", category=category)
+
+
+@contextmanager
+def warnings_suppressed() -> Generator:
+    """Context manager that temporarily suppresses all warnings.
+
+    Yields:
+        None: Warnings are suppressed inside the context block.
+    """
+    logging.captureWarnings(False)
+    warnings.filterwarnings("ignore")
+    try:
+        yield
+    finally:
+        logging.captureWarnings(True)
+        warnings.resetwarnings()
+
+
+def prepare_logger(log_config_filename: str) -> dict:
+    """Prepare and configure logging from a YAML file.
+
+    This function locates or creates a logging configuration YAML file using
+    :func:`recnexteval.utils.yaml_tool.create_config_yaml`, ensures the
+    directory for the configured log file exists, writes an ASCII art header
+    to the log file, and configures the Python logging system using
+    :func:`logging.config.dictConfig`.
+
+    Args:
+        log_config_filename: Name of the logging configuration YAML file.
+
+    Returns:
+        dict: The parsed logging configuration dictionary.
+
+    Raises:
+        FileNotFoundError: If the resolved YAML configuration file cannot be found.
+        ValueError: If there is an error parsing the YAML content.
+    """
+    _, yaml_file_path = create_config_yaml(log_config_filename)
+    try:
+        with open(yaml_file_path, "r") as stream:
+            config = yaml.load(
+                stream, Loader=yaml.FullLoader
+            )
+    except FileNotFoundError:
+        raise FileNotFoundError(f"Configuration file not found at {yaml_file_path}.")
+    except yaml.YAMLError as e:
+        raise ValueError(f"Error parsing YAML configuration: {e}")
+
+    # Get the log file path from the configuration
+    log_file = config["handlers"]["file"]["filename"]
+
+    # Ensure the log file directory exists
+    dir_name = os.path.dirname(log_file)
+    safe_dir(dir_name)
+
+    # Write ASCII art to the log file
+    with open(log_file, "w") as log:
+        ascii_art = pyfiglet.figlet_format("recnexteval")
+        log.write(ascii_art)
+        log.write("\n")
+
+    logging.config.dictConfig(config)
+    logging.captureWarnings(True)
+    return config

recnexteval/utils/path.py

@@ -0,0 +1,155 @@
+"""Path utilities for recnexteval library.
+
+This module provides functions to resolve paths relative to the repository root,
+ensuring that data and logs are stored consistently regardless of where the
+library is run from.
+"""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+
+_REPO_ROOT_CACHE: Optional[Path] = None
+
+
+def get_repo_root(
+    marker_files: tuple[str, ...] = (
+        ".git",
+        "pyproject.toml",
+        "setup.py",
+        "setup.cfg",
+        "README.md",
+        "requirements.txt",
+    ),
+) -> Path:
+    """Find and return the repository root directory.
+
+    The function searches upward from the current file's directory looking for
+    common repository marker files (for example, `.git` or `pyproject.toml`).
+    The result is cached to avoid repeated filesystem traversal.
+
+    Args:
+        marker_files: Tuple of filenames that indicate the repository root.
+
+    Returns:
+        Path to the repository root directory.
+
+    Raises:
+        RuntimeError: If the repository root cannot be located and the
+            `STREAMSIGHT_ROOT` environment variable is not set or invalid.
+    """
+    global _REPO_ROOT_CACHE
+
+    if _REPO_ROOT_CACHE is not None:
+        return _REPO_ROOT_CACHE
+
+    # Start from this file's location
+    current = Path(__file__).resolve().parent
+    max_depth = 10
+
+    for _ in range(max_depth):
+        # Check for marker files
+        if any((current / marker).exists() for marker in marker_files):
+            _REPO_ROOT_CACHE = current
+            return current
+
+        # Move up one directory
+        parent = current.parent
+        if parent == current:  # Reached filesystem root
+            break
+        current = parent
+
+    # Fallback: try environment variable
+    if "STREAMSIGHT_ROOT" in os.environ:
+        root = Path(os.environ["STREAMSIGHT_ROOT"])
+        if root.exists():
+            _REPO_ROOT_CACHE = root
+            return root
+
+    raise RuntimeError(
+        "Could not find repository root. Please set STREAMSIGHT_ROOT "
+        "environment variable or ensure you're running from within the repo."
+    )
+
+
+def get_data_dir(subdir: str = "") -> Path:
+    """Return the `data/` directory inside the repository.
+
+    Args:
+        subdir: Optional subdirectory within `data/` to append.
+
+    Returns:
+        Path to the data directory (with `subdir` appended when provided).
+    """
+    data_dir = get_repo_root() / "data"
+    if subdir:
+        data_dir = data_dir / subdir
+    return data_dir
+
+
+def get_logs_dir(subdir: str = "") -> Path:
+    """Return the `logs/` directory inside the repository.
+
+    Args:
+        subdir: Optional subdirectory within `logs/` to append.
+
+    Returns:
+        Path to the logs directory (with `subdir` appended when provided).
+    """
+    logs_dir = get_repo_root() / "logs"
+    if subdir:
+        logs_dir = logs_dir / subdir
+    return logs_dir
+
+
+def get_cache_dir(subdir: str = "") -> Path:
+    """Return the `cache/` directory inside the repository.
+
+    Args:
+        subdir: Optional subdirectory within `cache/` to append.
+
+    Returns:
+        Path to the cache directory (with `subdir` appended when provided).
+    """
+    cache_dir = get_repo_root() / "cache"
+    if subdir:
+        cache_dir = cache_dir / subdir
+    return cache_dir
+
+
+def safe_dir(path: Path | str) -> Path:
+    """Ensure the given directory exists, creating it if necessary.
+
+    Args:
+        path: Directory path as a :class:`pathlib.Path` or string.
+
+    Returns:
+        The directory path (created if it did not exist).
+    """
+    path = Path(path)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def resolve_path(path: str | Path, relative_to_root: bool = True) -> Path:
+    """Resolve a path to an absolute :class:`pathlib.Path`.
+
+    Args:
+        path: Path to resolve, either a string or :class:`pathlib.Path`.
+        relative_to_root: If True and `path` is relative, resolve it relative to
+            the repository root. If False, resolve it relative to the current
+            working directory.
+
+    Returns:
+        The resolved absolute path.
+    """
+    path = Path(path)
+
+    if path.is_absolute():
+        return path
+
+    if relative_to_root:
+        return get_repo_root() / path
+
+    return path.resolve()

recnexteval/utils/url_certificate_installer.py

@@ -0,0 +1,54 @@
+# install_certifi.py
+#
+# sample script to install or update a set of default Root Certificates
+# for the ssl module.  Uses the certificates provided by the certifi package:
+#       https://pypi.python.org/pypi/certifi
+
+# solution is obtained from https://stackoverflow.com/questions/44649449/brew-installation-of-python-3-6-1-ssl-certificate-verify-failed-certificate/49953648#49953648
+
+import contextlib
+import os
+import os.path
+import ssl
+import stat
+import subprocess
+import sys
+
+
+STAT_0o775 = (
+    stat.S_IRUSR
+    | stat.S_IWUSR
+    | stat.S_IXUSR
+    | stat.S_IRGRP
+    | stat.S_IWGRP
+    | stat.S_IXGRP
+    | stat.S_IROTH
+    | stat.S_IXOTH
+)
+
+
+def main():
+    openssl_dir, openssl_cafile = os.path.split(ssl.get_default_verify_paths().openssl_cafile)
+
+    print(" -- pip install --upgrade certifi")
+    subprocess.check_call(
+        [sys.executable, "-E", "-s", "-m", "pip", "install", "--upgrade", "certifi"]
+    )
+
+    import certifi
+
+    # change working directory to the default SSL directory
+    os.chdir(openssl_dir)
+    relpath_to_certifi_cafile = os.path.relpath(certifi.where())
+    print(" -- removing any existing file or link")
+    with contextlib.suppress(FileNotFoundError):
+        os.remove(openssl_cafile)
+    print(" -- creating symlink to certifi certificate bundle")
+    os.symlink(relpath_to_certifi_cafile, openssl_cafile)
+    print(" -- setting permissions")
+    os.chmod(openssl_cafile, STAT_0o775)
+    print(" -- update complete")
+
+
+if __name__ == "__main__":
+    main()

recnexteval/utils/util.py

@@ -0,0 +1,166 @@
+import logging
+from typing import Union
+
+import numpy as np
+import progressbar
+from scipy.sparse import csr_matrix
+
+
+logger = logging.getLogger(__name__)
+
+
+def to_tuple(element) -> tuple:
+    """Whether single element or tuple, always returns as tuple."""
+    if isinstance(element, tuple):
+        return element
+    else:
+        return (element,)
+
+
+def arg_to_str(arg: type | str) -> str:
+    """Converts a type to its name or returns the string.
+
+    :param arg: Argument to convert to string.
+    :type arg: Union[type, str]
+    :return: String representation of the argument.
+    :rtype: str
+    :raises TypeError: If the argument is not a string or a type.
+    """
+    if isinstance(arg, type):
+        return arg.__name__
+    elif not isinstance(arg, str):
+        raise TypeError(f"Argument should be string or type, not {type(arg)}!")
+    return arg
+
+
+def df_to_sparse(
+    df,
+    item_ix,
+    user_ix,
+    value_ix=None,
+    shape=None,
+) -> csr_matrix:
+    if value_ix is not None and value_ix in df:
+        values = df[value_ix]
+    else:
+        if value_ix is not None:
+            # value_ix provided, but not in df
+            logger.warning(f"Value column {value_ix} not found in dataframe. Using ones instead.")
+
+        num_entries = df.shape[0]
+        # Scipy sums up the entries when an index-pair occurs more than once,
+        # resulting in the actual counts being stored. Neat!
+        values = np.ones(num_entries)
+
+    indices = list(zip(*df.loc[:, [user_ix, item_ix]].values))
+
+    if indices == []:
+        indices = [[], []]  # Empty zip does not evaluate right
+
+    if shape is None:
+        shape = df[user_ix].max() + 1, df[item_ix].max() + 1
+    sparse_matrix = csr_matrix((values, indices), shape=shape, dtype=values.dtype)
+
+    return sparse_matrix
+
+
+def to_binary(X: csr_matrix) -> csr_matrix:
+    """Converts a matrix to binary by setting all non-zero values to 1.
+
+    :param X: Matrix to convert to binary.
+    :type X: csr_matrix
+    :return: Binary matrix.
+    :rtype: csr_matrix
+    """
+    X_binary = X.astype(bool).astype(X.dtype)
+
+    return X_binary
+
+
+def invert(x: Union[np.ndarray, csr_matrix]) -> Union[np.ndarray, csr_matrix]:
+    """Invert an array.
+
+    :param x: [description]
+    :type x: [type]
+    :return: [description]
+    :rtype: [type]
+    """
+    if isinstance(x, np.ndarray):
+        ret = np.zeros(x.shape)
+    elif isinstance(x, csr_matrix):
+        ret = csr_matrix(x.shape)
+    else:
+        raise TypeError("Unsupported type for argument x.")
+    ret[x.nonzero()] = 1 / x[x.nonzero()]
+    return ret
+
+
+class ProgressBar:
+    """Progress bar as visual."""
+
+    def __init__(self) -> None:
+        self.pbar = None
+
+    def __call__(self, block_num, block_size, total_size) -> None:
+        if not self.pbar:
+            self.pbar = progressbar.ProgressBar(maxval=total_size)
+            self.pbar.start()
+
+        downloaded = block_num * block_size
+        if downloaded < total_size:
+            self.pbar.update(downloaded)
+        else:
+            self.pbar.finish()
+
+
+def add_rows_to_csr_matrix(matrix: csr_matrix, n: int = 1) -> csr_matrix:
+    """Add a row of zeros to a csr_matrix.
+
+    ref: https://stackoverflow.com/questions/52299420/scipy-csr-matrix-understand-indptr
+
+    :param matrix: Matrix to add a row of zeros to.
+    :type matrix: csr_matrix
+    :return: Matrix with a row of zeros added.
+    :rtype: csr_matrix
+    """
+    new_shape = (matrix.shape[0] + n, matrix.shape[1])
+    new_indptr = np.append(matrix.indptr, [matrix.indptr[-1]] * n)
+    matrix = csr_matrix((matrix.data, matrix.indices, new_indptr), shape=new_shape, copy=False)
+    return matrix
+
+
+def add_columns_to_csr_matrix(matrix: csr_matrix, n: int = 1) -> csr_matrix:
+    """Add a column of zeros to a csr_matrix.
+
+    https://stackoverflow.com/questions/30691160/effectively-change-dimension-of-scipy-spare-csr-matrix
+
+    :param matrix: Matrix to add a column of zeros to.
+    :type matrix: csr_matrix
+    :return: Matrix with a column of zeros added.
+    :rtype: csr_matrix
+    """
+    new_shape = (matrix.shape[0], matrix.shape[1] + n)
+    matrix = csr_matrix(
+        (matrix.data, matrix.indices, matrix.indptr),
+        shape=new_shape,
+        copy=False,
+    )
+    return matrix
+
+
+def set_row_csr_addition(A: csr_matrix, row_idx: int, new_row: np.ndarray) -> None:
+    """Set row of a csr_matrix to a new row.
+
+    ref: https://stackoverflow.com/questions/28427236/set-row-of-csr-matrix
+
+    :param A: Matrix to set a row of.
+    :type A: csr_matrix
+    :param row_idx: Index of the row to set.
+    :type row_idx: int
+    :param new_row: New row to set.
+    :type new_row: np.ndarray
+    """
+    indptr = np.zeros(A.shape[1] + 1)
+    indptr[row_idx + 1 :] = A.shape[1]
+    indices = np.arange(A.shape[1])
+    A += csr_matrix((new_row, indices, indptr), shape=A.shape)

recnexteval/utils/uuid_util.py

@@ -0,0 +1,7 @@
+import datetime
+from uuid import NAMESPACE_DNS, UUID, uuid5
+
+
+def generate_algorithm_uuid(name: str) -> UUID:
+    """Generate a UUID for an algorithm based on its name and current timestamp."""
+    return uuid5(NAMESPACE_DNS, f"{name}{datetime.datetime.now()}")