MLPlatform/doc/development_doc.md

# 机器学习平台开发文档

## 数据处理模块接口文档

### 1. DataProcessor (数据处理基类)
基础数据处理类，提供数据读取和保存功能。

#### 1.1 初始化参数
```python
config: Dict = None
    - csv_params: Dict  # CSV文件读取参数
    - log_level: str    # 日志级别
```

#### 1.2 主要方法
```python
def load_data(file_path: str) -> pd.DataFrame:
    """
    加载数据文件
    参数:
        file_path: 数据文件路径
    支持格式:
        - CSV
        - Parquet
        - HDF5
    """

def save_data(df: pd.DataFrame, file_path: str):
    """
    保存数据文件
    参数:
        df: 要保存的数据框
        file_path: 保存路径
    """
```

### 2. DataCleaner (数据清洗类)
继承自DataProcessor，提供数据清洗相关功能。

#### 2.1 初始化参数
```python
config: Dict = None
    - log_dir: str  # 日志保存路径
    - missing_value_methods: Dict  # 缺失值处理方法配置
```

#### 2.2 主要方法
```python
def handle_missing_values(
    df: pd.DataFrame,
    method: str = 'mean',
    columns: List[str] = None
) -> pd.DataFrame:
    """
    处理缺失值
    参数:
        df: 输入数据框
        method: 处理方法，可选['mean', 'median', 'mode', 'constant']
        columns: 需要处理的列，默认处理所有数值列
    """

def remove_duplicates(
    df: pd.DataFrame,
    subset: List[str] = None
) -> pd.DataFrame:
    """
    删除重复值
    参数:
        df: 输入数据框
        subset: 用于判断重复的列，默认使用所有列
    """

def detect_outliers(
    df: pd.DataFrame,
    method: str = 'zscore',
    threshold: float = 3
) -> pd.DataFrame:
    """
    检测并移除异常值
    参数:
        df: 输入数据框
        method: 检测方法，可选['zscore', 'isolation_forest']
        threshold: zscore方法的阈值
    """

def save_processed_data(
    df: pd.DataFrame,
    filename: str
):
    """
    保存处理后的数据到指定目录
    参数:
        df: 数据框
        filename: 文件名
    保存位置: dataset/dataset_processed/
    """
```

### 3. FeatureEngineer (特征工程类)
继承自DataProcessor，提供特征工程相关功能。

#### 3.1 初始化参数
```python
config: Dict = None
    包含特征工程相关配置
```

#### 3.2 主要方法
```python
def scale_features(
    df: pd.DataFrame,
    method: str = 'standard',
    columns: List[str] = None
) -> pd.DataFrame:
    """
    特征缩放
    参数:
        df: 输入数据框
        method: 缩放方法，可选['standard', 'minmax', 'robust']
        columns: 需要缩放的列，默认所有数值列
    """

def select_features(
    df: pd.DataFrame,
    target: str,
    method: str = 'chi2',
    k: int = 10
) -> pd.DataFrame:
    """
    特征选择
    参数:
        df: 输入数据框
        target: 目标变量列名
        method: 选择方法，可选['chi2', 'f_classif']
        k: 选择的特征数量
    """

def create_datetime_features(
    df: pd.DataFrame,
    datetime_column: str
) -> pd.DataFrame:
    """
    创建时间特征
    参数:
        df: 输入数据框
        datetime_column: 时间列名
    生成特征:
        - year
        - month
        - day
        - weekday
        - is_weekend
    """
```

### 4. DataSplitter (数据集划分类)
继承自DataProcessor，提供数据集划分功能。

#### 4.1 初始化参数
```python
config: Dict = None
```

#### 4.2 主要方法
```python
def train_val_test_split(
    df: pd.DataFrame,
    target: str,
    test_size: float = 0.2,
    val_size: float = 0.2,
    random_state: int = 42
) -> Tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
    """
    划分训练集、验证集和测试集
    参数:
        df: 输入数据框
        target: 目标变量列名
        test_size: 测试集比例
        val_size: 验证集比例
        random_state: 随机种子
    返回:
        (训练集, 验证集, 测试集)
    """
```

### 5. 使用示例

```python
# 配置
config = {
    'log_dir': '.log',
    'csv_params': {
        'encoding': 'utf-8',
        'na_values': ['', 'NULL', 'null']
    }
}

# 创建处理器实例
cleaner = DataCleaner(config)
engineer = FeatureEngineer(config)
splitter = DataSplitter(config)

# 数据处理流程
df = cleaner.load_data('dataset/dataset_raw/data.csv')
df = cleaner.handle_missing_values(df, method='mean')
df = cleaner.remove_duplicates(df)
df = cleaner.detect_outliers(df, method='zscore')

# 特征工程
df = engineer.scale_features(df, method='standard')
df = engineer.create_datetime_features(df, 'date_column')
df = engineer.select_features(df, target='target', k=10)

# 数据集划分
train, val, test = splitter.train_val_test_split(df, target='target')

# 保存处理后的数据
cleaner.save_processed_data(train, 'train.csv')
cleaner.save_processed_data(val, 'val.csv')
cleaner.save_processed_data(test, 'test.csv')
```

### 6. 注意事项

1. 数据存储规范：
   - 原始数据存放在 `dataset/dataset_raw/` 目录
   - 处理后数据存放在 `dataset/dataset_processed/` 目录
   - 日志文件存放在 `.log/` 目录

2. 异常处理：
   - 所有方法都包含异常处理
   - 异常信息会记录到日志文件
   - 建议使用try-except进行错误处理

3. 日志记录：
   - 每个操作都会记录详细日志
   - 异常值信息会单独保存
   - 可通过日志追踪数据处理过程

4. 配置管理：
   - 通过config字典统一管理配置
   - 支持自定义配置扩展
   - 关键参数都可配置化