Tabular-to-Graph ETL API Reference

k3_node.etl.table_to_graph.TableToGraph

ETL pipeline converting tabular datasets (DataFrames, CSVs, or dictionaries) into graph :class:k3_node.data.Data objects with node features, graph topology, labels, and split masks.

Parameters:

Name	Type	Description	Default
feature_cols	Optional[List[str]]	List of column names used as node features. If :obj:None, all columns except :obj:target_col and :obj:id_col are used.	None
target_col	str	Target column used to create ground-truth labels :obj:y.	None
id_col	str	Unique row identifier column (e.g. customer_id, product_id). Stored in :obj:data.node_ids and :obj:data.id_to_index.	None
edge_strategy	str or callable	Strategy for constructing edges ("knn", "similarity", "shared_entity", "sequential", or a custom callable). (default: "knn")	'knn'
edge_kwargs	dict	Keyword arguments forwarded to the edge builder. (e.g., {"k": 5, "metric": "cosine"} for KNN).	None
column_encoders	dict	Explicit mapping from column names to encoder instances.	None
train_ratio	float	Fraction of nodes for training mask. (default: None)	None
val_ratio	float	Fraction of nodes for validation mask. (default: None)	None
test_ratio	float	Fraction of nodes for test mask. (default: None)	None
random_state	int	Random seed for mask splits. (default: 42)	42

fit(df_or_dict)

Fits the tabular feature encoder on the input table.

fit_transform(df_or_dict)

Fits encoders and transforms tabular data into a graph in a single call.

from_csv(filepath, feature_cols=None, target_col=None, id_col=None, edge_strategy='knn', **kwargs) classmethod

Convenience factory method directly loading a CSV file and converting it into a :class:Data object.

from_dataframe(df, feature_cols=None, target_col=None, id_col=None, edge_strategy='knn', **kwargs) classmethod

Convenience factory method directly converting a pandas DataFrame into a :class:Data object.

transform(df_or_dict)

Encodes features, constructs graph edges, and builds a :class:Data object.

k3_node.etl.relational_to_graph.RelationalToGraph

ETL pipeline converting multi-table relational databases / DataFrames into a heterogeneous graph :class:k3_node.data.HeteroData object.

Parameters:

Name	Type	Description	Default
id_cols	dict	Mapping from :obj:NodeType to the primary key column name. (e.g., {"user": "user_id", "movie": "movie_id"}).	required
edge_cols	dict	Mapping from :obj:EdgeType to the tuple of foreign key column names (source_id_col, target_id_col). (e.g., {("user", "rates", "movie"): ("user_id", "movie_id")}).	required
feature_cols	dict	Mapping from :obj:NodeType to a list of feature columns. If omitted, all columns except the primary key are encoded.	None
edge_attr_cols	dict	Mapping from :obj:EdgeType to a list of edge attribute columns.	None
node_target_cols	dict	Mapping from :obj:NodeType to the target label column.	None
edge_target_cols	dict	Mapping from :obj:EdgeType to the target edge label column.	None

fit(nodes, edges=None)

Fits encoders and builds entity ID mappings across all tables.

fit_transform(nodes, edges=None)

Fits encoders and builds the heterogeneous graph in a single call.

transform(nodes, edges=None)

Constructs a :class:k3_node.data.HeteroData instance from relational tables.

k3_node.etl.encoders.NumericalEncoder

Encodes numerical tabular features with scaling and missing value imputation.

Parameters:

Name	Type	Description	Default
strategy	str	Scaling method ("standard", "minmax", "log1p", or "none"). (default: "standard")	'standard'
impute_strategy	Union[str, float]	How to fill missing values / NaNs ("mean", "median", "zero", or float constant). (default: "mean")	'mean'

k3_node.etl.encoders.CategoricalEncoder

Encodes categorical strings or integer values into one-hot or ordinal representations.

Parameters:

Name	Type	Description	Default
strategy	str	Encoding method ("onehot", "ordinal", or "hash"). (default: "onehot")	'onehot'
handle_unknown	str	How to handle unseen categories during transform ("ignore", "error", or "use_encoded_value"). (default: "ignore")	'ignore'
unknown_value	int	Numerical value assigned to unseen categories when using ordinal encoding. (default: -1)	-1
hash_dim	int	Output dimension when using "hash" strategy. (default: 16)	16

k3_node.etl.encoders.TabularEncoder

Column-wise encoder aggregating multiple numerical and categorical column encoders.

Parameters:

Name	Type	Description	Default
column_encoders	Optional[Dict[str, Union[NumericalEncoder, CategoricalEncoder]]]	Optional dictionary mapping column names to :class:NumericalEncoder or :class:CategoricalEncoder instances.	None
default_numerical_strategy	str	Strategy used for detected numerical columns without an explicit encoder. (default: "standard")	'standard'
default_categorical_strategy	str	Strategy used for detected categorical columns without an explicit encoder. (default: "onehot")	'onehot'

k3_node.etl.graph_builders.KNNGraphBuilder

Constructs a k-nearest-neighbors graph from a node feature matrix.

Parameters:

Name	Type	Description	Default
k	int	Number of nearest neighbors per node. (default: 5)	5
metric	str	Distance metric ("cosine", "euclidean", or "manhattan"). (default: "cosine")	'cosine'
loop	bool	Whether to include self-loops. (default: False)	False
bidirectional	bool	Whether to make the resulting graph undirected. (default: True)	True

k3_node.etl.graph_builders.SimilarityGraphBuilder

Constructs a graph connecting node pairs whose pairwise similarity exceeds a threshold.

Parameters:

Name	Type	Description	Default
threshold	float	Minimum similarity required to create an edge. (default: 0.7)	0.7
metric	str	Similarity function ("cosine" or "rbf"). (default: "cosine")	'cosine'
gamma	float	Bandwidth parameter for RBF kernel. (default: 1.0)	1.0
loop	bool	Whether to include self-loops. (default: False)	False

k3_node.etl.graph_builders.SharedEntityGraphBuilder

Connects tabular rows that share one or more categorical identifier values. (e.g., users sharing the same IP address, device, category, or cluster).

Parameters:

Name	Type	Description	Default
entity_cols	Sequence[str]	List of column names to check for shared values.	required
max_degree	int	Maximum number of neighbors created per shared entity (to avoid supernode explosion). (default: 50)	50
loop	bool	Whether to include self-loops. (default: False)	False

k3_node.etl.graph_builders.SequentialGraphBuilder

Connects tabular rows sequentially in order of an index or timestamp column, optionally partitioned by a group entity column.

Parameters:

Name	Type	Description	Default
order_col	Optional[str]	Optional column name used to sort rows (e.g. timestamp or sequence index).	None
group_by_col	Optional[str]	Optional column name to partition sequences (e.g. user_id or session_id).	None
window_size	int	Number of forward/backward sequential steps to connect. (default: 1)	1
bidirectional	bool	Whether to create undirected edges. (default: True)	True