# myffe - A Powerful Feature Engineering Framework

[![Python Version](https://img.shields.io/badge/python-3.7%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-GPLv3-green.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/nan-luoyan-nan/myffe)
[![Test Coverage](https://img.shields.io/badge/coverage-95%25-green.svg)](https://github.com/nan-luoyan-nan/myffe)
[![Latest Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](https://pypi.org/project/myffe/)
[![Documentation](https://img.shields.io/badge/docs-available-blue.svg)](https://github.com/nan-luoyan-nan/myffe)
[![Contributors](https://img.shields.io/badge/contributors-welcome-orange.svg)](https://github.com/nan-luoyan-nan/myffe)

myffe (My First Feature Engine) 是一个功能强大的工业级特征工程框架，提供完整的特征工程工具链，支持数据清洗、特征提取、样本处理等功能。

## 🚀 亮点特性

- **🤖 自编码器预处理**：基于神经网络的缺失值填充，支持多种激活函数和损失函数，C++和Python混合实现，性能优化
- **🧠 智能路线推荐**：自动检测数据特征，推荐最佳预处理路线
- **🔧 全面的预处理工具**：支持缺失值处理、异常值处理、字符串处理、时间特征提取等
- **🏭 工业级封装**：外部接口简洁易用，适合生产环境
- **📊 数据评估功能**：评估数据质量和处理效果
- **🎨 可视化支持**：路线可视化和数据描述

## 📦 安装

```bash
pip install myffe
```

## 🚀 快速开始

### 简单使用

```python
import pandas as pd
from myffe import process_data

# 读取数据
data = pd.read_csv('your_data.csv')

# 使用预定义路线 1（基础路线）处理数据
processed_data = process_data(data, data_label='label', route_number=1)

# 保存参数配置
processed_data = process_data(data, data_label='label', route_number=1, save_params='./params.json')
```

### 高级使用

```python
from myffe import FFE

# 创建 FFE 实例
ffe = FFE()

# 创建流水线
console, tools = ffe.create_pipeline('label', route_number=3)

# 处理数据
console(tools, data, save_path='processed_data.csv')

# 创建流水线并保存参数
console, tools = ffe.create_pipeline('label', route_number=3, save_params='./params.json')
console(tools, data, save_path='processed_data.csv')
```

### 自动推荐路线

```python
from myffe import FFE

ffe = FFE()

# 自动检测数据并推荐路线
recommended_route = ffe.auto_detect_route(data)

# 使用推荐的路线处理数据
console, tools = ffe.create_pipeline('label', route=recommended_route)
console(tools, data, save_path='processed_data.csv')
```

## ✨ 特性

- **🧩 模块化设计**：易于扩展和定制
- **🔧 多种预处理方法**：支持缺失值处理、异常值处理、标准化、归一化等
- **🚗 预定义路线**：提供 20+ 种预定义的特征工程路线
- **🤖 自动参数推荐**：智能推荐最佳预处理参数
- **🏭 工业级封装**：外部接口简洁易用
- **🐍 纯 Python 实现**：无需编译，跨平台兼容
- **📋 完整的日志系统**：详细记录处理过程
- **📊 数据评估功能**：评估数据质量和处理效果
- **🎨 可视化支持**：路线可视化和数据描述
- **💾 参数保存功能**：支持保存和加载特征工程参数配置

## 🗺️ 预定义路线

myffe 提供 20+ 种预定义路线，适用于不同场景：

| 路线编号 | 路线名称 | 适用场景 |
|---------|---------|----------|
| 1 | **基础路线** | 适合大多数数据集 |
| 2 | **股票数据路线** | 专为股票数据优化 |
| 3 | **文本数据路线** | 包含文本处理 |
| 4 | **时间序列路线** | 强化时间特征提取 |
| 5 | **完整路线** | 包含所有预处理步骤 |
| 6 | **轻量级路线** | 快速处理小数据集 |
| 7 | **异常检测路线** | 专注于异常值处理 |
| 8 | **特征增强路线** | 强化特征工程 |
| 9 | **分类数据路线** | 适合分类任务 |
| 10 | **回归数据路线** | 适合回归任务 |
| 11 | **中文文本路线** | 专为中文文本数据优化 |
| 12 | **不平衡数据路线** | 处理类别不平衡的数据集 |
| 13 | **高维数据路线** | 处理特征维度较高的数据集 |
| 14 | **金融数据路线** | 专为金融数据优化 |
| 15 | **医疗数据路线** | 适合医疗数据集的处理 |
| 16 | **电商数据路线** | 专为电商数据优化 |
| 17 | **社交媒体数据路线** | 处理社交媒体数据 |
| 18 | **传感器数据路线** | 处理传感器数据 |
| 19 | **多模态数据路线** | 处理包含多种类型数据的数据集 |
| 20 | **实时数据路线** | 适合实时数据流处理 |

查看可用路线：

```python
from myffe import show_available_routes
show_available_routes()
```

## 🧠 核心模块

### 1. 📥 数据预处理 (preprocessing)

#### 参数文档

详细的参数配置说明请参考 [参数文档](myffe/learning/all_parameters.md)，包含所有预处理模块的完整参数配置，包括占位参数。参数配置现已通过 RouteManager 统一管理，支持手动配置和自动推荐两种模式。

- **nan_preprocessing** - 缺失值处理
  - 支持多种填充策略：均值、中位数、众数、固定值、前向填充、后向填充、KNN填充、智能填充、集成填充(EI)等
  - 支持按列自定义填充方法
  - 支持缺失值比例统计和可视化
  - 智能推荐填充方法，根据数据类型和单调性自动选择最佳填充策略
  - 集成填充(EI)：通过集成多种填充策略（均值、中位数、众数）和多项式回归模型，对预测结果进行加权平均，提供更准确的填充结果。采用验证集评估各填充方法的性能，并根据性能分配不同权重，优化预测准确性。实现了智能迭代次数调整，从20-100之间随机选择初始迭代次数，并根据验证分数自动调整，确保在合理范围内（5-1000次）找到最佳结果。支持多项式阶数设置，可根据数据维度智能推荐：特征数量较少时使用较低阶数（2-3），特征数量较多时使用较高阶数（3-4），数据量特别大时（5000行以上）可适当增加阶数。特别适用于数据量充足（1000行以上）、特征数量适中（编码后不超过30个特征，原始列数量达到3个以上）、缺失比例合理（整体缺失行比例小于30%，目标列缺失比例在5%-40%之间）的数据集。支持自动推荐和手动选择，是处理复杂缺失值场景的强大工具
- **outlier_preprocessing** - 异常值处理
  - 支持多种异常值检测方法：IQR、Z-score、Isolation Forest、Multivariate等
  - 支持异常值替换或删除
  - 支持异常值统计和可视化
- **str_preprocessing** - 字符串处理
  - 支持文本清洗、分词、编码
  - 支持类别特征的one-hot编码、标签编码、频率编码
  - 支持文本特征提取（TF-IDF、LDA）
  - 支持中文文本处理和分词
- **time_preprocessing** - 时间特征提取
  - 支持日期时间解析
  - 支持时间特征衍生：年、月、日、时、分、秒、星期、季度等
  - 支持时间差计算
  - 支持周期性特征编码（正弦/余弦）
- **standard_preprocessing** - 数据标准化
  - 支持Z-score标准化
  - 支持Min-Max标准化
  - 支持MaxAbs标准化
  - 支持Robust标准化
  - 支持QuantileTransformer标准化
  - 支持均值归一化
  - 支持单位长度归一化
  - 支持自定义缩放
- **normalized_preprocessing** - 数据归一化
  - 支持L1、L2归一化
  - 支持MaxAbs归一化
  - 支持Robust归一化
  - 支持幂次归一化
  - 支持对数归一化
  - 支持平方根归一化
- **sample_preprocessing** - 样本处理
  - 支持数据采样
  - 支持类别平衡处理（SMOTE、ADASYN等）
  - 支持数据分割
- **relative_preprocessing** - 相对特征处理
  - 支持特征间的线性组合
  - 支持特征重要性分析
  - 支持PCA/LDA降维
  - 支持核方法
- **specify_preprocessing** - 指定特征处理
  - 支持自定义特征处理逻辑
  - 支持特征选择和变换
  - 支持列和行的删除
- **autoencoder_preprocessing** - 自编码器预处理
  - **先进的缺失值填充**：基于神经网络的智能填充，比传统方法更准确
  - **丰富的激活函数**：支持 relu、sigmoid、tanh、leaky_relu、gelu、mish、softmax 等多种激活函数
  - **灵活的损失函数**：支持 mse、mae、huber、log_cosh 等多种损失函数，适应不同数据分布
  - **可定制的网络结构**：支持自定义隐藏层结构，适应不同复杂度的数据
  - **智能数据归一化**：自动处理数据范围，防止梯度爆炸
  - **双实现机制**：C++ 和 Python 混合实现，性能优化，同时确保跨平台兼容性
  - **鲁棒的错误处理**：当 C++ 模块不可用时，自动回退到 Python 实现，确保稳定运行
  - **详细的训练日志**：提供完整的训练过程和数据评估，便于调优
  - **支持批量训练**：高效处理大规模数据集

### 2. 🗺️ 路线配置 (route)

- **predefined_routes** - 预定义路线
  - 提供 20+ 种预定义的特征工程路线
  - 支持路线参数获取和可视化

- **RouteManager** - 路由管理器
  - 整合了 route_config 和 auto_route 的功能
  - 支持手动配置和自动推荐两种模式
  - 提供统一的路由配置和管理接口
  - 支持按顺序执行工具，确保处理流程的一致性

### 3. 🛠️ 工具 (tools)

- **datadescription** - 数据描述
  - 提供详细的数据统计信息
  - 支持数据质量评估
  - 支持数据分布可视化
- **datainspector** - 数据检查
  - 支持数据类型检查
  - 支持缺失值检测
  - 支持异常值检测
- **visualizeroute** - 路线可视化
  - 支持处理路线的可视化展示
  - 支持处理流程的图形化表示
- **logger** - 日志系统
  - 支持多级别日志
  - 支持控制台和文件日志
  - 支持处理过程的详细记录
  - 支持自定义日志路径
- **color_printer** - 彩色打印
  - 支持彩色输出
  - 支持不同级别的信息展示
  - **限制**：在 Windows 终端中默认禁用颜色输出，以避免编码问题
- **interactive** - 交互式工具
  - 提供交互式数据处理界面
- **evaluation_decorator** - 评估装饰器
  - 用于评估数据处理前后的质量变化
- **input_utils** - 输入工具
  - 提供类型安全的交互式输入功能
  - 支持整数和浮点数输入
  - 自动进行范围验证和错误处理
- **system_validator** - 系统验证
  - 验证系统状态和模块可用性
- **unified_config_manager** - 统一配置管理器
  - 已整合到 RouteManager 中，提供统一的参数配置管理
  - 管理所有预处理模块的配置参数
  - 支持参数的保存和加载

## 🔌 核心接口

### FFE 类

```python
class FFE:
    def __init__(self, log_level='info'):
        """初始化FFE框架
        
        Args:
            log_level (str): 日志级别，可选值: 'debug', 'info', 'warning', 'error'，默认为'info'
        """
    
    def create_pipeline(self, data_label, route_number=None, route=None, use_modin=False, save_params=None, **kwargs):
        """创建特征工程流水线
        
        Args:
            data_label (str): 标签列名称，指定数据中的目标变量列
            route_number (int, optional): 预定义路线编号，1-20之间的整数，默认为None
            route (dict, optional): 自定义路线参数字典，由auto_detect_route生成，默认为None
            use_modin (bool, optional): 是否使用 Modin 进行数据处理，默认为 False
            save_params (str, optional): 保存参数的路径，默认为 None（不保存）
            **kwargs: 其他参数，如batch_size等
        
        Returns:
            tuple: (console, tools) - 控制台实例和预处理工具字典
        """
    
    def auto_detect_route(self, data, label_columns=None, drop_threshold=0.5):
        """自动检测数据并推荐特征工程路线
        
        Args:
            data (DataFrame): 输入数据，pandas DataFrame格式
            label_columns (list, optional): 标签列名称列表，默认为None
            drop_threshold (float, optional): 缺失值阈值，超过此阈值的列会被丢弃，默认为0.5
        
        Returns:
            dict: 推荐的特征工程参数字典
        """
    
    def validate_system(self):
        """验证系统状态
        
        Returns:
            dict: 系统状态验证结果，包含各模块的状态信息
        """
```

### 便捷函数

- **process_data(data, data_label, route_number=None, route=None, save_path='./processed_data.csv', use_modin=False, save_params=None, **kwargs)**
  - 便捷的数据处理函数，一站式完成数据预处理
  - 参数：
    - data (DataFrame): 输入数据，pandas DataFrame格式
    - data_label (str): 标签列名称，指定数据中的目标变量列
    - route_number (int, optional): 预定义路线编号，1-20之间的整数，默认为None
    - route (dict, optional): 自定义路线参数字典，由auto_detect_route生成，默认为None
    - save_path (str): 处理后数据的保存路径，默认为'./processed_data.csv'
    - use_modin (bool, optional): 是否使用 Modin 进行数据处理，默认为 False
    - save_params (str, optional): 保存参数的路径，默认为 None（不保存）
    - **kwargs: 其他参数，如batch_size等
  - 返回：处理后的数据，pandas DataFrame格式
- **get_recommended_route(data, label_columns=None)**
  - 获取推荐的特征工程路线
  - 参数：
    - data (DataFrame): 输入数据，pandas DataFrame格式
    - label_columns (list, optional): 标签列名称列表，默认为None
  - 返回：推荐的路线参数字典
- **show_available_routes()**
  - 显示所有可用的预定义路线
  - 返回：路线列表，包含所有可用的预定义路线编号和名称
- **get_route_params(route_number)**
  - 获取指定路线的参数
  - 参数：
    - route_number (int): 路线编号，1-20之间的整数
  - 返回：路线参数字典，包含该路线的所有预处理步骤和参数
- **describe_data(data)**
  - 描述数据，生成详细的数据统计信息
  - 参数：
    - data (DataFrame): 输入数据，pandas DataFrame格式
  - 返回：数据描述信息，包含数据基本信息、质量评估、分布情况等
- **evaluate_dataset(data, label_column=None)**
  - 评估数据集质量
  - 参数：
    - data (DataFrame): 输入数据，pandas DataFrame格式
    - label_column (str, optional): 标签列名称，默认为None
  - 返回：评估指标字典，包含数据完整性、质量、特征质量等多个维度的评估结果
- **visualize_route(route)**
  - 可视化路线，展示处理流程
  - 参数：
    - route (dict): 路线参数字典，由get_route_params或auto_detect_route生成
  - 返回：可视化结果，展示路线的处理流程和参数
- **set_logging_mode(mode)**
  - 设置全局日志模式
  - 参数：
    - mode (str): 日志模式，可选值: 'None', 'use', 'test'
  - 返回：无
- **set_logging_enabled(enabled)**
  - 控制控制台日志输出
  - 参数：
    - enabled (bool): 是否启用控制台输出，True为启用，False为禁用
  - 返回：无
- **set_logging_path(log_path)**
  - 设置自定义日志文件路径
  - 参数：
    - log_path (str): 自定义日志文件路径
  - 返回：无
- **get_logging_status()**
  - 获取当前日志状态
  - 参数：无
  - 返回：包含日志模式、控制台输出状态和日志文件路径的字典

### RouteManager 模块

```python
class RouteManager:
    def __init__(self):
        """初始化路由管理器
        
        整合了 route_config 和 auto_route 的功能，提供统一的路由配置和管理接口
        """
    
    def auto_detect_route(self, data, label_columns=None, drop_threshold=0.5):
        """自动检测数据并推荐特征工程路线
        
        Args:
            data (DataFrame): 输入数据，pandas DataFrame格式
            label_columns (list, optional): 标签列名称列表，默认为None
            drop_threshold (float, optional): 缺失值阈值，超过此阈值的列会被丢弃，默认为0.5
        
        Returns:
            dict: 推荐的特征工程参数字典
        """
    
    def create_route(self, tools):
        """手动创建特征工程路线
        
        Args:
            tools (list): 工具列表，每个工具可以是字符串或字典
        
        Returns:
            dict: 特征工程参数字典
        """
    
    def validate_route(self, route):
        """验证路线配置的有效性
        
        Args:
            route (dict): 路线参数字典
        
        Returns:
            bool: 路线配置是否有效
        """
```

## 📝 使用示例

### 示例 1：基础数据处理

```python
import pandas as pd
from myffe import process_data

# 创建示例数据
data = pd.DataFrame({
    'feature1': [1.0, 2.0, None, 4.0, 5.0],
    'feature2': ['A', 'B', 'A', None, 'C'],
    'label': [0, 1, 0, 1, 0]
})

# 处理数据
processed = process_data(data, data_label='label', route_number=1)
print(processed.head())
```

### 示例 2：自定义路线

```python
from myffe import FFE, get_route_params

# 获取路线 3 的参数
params = get_route_params(3)

# 创建 FFE 实例
ffe = FFE()

# 创建流水线
console, tools = ffe.create_pipeline('label', route=params)

# 处理数据
console(tools, data, save_path='output.csv')
```

### 示例 3：数据评估

```python
from myffe import FFE, evaluate_dataset, print_evaluation_result

ffe = FFE()

# 评估数据集
metrics = evaluate_dataset(data, label_column='label')
print_evaluation_result(metrics)
```

### 示例 4：自动推荐路线

```python
from myffe import FFE, process_data

# 创建示例数据
import pandas as pd
import numpy as np
data = pd.DataFrame({
    'feature1': np.random.randn(100),
    'feature2': np.random.randint(0, 10, 100),
    'feature3': np.random.choice(['A', 'B', 'C'], 100),
    'feature4': np.random.rand(100),
    'feature5': np.random.randn(100),
    'label': np.random.randint(0, 2, 100)
})
# 添加一些缺失值
data['feature1'][::10] = np.nan
data['feature4'][::15] = np.nan

# 获取推荐路线
ffe = FFE()
recommended_route = ffe.auto_detect_route(data, label_columns=['label'])
print(f"推荐路线: {recommended_route}")

# 使用推荐路线处理数据
processed = process_data(data, data_label='label', route=recommended_route)
print(f"处理后数据形状: {processed.shape}")
```

### 示例 5：系统验证

```python
from myffe import FFE

ffe = FFE()

# 验证系统状态
status = ffe.validate_system()
print(f"系统状态: {status}")
```

### 示例 6：使用 RouteManager 模块

```python
from myffe.route.src.route_manager import RouteManager

# 创建 RouteManager 实例
route_manager = RouteManager()

# 自动检测数据并推荐路线
import pandas as pd
data = pd.read_csv('your_data.csv')
recommended_route = route_manager.auto_detect_route(data, label_columns=['label'])
print(f"推荐路线: {recommended_route}")

# 手动配置路线
custom_route = route_manager.create_route([
    {'nan_preprocessing': {'nan_missing_process_choice': 'mean'}},
    {'autoencoder_preprocessing': {'epochs': 100, 'batch_size': 32}}
])
print(f"自定义路线: {custom_route}")
```

## 📋 日志系统

myffe 内置日志系统，支持多种日志模式和控制选项：

### 日志模式

- **None模式** - 不记录任何日志
- **use模式** - 生产环境模式，简洁的控制台输出
- **test模式** - 测试模式，详细的日志记录

### 日志控制函数

```python
from myffe import logger, set_logging_enabled, set_logging_mode, get_logging_status, set_logging_path

# 设置日志模式
set_logging_mode('use')  # 设置为生产环境模式
set_logging_mode('test') # 设置为测试模式
set_logging_mode('None') # 禁用日志

# 控制控制台输出
set_logging_enabled(True)  # 启用控制台输出
set_logging_enabled(False) # 禁用控制台输出

# 自定义日志路径
set_logging_path('D:/custom/logs/preprocessing.log')

# 获取当前日志状态
status = get_logging_status()
print(f"当前日志模式: {status['mode']}")
print(f"控制台输出: {status['console_enabled']}")
print(f"日志文件路径: {status['log_path']}")
```

### 日志文件

- **默认路径**：日志文件默认保存在用户主目录下的 `.myffe/logs` 文件夹中，例如：
  - Windows: `C:\Users\用户名\.myffe\logs\preprocessing.log`
  - Linux/macOS: `/home/用户名/.myffe/logs/preprocessing.log`
- **自定义路径**：可以使用 `set_logging_path` 函数自定义日志路径

### 示例：使用不同日志模式

```python
from myffe import FFE, process_data, set_logging_mode, set_logging_enabled
import pandas as pd
import numpy as np

# 创建示例数据
data = pd.DataFrame({
    'feature1': np.random.randn(100),
    'feature2': np.random.randint(0, 10, 100),
    'label': np.random.randint(0, 2, 100)
})

# 测试 None 模式
print("\n=== 测试 None 模式 ===")
set_logging_mode('None')
result = process_data(data, 'label', route_number=1, save_path=None)
print("处理完成，无日志输出")

# 测试 use 模式
print("\n=== 测试 use 模式 ===")
set_logging_mode('use')
set_logging_enabled(True)  # 启用控制台输出
result = process_data(data, 'label', route_number=1, save_path=None)

# 测试 test 模式
print("\n=== 测试 test 模式 ===")
set_logging_mode('test')
set_logging_enabled(True)  # 启用控制台输出
result = process_data(data, 'label', route_number=1, save_path=None)
```

## 🛡️ 系统要求

- Python >= 3.7
- pandas >= 1.3.0
- numpy >= 1.20.0
- scikit-learn >= 0.24.0
- scipy >= 1.6.0
- imbalanced-learn >= 0.8.0 (用于高级采样方法)

## 📄 许可证

GNU General Public License v3.0

## 🤝 贡献

欢迎贡献代码！请提交 Issue 或 Pull Request。

## 📅 版本历史

- **1.1.0** - 新增自编码器预处理工具用于缺失值填充，采用C++和Python混合实现，性能优化；整合路由配置功能，改进参数保存功能，统一配置管理；增强字符串处理模块，添加日期列自动检测功能。
- **1.0.4** - 重构了多个处理模块，优化了配置结构，采用嵌套字典列表形式，确保每个列的参数独立设置。
- **1.0.3** - 优化标签列处理逻辑，增强时间处理模块，支持多时间列独立处理。
- **1.0.2** - 优化缺失值处理模块，简化代码结构，改进KNN填充和智能填充实现。
- **1.0.1** - 优化日志系统，使用用户主目录作为默认日志路径，添加自定义日志路径功能。
- **1.0.0** - 正式发布版本，包含完整的特征工程工具链。
- **3.3.4** - 修复日志系统，添加日志模式控制功能。
- **3.3.2** - 修复导入路径和bug。
- **3.3.1** - 优化自动路线推荐。
- **3.3.0** - 初始版本。

### 详细更新日志

更多详细的更新信息，请查看以下更新日志文件：

- [1.1.0 更新日志](./myffe/update_log/1.1.0.md)
- [1.0.4 更新日志](./myffe/update_log/1.0.4.md)
- [1.0.3 更新日志](./myffe/update_log/1.0.3.md)

## ✅ 测试结果

myffe 库经过全面的测试验证，确保所有功能正常运行。测试覆盖以下方面：

- **基础功能测试**：数据预处理、特征提取、样本处理等核心功能
- **高级功能测试**：流水线创建、自动路线推荐、数据评估等
- **工具模块测试**：日志系统、数据描述、路线可视化等
- **异常处理测试**：处理缺失值、异常值、边界情况等
- **性能测试**：处理不同规模数据集的性能
- **接口测试**：所有核心接口和便捷函数

所有测试均已通过，确保库在各种场景下的可靠性和稳定性。

## 📞 联系方式

- Email: <1757175380@qq.com>
- GitHub: <https://github.com/nan-luoyan-nan/myffe>