kumoai 2.14.0.dev202601011731__cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

kumoai/experimental/rfm/backend/local/__init__.py

@@ -0,0 +1,42 @@
+try:
+    import kumoai.kumolib  # noqa: F401
+except Exception as e:
+    import platform
+
+    _msg = f"""RFM is not supported in your environment.
+
+💻 Your Environment:
+Python version: {platform.python_version()}
+Operating system: {platform.system()}
+CPU architecture: {platform.machine()}
+glibc version: {platform.libc_ver()[1]}
+
+✅ Supported Environments:
+* Python versions: 3.10, 3.11, 3.12, 3.13
+* Operating systems and CPU architectures:
+  * Linux (x86_64)
+  * macOS (arm64)
+  * Windows (x86_64)
+* glibc versions: >=2.28
+
+❌ Unsupported Environments:
+* Python versions: 3.8, 3.9, 3.14
+* Operating systems and CPU architectures:
+  * Linux (arm64)
+  * macOS (x86_64)
+  * Windows (arm64)
+* glibc versions: <2.28
+
+Please create a feature request at 'https://github.com/kumo-ai/kumo-rfm'."""
+
+    raise RuntimeError(_msg) from e
+
+from .table import LocalTable
+from .graph_store import LocalGraphStore
+from .sampler import LocalSampler
+
+__all__ = [
+    'LocalTable',
+    'LocalGraphStore',
+    'LocalSampler',
+]

kumoai/experimental/rfm/backend/local/graph_store.py

@@ -0,0 +1,297 @@
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+from kumoapi.rfm.context import Subgraph
+
+from kumoai.experimental.rfm.backend.local import LocalTable
+from kumoai.experimental.rfm.base import Table
+from kumoai.utils import ProgressLogger
+
+try:
+    import torch
+    WITH_TORCH = True
+except ImportError:
+    WITH_TORCH = False
+
+if TYPE_CHECKING:
+    from kumoai.experimental.rfm import Graph
+
+
+class LocalGraphStore:
+    def __init__(
+        self,
+        graph: 'Graph',
+        verbose: bool | ProgressLogger = True,
+    ) -> None:
+
+        if not isinstance(verbose, ProgressLogger):
+            verbose = ProgressLogger.default(
+                msg="Materializing graph",
+                verbose=verbose,
+            )
+
+        with verbose as logger:
+            self.df_dict, self.mask_dict = self.sanitize(graph)
+            logger.log("Sanitized input data")
+
+            self.pkey_map_dict = self.get_pkey_map_dict(graph)
+            num_pkeys = sum(t.has_primary_key() for t in graph.tables.values())
+            if num_pkeys > 1:
+                logger.log(f"Collected primary keys from {num_pkeys} tables")
+            else:
+                logger.log(f"Collected primary key from {num_pkeys} table")
+
+            self.time_dict, self.min_max_time_dict = self.get_time_data(graph)
+            if len(self.min_max_time_dict) > 0:
+                min_time = min(t for t, _ in self.min_max_time_dict.values())
+                max_time = max(t for _, t in self.min_max_time_dict.values())
+                logger.log(f"Identified temporal graph from "
+                           f"{min_time.date()} to {max_time.date()}")
+            else:
+                logger.log("Identified static graph without timestamps")
+
+            self.row_dict, self.colptr_dict = self.get_csc(graph)
+            num_nodes = sum(len(df) for df in self.df_dict.values())
+            num_edges = sum(len(row) for row in self.row_dict.values())
+            logger.log(f"Created graph with {num_nodes:,} nodes and "
+                       f"{num_edges:,} edges")
+
+    def get_node_id(self, table_name: str, pkey: pd.Series) -> np.ndarray:
+        r"""Returns the node ID given primary keys.
+
+        Args:
+            table_name: The table name.
+            pkey: The primary keys to receive node IDs for.
+        """
+        if table_name not in self.df_dict.keys():
+            raise KeyError(f"Table '{table_name}' does not exist")
+
+        if table_name not in self.pkey_map_dict.keys():
+            raise ValueError(f"Table '{table_name}' does not have a primary "
+                             f"key")
+
+        if len(pkey) == 0:
+            raise KeyError(f"No primary keys passed for table '{table_name}'")
+
+        pkey_map = self.pkey_map_dict[table_name]
+
+        try:
+            pkey = pkey.astype(type(pkey_map.index[0]))
+        except ValueError as e:
+            raise ValueError(f"Could not cast primary keys "
+                             f"{pkey.tolist()} to the expected data "
+                             f"type '{pkey_map.index.dtype}'") from e
+
+        try:
+            return pkey_map.loc[pkey]['arange'].to_numpy()
+        except KeyError as e:
+            missing = ~np.isin(pkey, pkey_map.index)
+            raise KeyError(f"The primary keys {pkey[missing].tolist()} do "
+                           f"not exist in the '{table_name}' table") from e
+
+    def sanitize(
+        self,
+        graph: 'Graph',
+    ) -> tuple[dict[str, pd.DataFrame], dict[str, np.ndarray]]:
+        r"""Sanitizes raw data according to table schema definition:
+
+        In particular, it:
+        * converts timestamp data to `pd.Datetime`
+        * drops timezone information from timestamps
+        * drops duplicate primary keys
+        * removes rows with missing primary keys or time values
+        """
+        df_dict: dict[str, pd.DataFrame] = {}
+        for table_name, table in graph.tables.items():
+            assert isinstance(table, LocalTable)
+            df_dict[table_name] = Table._sanitize(
+                df=table._data.copy(deep=False).reset_index(drop=True),
+                dtype_dict={
+                    column.name: column.dtype
+                    for column in table.columns
+                },
+                stype_dict={
+                    column.name: column.stype
+                    for column in table.columns
+                },
+            )
+
+        mask_dict: dict[str, np.ndarray] = {}
+        for table in graph.tables.values():
+            mask: np.ndarray | None = None
+            if table._time_column is not None:
+                ser = df_dict[table.name][table._time_column]
+                mask = ser.notna().to_numpy()
+
+            if table._primary_key is not None:
+                ser = df_dict[table.name][table._primary_key]
+                _mask = (~ser.duplicated().to_numpy()) & ser.notna().to_numpy()
+                mask = _mask if mask is None else (_mask & mask)
+
+            if mask is not None and not mask.all():
+                mask_dict[table.name] = mask
+
+        return df_dict, mask_dict
+
+    def get_pkey_map_dict(
+        self,
+        graph: 'Graph',
+    ) -> dict[str, pd.DataFrame]:
+        pkey_map_dict: dict[str, pd.DataFrame] = {}
+
+        for table in graph.tables.values():
+            if table._primary_key is None:
+                continue
+
+            pkey = self.df_dict[table.name][table._primary_key]
+            pkey_map = pd.DataFrame(
+                dict(arange=range(len(pkey))),
+                index=pkey,
+            )
+            if table.name in self.mask_dict:
+                pkey_map = pkey_map[self.mask_dict[table.name]]
+
+            if len(pkey_map) == 0:
+                error_msg = f"Found no valid rows in table '{table.name}'. "
+                if table.has_time_column():
+                    error_msg += ("Please make sure that there exists valid "
+                                  "non-N/A primary key and time column pairs "
+                                  "in this table.")
+                else:
+                    error_msg += ("Please make sure that there exists valid "
+                                  "non-N/A primary keys in this table.")
+                raise ValueError(error_msg)
+
+            pkey_map_dict[table.name] = pkey_map
+
+        return pkey_map_dict
+
+    def get_time_data(
+        self,
+        graph: 'Graph',
+    ) -> tuple[
+            dict[str, np.ndarray],
+            dict[str, tuple[pd.Timestamp, pd.Timestamp]],
+    ]:
+        time_dict: dict[str, np.ndarray] = {}
+        min_max_time_dict: dict[str, tuple[pd.Timestamp, pd.Timestamp]] = {}
+        for table in graph.tables.values():
+            if table._time_column is None:
+                continue
+
+            time = self.df_dict[table.name][table._time_column]
+            time_dict[table.name] = time.astype(int).to_numpy() // 1000**3
+
+            if table.name in self.mask_dict.keys():
+                time = time[self.mask_dict[table.name]]
+            if len(time) > 0:
+                min_max_time_dict[table.name] = (time.min(), time.max())
+            else:
+                min_max_time_dict[table.name] = (
+                    pd.Timestamp.max,
+                    pd.Timestamp.min,
+                )
+
+        return time_dict, min_max_time_dict
+
+    def get_csc(
+        self,
+        graph: 'Graph',
+    ) -> tuple[
+            dict[tuple[str, str, str], np.ndarray],
+            dict[tuple[str, str, str], np.ndarray],
+    ]:
+        # A mapping from raw primary keys to node indices (0 to N-1):
+        map_dict: dict[str, pd.CategoricalDtype] = {}
+        # A dictionary to manage offsets of node indices for invalid rows:
+        offset_dict: dict[str, np.ndarray] = {}
+        for table_name in {edge.dst_table for edge in graph.edges}:
+            ser = self.df_dict[table_name][graph[table_name]._primary_key]
+            if table_name in self.mask_dict.keys():
+                mask = self.mask_dict[table_name]
+                ser = ser[mask]
+                offset_dict[table_name] = np.cumsum(~mask)[mask]
+            map_dict[table_name] = pd.CategoricalDtype(ser, ordered=True)
+
+        # Build CSC graph representation:
+        row_dict: dict[tuple[str, str, str], np.ndarray] = {}
+        colptr_dict: dict[tuple[str, str, str], np.ndarray] = {}
+        for src_table, fkey, dst_table in graph.edges:
+            src_df = self.df_dict[src_table]
+            dst_df = self.df_dict[dst_table]
+
+            src = np.arange(len(src_df))
+            dst = src_df[fkey].astype(map_dict[dst_table]).cat.codes.to_numpy()
+            dst = dst.astype(int)
+            mask = dst >= 0
+            if dst_table in offset_dict.keys():
+                dst = dst + offset_dict[dst_table][dst]
+            if src_table in self.mask_dict.keys():
+                mask &= self.mask_dict[src_table]
+            src, dst = src[mask], dst[mask]
+
+            # Sort by destination/column (and time within neighborhoods):
+            # `lexsort` is expensive (especially in numpy) so avoid it if
+            # possible by grouping `time` and `node_id` together:
+            if src_table in self.time_dict:
+                src_time = self.time_dict[src_table][src]
+                min_time = int(src_time.min())
+                max_time = int(src_time.max())
+                offset = (max_time - min_time) + 1
+                if offset * len(dst_df) <= np.iinfo(np.int64).max:
+                    index = dst * offset + (src_time - min_time)
+                    perm = _argsort(index)
+                else:  # Safe route to avoid `int64` overflow:
+                    perm = _lexsort([src_time, dst])
+            else:
+                perm = _argsort(dst)
+
+            row, col = src[perm], dst[perm]
+
+            # Convert into compressed representation:
+            colcount = np.bincount(col, minlength=len(dst_df))
+            colptr = np.empty(len(colcount) + 1, dtype=colcount.dtype)
+            colptr[0] = 0
+            np.cumsum(colcount, out=colptr[1:])
+            edge_type = (src_table, fkey, dst_table)
+            row_dict[edge_type] = row
+            colptr_dict[edge_type] = colptr
+
+            # Reverse connection - no sort and no time handling needed since
+            # the reverse mapping is 1-to-many.
+            row, col = dst, src
+            colcount = np.bincount(col, minlength=len(src_df))
+            colptr = np.empty(len(colcount) + 1, dtype=colcount.dtype)
+            colptr[0] = 0
+            np.cumsum(colcount, out=colptr[1:])
+            edge_type = Subgraph.rev_edge_type(edge_type)
+            row_dict[edge_type] = row
+            colptr_dict[edge_type] = colptr
+
+        return row_dict, colptr_dict
+
+
+def _argsort(input: np.ndarray) -> np.ndarray:
+    if not WITH_TORCH:
+        return np.argsort(input)
+    return torch.from_numpy(input).argsort().numpy()
+
+
+def _lexsort(inputs: list[np.ndarray]) -> np.ndarray:
+    assert len(inputs) >= 1
+
+    if not WITH_TORCH:
+        return np.lexsort(inputs)
+
+    try:
+        out = torch.from_numpy(inputs[0]).argsort(stable=True)
+    except Exception:
+        return np.lexsort(inputs)  # PyTorch<1.9 without `stable` support.
+
+    for input in inputs[1:]:
+        index = torch.from_numpy(input)[out]
+        index = index.argsort(stable=True)
+        out = out[index]
+
+    return out.numpy()

kumoai/experimental/rfm/backend/local/sampler.py

@@ -0,0 +1,312 @@
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+import pandas as pd
+from kumoapi.pquery import ValidatedPredictiveQuery
+
+from kumoai.experimental.rfm.backend.local import LocalGraphStore
+from kumoai.experimental.rfm.base import Sampler, SamplerOutput
+from kumoai.experimental.rfm.pquery import PQueryPandasExecutor
+from kumoai.utils import ProgressLogger
+
+if TYPE_CHECKING:
+    from kumoai.experimental.rfm import Graph
+
+
+class LocalSampler(Sampler):
+    def __init__(
+        self,
+        graph: 'Graph',
+        verbose: bool | ProgressLogger = True,
+    ) -> None:
+        super().__init__(graph=graph, verbose=verbose)
+
+        import kumoai.kumolib as kumolib
+
+        self._graph_store = LocalGraphStore(graph, verbose)
+        self._graph_sampler = kumolib.NeighborSampler(
+            list(self.table_stype_dict.keys()),
+            self.edge_types,
+            {
+                '__'.join(edge_type): colptr
+                for edge_type, colptr in self._graph_store.colptr_dict.items()
+            },
+            {
+                '__'.join(edge_type): row
+                for edge_type, row in self._graph_store.row_dict.items()
+            },
+            self._graph_store.time_dict,
+        )
+
+    def _get_min_max_time_dict(
+        self,
+        table_names: list[str],
+    ) -> dict[str, tuple[pd.Timestamp, pd.Timestamp]]:
+        return {
+            key: value
+            for key, value in self._graph_store.min_max_time_dict.items()
+            if key in table_names
+        }
+
+    def _sample_subgraph(
+        self,
+        entity_table_name: str,
+        entity_pkey: pd.Series,
+        anchor_time: pd.Series | Literal['entity'],
+        columns_dict: dict[str, set[str]],
+        num_neighbors: list[int],
+    ) -> SamplerOutput:
+
+        index = self._graph_store.get_node_id(entity_table_name, entity_pkey)
+
+        if isinstance(anchor_time, pd.Series):
+            time = anchor_time.astype(int).to_numpy() // 1000**3  # to seconds
+        else:
+            assert anchor_time == 'entity'
+            time = self._graph_store.time_dict[entity_table_name][index]
+
+        (
+            row_dict,
+            col_dict,
+            node_dict,
+            batch_dict,
+            num_sampled_nodes_dict,
+            num_sampled_edges_dict,
+        ) = self._graph_sampler.sample(
+            {
+                '__'.join(edge_type): num_neighbors
+                for edge_type in self.edge_types
+            },
+            {},
+            entity_table_name,
+            index,
+            time,
+        )
+
+        df_dict: dict[str, pd.DataFrame] = {}
+        inverse_dict: dict[str, np.ndarray] = {}
+        for table_name, node in node_dict.items():
+            df = self._graph_store.df_dict[table_name]
+            columns = columns_dict[table_name]
+            if self.end_time_column_dict.get(table_name, None) in columns:
+                df = df.iloc[node]
+            elif len(columns) == 0:
+                df = df.iloc[node]
+            else:
+                # Only store unique rows in `df` above a certain threshold:
+                unique_node, inverse = np.unique(node, return_inverse=True)
+                if len(node) > 1.05 * len(unique_node):
+                    df = df.iloc[unique_node]
+                    inverse_dict[table_name] = inverse
+                else:
+                    df = df.iloc[node]
+            df = df.reset_index(drop=True)
+            df = df[list(columns)]
+            df_dict[table_name] = df
+
+        num_sampled_nodes_dict = {
+            table_name: num_sampled_nodes.tolist()
+            for table_name, num_sampled_nodes in
+            num_sampled_nodes_dict.items()
+        }
+
+        row_dict = {
+            edge_type: row_dict['__'.join(edge_type)]
+            for edge_type in self.edge_types
+        }
+        col_dict = {
+            edge_type: col_dict['__'.join(edge_type)]
+            for edge_type in self.edge_types
+        }
+        num_sampled_edges_dict = {
+            edge_type: num_sampled_edges_dict['__'.join(edge_type)].tolist()
+            for edge_type in self.edge_types
+        }
+
+        return SamplerOutput(
+            anchor_time=time * 1000**3,  # to nanoseconds
+            df_dict=df_dict,
+            inverse_dict=inverse_dict,
+            batch_dict=batch_dict,
+            num_sampled_nodes_dict=num_sampled_nodes_dict,
+            row_dict=row_dict,
+            col_dict=col_dict,
+            num_sampled_edges_dict=num_sampled_edges_dict,
+        )
+
+    def _sample_entity_table(
+        self,
+        table_name: str,
+        columns: set[str],
+        num_rows: int,
+        random_seed: int | None = None,
+    ) -> pd.DataFrame:
+        pkey_map = self._graph_store.pkey_map_dict[table_name]
+        if len(pkey_map) > num_rows:
+            pkey_map = pkey_map.sample(
+                n=num_rows,
+                random_state=random_seed,
+                ignore_index=True,
+            )
+        df = self._graph_store.df_dict[table_name]
+        df = df.iloc[pkey_map['arange']][list(columns)]
+        return df
+
+    def _sample_target(
+        self,
+        query: ValidatedPredictiveQuery,
+        entity_df: pd.DataFrame,
+        train_index: np.ndarray,
+        train_time: pd.Series,
+        num_train_examples: int,
+        test_index: np.ndarray,
+        test_time: pd.Series,
+        num_test_examples: int,
+        columns_dict: dict[str, set[str]],
+        time_offset_dict: dict[
+            tuple[str, str, str],
+            tuple[pd.DateOffset | None, pd.DateOffset],
+        ],
+    ) -> tuple[pd.Series, np.ndarray, pd.Series, np.ndarray]:
+
+        train_y, train_mask = self._sample_target_set(
+            query=query,
+            pkey=entity_df[self.primary_key_dict[query.entity_table]],
+            index=train_index,
+            anchor_time=train_time,
+            num_examples=num_train_examples,
+            columns_dict=columns_dict,
+            time_offset_dict=time_offset_dict,
+        )
+
+        test_y, test_mask = self._sample_target_set(
+            query=query,
+            pkey=entity_df[self.primary_key_dict[query.entity_table]],
+            index=test_index,
+            anchor_time=test_time,
+            num_examples=num_test_examples,
+            columns_dict=columns_dict,
+            time_offset_dict=time_offset_dict,
+        )
+
+        return train_y, train_mask, test_y, test_mask
+
+    # Helper Methods ##########################################################
+
+    def _sample_target_set(
+        self,
+        query: ValidatedPredictiveQuery,
+        pkey: pd.Series,
+        index: np.ndarray,
+        anchor_time: pd.Series,
+        num_examples: int,
+        columns_dict: dict[str, set[str]],
+        time_offset_dict: dict[
+            tuple[str, str, str],
+            tuple[pd.DateOffset | None, pd.DateOffset],
+        ],
+        batch_size: int = 10_000,
+    ) -> tuple[pd.Series, np.ndarray]:
+
+        num_hops = 1 if len(time_offset_dict) > 0 else 0
+        num_neighbors_dict: dict[str, list[int]] = {}
+        unix_time_offset_dict: dict[str, list[list[int | None]]] = {}
+        for edge_type, (start, end) in time_offset_dict.items():
+            unix_time_offset_dict['__'.join(edge_type)] = [[
+                date_offset_to_seconds(start) if start is not None else None,
+                date_offset_to_seconds(end),
+            ]]
+        for edge_type in set(self.edge_types) - set(time_offset_dict.keys()):
+            num_neighbors_dict['__'.join(edge_type)] = [0] * num_hops
+
+        count = 0
+        ys: list[pd.Series] = []
+        mask = np.full(len(index), False, dtype=bool)
+        for start in range(0, len(index), batch_size):
+            subset = pkey.iloc[index[start:start + batch_size]]
+            time = anchor_time.iloc[start:start + batch_size]
+
+            _, _, node_dict, batch_dict, _, _ = self._graph_sampler.sample(
+                num_neighbors_dict,
+                unix_time_offset_dict,
+                query.entity_table,
+                self._graph_store.get_node_id(query.entity_table, subset),
+                time.astype(int).to_numpy() // 1000**3,  # to seconds
+            )
+
+            feat_dict: dict[str, pd.DataFrame] = {}
+            time_dict: dict[str, pd.Series] = {}
+            for table_name, columns in columns_dict.items():
+                df = self._graph_store.df_dict[table_name]
+                df = df.iloc[node_dict[table_name]].reset_index(drop=True)
+                df = df[list(columns)]
+                feat_dict[table_name] = df
+
+                time_column = self.time_column_dict.get(table_name)
+                if time_column in columns:
+                    time_dict[table_name] = df[time_column]
+
+            y, _mask = PQueryPandasExecutor().execute(
+                query=query,
+                feat_dict=feat_dict,
+                time_dict=time_dict,
+                batch_dict=batch_dict,
+                anchor_time=time,
+                num_forecasts=query.num_forecasts,
+            )
+            ys.append(y)
+            mask[start:start + batch_size] = _mask
+
+            count += len(y)
+            if count >= num_examples:
+                break
+
+        if len(ys) == 0:
+            y = pd.Series([], dtype=float)
+        elif len(ys) == 1:
+            y = ys[0]
+        else:
+            y = pd.concat(ys, axis=0, ignore_index=True)
+
+        return y, mask
+
+
+# Helper Functions ############################################################
+
+
+def date_offset_to_seconds(offset: pd.DateOffset) -> int:
+    r"""Convert a :class:`pandas.DateOffset` into a number of seconds.
+
+    .. note::
+        We are conservative and take months and years as their maximum value.
+        Additional values are then dropped in label computation where we know
+        the actual dates.
+    """
+    MAX_DAYS_IN_MONTH = 31
+    MAX_DAYS_IN_YEAR = 366
+
+    SECONDS_IN_MINUTE = 60
+    SECONDS_IN_HOUR = 60 * SECONDS_IN_MINUTE
+    SECONDS_IN_DAY = 24 * SECONDS_IN_HOUR
+
+    total_sec = 0
+    multiplier = getattr(offset, 'n', 1)  # The multiplier (if present).
+
+    for attr, value in offset.__dict__.items():
+        if value is None or value == 0:
+            continue
+        scaled_value = value * multiplier
+        if attr == 'years':
+            total_sec += scaled_value * MAX_DAYS_IN_YEAR * SECONDS_IN_DAY
+        elif attr == 'months':
+            total_sec += scaled_value * MAX_DAYS_IN_MONTH * SECONDS_IN_DAY
+        elif attr == 'days':
+            total_sec += scaled_value * SECONDS_IN_DAY
+        elif attr == 'hours':
+            total_sec += scaled_value * SECONDS_IN_HOUR
+        elif attr == 'minutes':
+            total_sec += scaled_value * SECONDS_IN_MINUTE
+        elif attr == 'seconds':
+            total_sec += scaled_value
+
+    return total_sec