sklears_preprocessing/

encoding.rs

//! Data encoding and categorical feature transformation utilities
//!
//! This module provides comprehensive data encoding implementations including
//! label encoding, one-hot encoding, ordinal encoding, binary encoding, hash encoding,
//! frequency encoding, target encoding, feature hashing, categorical transformations,
//! cardinality reduction, embedding-based encoding, statistical encoding, smoothing techniques,
//! regularization methods, cross-validation encoding, time-aware encoding, and
//! high-performance categorical feature processing pipelines. All algorithms have been
//! refactored into focused modules for better maintainability and comply with SciRS2 Policy.

// FIXME: These modules are not implemented yet - commenting out to allow compilation
// // Core encoding types and base structures
// mod encoding_core;
// pub use encoding_core::{
//     EncodingProcessor, EncodingConfig, EncodingValidator, EncodingEstimator,
//     EncodingTransformer, EncodingAnalyzer, CategoricalProcessor, FeatureEncoder
// };

// // Label encoding and categorical to numerical transformation
// mod label_encoding;
// pub use label_encoding::{
//     LabelEncoder, LabelEncodingConfig, LabelEncodingValidator, CategoricalToNumerical,
//     StringEncoder, ClassEncoder, IndexMapping, LabelTransformer,
//     InverseLabelEncoder, LabelMappingAnalyzer, MultiLabelEncoder
// };

// // One-hot encoding and sparse representation
// mod onehot_encoding;
// pub use onehot_encoding::{
//     OneHotEncoder, OneHotConfig, OneHotValidator, SparseOneHot,
//     DenseOneHot, BinaryIndicator, CategoricalExpansion, OneHotTransformer,
//     SparseMatrixEncoder, OneHotOptimizer, MemoryEfficientOneHot
// };

// // Ordinal encoding and rank-based transformation
// mod ordinal_encoding;
// pub use ordinal_encoding::{
//     OrdinalEncoder, OrdinalConfig, OrdinalValidator, RankBasedEncoder,
//     OrderedCategorical, OrdinalMapping, CategoryRanking, OrdinalTransformer,
//     CustomOrderEncoder, SequentialEncoder, OrdinalOptimizer
// };

// // Binary encoding and bit-based representation
// mod binary_encoding;
// pub use binary_encoding::{
//     BinaryEncoder, BinaryEncoderConfig, BinaryValidator, BitEncoder,
//     BinaryRepresentation, BitVectorEncoder, CompactBinaryEncoder,
//     BinaryFeatureGenerator, BinaryTransformer, BinaryOptimizer
// };

// // Hash encoding and feature hashing
// mod hash_encoding;
// pub use hash_encoding::{
//     HashEncoder, HashEncoderConfig, HashValidator, FeatureHashing,
//     HashingTrick, CollisionHandling, HashFunction, MurmurHashEncoder,
//     CityHashEncoder, HashOptimizer, ConsistentHashing, HashAnalyzer
// };

// // Frequency encoding and count-based transformation
// mod frequency_encoding;
// pub use frequency_encoding::{
//     FrequencyEncoder, FrequencyEncoderConfig, FrequencyValidator, CountEncoder,
//     CategoryFrequency, FrequencyTransformer, CountBasedEncoder, RareCategoryHandler,
//     FrequencyBinning, FrequencyOptimizer, StatisticalFrequencyEncoder
// };

// // Target encoding and statistical encoding
// mod target_encoding;
// pub use target_encoding::{
//     TargetEncoder, TargetEncodingConfig, TargetValidator, MeanTargetEncoder,
//     BayesianTargetEncoder, SmoothTargetEncoder, CrossValidationTargetEncoder,
//     RegularizedTargetEncoder, TargetStatistics, TargetOptimizer, LeaveOneOutEncoder
// };

// // Embedding-based encoding and learned representations
// mod embedding_encoding;
// pub use embedding_encoding::{
//     EmbeddingEncoder, EmbeddingConfig, EmbeddingValidator, LearnedEmbedding,
//     CategoricalEmbedding, NeuralEmbedding, Word2VecEncoder, AutoencoderEmbedding,
//     EmbeddingTransformer, DimensionalityReducedEmbedding, EmbeddingOptimizer
// };

// // High-cardinality encoding and dimensionality reduction
// mod cardinality_reduction;
// pub use cardinality_reduction::{
//     CardinalityReducer, CardinalityConfig, CardinalityValidator, HighCardinalityHandler,
//     RareCategoryGrouping, TopKCategorySelector, FrequencyBasedReduction,
//     HierarchicalGrouping, CardinalityOptimizer, CategoryConsolidator
// };

// FIXME: Additional modules not implemented yet - commenting out to allow compilation
// // Time-aware encoding and temporal features
// mod temporal_encoding;
// pub use temporal_encoding::{
//     TemporalEncoder, TemporalConfig, TemporalValidator, TimeAwareEncoder,
//     SeasonalEncoder, CyclicEncoder, DateTimeEncoder, TimeSeriesEncoder,
//     TemporalFeatureExtractor, TimestampEncoder, TemporalOptimizer
// };

// // Cross-validation and robust encoding methods
// mod crossval_encoding;
// pub use crossval_encoding::{
//     CrossValidationEncoder, CVEncodingConfig, CVValidator, FoldBasedEncoder,
//     KFoldEncoder, StratifiedEncoder, TimeSeriesCVEncoder, RobustEncoder,
//     LeaveOneOutEncoder, CrossValidationOptimizer, ValidationAwareEncoder
// };

// // Smoothing and regularization techniques
// mod smoothing_techniques;
// pub use smoothing_techniques::{
//     SmoothingEncoder, SmoothingConfig, SmoothingValidator, BayesianSmoothing,
//     LaplaceSmoothing, JamesSteinSmoothing, EmpiricalBayesSmoothing,
//     AdaptiveSmoothing, SmoothingOptimizer, RegularizedSmoothing
// };

// // Performance optimization and computational efficiency
// mod performance_optimization;
// pub use performance_optimization::{
//     EncodingPerformanceOptimizer, ComputationalEfficiency, MemoryOptimizer,
//     AlgorithmicOptimizer, CacheOptimizer, ParallelEncodingProcessor
// };

// // Utilities and helper functions
// mod encoding_utilities;
// pub use encoding_utilities::{
//     EncodingUtilities, CategoricalMathUtils, EncodingAnalysisUtils, ValidationUtils,
//     ComputationalUtils, HelperFunctions, StatisticalUtils, UtilityValidator
// };

// FIXME: Re-exports commented out since modules are not implemented
// // Re-export main encoding classes for backwards compatibility
// pub use label_encoding::LabelEncoder;
// pub use onehot_encoding::OneHotEncoder;
// pub use ordinal_encoding::OrdinalEncoder;
// pub use binary_encoding::{BinaryEncoder, BinaryEncoderConfig};
// pub use hash_encoding::{HashEncoder, HashEncoderConfig};
// pub use frequency_encoding::{FrequencyEncoder, FrequencyEncoderConfig};
// pub use target_encoding::TargetEncoder;
// pub use embedding_encoding::EmbeddingEncoder;
// pub use cardinality_reduction::CardinalityReducer;

// FIXME: Re-export common configurations and types (commented out until modules are implemented)
// pub use encoding_core::EncodingConfig;
// pub use label_encoding::LabelEncodingConfig;
// pub use onehot_encoding::OneHotConfig;
// pub use ordinal_encoding::OrdinalConfig;
// pub use binary_encoding::BinaryEncoderConfig;
// pub use hash_encoding::HashEncoderConfig;
// pub use frequency_encoding::FrequencyEncoderConfig;
// pub use target_encoding::TargetEncodingConfig;
// pub use embedding_encoding::EmbeddingConfig;
// pub use temporal_encoding::TemporalConfig;

// Actual implementations of encoding functionality

use sklears_core::{
    error::{Result, SklearsError},
    traits::{Estimator, Fit, Trained, Untrained},
    types::Float,
};
use std::collections::HashMap;
use std::marker::PhantomData;

#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

/// Configuration for BinaryEncoder
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct BinaryEncoderConfig {
    /// Whether to drop the first binary column to avoid collinearity
    pub drop_first: bool,
    /// How to handle unknown categories during transform
    pub handle_unknown: UnknownStrategy,
    /// Whether to use base-2 encoding (true) or natural binary representation (false)
    pub use_base2: bool,
}

impl Default for BinaryEncoderConfig {
    fn default() -> Self {
        Self {
            drop_first: false,
            handle_unknown: UnknownStrategy::Error,
            use_base2: true,
        }
    }
}

/// Strategy for handling unknown categories
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum UnknownStrategy {
    /// Raise an error when unknown category is encountered
    Error,
    /// Assign unknown categories to a special "unknown" encoding
    Ignore,
    /// Use all zeros for unknown categories
    Zero,
}

/// Binary encoder for high-cardinality categorical features
pub struct BinaryEncoder<State = Untrained> {
    config: BinaryEncoderConfig,
    fitted_state: Option<BinaryEncoderFitted>,
    state: PhantomData<State>,
}

/// Fitted state of BinaryEncoder
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct BinaryEncoderFitted {
    config: BinaryEncoderConfig,
    /// Mapping from category to binary index
    category_mapping: HashMap<String, usize>,
    /// Number of binary columns needed
    n_binary_cols: usize,
    /// Categories seen during fitting
    categories: Vec<String>,
}

impl BinaryEncoder<Untrained> {
    /// Create a new BinaryEncoder
    pub fn new() -> Self {
        Self {
            config: BinaryEncoderConfig::default(),
            fitted_state: None,
            state: PhantomData,
        }
    }

    /// Set whether to drop the first column
    pub fn drop_first(mut self, drop_first: bool) -> Self {
        self.config.drop_first = drop_first;
        self
    }

    /// Set the strategy for handling unknown categories
    pub fn handle_unknown(mut self, strategy: UnknownStrategy) -> Self {
        self.config.handle_unknown = strategy;
        self
    }

    /// Set whether to use base-2 encoding
    pub fn use_base2(mut self, use_base2: bool) -> Self {
        self.config.use_base2 = use_base2;
        self
    }
}

impl Default for BinaryEncoder<Untrained> {
    fn default() -> Self {
        Self::new()
    }
}

impl Estimator for BinaryEncoder<Untrained> {
    type Config = BinaryEncoderConfig;
    type Error = SklearsError;
    type Float = Float;

    fn config(&self) -> &Self::Config {
        &self.config
    }
}

impl Estimator for BinaryEncoder<Trained> {
    type Config = BinaryEncoderConfig;
    type Error = SklearsError;
    type Float = Float;

    fn config(&self) -> &Self::Config {
        &self.fitted_state().config
    }
}

impl BinaryEncoder<Trained> {
    fn fitted_state(&self) -> &BinaryEncoderFitted {
        self.fitted_state
            .as_ref()
            .expect("BinaryEncoder<Trained> must have fitted_state")
    }
}

impl Fit<Vec<String>, ()> for BinaryEncoder<Untrained> {
    type Fitted = BinaryEncoder<Trained>;

    fn fit(self, x: &Vec<String>, _y: &()) -> Result<Self::Fitted> {
        // Extract unique categories and sort them for deterministic encoding
        let mut categories = x.clone();
        categories.sort();
        categories.dedup();

        let n_categories = categories.len();

        // Calculate number of binary columns needed for encoding
        // log2(n_categories) rounded up gives the minimum bits needed
        let n_binary_cols = if n_categories <= 1 {
            1
        } else {
            (n_categories as f64).log2().ceil() as usize
        };

        // Create mapping from category to its index
        let category_mapping: HashMap<String, usize> = categories
            .iter()
            .enumerate()
            .map(|(i, cat)| (cat.clone(), i))
            .collect();

        // Create fitted state
        let fitted_state = BinaryEncoderFitted {
            config: self.config.clone(),
            category_mapping,
            n_binary_cols,
            categories,
        };

        // Return trained encoder with fitted state
        Ok(BinaryEncoder {
            config: self.config,
            fitted_state: Some(fitted_state),
            state: PhantomData,
        })
    }
}

/// Configuration for HashEncoder
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct HashEncoderConfig {
    /// Number of hash buckets
    pub n_components: usize,
    /// Hash function to use
    pub hash_method: HashMethod,
    /// Whether to use signed hash (can have negative values)
    pub alternate_sign: bool,
}

impl Default for HashEncoderConfig {
    fn default() -> Self {
        Self {
            n_components: 32,
            hash_method: HashMethod::Md5,
            alternate_sign: true,
        }
    }
}

/// Hash function options
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum HashMethod {
    /// MD5 hash function
    Md5,
    /// Simple modulo hash
    Modulo,
}

/// Hash encoder for categorical features using feature hashing
pub struct HashEncoder<State = Untrained> {
    config: HashEncoderConfig,
    state: PhantomData<State>,
}

impl HashEncoder<Untrained> {
    /// Create a new HashEncoder
    pub fn new() -> Self {
        Self {
            config: HashEncoderConfig::default(),
            state: PhantomData,
        }
    }

    /// Set the number of hash components
    pub fn n_components(mut self, n_components: usize) -> Self {
        self.config.n_components = n_components;
        self
    }

    /// Set the hash method
    pub fn hash_method(mut self, method: HashMethod) -> Self {
        self.config.hash_method = method;
        self
    }
}

impl Default for HashEncoder<Untrained> {
    fn default() -> Self {
        Self::new()
    }
}

/// Frequency encoder configuration
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct FrequencyEncoderConfig {
    /// Whether to normalize frequencies to probabilities
    pub normalize: bool,
    /// Strategy for handling rare categories
    pub rare_strategy: RareStrategy,
    /// Threshold for considering categories as rare
    pub rare_threshold: usize,
}

impl Default for FrequencyEncoderConfig {
    fn default() -> Self {
        Self {
            normalize: false,
            rare_strategy: RareStrategy::Keep,
            rare_threshold: 1,
        }
    }
}

/// Strategy for handling rare categories
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub enum RareStrategy {
    /// Keep rare categories as-is
    Keep,
    /// Group rare categories together
    Group,
    /// Replace rare categories with mean frequency
    MeanFrequency,
}

/// Frequency encoder transforms categories to their occurrence frequencies
pub struct FrequencyEncoder<State = Untrained> {
    config: FrequencyEncoderConfig,
    state: PhantomData<State>,
}

impl FrequencyEncoder<Untrained> {
    /// Create a new FrequencyEncoder
    pub fn new() -> Self {
        Self {
            config: FrequencyEncoderConfig::default(),
            state: PhantomData,
        }
    }

    /// Set whether to normalize frequencies
    pub fn normalize(mut self, normalize: bool) -> Self {
        self.config.normalize = normalize;
        self
    }

    /// Set the rare category strategy
    pub fn rare_strategy(mut self, strategy: RareStrategy) -> Self {
        self.config.rare_strategy = strategy;
        self
    }
}

impl Default for FrequencyEncoder<Untrained> {
    fn default() -> Self {
        Self::new()
    }
}

/// Configuration for CategoricalEmbedding
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct CategoricalEmbeddingConfig {
    /// Embedding dimension
    pub embedding_dim: usize,
    /// Learning rate for training
    pub learning_rate: Float,
    /// Number of training epochs
    pub epochs: usize,
    /// Batch size for training
    pub batch_size: usize,
}

impl Default for CategoricalEmbeddingConfig {
    fn default() -> Self {
        Self {
            embedding_dim: 50,
            learning_rate: 0.01,
            epochs: 100,
            batch_size: 32,
        }
    }
}

/// Categorical embedding using neural network-style embeddings
pub struct CategoricalEmbedding<State = Untrained> {
    config: CategoricalEmbeddingConfig,
    state: PhantomData<State>,
}

impl CategoricalEmbedding<Untrained> {
    /// Create a new CategoricalEmbedding
    pub fn new() -> Self {
        Self {
            config: CategoricalEmbeddingConfig::default(),
            state: PhantomData,
        }
    }

    /// Set the embedding dimension
    pub fn embedding_dim(mut self, dim: usize) -> Self {
        self.config.embedding_dim = dim;
        self
    }

    /// Set the learning rate
    pub fn learning_rate(mut self, lr: Float) -> Self {
        self.config.learning_rate = lr;
        self
    }
}

impl Default for CategoricalEmbedding<Untrained> {
    fn default() -> Self {
        Self::new()
    }
}

// Placeholder implementations for the basic encoders
// These should be replaced with full implementations

/// Label encoder for transforming categorical labels to integers
#[derive(Debug, Clone, Default)]
pub struct LabelEncoder {
    // Placeholder - should implement proper label encoding
}

/// One-hot encoder for categorical features
#[derive(Debug, Clone, Default)]
pub struct OneHotEncoder {
    // Placeholder - should implement proper one-hot encoding
}

/// Ordinal encoder for categorical features with inherent ordering
#[derive(Debug, Clone, Default)]
pub struct OrdinalEncoder {
    // Placeholder - should implement proper ordinal encoding
}

/// Target encoder using target statistics for categorical encoding
#[derive(Debug, Clone, Default)]
pub struct TargetEncoder {
    // Placeholder - should implement proper target encoding
}