k3-node 1.0.0__py3-none-any.whl

k3_node/datasets/wikics.py

@@ -0,0 +1,85 @@
+import json
+import warnings
+from itertools import chain
+from typing import Callable, List, Optional
+import numpy as np
+from keras import ops
+
+from k3_node.data import Data, InMemoryDataset
+from k3_node.io import fs
+from k3_node.transforms.utils import to_undirected
+
+
+class WikiCS(InMemoryDataset):
+    r"""The semi-supervised Wikipedia-based dataset from the
+    "Wiki-CS: A Wikipedia-Based Benchmark for Graph Neural Networks" paper.
+
+    Args:
+        root (str): Root directory where the dataset should be saved.
+        transform (callable, optional): Transform function.
+        pre_transform (callable, optional): Pre-transform function.
+        is_undirected (bool, optional): Whether the graph is undirected. (default: True)
+        force_reload (bool, optional): Whether to re-process the dataset.
+    """
+
+    url = "https://github.com/pmernyei/wiki-cs-dataset/raw/master/dataset"
+
+    def __init__(
+        self,
+        root: str,
+        transform: Optional[Callable] = None,
+        pre_transform: Optional[Callable] = None,
+        is_undirected: Optional[bool] = None,
+        force_reload: bool = False,
+    ):
+        if is_undirected is None:
+            is_undirected = True
+        self.is_undirected = is_undirected
+        super().__init__(root, transform, pre_transform, force_reload=force_reload)
+        self.load(self.processed_paths[0])
+
+    @property
+    def raw_file_names(self) -> List[str]:
+        return ["data.json"]
+
+    @property
+    def processed_file_names(self) -> str:
+        return "data_undirected.pt" if self.is_undirected else "data.pt"
+
+    def download(self):
+        for name in self.raw_file_names:
+            fs.cp(f"{self.url}/{name}", self.raw_dir)
+
+    def process(self):
+        with open(self.raw_paths[0]) as f:
+            data = json.load(f)
+
+        x = np.array(data["features"], dtype=np.float32)
+        y = np.array(data["labels"], dtype=np.int64)
+
+        edges = [[(i, j) for j in js] for i, js in enumerate(data["links"])]
+        edges = list(chain(*edges))
+        edge_index = np.array(edges, dtype=np.int64).T
+        if self.is_undirected:
+            edge_index = to_undirected(edge_index, num_nodes=x.shape[0])
+
+        train_mask = np.array(data["train_masks"], dtype=bool).T
+        val_mask = np.array(data["val_masks"], dtype=bool).T
+        test_mask = np.array(data["test_mask"], dtype=bool)
+        stopping_mask = np.array(data["stopping_masks"], dtype=bool).T
+
+        data_obj = Data(
+            x=ops.convert_to_tensor(x, dtype="float32"),
+            y=ops.convert_to_tensor(y, dtype="int64"),
+            edge_index=ops.convert_to_tensor(edge_index, dtype="int64"),
+            train_mask=ops.convert_to_tensor(train_mask, dtype="bool"),
+            val_mask=ops.convert_to_tensor(val_mask, dtype="bool"),
+            test_mask=ops.convert_to_tensor(test_mask, dtype="bool"),
+            stopping_mask=ops.convert_to_tensor(stopping_mask, dtype="bool"),
+        )
+
+        if self.pre_transform is not None:
+            data_obj = self.pre_transform(data_obj)
+
+        self.save([data_obj], self.processed_paths[0])
+

k3_node/datasets/word_net.py

@@ -0,0 +1,184 @@
+from typing import Callable, List, Optional
+import numpy as np
+from keras import ops
+
+from k3_node.data import Data, InMemoryDataset
+from k3_node.io import fs
+
+
+class WordNet18(InMemoryDataset):
+    r"""The WordNet18 dataset containing 40,943 entities, 18 relations and 151,442 fact triplets."""
+
+    url = "https://raw.githubusercontent.com/villmow/datasets_knowledge_embedding/master/WN18/original"
+
+    def __init__(
+        self,
+        root: str,
+        transform: Optional[Callable] = None,
+        pre_transform: Optional[Callable] = None,
+        force_reload: bool = False,
+    ):
+        super().__init__(root, transform, pre_transform, force_reload=force_reload)
+        self.load(self.processed_paths[0])
+
+    @property
+    def raw_file_names(self) -> List[str]:
+        return ["train.txt", "valid.txt", "test.txt"]
+
+    @property
+    def processed_file_names(self) -> str:
+        return "data.pt"
+
+    def download(self):
+        for filename in self.raw_file_names:
+            fs.cp(f"{self.url}/{filename}", self.raw_dir)
+
+    def process(self):
+        srcs, dsts, edge_types = [], [], []
+        for path in self.raw_paths:
+            with open(path) as f:
+                edges = [int(x) for x in f.read().split()[1:]]
+                edge = np.array(edges, dtype=np.int64)
+                srcs.append(edge[::3])
+                dsts.append(edge[1::3])
+                edge_types.append(edge[2::3])
+
+        src = np.concatenate(srcs, axis=0)
+        dst = np.concatenate(dsts, axis=0)
+        edge_type = np.concatenate(edge_types, axis=0)
+
+        n_train = len(srcs[0])
+        n_val = len(srcs[1])
+        n_test = len(srcs[2])
+
+        train_mask = np.zeros(len(src), dtype=bool)
+        train_mask[:n_train] = True
+        val_mask = np.zeros(len(src), dtype=bool)
+        val_mask[n_train : n_train + n_val] = True
+        test_mask = np.zeros(len(src), dtype=bool)
+        test_mask[n_train + n_val :] = True
+
+        num_nodes = int(max(src.max(), dst.max())) + 1
+        perm = np.argsort(num_nodes * src + dst)
+
+        edge_index = np.stack([src[perm], dst[perm]], axis=0)
+        edge_type = edge_type[perm]
+        train_mask = train_mask[perm]
+        val_mask = val_mask[perm]
+        test_mask = test_mask[perm]
+
+        data = Data(
+            edge_index=ops.convert_to_tensor(edge_index, dtype="int64"),
+            edge_type=ops.convert_to_tensor(edge_type, dtype="int64"),
+            train_mask=ops.convert_to_tensor(train_mask, dtype="bool"),
+            val_mask=ops.convert_to_tensor(val_mask, dtype="bool"),
+            test_mask=ops.convert_to_tensor(test_mask, dtype="bool"),
+            num_nodes=num_nodes,
+        )
+
+        if self.pre_transform is not None:
+            data = self.pre_transform(data)
+
+        self.save([data], self.processed_paths[0])
+
+
+class WordNet18RR(InMemoryDataset):
+    r"""The WordNet18RR dataset."""
+
+    url = "https://raw.githubusercontent.com/villmow/datasets_knowledge_embedding/master/WN18RR/original"
+
+    edge2id = {
+        "_also_see": 0,
+        "_derivationally_related_form": 1,
+        "_has_part": 2,
+        "_hypernym": 3,
+        "_instance_hypernym": 4,
+        "_member_meronym": 5,
+        "_member_of_domain_region": 6,
+        "_member_of_domain_usage": 7,
+        "_similar_to": 8,
+        "_synset_domain_topic_of": 9,
+        "_verb_group": 10,
+    }
+
+    def __init__(
+        self,
+        root: str,
+        transform: Optional[Callable] = None,
+        pre_transform: Optional[Callable] = None,
+        force_reload: bool = False,
+    ):
+        super().__init__(root, transform, pre_transform, force_reload=force_reload)
+        self.load(self.processed_paths[0])
+
+    @property
+    def raw_file_names(self) -> List[str]:
+        return ["train.txt", "valid.txt", "test.txt"]
+
+    @property
+    def processed_file_names(self) -> str:
+        return "data.pt"
+
+    def download(self):
+        for filename in self.raw_file_names:
+            fs.cp(f"{self.url}/{filename}", self.raw_dir)
+
+    @staticmethod
+    def _node_id(node2id, name):
+        if name not in node2id:
+            node2id[name] = len(node2id)
+        return node2id[name]
+
+    def process(self):
+        # Entities are WordNet synset offsets; map them to consecutive ids, as PyG does
+        node2id = {}
+        srcs, dsts, edge_types = [], [], []
+        for path in self.raw_paths:
+            with open(path) as f:
+                lines = [line.split() for line in f.read().split("\n")[:-1]]
+                src, dst = [], []
+                for h, _, t in lines:
+                    src.append(self._node_id(node2id, h))
+                    dst.append(self._node_id(node2id, t))
+                rel = [self.edge2id[r] for _, r, _ in lines]
+                srcs.append(np.array(src, dtype=np.int64))
+                dsts.append(np.array(dst, dtype=np.int64))
+                edge_types.append(np.array(rel, dtype=np.int64))
+
+        src = np.concatenate(srcs, axis=0)
+        dst = np.concatenate(dsts, axis=0)
+        edge_type = np.concatenate(edge_types, axis=0)
+
+        n_train = len(srcs[0])
+        n_val = len(srcs[1])
+
+        train_mask = np.zeros(len(src), dtype=bool)
+        train_mask[:n_train] = True
+        val_mask = np.zeros(len(src), dtype=bool)
+        val_mask[n_train : n_train + n_val] = True
+        test_mask = np.zeros(len(src), dtype=bool)
+        test_mask[n_train + n_val :] = True
+
+        num_nodes = len(node2id)
+        perm = np.argsort(num_nodes * src + dst)
+
+        edge_index = np.stack([src[perm], dst[perm]], axis=0)
+        edge_type = edge_type[perm]
+        train_mask = train_mask[perm]
+        val_mask = val_mask[perm]
+        test_mask = test_mask[perm]
+
+        data = Data(
+            edge_index=ops.convert_to_tensor(edge_index, dtype="int64"),
+            edge_type=ops.convert_to_tensor(edge_type, dtype="int64"),
+            train_mask=ops.convert_to_tensor(train_mask, dtype="bool"),
+            val_mask=ops.convert_to_tensor(val_mask, dtype="bool"),
+            test_mask=ops.convert_to_tensor(test_mask, dtype="bool"),
+            num_nodes=num_nodes,
+        )
+
+        if self.pre_transform is not None:
+            data = self.pre_transform(data)
+
+        self.save([data], self.processed_paths[0])
+

k3_node/etl/__init__.py

@@ -0,0 +1,37 @@
+"""Tabular-to-Graph ETL (Extract, Transform, Load) pipelines for K3-Node."""
+
+from k3_node.etl.encoders import (
+    NumericalEncoder,
+    CategoricalEncoder,
+    TabularEncoder,
+)
+from k3_node.etl.graph_builders import (
+    KNNGraphBuilder,
+    SimilarityGraphBuilder,
+    SharedEntityGraphBuilder,
+    SequentialGraphBuilder,
+)
+from k3_node.etl.table_to_graph import (
+    TableToGraph,
+    TabularToGraph,
+    table_to_graph,
+)
+from k3_node.etl.relational_to_graph import (
+    RelationalToGraph,
+    relational_to_graph,
+)
+
+__all__ = [
+    "NumericalEncoder",
+    "CategoricalEncoder",
+    "TabularEncoder",
+    "KNNGraphBuilder",
+    "SimilarityGraphBuilder",
+    "SharedEntityGraphBuilder",
+    "SequentialGraphBuilder",
+    "TableToGraph",
+    "TabularToGraph",
+    "table_to_graph",
+    "RelationalToGraph",
+    "relational_to_graph",
+]

k3_node/etl/encoders.py

@@ -0,0 +1,248 @@
+"""Feature preprocessors and encoders for tabular data."""
+
+from typing import Any, Dict, List, Optional, Sequence, Union
+import numpy as np
+
+
+class NumericalEncoder:
+    r"""Encodes numerical tabular features with scaling and missing value imputation.
+
+    Args:
+        strategy: Scaling method (``"standard"``, ``"minmax"``, ``"log1p"``, or ``"none"``).
+            (default: ``"standard"``)
+        impute_strategy: How to fill missing values / NaNs (``"mean"``, ``"median"``,
+            ``"zero"``, or float constant). (default: ``"mean"``)
+    """
+
+    def __init__(self, strategy: str = "standard", impute_strategy: Union[str, float] = "mean"):
+        self.strategy = strategy.lower()
+        self.impute_strategy = impute_strategy
+        self.mean_: Optional[float] = None
+        self.std_: Optional[float] = None
+        self.min_: Optional[float] = None
+        self.max_: Optional[float] = None
+        self.fill_value_: float = 0.0
+
+    def fit(self, values: Sequence[Any]):
+        arr = np.asarray(values, dtype=np.float64).flatten()
+        valid = arr[~np.isnan(arr)]
+        if len(valid) == 0:
+            valid = np.array([0.0])
+
+        if self.impute_strategy == "mean":
+            self.fill_value_ = float(np.mean(valid))
+        elif self.impute_strategy == "median":
+            self.fill_value_ = float(np.median(valid))
+        elif self.impute_strategy == "min":
+            self.fill_value_ = float(np.min(valid))
+        elif self.impute_strategy == "zero":
+            self.fill_value_ = 0.0
+        elif isinstance(self.impute_strategy, (int, float)):
+            self.fill_value_ = float(self.impute_strategy)
+        else:
+            self.fill_value_ = float(np.mean(valid))
+
+        self.mean_ = float(np.mean(valid))
+        self.std_ = float(np.std(valid))
+        if self.std_ < 1e-8:
+            self.std_ = 1.0
+
+        self.min_ = float(np.min(valid))
+        self.max_ = float(np.max(valid))
+        if abs(self.max_ - self.min_) < 1e-8:
+            self.max_ = self.min_ + 1.0
+
+        return self
+
+    def transform(self, values: Sequence[Any]) -> np.ndarray:
+        arr = np.asarray(values, dtype=np.float32).flatten()
+        arr = np.nan_to_num(arr, nan=self.fill_value_)
+
+        if self.strategy == "standard":
+            mean = self.mean_ if self.mean_ is not None else 0.0
+            std = self.std_ if self.std_ is not None else 1.0
+            res = (arr - mean) / std
+        elif self.strategy == "minmax":
+            vmin = self.min_ if self.min_ is not None else 0.0
+            vmax = self.max_ if self.max_ is not None else 1.0
+            res = np.clip((arr - vmin) / (vmax - vmin), 0.0, 1.0)
+        elif self.strategy == "log1p":
+            res = np.log1p(np.maximum(arr, 0.0))
+        elif self.strategy == "none":
+            res = arr
+        else:
+            raise ValueError(f"Unknown numerical strategy '{self.strategy}'.")
+
+        return res.reshape(-1, 1)
+
+    def fit_transform(self, values: Sequence[Any]) -> np.ndarray:
+        return self.fit(values).transform(values)
+
+
+class CategoricalEncoder:
+    r"""Encodes categorical strings or integer values into one-hot or ordinal representations.
+
+    Args:
+        strategy: Encoding method (``"onehot"``, ``"ordinal"``, or ``"hash"``).
+            (default: ``"onehot"``)
+        handle_unknown: How to handle unseen categories during transform (``"ignore"``,
+            ``"error"``, or ``"use_encoded_value"``). (default: ``"ignore"``)
+        unknown_value: Numerical value assigned to unseen categories when using ordinal encoding.
+            (default: ``-1``)
+        hash_dim: Output dimension when using ``"hash"`` strategy. (default: ``16``)
+    """
+
+    def __init__(
+        self,
+        strategy: str = "onehot",
+        handle_unknown: str = "ignore",
+        unknown_value: int = -1,
+        hash_dim: int = 16,
+    ):
+        self.strategy = strategy.lower()
+        self.handle_unknown = handle_unknown.lower()
+        self.unknown_value = unknown_value
+        self.hash_dim = hash_dim
+        self.vocab_: Dict[Any, int] = {}
+        self.inv_vocab_: List[Any] = []
+
+    def fit(self, values: Sequence[Any]):
+        arr = [str(v) if v is not None and not (isinstance(v, float) and np.isnan(v)) else "__MISSING__" for v in values]
+        unique_cats = sorted(list(set(arr)))
+        self.vocab_ = {cat: idx for idx, cat in enumerate(unique_cats)}
+        self.inv_vocab_ = unique_cats
+        return self
+
+    def transform(self, values: Sequence[Any]) -> np.ndarray:
+        arr = [str(v) if v is not None and not (isinstance(v, float) and np.isnan(v)) else "__MISSING__" for v in values]
+        num_samples = len(arr)
+
+        if self.strategy == "onehot":
+            num_classes = len(self.vocab_)
+            if num_classes == 0:
+                return np.zeros((num_samples, 1), dtype=np.float32)
+            out = np.zeros((num_samples, num_classes), dtype=np.float32)
+            for i, val in enumerate(arr):
+                if val in self.vocab_:
+                    out[i, self.vocab_[val]] = 1.0
+                elif self.handle_unknown == "error":
+                    raise ValueError(f"Encountered unknown category: '{val}'")
+            return out
+
+        elif self.strategy == "ordinal":
+            out = np.zeros((num_samples, 1), dtype=np.int64)
+            for i, val in enumerate(arr):
+                if val in self.vocab_:
+                    out[i, 0] = self.vocab_[val]
+                elif self.handle_unknown == "error":
+                    raise ValueError(f"Encountered unknown category: '{val}'")
+                else:
+                    out[i, 0] = self.unknown_value
+            return out
+
+        elif self.strategy == "hash":
+            out = np.zeros((num_samples, self.hash_dim), dtype=np.float32)
+            for i, val in enumerate(arr):
+                h = abs(hash(val)) % self.hash_dim
+                out[i, h] = 1.0
+            return out
+
+        else:
+            raise ValueError(f"Unknown categorical strategy '{self.strategy}'.")
+
+    def fit_transform(self, values: Sequence[Any]) -> np.ndarray:
+        return self.fit(values).transform(values)
+
+
+class TabularEncoder:
+    r"""Column-wise encoder aggregating multiple numerical and categorical column encoders.
+
+    Args:
+        column_encoders: Optional dictionary mapping column names to :class:`NumericalEncoder`
+            or :class:`CategoricalEncoder` instances.
+        default_numerical_strategy: Strategy used for detected numerical columns without an explicit encoder.
+            (default: ``"standard"``)
+        default_categorical_strategy: Strategy used for detected categorical columns without an explicit encoder.
+            (default: ``"onehot"``)
+    """
+
+    def __init__(
+        self,
+        column_encoders: Optional[Dict[str, Union[NumericalEncoder, CategoricalEncoder]]] = None,
+        default_numerical_strategy: str = "standard",
+        default_categorical_strategy: str = "onehot",
+    ):
+        self.column_encoders = column_encoders or {}
+        self.default_numerical_strategy = default_numerical_strategy
+        self.default_categorical_strategy = default_categorical_strategy
+        self.fitted_encoders_: Dict[str, Union[NumericalEncoder, CategoricalEncoder]] = {}
+        self.column_order_: List[str] = []
+
+    def fit(self, df_or_dict: Any, columns: Optional[List[str]] = None):
+        columns = columns or _get_column_names(df_or_dict)
+        self.column_order_ = list(columns)
+        self.fitted_encoders_ = {}
+
+        for col in self.column_order_:
+            vals = _get_column_values(df_or_dict, col)
+            if col in self.column_encoders:
+                enc = self.column_encoders[col]
+            else:
+                if _is_numerical_series(vals):
+                    enc = NumericalEncoder(strategy=self.default_numerical_strategy)
+                else:
+                    enc = CategoricalEncoder(strategy=self.default_categorical_strategy)
+            enc.fit(vals)
+            self.fitted_encoders_[col] = enc
+
+        return self
+
+    def transform(self, df_or_dict: Any) -> np.ndarray:
+        parts = []
+        for col in self.column_order_:
+            vals = _get_column_values(df_or_dict, col)
+            enc = self.fitted_encoders_[col]
+            encoded = enc.transform(vals)
+            parts.append(encoded)
+
+        if not parts:
+            num_rows = len(_get_column_values(df_or_dict, list(self.column_encoders.keys())[0])) if self.column_encoders else 0
+            return np.zeros((num_rows, 0), dtype=np.float32)
+
+        return np.concatenate(parts, axis=1).astype(np.float32)
+
+    def fit_transform(self, df_or_dict: Any, columns: Optional[List[str]] = None) -> np.ndarray:
+        return self.fit(df_or_dict, columns=columns).transform(df_or_dict)
+
+
+def _get_column_names(df_or_dict: Any) -> List[str]:
+    if hasattr(df_or_dict, "columns"):
+        return list(df_or_dict.columns)
+    elif isinstance(df_or_dict, dict):
+        return list(df_or_dict.keys())
+    raise TypeError(f"Expected pandas DataFrame or dictionary of columns, got {type(df_or_dict)}")
+
+
+def _get_column_values(df_or_dict: Any, col: str) -> List[Any]:
+    if hasattr(df_or_dict, "__getitem__"):
+        series = df_or_dict[col]
+        if hasattr(series, "tolist"):
+            return series.tolist()
+        elif hasattr(series, "to_numpy"):
+            return series.to_numpy().tolist()
+        elif isinstance(series, np.ndarray):
+            return series.tolist()
+        return list(series)
+    raise TypeError(f"Cannot extract column '{col}' from object of type {type(df_or_dict)}")
+
+
+def _is_numerical_series(vals: Sequence[Any]) -> bool:
+    count_num = 0
+    total = 0
+    for v in vals:
+        if v is None or (isinstance(v, float) and np.isnan(v)):
+            continue
+        total += 1
+        if isinstance(v, (int, float, np.integer, np.floating)) and not isinstance(v, bool):
+            count_num += 1
+    return total > 0 and (count_num / total) > 0.8