replay-rec 0.20.3__py3-none-any.whl → 0.20.3rc0__py3-none-any.whl

replay/experimental/preprocessing/padder.py

@@ -0,0 +1,229 @@
+from collections.abc import Iterable
+from typing import Optional, Union
+
+from pandas.api.types import is_object_dtype
+
+from replay.utils import PYSPARK_AVAILABLE, DataFrameLike, PandasDataFrame, SparkDataFrame
+
+if PYSPARK_AVAILABLE:
+    from pyspark.sql import functions as sf
+
+
+class Padder:
+    """
+    Pad array columns in dataframe.
+
+    >>> import pandas as pd
+    >>> pad_interactions = pd.DataFrame({
+    ...    "user_id": [1, 1, 1, 1, 2, 2, 3, 3, 3],
+    ...    "timestamp": [[1], [1, 2], [1, 2, 4], [1, 2, 4, 6], [4, 7, 12],
+    ...                  [4, 7, 12, 126], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5, 6],
+    ...                  [1, 2, 3, 4, 5, 6, 7]],
+    ...    "item_id": [['a'], ['a', 'b'], ['a', 'b', 'd'], ['a', 'b', 'd', 'f'], ['d', 'e', 'm'],
+    ...                ['d', 'e', 'm', 'g'], ['a', 'b', 'c', 'd', 'a'], ['a', 'b', 'c', 'd', 'a', 'f'],
+    ...                ['a', 'b', 'c', 'd', 'a', 'f', 'e']]
+    ... })
+    >>> pad_interactions
+        user_id              timestamp                item_id
+    0        1                    [1]                    [a]
+    1        1                 [1, 2]                 [a, b]
+    2        1              [1, 2, 4]              [a, b, d]
+    3        1           [1, 2, 4, 6]           [a, b, d, f]
+    4        2             [4, 7, 12]              [d, e, m]
+    5        2        [4, 7, 12, 126]           [d, e, m, g]
+    6        3        [1, 2, 3, 4, 5]        [a, b, c, d, a]
+    7        3     [1, 2, 3, 4, 5, 6]     [a, b, c, d, a, f]
+    8        3  [1, 2, 3, 4, 5, 6, 7]  [a, b, c, d, a, f, e]
+    >>> Padder(
+    ...    pad_columns=["item_id", "timestamp"],
+    ...    padding_side="right",
+    ...    padding_value=["[PAD]", 0],
+    ...    array_size=5,
+    ...    cut_array=True,
+    ...    cut_side="right"
+    ... ).transform(pad_interactions)
+       user_id           timestamp                          item_id
+    0        1     [1, 0, 0, 0, 0]  [a, [PAD], [PAD], [PAD], [PAD]]
+    1        1     [1, 2, 0, 0, 0]      [a, b, [PAD], [PAD], [PAD]]
+    2        1     [1, 2, 4, 0, 0]          [a, b, d, [PAD], [PAD]]
+    3        1     [1, 2, 4, 6, 0]              [a, b, d, f, [PAD]]
+    4        2    [4, 7, 12, 0, 0]          [d, e, m, [PAD], [PAD]]
+    5        2  [4, 7, 12, 126, 0]              [d, e, m, g, [PAD]]
+    6        3     [1, 2, 3, 4, 5]                  [a, b, c, d, a]
+    7        3     [2, 3, 4, 5, 6]                  [b, c, d, a, f]
+    8        3     [3, 4, 5, 6, 7]                  [c, d, a, f, e]
+    <BLANKLINE>
+    """
+
+    def __init__(
+        self,
+        pad_columns: Union[str, list[str]],
+        padding_side: Optional[str] = "right",
+        padding_value: Union[str, float, list, None] = 0,
+        array_size: Optional[int] = None,
+        cut_array: Optional[bool] = True,
+        cut_side: Optional[str] = "right",
+    ):
+        """
+        :param pad_columns: Name of columns to pad.
+        :param padding_side: side of array to which add padding values. Can be "right" or "left",
+            default: ``right``.
+        :param padding_value: value to fill missing spacec,
+            default: ``0``.
+        :param array_size: needed array size,
+            default: ``None``
+        :param cut_array: is cutting arrays with shape more than array_size needed,
+            default: ``True``.
+        :param cut_side: side of array on which to cut to needed length. Can be "right" or "left",
+                default: ``right``.
+        """
+        self.pad_columns = (
+            pad_columns if (isinstance(pad_columns, Iterable) and not isinstance(pad_columns, str)) else [pad_columns]
+        )
+        if padding_side not in (
+            "right",
+            "left",
+        ):
+            msg = f"padding_side value {padding_side} is not implemented. Should be 'right' or 'left'"
+            raise ValueError(msg)
+
+        self.padding_side = padding_side
+        self.padding_value = (
+            padding_value
+            if (isinstance(padding_value, Iterable) and not isinstance(padding_value, str))
+            else [padding_value]
+        )
+        if len(self.padding_value) == 1 and len(self.pad_columns) > 1:
+            self.padding_value = self.padding_value * len(self.pad_columns)
+        if len(self.pad_columns) != len(self.padding_value):
+            msg = "pad_columns and padding_value should have same length"
+            raise ValueError(msg)
+
+        self.array_size = array_size
+        if self.array_size is not None:
+            if self.array_size < 1 or not isinstance(self.array_size, int):
+                msg = "array_size should be positive integer greater than 0"
+                raise ValueError(msg)
+        else:
+            self.array_size = -1
+
+        self.cut_array = cut_array
+        self.cut_side = cut_side
+
+    def transform(self, interactions: DataFrameLike) -> DataFrameLike:
+        """Pad dataframe.
+
+        :param interactions: DataFrame with array columns with names pad_columns.
+
+        :returns: DataFrame with padded array columns.
+
+        """
+        df_transformed = interactions
+        is_spark = isinstance(interactions, SparkDataFrame)
+        column_dtypes = dict(df_transformed.dtypes)
+
+        for col, pad_value in zip(self.pad_columns, self.padding_value):
+            if col not in df_transformed.columns:
+                msg = f"Column {col} not in DataFrame columns."
+                raise ValueError(msg)
+            if is_spark is True and not column_dtypes[col].startswith("array"):
+                msg = f"Column {col} should have ArrayType to be padded."
+                raise ValueError(msg)
+            if is_spark is False and not is_object_dtype(df_transformed[col]):
+                msg = f"Column {col} should have object dtype to be padded."
+                raise ValueError()
+
+            if is_spark is True:
+                df_transformed = self._transform_spark(df_transformed, col, pad_value)
+            else:
+                df_transformed = self._transform_pandas(df_transformed, col, pad_value)
+
+        return df_transformed
+
+    def _transform_pandas(
+        self, df_transformed: PandasDataFrame, col: str, pad_value: Union[str, float, list, None]
+    ) -> PandasDataFrame:
+        max_array_size = df_transformed[col].str.len().max() if self.array_size == -1 else self.array_size
+
+        def right_cut(sample: list) -> list:
+            # fmt: off
+            return sample[-min(len(sample), max_array_size):]
+            # fmt: on
+
+        def left_cut(sample: list) -> list:
+            # fmt: off
+            return sample[:min(len(sample), max_array_size)]
+            # fmt: on
+
+        res = df_transformed.copy(deep=True)
+        res[col] = res[col].apply(lambda sample: sample if isinstance(sample, list) else [])
+        cut_col_name = f"{col}_cut"
+        if self.cut_array:
+            cut_func = right_cut if self.cut_side == "right" else left_cut
+
+            res[cut_col_name] = res[col].apply(cut_func)
+        else:
+            res[cut_col_name] = res[col]
+
+        paddings = res[cut_col_name].apply(lambda x: [pad_value for _ in range(max_array_size - len(x))])
+        if self.padding_side == "right":
+            res[col] = res[cut_col_name] + paddings
+        else:
+            res[col] = paddings + res[cut_col_name]
+
+        res.drop(columns=[cut_col_name], inplace=True)
+
+        return res
+
+    def _transform_spark(
+        self, df_transformed: SparkDataFrame, col: str, pad_value: Union[str, float, list, None]
+    ) -> SparkDataFrame:
+        if self.array_size == -1:
+            max_array_size = df_transformed.agg(sf.max(sf.size(col)).alias("max_array_len")).first()[0]
+        else:
+            max_array_size = self.array_size
+
+        df_transformed = df_transformed.withColumn(col, sf.coalesce(col, sf.array()))
+        insert_value = pad_value if not isinstance(pad_value, str) else "'" + pad_value + "'"
+
+        cut_col_name = f"{col}_cut"
+        drop_cols = [cut_col_name, "pre_zeros", "zeros"]
+
+        if self.cut_array:
+            slice_col_name = f"{col}_slice_point"
+            drop_cols += [slice_col_name]
+
+            if self.cut_side == "right":
+                slice_func = (-1) * sf.least(sf.size(col), sf.lit(max_array_size))
+                cut_func = sf.when(
+                    sf.size(col) > 0, sf.expr(f"slice({col}, {slice_col_name}, {max_array_size})")
+                ).otherwise(sf.array())
+            else:
+                slice_func = sf.least(sf.size(col), sf.lit(max_array_size))
+                cut_func = sf.when(sf.size(col) > 0, sf.expr(f"slice({col}, 1, {slice_col_name})")).otherwise(
+                    sf.array()
+                )
+
+            df_transformed = df_transformed.withColumn(slice_col_name, slice_func).withColumn(cut_col_name, cut_func)
+
+        else:
+            df_transformed = df_transformed.withColumn(cut_col_name, sf.col(col))
+
+        if self.padding_side == "right":
+            concat_func = sf.concat(sf.col(cut_col_name), sf.col("zeros"))
+        else:
+            concat_func = sf.concat(sf.col("zeros"), sf.col(cut_col_name))
+
+        df_transformed = (
+            df_transformed.withColumn(
+                "pre_zeros",
+                sf.sequence(sf.lit(0), sf.greatest(sf.lit(max_array_size) - sf.size(sf.col(cut_col_name)), sf.lit(0))),
+            )
+            .withColumn(
+                "zeros", sf.expr(f"transform(slice(pre_zeros, 1, size(pre_zeros) - 1), element -> {insert_value})")
+            )
+            .withColumn(col, concat_func)
+            .drop(*drop_cols)
+        )
+
+        return df_transformed

replay/experimental/preprocessing/sequence_generator.py

@@ -0,0 +1,208 @@
+from typing import Optional, Union
+
+import pandas as pd
+
+from replay.utils import PYSPARK_AVAILABLE, DataFrameLike, PandasDataFrame, SparkDataFrame
+
+if PYSPARK_AVAILABLE:
+    from pyspark.sql import (
+        Column,
+        Window,
+        functions as sf,
+    )
+
+
+class SequenceGenerator:
+    """
+    Creating sequences for sequential models.
+
+    E.g., ``u1`` has purchase sequence ``<i1, i2, i3, i4>``,
+    then after processing, there will be generated three cases.
+
+    ``u1, <i1> | i2``
+
+    (Which means given user_id ``u1`` and item_seq ``<i1>``,
+    model need to predict the next item ``i2``.)
+
+    The other cases are below:
+
+    ``u1, <i1, i2> | i3``
+
+    ``u1, <i1, i2, i3> | i4``
+
+    >>> import pandas as pd
+    >>> time_interactions = pd.DataFrame({
+    ...    "user_id": [1, 1, 1, 2, 2, 2, 3, 3, 3, 3],
+    ...    "item_id": [3, 7, 10, 5, 8, 11, 4, 9, 2, 5],
+    ...    "timestamp": [1, 2, 3, 3, 2, 1, 3, 12, 1, 4]
+    ... })
+    >>> time_interactions
+       user_id  item_id  timestamp
+    0        1        3          1
+    1        1        7          2
+    2        1       10          3
+    3        2        5          3
+    4        2        8          2
+    5        2       11          1
+    6        3        4          3
+    7        3        9         12
+    8        3        2          1
+    9        3        5          4
+    >>> sequences = (
+    ...    SequenceGenerator(
+    ...        groupby_column="user_id", transform_columns=["item_id", "timestamp"]
+    ...    ).transform(time_interactions)
+    ... )
+    >>> sequences
+       user_id item_id_list timestamp_list  label_item_id  label_timestamp
+    0        1          [3]            [1]              7                2
+    1        1       [3, 7]         [1, 2]             10                3
+    2        2          [5]            [3]              8                2
+    3        2       [5, 8]         [3, 2]             11                1
+    4        3          [4]            [3]              9               12
+    5        3       [4, 9]        [3, 12]              2                1
+    6        3    [4, 9, 2]     [3, 12, 1]              5                4
+    <BLANKLINE>
+    """
+
+    def __init__(
+        self,
+        groupby_column: Union[str, list[str]],
+        orderby_column: Union[str, list[str], None] = None,
+        transform_columns: Union[None, str, list[str]] = None,
+        len_window: int = 50,
+        sequence_prefix: Optional[str] = None,
+        sequence_suffix: Optional[str] = "_list",
+        label_prefix: Optional[str] = "label_",
+        label_suffix: Optional[str] = None,
+        get_list_len: Optional[bool] = False,
+        list_len_column: str = "list_len",
+    ):
+        """
+        :param groupby_column: Name of column to group by.
+        :param orderby_column Columns to sort by. If None
+            than values are not ordered.
+            default: ``None``.
+        :param transform_columns: Names of interaction columns to process. If None
+            than all columns are processed except grouping ones.
+            default: ``None``.
+        :param len_window: Max len of sequention, must be positive.
+            default: ``50``.
+        :param sequence_prefix: prefix added to column name after creating sequences.
+            default: ``None``.
+        :param sequence_suffix: suffix added to column name after creating sequences.
+            default: ``_list``.
+        :param label_prefix: prefix added to label column after creating sequences.
+            default: ``label_``.
+        :param label_suffix: suffix added to label column after creating sequences.
+            default: ``None``.
+        :param get_list_len: flag to calculate length of processed list or not.
+            default: ``False``.
+        :param list_len_column: List length column name. Used if get_list_len.
+            default: ``list_len``.
+        """
+        self.groupby_column = groupby_column if not isinstance(groupby_column, str) else [groupby_column]
+        self.orderby_column: Union[list, Column, None]
+        if orderby_column is None:
+            self.orderby_column = None
+        else:
+            self.orderby_column = orderby_column if not isinstance(orderby_column, str) else [orderby_column]
+
+        self.transform_columns = transform_columns
+        self.len_window = len_window
+
+        self.sequence_prefix = "" if sequence_prefix is None else sequence_prefix
+        self.sequence_suffix = "" if sequence_suffix is None else sequence_suffix
+
+        self.label_prefix = "" if label_prefix is None else label_prefix
+        self.label_suffix = "" if label_suffix is None else label_suffix
+
+        self.get_list_len = get_list_len
+        self.list_len_column = list_len_column
+
+    def transform(self, interactions: DataFrameLike) -> DataFrameLike:
+        """Create sequences from given interactions.
+
+        :param interactions: DataFrame.
+
+        :returns: DataFrame with transformed interactions. Sequential interactions in list.
+
+        """
+        if self.transform_columns is None:
+            self.transform_columns = list(set(interactions.columns).difference(self.groupby_column))
+        else:
+            self.transform_columns = (
+                self.transform_columns if not isinstance(self.transform_columns, str) else [self.transform_columns]
+            )
+
+        if isinstance(interactions, SparkDataFrame):
+            return self._transform_spark(interactions)
+
+        return self._transform_pandas(interactions)
+
+    def _transform_pandas(self, interactions: PandasDataFrame) -> PandasDataFrame:
+        assert self.transform_columns is not None
+        processed_interactions = interactions.copy(deep=True)
+
+        def seq_rolling(col: pd.Series) -> list:
+            return [window.to_list()[:-1] for window in col.rolling(self.len_window + 1)]
+
+        for transform_col in self.transform_columns:
+            if self.orderby_column is not None:
+                processed_interactions.sort_values(by=self.orderby_column, inplace=True)
+            else:
+                processed_interactions.sort_values(by=self.groupby_column, inplace=True)
+
+            processed_interactions[self.sequence_prefix + transform_col + self.sequence_suffix] = [
+                item
+                for sublist in processed_interactions.groupby(self.groupby_column, sort=False)[transform_col].apply(
+                    seq_rolling
+                )
+                for item in sublist
+            ]
+            processed_interactions[self.label_prefix + transform_col + self.label_suffix] = processed_interactions[
+                transform_col
+            ]
+
+        first_tranformed_col = self.sequence_prefix + self.transform_columns[0] + self.sequence_suffix
+        processed_interactions = processed_interactions[processed_interactions[first_tranformed_col].str.len() > 0]
+
+        transformed_columns = [self.sequence_prefix + x + self.sequence_suffix for x in self.transform_columns]
+        label_columns = [self.label_prefix + x + self.label_suffix for x in self.transform_columns]
+        select_columns = self.groupby_column + transformed_columns + label_columns
+
+        if self.get_list_len:
+            processed_interactions[self.list_len_column] = processed_interactions[first_tranformed_col].str.len()
+            select_columns += [self.list_len_column]
+
+        processed_interactions.reset_index(inplace=True)
+
+        return processed_interactions[select_columns]
+
+    def _transform_spark(self, interactions: SparkDataFrame) -> SparkDataFrame:
+        assert self.transform_columns is not None
+        processed_interactions = interactions
+        orderby_column: Union[Column, list]
+        orderby_column = sf.lit(1) if self.orderby_column is None else self.orderby_column
+
+        window = Window.partitionBy(self.groupby_column).orderBy(orderby_column).rowsBetween(-self.len_window, -1)
+        for transform_col in self.transform_columns:
+            processed_interactions = processed_interactions.withColumn(
+                self.sequence_prefix + transform_col + self.sequence_suffix,
+                sf.collect_list(transform_col).over(window),
+            ).withColumn(self.label_prefix + transform_col + self.label_suffix, sf.col(transform_col))
+
+        first_tranformed_col = self.sequence_prefix + self.transform_columns[0] + self.sequence_suffix
+        processed_interactions = processed_interactions.filter(sf.size(first_tranformed_col) > 0)
+
+        transformed_columns = [self.sequence_prefix + x + self.sequence_suffix for x in self.transform_columns]
+        label_columns = [self.label_prefix + x + self.label_suffix for x in self.transform_columns]
+        select_columns = self.groupby_column + transformed_columns + label_columns
+
+        if self.get_list_len:
+            processed_interactions = processed_interactions.withColumn(
+                self.list_len_column, sf.size(first_tranformed_col)
+            )
+            select_columns += [self.list_len_column]
+
+        return processed_interactions.select(select_columns)

replay/experimental/scenarios/__init__.py

@@ -0,0 +1 @@
+from replay.experimental.scenarios.two_stages.two_stages_scenario import TwoStagesScenario

replay/experimental/scenarios/obp_wrapper/__init__.py

@@ -0,0 +1,8 @@
+"""
+This module contains Learner class for RePlay models training on bandit dataset.
+The format of the bandit dataset should be the same as in OpenBanditPipeline.
+Learner class has methods `fit` and `predict` which are wrappers for the corresponding
+methods of RePlay model. Optimize is based on optimization over CTR estimated by OBP.
+"""
+
+from replay.experimental.scenarios.obp_wrapper.replay_offline import OBPOfflinePolicyLearner

replay/experimental/scenarios/obp_wrapper/obp_optuna_objective.py

@@ -0,0 +1,74 @@
+from functools import partial
+from typing import Any, Optional
+
+import numpy as np
+from obp.ope import DirectMethod, DoublyRobust, InverseProbabilityWeighting, OffPolicyEvaluation
+from optuna import Trial
+
+from replay.experimental.scenarios.obp_wrapper.utils import get_est_rewards_by_reg
+from replay.models.optimization.optuna_objective import ObjectiveWrapper, suggest_params
+
+
+def obp_objective_calculator(
+    trial: Trial,
+    search_space: dict[str, list[Optional[Any]]],
+    bandit_feedback_train: dict[str, np.ndarray],
+    bandit_feedback_val: dict[str, np.ndarray],
+    learner,
+    criterion: str,
+    k: int,
+) -> float:
+    """
+    Sample parameters and calculate criterion value
+    :param trial: optuna trial
+    :param search_space: hyper parameter search space
+    :bandit_feedback_train: dict with bandit train data
+    :bandit_feedback_cal: dist with bandit validation data
+    :param criterion: optimization metric
+    :param k: length of a recommendation list
+    :return: criterion value
+    """
+
+    params_for_trial = suggest_params(trial, search_space)
+    learner.replay_model.set_params(**params_for_trial)
+
+    timestamp = np.arange(bandit_feedback_train["n_rounds"])
+
+    learner.fit(
+        action=bandit_feedback_train["action"],
+        reward=bandit_feedback_train["reward"],
+        timestamp=timestamp,
+        context=bandit_feedback_train["context"],
+        action_context=bandit_feedback_train["action_context"],
+    )
+
+    action_dist = learner.predict(bandit_feedback_val["n_rounds"], bandit_feedback_val["context"])
+
+    ope_estimator = None
+    if criterion == "ipw":
+        ope_estimator = InverseProbabilityWeighting()
+    elif criterion == "dm":
+        ope_estimator = DirectMethod()
+    elif criterion == "dr":
+        ope_estimator = DoublyRobust()
+    else:
+        msg = f"There is no criterion with name {criterion}"
+        raise NotImplementedError(msg)
+
+    ope = OffPolicyEvaluation(bandit_feedback=bandit_feedback_val, ope_estimators=[ope_estimator])
+
+    estimated_rewards_by_reg_model = None
+    if criterion in ("dm", "dr"):
+        estimated_rewards_by_reg_model = get_est_rewards_by_reg(
+            learner.n_actions, k, bandit_feedback_train, bandit_feedback_val
+        )
+
+    estimated_policy_value = ope.estimate_policy_values(
+        action_dist=action_dist,
+        estimated_rewards_by_reg_model=estimated_rewards_by_reg_model,
+    )[criterion]
+
+    return estimated_policy_value
+
+
+OBPObjective = partial(ObjectiveWrapper, objective_calculator=obp_objective_calculator)