API Reference

This page is generated automatically from the docstrings in the row2vec package, so it always matches the installed code.

Row2Vec: A library for learning embeddings from tabular data.

This library provides both neural network and classical machine learning approaches for creating vector embeddings from tabular datasets.

ArchitectureSearchConfig dataclass

ArchitectureSearchConfig(method: str = 'random', max_trials: int = 30, max_time: float | None = 1800, patience: int = 10, min_improvement: float = 0.01, layer_range: tuple[int, int] = (1, 4), max_layers: int = 4, width_options: list[int] = (lambda: [32, 64, 128, 256, 512])(), dropout_options: list[float] = (lambda: [0.0, 0.1, 0.2, 0.3, 0.4, 0.5])(), activation_options: list[str] = (lambda: ['relu', 'elu', 'swish'])(), initial_epochs: int = 10, intermediate_epochs: int = 25, final_epochs: int = 50, top_k_intermediate: int = 10, top_k_final: int = 3, reconstruction_weight: float = 0.4, clustering_weight: float = 0.3, efficiency_weight: float = 0.2, stability_weight: float = 0.1, verbose: bool = True, random_seed: int | None = None, return_full_history: bool = False)

Configuration for automatic neural architecture search.

This class defines the search space, evaluation criteria, and stopping conditions for finding optimal neural network architectures.

ArchitectureSearcher

ArchitectureSearcher(config: ArchitectureSearchConfig)

Main class for performing neural architecture search.

Implements multiple search strategies to find optimal neural network architectures for embedding generation tasks.

search

search(df: DataFrame, base_config: EmbeddingConfig, target_column: str | None = None) -> ArchitectureSearchResult

Perform architecture search on the given dataset.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input dataframe for embedding generation	required
base_config	EmbeddingConfig	Base embedding configuration	required
target_column	str | None	Optional target column for supervised evaluation	None

Returns:

Type	Description
ArchitectureSearchResult	ArchitectureSearchResult containing the best architecture and metadata

ArchitectureSearchResult

ArchitectureSearchResult(best_architecture: dict[str, Any], best_score: float, search_history: list[dict[str, Any]], total_time: float, trials_completed: int)

Container for architecture search results.

summary

summary() -> dict[str, Any]

Get a summary of the search results.

AutoDimensionSelector

AutoDimensionSelector(methods: list[str] | None = None, performance_weight: float = 0.4, efficiency_weight: float = 0.3, intrinsic_weight: float = 0.3, max_dimension: int | None = None, min_dimension: int = 2, n_trials: int = 5, verbose: bool = True)

Automatically selects optimal embedding dimensions using multiple strategies.

Combines data-driven analysis, performance optimization, and heuristic rules to determine the best embedding dimension for a given dataset.

Initialize automatic dimension selector.

Parameters:

Name	Type	Description	Default
methods	list[str] | None	List of selection methods to use	None
performance_weight	float	Weight for performance-based selection	0.4
efficiency_weight	float	Weight for efficiency considerations	0.3
intrinsic_weight	float	Weight for intrinsic dimensionality estimation	0.3
max_dimension	int | None	Maximum dimension to consider (auto if None)	None
min_dimension	int	Minimum dimension to consider	2
n_trials	int	Number of trials for performance evaluation	5
verbose	bool	Whether to show selection progress	True

select_dimension

select_dimension(df: DataFrame, config: EmbeddingConfig, target_column: str | None = None, candidate_dims: list[int] | None = None) -> tuple[int, dict[str, Any]]

Select optimal embedding dimension for the given data.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input dataframe	required
config	EmbeddingConfig	Base embedding configuration (dimension will be overridden)	required
target_column	str | None	Optional target for supervised evaluation	None
candidate_dims	list[int] | None	Specific dimensions to evaluate (auto-generated if None)	None

Returns:

Type	Description
tuple[int, dict[str, Any]]	Tuple of (optimal_dimension, selection_metadata)

CategoricalAnalyzer

CategoricalAnalyzer(config: CategoricalEncodingConfig)

Analyzes categorical data to recommend optimal encoding strategies.

analyze_column

analyze_column(series: Series, target: Series | None = None) -> dict[str, Any]

Analyze a categorical column to recommend encoding strategy.

Parameters:

Name	Type	Description	Default
series	Series	Categorical column to analyze	required
target	Series	Target variable for correlation analysis	None

Returns:

Type	Description
dict[str, Any]	Dict[str, Any] Analysis results and strategy recommendation

CategoricalEncoder

CategoricalEncoder(config: CategoricalEncodingConfig | None = None)

Bases: BaseEstimator, TransformerMixin

Intelligent categorical encoder with adaptive strategy selection.

This encoder analyzes categorical data characteristics and automatically selects optimal encoding strategies while providing full control for advanced users.

fit

fit(X: DataFrame, y: Series | None = None) -> CategoricalEncoder

Fit the categorical encoder on training data.

Parameters:

Name	Type	Description	Default
X	DataFrame	Categorical features to encode	required
y	Series	Target variable for supervised encoding strategies	None

Returns:

Name	Type	Description
self	CategoricalEncoder	Fitted encoder instance

transform

transform(X: DataFrame) -> pd.DataFrame

Transform categorical data using fitted encoders.

Parameters:

Name	Type	Description	Default
X	DataFrame	Categorical data to transform	required

Returns:

Type	Description
DataFrame	pd.DataFrame Encoded categorical data

get_feature_names_out

get_feature_names_out(input_features: list[str] | None = None) -> list[str]

Get output feature names for transformation.

get_analysis_report

get_analysis_report() -> dict[str, dict[str, Any]]

Get detailed analysis report for all columns.

CategoricalEncodingConfig dataclass

CategoricalEncodingConfig(encoding_strategy: str = 'adaptive', onehot_threshold: int = 20, target_threshold: int = 100, entity_threshold: int = 1000, correlation_threshold: float = 0.1, target_smoothing: float = 1.0, target_noise: float = 0.01, target_cv_folds: int = 5, embedding_dim_ratio: float = 0.5, min_embedding_dim: int = 2, max_embedding_dim: int = 50, entity_epochs: int = 50, entity_batch_size: int = 256, prefer_speed: bool = True, preserve_interpretability: bool = False, enable_feature_selection: bool = False, feature_importance_threshold: float = 0.01, custom_strategies: dict[str, str] = dict(), handle_unknown: str = 'ignore', random_state: int = 42)

Configuration for intelligent categorical encoding strategies.

This class provides comprehensive control over how categorical variables are encoded, with intelligent defaults that automatically select optimal strategies based on data characteristics while allowing expert users to fine-tune every aspect.

encoding_strategy class-attribute instance-attribute

encoding_strategy: str = 'adaptive'

Encoding strategy selection. Options: - "adaptive": Automatically selects best strategy based on data analysis - "onehot": One-hot encoding for all categorical features - "target": Target encoding for all categorical features - "entity": Entity embeddings for all categorical features - "ordinal": Ordinal encoding (assumes natural order) - "mixed": Use custom strategies per column (requires custom_strategies)

onehot_threshold class-attribute instance-attribute

onehot_threshold: int = 20

Use OneHot encoding if cardinality <= this threshold and correlation is low.

target_threshold class-attribute instance-attribute

target_threshold: int = 100

Use target encoding if cardinality is between onehot_threshold and this value.

entity_threshold class-attribute instance-attribute

entity_threshold: int = 1000

Use entity embeddings if cardinality > target_threshold and <= this value.

correlation_threshold class-attribute instance-attribute

correlation_threshold: float = 0.1

Minimum mutual information score to prefer target/entity over onehot.

target_smoothing class-attribute instance-attribute

target_smoothing: float = 1.0

Bayesian smoothing factor for target encoding. Higher values = more smoothing.

target_noise class-attribute instance-attribute

target_noise: float = 0.01

Gaussian noise standard deviation added to target encodings to prevent overfitting.

target_cv_folds class-attribute instance-attribute

target_cv_folds: int = 5

Number of cross-validation folds for target encoding to prevent data leakage.

embedding_dim_ratio class-attribute instance-attribute

embedding_dim_ratio: float = 0.5

Embedding dimension as ratio of sqrt(cardinality). Controls embedding size.

min_embedding_dim class-attribute instance-attribute

min_embedding_dim: int = 2

Minimum embedding dimension for entity embeddings.

max_embedding_dim class-attribute instance-attribute

max_embedding_dim: int = 50

Maximum embedding dimension for entity embeddings.

entity_epochs class-attribute instance-attribute

entity_epochs: int = 50

Number of training epochs for entity embedding networks.

entity_batch_size class-attribute instance-attribute

entity_batch_size: int = 256

Batch size for entity embedding training.

prefer_speed class-attribute instance-attribute

prefer_speed: bool = True

Whether to prefer faster methods over more accurate but slower ones.

preserve_interpretability class-attribute instance-attribute

preserve_interpretability: bool = False

Whether to prefer interpretable encodings (OneHot/Ordinal) when possible.

enable_feature_selection class-attribute instance-attribute

enable_feature_selection: bool = False

Whether to enable automatic feature selection based on importance.

feature_importance_threshold class-attribute instance-attribute

feature_importance_threshold: float = 0.01

Minimum feature importance score to keep feature (only if enable_feature_selection=True).

custom_strategies class-attribute instance-attribute

custom_strategies: dict[str, str] = field(default_factory=dict)

Custom encoding strategy for specific columns. Format: {column_name: strategy}

handle_unknown class-attribute instance-attribute

handle_unknown: str = 'ignore'

How to handle unknown categories. Options: 'ignore', 'error', 'infrequent_if_exist'

random_state class-attribute instance-attribute

random_state: int = 42

Random state for reproducible results.

EntityEmbeddingTrainer

EntityEmbeddingTrainer(config: CategoricalEncodingConfig)

Trains entity embeddings for high-cardinality categorical features.

fit_column_embedding

fit_column_embedding(series: Series, target: Series | None = None, embedding_dim: int = 10) -> NDArray[Any]

Train entity embeddings for a categorical column.

Parameters:

Name	Type	Description	Default
series	Series	Categorical column to embed	required
target	Series	Target variable for supervised embedding	None
embedding_dim	int	Dimension of embedding vectors	10

Returns:

Type	Description
NDArray[Any]	np.ndarray Trained embedding matrix of shape (cardinality, embedding_dim)

TargetEncoder

TargetEncoder(config: CategoricalEncodingConfig)

Implements Bayesian target encoding with cross-validation.

fit_transform

fit_transform(series: Series, target: Series) -> pd.Series

Fit target encoder and transform the series.

Parameters:

Name	Type	Description	Default
series	Series	Categorical column to encode	required
target	Series	Target variable	required

Returns:

Type	Description
Series	pd.Series Target-encoded values

transform

transform(series: Series) -> pd.Series

Transform new data using fitted encodings.

ClassicalConfig dataclass

ClassicalConfig(n_neighbors: int = 15, min_dist: float = 0.1, perplexity: float = 30.0, n_iter: int = 1000)

Configuration for classical ML dimensionality reduction methods.

ContrastiveConfig dataclass

ContrastiveConfig(loss_type: str = 'triplet', similar_pairs: list[tuple[int, int]] | None = None, dissimilar_pairs: list[tuple[int, int]] | None = None, auto_pairs: str | None = None, margin: float = 1.0, negative_samples: int = 5)

Configuration for contrastive learning.

EmbeddingConfig dataclass

EmbeddingConfig(embedding_dim: int = 10, mode: str = 'unsupervised', reference_column: str | None = None, seed: int = 1305, verbose: bool = False, neural: NeuralConfig = NeuralConfig(), classical: ClassicalConfig = ClassicalConfig(), contrastive: ContrastiveConfig = ContrastiveConfig(), scaling: ScalingConfig = ScalingConfig(), logging: LoggingConfig = LoggingConfig(), preprocessing: PreprocessingConfig = PreprocessingConfig())

Complete configuration for embedding learning.

from_dict classmethod

from_dict(config_dict: dict[str, Any]) -> EmbeddingConfig

Create config from dictionary (e.g., from YAML).

from_yaml classmethod

from_yaml(yaml_path: str | Path) -> EmbeddingConfig

Create config from YAML file.

to_dict

to_dict() -> dict[str, Any]

Convert config to dictionary.

to_yaml

to_yaml(yaml_path: str | Path) -> None

Save config to YAML file.

LoggingConfig dataclass

LoggingConfig(level: str = 'INFO', file: str | None = None, enabled: bool = True)

Configuration for logging and output.

NeuralConfig dataclass

NeuralConfig(max_epochs: int = 50, batch_size: int = 64, dropout_rate: float = 0.2, hidden_units: int | list[int] = 128, activation: str = 'relu', early_stopping: bool = True)

Configuration for neural network-based embedding methods.

PreprocessingConfig dataclass

PreprocessingConfig(handle_missing: str = 'auto', numeric_scaling: str = 'standard', categorical_encoding_strategy: str = 'adaptive', categorical_onehot_threshold: int = 20, categorical_target_threshold: int = 100, categorical_entity_threshold: int = 1000)

Configuration for data preprocessing including categorical encoding.

ScalingConfig dataclass

ScalingConfig(method: str | None = None, range: tuple[float, float] | None = None)

Configuration for embedding scaling/normalization.

AdaptiveImputer

AdaptiveImputer(config: ImputationConfig)

Bases: BaseEstimator

Adaptive imputer that automatically selects and applies appropriate imputation strategies based on data characteristics.

fit

fit(X: DataFrame, y: Any = None) -> AdaptiveImputer

Fit the adaptive imputer to the data.

Parameters:

Name	Type	Description	Default
X	DataFrame	Input DataFrame with potential missing values	required
y	Any	Ignored, present for API compatibility	None

Returns:

Name	Type	Description
self	AdaptiveImputer	Fitted imputer

transform

transform(X: DataFrame) -> pd.DataFrame

Transform the data by applying imputation strategies.

Parameters:

Name	Type	Description	Default
X	DataFrame	Input DataFrame with potential missing values	required

Returns:

Type	Description
DataFrame	DataFrame with missing values imputed

fit_transform

fit_transform(X: DataFrame, y: Any = None, **fit_params: Any) -> pd.DataFrame

Fit the imputer and transform the data in one step.

get_imputation_report

get_imputation_report() -> dict[str, Any]

Get detailed report about the imputation process.

Returns:

Type	Description
dict[str, Any]	Dict containing analysis and imputation details

ImputationConfig dataclass

ImputationConfig(numeric_strategy: str = 'adaptive', categorical_strategy: str = 'adaptive', prefer_speed: bool = True, missing_threshold: float = 0.7, row_missing_threshold: float = 0.9, knn_neighbors: int = 5, preserve_missing_patterns: bool = False, missing_indicator_suffix: str = '_was_missing', auto_detect_patterns: bool = True, warn_high_missingness: bool = True, categorical_fill_value: str = 'Missing')

Configuration for intelligent missing value imputation strategies.

This class provides comprehensive control over how missing values are handled, with sensible defaults that work well for most datasets while allowing power users to fine-tune every aspect of the imputation process.

numeric_strategy class-attribute instance-attribute

numeric_strategy: str = 'adaptive'

Numeric imputation strategy. Options: - "adaptive": Automatically selects best strategy based on missing percentage - "mean": Mean imputation (fastest, good for <10% missing) - "median": Median imputation (robust to outliers, good for 10-30% missing) - "knn": K-nearest neighbors imputation (better for >30% missing) - "iterative": MICE-style iterative imputation (best quality, slowest)

categorical_strategy class-attribute instance-attribute

categorical_strategy: str = 'adaptive'

Categorical imputation strategy. Options: - "adaptive": Automatically selects best strategy based on data characteristics - "mode": Most frequent value imputation - "constant": Fill with specified constant value - "missing_category": Create explicit "Missing" category

prefer_speed class-attribute instance-attribute

prefer_speed: bool = True

Whether to prefer faster methods over more accurate but slower ones. When True, uses simpler strategies by default. When False, prefers more sophisticated methods even if they take longer.

missing_threshold class-attribute instance-attribute

missing_threshold: float = 0.7

Columns with more than this fraction of missing values will be flagged. Conservative default of 0.7 to avoid dropping useful but sparse columns.

row_missing_threshold class-attribute instance-attribute

row_missing_threshold: float = 0.9

Rows with more than this fraction of missing values will be flagged. Very conservative default to avoid losing data.

knn_neighbors class-attribute instance-attribute

knn_neighbors: int = 5

Number of neighbors for KNN imputation. Should be odd to avoid ties.

preserve_missing_patterns class-attribute instance-attribute

preserve_missing_patterns: bool = False

Whether to preserve missing patterns when they might be informative.

When True, adds binary indicator columns for originally missing values. This is useful when missingness itself carries information (e.g., customers not providing income information might be systematically different).

Example

Original: [1.0, NaN, 3.0] -> After imputation: [1.0, 2.0, 3.0] With preservation: adds column [False, True, False] indicating missingness

missing_indicator_suffix class-attribute instance-attribute

missing_indicator_suffix: str = '_was_missing'

Suffix for missing indicator columns when preserve_missing_patterns=True.

auto_detect_patterns class-attribute instance-attribute

auto_detect_patterns: bool = True

Whether to automatically analyze missing data patterns and adjust strategies.

warn_high_missingness class-attribute instance-attribute

warn_high_missingness: bool = True

Whether to warn users about columns/rows with high missing percentages.

categorical_fill_value class-attribute instance-attribute

categorical_fill_value: str = 'Missing'

Fill value when using 'constant' strategy for categorical data.

MissingPatternAnalyzer

MissingPatternAnalyzer(config: ImputationConfig)

Analyzes missing data patterns to inform imputation strategy selection.

analyze

analyze(df: DataFrame) -> dict[str, Any]

Analyze missing data patterns in the DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input DataFrame to analyze	required

Returns:

Type	Description
dict[str, Any]	Dict containing analysis results and recommendations

Row2VecLogger

Row2VecLogger(name: str = 'row2vec', level: str = 'INFO', log_file: str | Path | None = None, include_performance: bool = True, include_memory: bool = True)

Centralized logging system for Row2Vec operations.

Provides structured logging for training progress, debug information, and performance metrics with configurable output formats and levels.

Initialize Row2Vec logger.

Parameters:

Name	Type	Description	Default
name	str	Logger name	'row2vec'
level	str	Logging level (DEBUG, INFO, WARNING, ERROR)	'INFO'
log_file	str | Path | None	Optional file path for logging output	None
include_performance	bool	Whether to include performance metrics	True
include_memory	bool	Whether to include memory usage tracking	True

start_training

start_training(**kwargs: Any) -> None

Log training start with configuration details.

start_epoch

start_epoch(epoch: int, total_epochs: int) -> None

Log epoch start.

log_epoch_metrics

log_epoch_metrics(epoch: int, loss: float, val_loss: float | None = None, additional_metrics: dict[str, float] | None = None) -> None

Log epoch completion with metrics.

log_early_stopping

log_early_stopping(epoch: int, reason: str) -> None

Log early stopping event.

end_training

end_training(final_loss: float, total_epochs: int) -> None

Log training completion with summary.

log_data_preprocessing

log_data_preprocessing(df_shape: tuple[int, int], processing_steps: list[str]) -> None

Log data preprocessing information.

log_preprocessing_result

log_preprocessing_result(original_shape: tuple[int, int], processed_shape: tuple[int, int], processing_time: float) -> None

Log preprocessing completion.

log_model_architecture

log_model_architecture(model_summary: str) -> None

Log model architecture details.

log_embedding_stats

log_embedding_stats(embeddings: DataFrame) -> None

Log embedding statistics.

log_performance_warning

log_performance_warning(message: str) -> None

Log performance-related warnings.

log_validation_issue

log_validation_issue(message: str) -> None

Log validation or data quality issues.

log_debug_info

log_debug_info(message: str, data: dict[str, Any] | None = None) -> None

Log debug information with optional data context.

log_error

log_error(error: Exception, context: str | None = None) -> None

Log error with context information.

log_completion

log_completion(message: str = 'Embedding generation completed successfully!') -> None

Log completion of embedding generation.

PipelineBuilder

PipelineBuilder(config: EmbeddingConfig | None = None)

Intelligent pipeline builder that analyzes data and constructs optimal preprocessing pipelines with adaptive strategies.

build_preprocessing_pipeline

build_preprocessing_pipeline(df: DataFrame, target: Series | None = None, mode: str = 'unsupervised') -> tuple[ColumnTransformer, dict[str, Any]]

Build intelligent preprocessing pipeline based on data analysis.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input dataset to analyze	required
target	Series	Target variable for supervised preprocessing	None
mode	str	Embedding mode that influences preprocessing strategy	'unsupervised'

Returns:

Type	Description
tuple[ColumnTransformer, dict[str, Any]]	Tuple[ColumnTransformer, Dict[str, Any]] Fitted preprocessing pipeline and analysis report

get_analysis_report

get_analysis_report() -> dict[str, Any]

Get detailed analysis report of the dataset.

get_pipeline_description

get_pipeline_description() -> dict[str, Any]

Get human-readable description of the constructed pipeline.

Row2VecModel

Row2VecModel(model: Any | BaseEstimator | None = None, preprocessor: ColumnTransformer | None = None, metadata: Row2VecModelMetadata | None = None)

Complete Row2Vec model with preprocessing pipeline and metadata.

This class encapsulates the trained model, preprocessing pipeline, and all metadata needed for inference.

validate_input_schema

validate_input_schema(df: DataFrame, strict: bool = True) -> bool

Validate input DataFrame schema against expected schema.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input DataFrame to validate	required
strict	bool	If True, fails on any schema mismatch. If False, warns only.	True

Returns:

Name	Type	Description
bool	bool	True if schema is valid

Raises:

Type	Description
ValueError	If strict=True and schema validation fails

predict

predict(df: DataFrame, validate_schema: bool = True) -> pd.DataFrame

Generate embeddings for new data.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input DataFrame	required
validate_schema	bool	Whether to validate input schema	True

Returns:

Type	Description
DataFrame	DataFrame with embeddings

Raises:

Type	Description
ValueError	If model is not loaded or schema validation fails

Row2VecModelMetadata

Row2VecModelMetadata(embedding_dim: int, mode: str, reference_column: str | None = None, max_epochs: int = 50, batch_size: int = 64, dropout_rate: float = 0.2, hidden_units: int = 128, early_stopping: bool = True, seed: int = 1305, scale_method: str | None = None, scale_range: tuple[float, float] | None = None, n_neighbors: int = 15, perplexity: float = 30.0, min_dist: float = 0.1, n_iter: int = 1000, training_history: dict[str, Any] | None = None, final_loss: float | None = None, epochs_trained: int | None = None, training_time: float | None = None, original_columns: list[str] | None = None, preprocessed_feature_names: list[str] | None = None, data_shape: tuple[int, int] | None = None, data_types: dict[str, str] | None = None, expected_schema: dict[str, Any] | None = None)

Container for Row2Vec model training metadata.

to_dict

to_dict() -> dict[str, Any]

Convert metadata to dictionary for serialization.

from_dict classmethod

from_dict(data: dict[str, Any]) -> Row2VecModelMetadata

Create metadata from dictionary.

Row2VecClassifier

Row2VecClassifier(embedding_dim: int = 10, classifier: Any = None, embedding_config: EmbeddingConfig | None = None, **embedding_kwargs: Any)

Bases: BaseEstimator

Scikit-learn compatible classifier using Row2Vec embeddings.

This combines Row2Vec embedding generation with a downstream classifier, making it easy to use embeddings for classification tasks in sklearn pipelines.

Parameters:

Name	Type	Description	Default
embedding_dim	int, default=10	Dimensionality of the embedding space.	10
classifier	sklearn classifier	The downstream classifier. If None, uses LogisticRegression.	None
embedding_config	EmbeddingConfig	Configuration for embedding generation.	None
**embedding_kwargs	Any	Additional parameters for the embedding configuration.	{}

Examples:

>>> import row2vec
>>> from row2vec.sklearn import Row2VecClassifier
>>> df = row2vec.generate_synthetic_data(80)
>>> y = df["Country"]
>>> clf = Row2VecClassifier(embedding_dim=2, mode="pca")
>>> _ = clf.fit(df.drop(columns=["Country"]), y)
>>> len(clf.predict(df.drop(columns=["Country"])))
80

fit

fit(X: Any, y: Any) -> Row2VecClassifier

Fit the embedding and classifier.

predict

predict(X: Any) -> np.ndarray[Any, Any]

Make predictions on new data.

predict_proba

predict_proba(X: Any) -> np.ndarray[Any, Any]

Predict class probabilities.

Row2VecTransformer

Row2VecTransformer(embedding_dim: int = 10, mode: str = 'unsupervised', reference_column: str | None = None, config: EmbeddingConfig | None = None, **kwargs: Any)

Bases: BaseEstimator, TransformerMixin

Scikit-learn compatible transformer for Row2Vec embeddings.

This transformer can be used in sklearn pipelines and follows the standard fit/transform API. It internally uses Row2Vec's config-based API for flexibility and type safety.

Parameters:

Name	Type	Description	Default
embedding_dim	int, default=10	Dimensionality of the embedding space.	10
mode	str, default="unsupervised"	Embedding mode. Options: "unsupervised", "target", "pca", "tsne", "umap", "contrastive".	'unsupervised'
reference_column	str	Reference column name for supervised ("target") mode.	None
config	EmbeddingConfig	Pre-configured EmbeddingConfig object. If provided, other parameters are ignored.	None
**kwargs	Any	Additional parameters passed to the embedding configuration, including nested ones such as neural__max_epochs=100.	{}

Attributes:

Name	Type	Description
config_	EmbeddingConfig	The configuration object used for embedding generation.
model_	object	The trained Row2Vec model (if using model-based modes).
feature_names_in_	ndarray of shape (n_features,	Names of features seen during fit.
n_features_in_	int	Number of features seen during fit.

Examples:

>>> import row2vec
>>> from row2vec.sklearn import Row2VecTransformer
>>> df = row2vec.generate_synthetic_data(60)
>>> transformer = Row2VecTransformer(embedding_dim=2, mode="pca")
>>> transformer.fit_transform(df).shape
(60, 2)

In a scikit-learn pipeline:

>>> from sklearn.pipeline import Pipeline
>>> pipeline = Pipeline(
...     [("embed", Row2VecTransformer(embedding_dim=2, mode="pca"))]
... )
>>> pipeline.fit_transform(df).shape
(60, 2)

fit

fit(X: Any, y: Any = None) -> Row2VecTransformer

Fit the Row2Vec transformer.

Parameters:

Name	Type	Description	Default
X	DataFrame or array-like of shape (n_samples, n_features)	Training data.	required
y	array-like of shape (n_samples,)	Target values (ignored, exists for sklearn compatibility).	None

Returns:

Name	Type	Description
self	Row2VecTransformer	Returns the instance itself.

transform

transform(X: Any) -> np.ndarray[Any, Any]

Transform data to embedding space.

Parameters:

Name	Type	Description	Default
X	DataFrame or array-like of shape (n_samples, n_features)	Data to transform.	required

Returns:

Name	Type	Description
X_embedded	ndarray of shape (n_samples, embedding_dim)	Embedded data.

fit_transform

fit_transform(X: Any, y: Any = None, **fit_params: Any) -> np.ndarray[Any, Any]

Fit the transformer and transform the data.

Parameters:

Name	Type	Description	Default
X	DataFrame or array-like of shape (n_samples, n_features)	Training data.	required
y	array-like of shape (n_samples,)	Target values (ignored, exists for sklearn compatibility).	None
**fit_params	dict	Additional parameters (ignored, exists for sklearn compatibility).	{}

Returns:

Name	Type	Description
X_embedded	ndarray of shape (n_samples, embedding_dim)	Embedded training data.

get_feature_names_out

get_feature_names_out(input_features: ndarray[Any, Any] | None = None) -> np.ndarray[Any, Any]

Get output feature names for transformation.

Parameters:

Name	Type	Description	Default
input_features	array-like of str or None, default=None	Not used, exists for sklearn compatibility.	None

Returns:

Name	Type	Description
feature_names_out	ndarray of shape (embedding_dim,), dtype=str	Feature names for the embedded space.

learn_embedding_classical

learn_embedding_classical(df: DataFrame, method: str = 'pca', embedding_dim: int = 10, **overrides: Any) -> pd.DataFrame

Learn classical ML embeddings (PCA, t-SNE, UMAP) with optimized defaults.

learn_embedding_contrastive

learn_embedding_contrastive(df: DataFrame, **overrides: Any) -> pd.DataFrame

Convenience function for contrastive learning with optimized defaults.

learn_embedding_target

learn_embedding_target(df: DataFrame, reference_column: str, embedding_dim: int = 10, **overrides: Any) -> pd.DataFrame

Learn target-based embeddings with optimized defaults.

learn_embedding_unsupervised

learn_embedding_unsupervised(df: DataFrame, embedding_dim: int = 10, **overrides: Any) -> pd.DataFrame

Learn unsupervised embeddings with optimized defaults.

learn_embedding_v2

learn_embedding_v2(df: DataFrame, config: EmbeddingConfig | None = None, auto_architecture: bool = False, architecture_search_config: Optional[ArchitectureSearchConfig] = None, **config_overrides: Any) -> pd.DataFrame

Modern config-based API for learning embeddings from tabular data.

This is the new recommended API that uses configuration objects instead of long parameter lists. It provides better organization, type safety, and extensibility.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input DataFrame containing the data to embed	required
config	EmbeddingConfig | None	Complete embedding configuration. If None, default config is used.	None
auto_architecture	bool	Enable automatic neural architecture search for neural modes	False
architecture_search_config	Optional[ArchitectureSearchConfig]	Custom architecture search configuration	None
**config_overrides	Any	Override specific config values (supports nested keys with dots)	{}

Returns:

Type	Description
DataFrame	DataFrame containing the learned embeddings

Examples:

Basic usage with defaults

embeddings = learn_embedding_v2(df)

Using a custom config

config = EmbeddingConfig( mode="contrastive", embedding_dim=50, contrastive=ContrastiveConfig(loss_type="triplet", margin=2.0) ) embeddings = learn_embedding_v2(df, config)

With automatic architecture search

embeddings = learn_embedding_v2(df, config, auto_architecture=True)

Quick overrides without config object

embeddings = learn_embedding_v2(df, embedding_dim=20, mode="target", reference_column="category")

Loading from YAML

config = EmbeddingConfig.from_yaml("my_config.yaml") embeddings = learn_embedding_v2(df, config)

learn_embedding_with_model_v2

learn_embedding_with_model_v2(df: DataFrame, config: EmbeddingConfig | None = None, **config_overrides: Any) -> tuple[pd.DataFrame, Any | BaseEstimator, ColumnTransformer, dict[str, Any]]

Modern config-based API for learning embeddings with model artifacts.

This function returns the embeddings along with the trained model, preprocessor, and metadata for serialization purposes.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input DataFrame containing the data to embed	required
config	EmbeddingConfig | None	Complete embedding configuration. If None, default config is used.	None
**config_overrides	Any	Override specific config values	{}

Returns:

Type	Description
tuple[DataFrame, Any | BaseEstimator, ColumnTransformer, dict[str, Any]]	Tuple of (embeddings, model, preprocessor, metadata)

search_architecture

search_architecture(df: DataFrame, base_config: EmbeddingConfig, search_config: ArchitectureSearchConfig | None = None, target_column: str | None = None) -> tuple[dict[str, Any], ArchitectureSearchResult]

Perform automatic neural architecture search.

This is the main entry point for architecture search functionality.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input dataframe for embedding generation	required
base_config	EmbeddingConfig	Base embedding configuration	required
search_config	ArchitectureSearchConfig | None	Architecture search configuration (uses defaults if None)	None
target_column	str | None	Optional target column for supervised evaluation	None

Returns:

Type	Description
tuple[dict[str, Any], ArchitectureSearchResult]	Tuple of (best_architecture_dict, full_search_result)

auto_select_dimension

auto_select_dimension(df: DataFrame, config: EmbeddingConfig | None = None, target_column: str | None = None, methods: list[str] | None = None, **selector_kwargs: Any) -> tuple[int, dict[str, Any]]

Convenience function for automatic dimension selection.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input dataframe	required
config	EmbeddingConfig | None	Base embedding configuration (uses defaults if None)	None
target_column	str | None	Optional target column for supervised evaluation	None
methods	list[str] | None	List of selection methods to use	None
**selector_kwargs	Any	Additional arguments for AutoDimensionSelector	{}

Returns:

Type	Description
tuple[int, dict[str, Any]]	Tuple of (optimal_dimension, selection_metadata)

learn_embedding

learn_embedding(df: DataFrame, embedding_dim: int = 10, mode: str = 'unsupervised', reference_column: str | None = None, max_epochs: int = 50, batch_size: int = 64, dropout_rate: float = 0.2, hidden_units: int | list[int] = 128, early_stopping: bool = True, seed: int = 1305, verbose: bool = False, scale_method: str | None = None, scale_range: tuple[float, float] | None = None, log_level: str = 'INFO', log_file: str | None = None, enable_logging: bool = True, n_neighbors: int = 15, perplexity: float = 30.0, min_dist: float = 0.1, n_iter: int = 1000, similar_pairs: list[tuple[int, int]] | None = None, dissimilar_pairs: list[tuple[int, int]] | None = None, auto_pairs: str | None = None, contrastive_loss: str = 'triplet', margin: float = 1.0, negative_samples: int = 5, config: EmbeddingConfig | None = None) -> pd.DataFrame

Learns a low-dimensional embedding from a pandas DataFrame.

Note

Current version supports numeric and categorical features. Textual and temporal features are not directly supported - please preprocess them yourself using appropriate tools (e.g., BERT-like embeddings for text, temporal libraries for time series). Support for these feature types is planned for future versions.

Parameters:

Name	Type	Description	Default
df	DataFrame	The input DataFrame containing numeric and categorical features.	required
embedding_dim	int	The dimensionality of the embedding space.	10
mode	str	Embedding method - 'unsupervised' (autoencoder), 'target' (supervised), 'pca' (Principal Component Analysis), 'tsne' (t-SNE), 'umap' (UMAP), or 'contrastive' (contrastive learning).	'unsupervised'
reference_column	str	The target column for 'target' mode.	None
max_epochs	int	The maximum number of training epochs (neural methods only).	50
batch_size	int	The batch size for training (neural methods only).	64
dropout_rate	float	The dropout rate for regularization (neural methods only).	0.2
hidden_units	Union[int, list[int]]	Hidden layer configuration - single int for one layer or list of ints for multiple layers (neural methods only).	128
early_stopping	bool	Whether to use early stopping (neural methods only).	True
seed	int	A random seed for reproducibility.	1305
verbose	bool	Whether to print training progress.	False
scale_method	str	Scaling method for embeddings. Options: 'none', 'minmax', 'standard', 'l2', 'tanh'.	None
scale_range	tuple	Range for minmax scaling. Default: (0, 1).	None
log_level	str	Logging level ('DEBUG', 'INFO', 'WARNING', 'ERROR').	'INFO'
log_file	str	File path for logging output.	None
enable_logging	bool	Whether to enable structured logging.	True
n_neighbors	int	Number of neighbors for UMAP (default: 15).	15
perplexity	float	Perplexity parameter for t-SNE (default: 30.0).	30.0
min_dist	float	Minimum distance for UMAP (default: 0.1).	0.1
n_iter	int	Number of iterations for t-SNE (default: 1000).	1000
similar_pairs	list[tuple[int, int]]	List of (row_idx1, row_idx2) pairs that should have similar embeddings (for contrastive mode).	None
dissimilar_pairs	list[tuple[int, int]]	List of (row_idx1, row_idx2) pairs that should have dissimilar embeddings (for contrastive mode).	None
auto_pairs	str	Strategy for automatic pair generation. Options: 'cluster' (cluster-based), 'neighbors' (k-NN based), 'categorical' (same category values), 'random' (random sampling).	None
contrastive_loss	str	Contrastive loss function. Options: 'triplet', 'contrastive'.	'triplet'
margin	float	Margin parameter for contrastive loss functions (default: 1.0).	1.0
negative_samples	int	Number of negative samples per positive pair (default: 5).	5
config	EmbeddingConfig	Configuration for preprocessing and model behavior. If None, intelligent defaults are used based on data analysis.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: A DataFrame containing the learned embeddings.

Raises:

Type	Description
ValueError	If input validation fails or unsupported mode is specified.
TypeError	If input types are incorrect.

learn_embedding_with_model

learn_embedding_with_model(df: DataFrame, embedding_dim: int = 10, mode: str = 'unsupervised', reference_column: str | None = None, max_epochs: int = 50, batch_size: int = 64, dropout_rate: float = 0.2, hidden_units: int | list[int] = 128, early_stopping: bool = True, seed: int = 1305, verbose: bool = False, scale_method: str | None = None, scale_range: tuple[float, float] | None = None, log_level: str = 'INFO', log_file: str | None = None, enable_logging: bool = True, n_neighbors: int = 15, perplexity: float = 30.0, min_dist: float = 0.1, n_iter: int = 1000, similar_pairs: list[tuple[int, int]] | None = None, dissimilar_pairs: list[tuple[int, int]] | None = None, auto_pairs: str | None = None, negative_samples: int = 5, contrastive_loss: str = 'triplet', margin: float = 1.0, config: EmbeddingConfig | None = None) -> tuple[pd.DataFrame, tf.keras.Model | BaseEstimator, ColumnTransformer, dict[str, Any]]

Extended version of learn_embedding that also returns the model, preprocessor, and training metadata.

This function is designed for use with the serialization system to capture all necessary components for saving and loading trained models.

Parameters:

Name	Type	Description	Default
df	DataFrame	The input DataFrame containing numeric and categorical features.	required
embedding_dim	int	The dimensionality of the embedding space.	10
mode	str	Embedding method - 'unsupervised' (autoencoder), 'target' (supervised), 'pca' (Principal Component Analysis), 'tsne' (t-SNE), 'umap' (UMAP), or 'contrastive' (contrastive learning).	'unsupervised'
reference_column	str	The target column for 'target' mode.	None
max_epochs	int	The maximum number of training epochs (neural methods only).	50
batch_size	int	The batch size for training (neural methods only).	64
dropout_rate	float	The dropout rate for regularization (neural methods only).	0.2
hidden_units	Union[int, list[int]]	Hidden layer configuration - single int for one layer or list of ints for multiple layers (neural methods only).	128
early_stopping	bool	Whether to use early stopping (neural methods only).	True
seed	int	A random seed for reproducibility.	1305
verbose	bool	Whether to print training progress.	False
scale_method	str	Scaling method for embeddings. Options: 'none', 'minmax', 'standard', 'l2', 'tanh'.	None
scale_range	tuple	Range for minmax scaling. Default: (0, 1).	None
log_level	str	Logging level ('DEBUG', 'INFO', 'WARNING', 'ERROR').	'INFO'
log_file	str	File path for logging output.	None
enable_logging	bool	Whether to enable structured logging.	True
n_neighbors	int	Number of neighbors for UMAP (default: 15).	15
perplexity	float	Perplexity parameter for t-SNE (default: 30.0).	30.0
min_dist	float	Minimum distance for UMAP (default: 0.1).	0.1
n_iter	int	Number of iterations for t-SNE (default: 1000).	1000
similar_pairs	list[tuple[int, int]]	List of (row_idx1, row_idx2) pairs that should have similar embeddings (for contrastive mode).	None
dissimilar_pairs	list[tuple[int, int]]	List of (row_idx1, row_idx2) pairs that should have dissimilar embeddings (for contrastive mode).	None
auto_pairs	str	Strategy for automatic pair generation. Options: 'cluster' (cluster-based), 'neighbors' (k-NN based), 'categorical' (same category values), 'random' (random sampling).	None
contrastive_loss	str	Contrastive loss function. Options: 'triplet', 'contrastive'.	'triplet'
margin	float	Margin parameter for contrastive loss functions (default: 1.0).	1.0
negative_samples	int	Number of negative samples per positive pair (default: 5).	5
config	EmbeddingConfig	Configuration for preprocessing and model behavior. If None, intelligent defaults are used based on data analysis.	None

Returns:

Type	Description
DataFrame	Tuple of (embeddings, model, preprocessor, metadata)
Model | BaseEstimator	embeddings: DataFrame with learned embeddings
ColumnTransformer	model: Trained model (Keras model for neural methods, sklearn estimator for classical)
dict[str, Any]	preprocessor: Fitted sklearn ColumnTransformer for data preprocessing
tuple[DataFrame, Model | BaseEstimator, ColumnTransformer, dict[str, Any]]	metadata: Dictionary containing training metadata and configuration

get_logger

get_logger(name: str = 'row2vec', level: str = 'INFO', log_file: str | Path | None = None, **kwargs: Any) -> Row2VecLogger

Create a Row2Vec logger with standard configuration.

Parameters:

Name	Type	Description	Default
name	str	Logger name	'row2vec'
level	str	Logging level	'INFO'
log_file	str | Path | None	Optional log file path	None
**kwargs	Any	Additional arguments for Row2VecLogger	{}

Returns:

Type	Description
Row2VecLogger	Configured Row2VecLogger instance

build_adaptive_pipeline

build_adaptive_pipeline(df: DataFrame, target: Series | None = None, config: EmbeddingConfig | None = None, mode: str = 'unsupervised') -> tuple[ColumnTransformer, dict[str, Any]]

Build adaptive preprocessing pipeline for Row2Vec.

This is the main entry point for intelligent pipeline construction. It analyzes the dataset and automatically selects optimal preprocessing strategies based on data characteristics.

Parameters:

Name	Type	Description	Default
df	DataFrame	Input dataset	required
target	Series	Target variable for supervised preprocessing	None
config	EmbeddingConfig	Configuration for preprocessing. If None, intelligent defaults are used.	None
mode	str	Embedding mode ("unsupervised", "target", etc.)	'unsupervised'

Returns:

Type	Description
tuple[ColumnTransformer, dict[str, Any]]	Tuple[ColumnTransformer, Dict[str, Any]] Preprocessing pipeline and analysis report

Examples:

>>> import row2vec
>>> from row2vec.pipeline_builder import build_adaptive_pipeline
>>> df = row2vec.generate_synthetic_data(60)
>>> pipeline, report = build_adaptive_pipeline(df)
>>> pipeline.fit_transform(df).shape[0]
60
>>> "dataset_shape" in report
True

load_model

load_model(script_path: str | Path) -> Row2VecModel

Load a Row2Vec model from the script file.

Parameters:

Name	Type	Description	Default
script_path	str | Path	Path to the Python script file	required

Returns:

Type	Description
Row2VecModel	Loaded Row2Vec model

Raises:

Type	Description
FileNotFoundError	If script or binary file not found
ValueError	If loading fails

save_model

save_model(model: Row2VecModel, base_path: str | Path, overwrite: bool = False) -> tuple[str, str]

Save a Row2Vec model using the two-file approach.

Parameters:

Name	Type	Description	Default
model	Row2VecModel	The Row2Vec model to save	required
base_path	str | Path	Base path for saving (without extension)	required
overwrite	bool	Whether to overwrite existing files	False

Returns:

Type	Description
tuple[str, str]	Tuple of (script_path, binary_path)

Raises:

Type	Description
FileExistsError	If files exist and overwrite=False
ValueError	If model is incomplete

train_and_save_model

train_and_save_model(df: DataFrame, base_path: str | Path, embedding_dim: int = 10, mode: str = 'unsupervised', reference_column: str | None = None, max_epochs: int = 50, batch_size: int = 64, dropout_rate: float = 0.2, hidden_units: int = 128, early_stopping: bool = True, seed: int = 1305, verbose: bool = False, scale_method: str | None = None, scale_range: tuple[float, float] | None = None, log_level: str = 'INFO', log_file: str | None = None, enable_logging: bool = True, n_neighbors: int = 15, perplexity: float = 30.0, min_dist: float = 0.1, n_iter: int = 1000, similar_pairs: list[tuple[int, int]] | None = None, dissimilar_pairs: list[tuple[int, int]] | None = None, auto_pairs: str | None = None, negative_samples: int = 5, contrastive_loss: str = 'triplet', margin: float = 1.0, overwrite: bool = False, include_training_history: bool = True) -> tuple[pd.DataFrame, str, str]

Train a Row2Vec model and save it using the two-file approach.

This is a convenience function that combines training and saving.

Parameters:

Name	Type	Description	Default
df	DataFrame	The input DataFrame containing numeric and categorical features.	required
base_path	str | Path	Base path for the saved model, without a suffix.	required
embedding_dim	int	The dimensionality of the embedding space.	10
mode	str	Embedding method - 'unsupervised' (autoencoder), 'target' (supervised), 'pca' (Principal Component Analysis), 'tsne' (t-SNE), 'umap' (UMAP), or 'contrastive' (contrastive learning).	'unsupervised'
reference_column	str	The target column for 'target' mode.	None
max_epochs	int	The maximum number of training epochs (neural methods only).	50
batch_size	int	The batch size for training (neural methods only).	64
dropout_rate	float	The dropout rate for regularization (neural methods only).	0.2
hidden_units	Union[int, list[int]]	Hidden layer configuration - single int for one layer or list of ints for multiple layers (neural methods only).	128
early_stopping	bool	Whether to use early stopping (neural methods only).	True
seed	int	A random seed for reproducibility.	1305
verbose	bool	Whether to print training progress.	False
scale_method	str	Scaling method for embeddings. Options: 'none', 'minmax', 'standard', 'l2', 'tanh'.	None
scale_range	tuple	Range for minmax scaling. Default: (0, 1).	None
log_level	str	Logging level ('DEBUG', 'INFO', 'WARNING', 'ERROR').	'INFO'
log_file	str	File path for logging output.	None
enable_logging	bool	Whether to enable structured logging.	True
n_neighbors	int	Number of neighbors for UMAP (default: 15).	15
perplexity	float	Perplexity parameter for t-SNE (default: 30.0).	30.0
min_dist	float	Minimum distance for UMAP (default: 0.1).	0.1
n_iter	int	Number of iterations for t-SNE (default: 1000).	1000
similar_pairs	list[tuple[int, int]]	List of (row_idx1, row_idx2) pairs that should have similar embeddings (for contrastive mode).	None
dissimilar_pairs	list[tuple[int, int]]	List of (row_idx1, row_idx2) pairs that should have dissimilar embeddings (for contrastive mode).	None
auto_pairs	str	Strategy for automatic pair generation. Options: 'cluster' (cluster-based), 'neighbors' (k-NN based), 'categorical' (same category values), 'random' (random sampling).	None
contrastive_loss	str	Contrastive loss function. Options: 'triplet', 'contrastive'.	'triplet'
margin	float	Margin parameter for contrastive loss functions (default: 1.0).	1.0
negative_samples	int	Number of negative samples per positive pair (default: 5).	5
overwrite	bool	Whether to overwrite existing model files.	False
include_training_history	bool	Whether to include the full training history in the metadata.	True

Returns:

Type	Description
tuple[DataFrame, str, str]	Tuple of (embeddings, script_path, binary_path)

create_dataframe_schema

create_dataframe_schema(df: DataFrame) -> dict[str, Any]

Create a schema dictionary from a DataFrame for validation purposes.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame to analyze	required

Returns:

Type	Description
dict[str, Any]	Dictionary containing schema information

generate_synthetic_data

generate_synthetic_data(num_records: int, seed: int = 1305) -> pd.DataFrame

Generates a synthetic DataFrame for demonstration purposes.

Parameters:

Name	Type	Description	Default
num_records	int	The number of records to generate.	required
seed	int	A random seed for reproducibility.	1305

Returns:

Type	Description
DataFrame	pd.DataFrame: A synthetic DataFrame with mixed data types.

validate_dataframe_schema

validate_dataframe_schema(df: DataFrame, expected_schema: dict[str, Any], allow_extra_columns: bool = False, allow_missing_columns: bool = False) -> None

Validate DataFrame schema against expected schema.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame to validate	required
expected_schema	dict[str, Any]	Expected schema dictionary	required
allow_extra_columns	bool	Whether to allow extra columns in df	False
allow_missing_columns	bool	Whether to allow missing columns in df	False

Raises:

Type	Description
ValueError	If schema validation fails