mflowy 0.1.0__py3-none-any.whl

mflowy/__init__.py

@@ -0,0 +1 @@
+"""MFlowy — MCP-native modular ML workflow engine."""

mflowy/compute/cleaners/filter/common_filter.py

@@ -0,0 +1,55 @@
+"""列过滤器 - 实体实现
+
+功能：按列名、列值过滤数据
+"""
+
+import logging
+from typing import Annotated
+
+import pandas as pd
+
+from mflowy.driver.config import StepType
+from mflowy.driver.handler import handler
+from mflowy.middlewares.data_inject import inject_df
+from mflowy.middlewares.log_df_diff import df_diff
+
+logger = logging.getLogger(__name__)
+
+
+@handler(StepType.CLEAN, inject_df, df_diff)
+def common_filter(
+    df: pd.DataFrame,
+    *,
+    drop: Annotated[list[str] | None, "排除指定列"] = None,
+    remain: Annotated[list[str] | None, "仅保留指定列"] = None,
+    **kwargs,
+) -> pd.DataFrame:
+    """按列名做"丢弃"或"保留"两种集合操作之一（仅作用于列，不作用于行）。
+
+    drop：从结果中删除指定列；remain：仅保留 remain 中且仍存在于 df.columns 的列、其余删除。两者可同时使用：drop 先执行，remain 再在剩余列上执行。drop 与 remain 中不存在于 df.columns 的列名被静默忽略；remain 中缺失的列名额外打印 warning。两者都为 None 时原样返回。
+
+    用于"硬性按业务规则裁列"场景（如去掉 ID 列、只留特征列），不涉及任何数值统计。
+
+    common_filter 用"按列名手工选/删列"场景，variance_filter / correlation_filter 用"按统计指标自动筛列"场景。
+    """
+    cleaned_df = df
+
+    if drop:
+        drop_cols = [col for col in drop if col in cleaned_df.columns]
+        if drop_cols:
+            cleaned_df = cleaned_df.drop(columns=drop_cols)
+            logger.debug(f"Dropped {','.join(drop_cols)}")
+
+    if remain:
+        keep_cols = [col for col in remain if col in cleaned_df.columns]
+        missing_cols = set(remain) - set(keep_cols)
+        drop_cols = [col for col in cleaned_df.columns if col not in keep_cols]
+
+        if missing_cols:
+            logger.warning(f"{len(missing_cols)} columns not found: {missing_cols}")
+
+        if drop_cols:
+            cleaned_df = cleaned_df.drop(columns=drop_cols)
+            logger.debug(f"Dropped {','.join(drop_cols)}")
+
+    return cleaned_df

mflowy/compute/cleaners/filter/correlation_filter.py

@@ -0,0 +1,153 @@
+"""相关性过滤器 - 实体实现
+
+功能：基于特征相关性阈值过滤冗余特征
+"""
+
+import logging
+from itertools import combinations
+from typing import Annotated, Literal
+
+import pandas as pd
+
+from mflowy.driver.config import StepType
+from mflowy.driver.handler import handler
+from mflowy.middlewares.data_inject import inject_df
+from mflowy.middlewares.log_df_diff import df_diff
+
+logger = logging.getLogger(__name__)
+
+
+@handler(StepType.CLEAN, inject_df, df_diff)
+def correlation_filter(
+    df: pd.DataFrame,
+    *,
+    threshold: Annotated[float, "相关系数阈值 (0~1)，超过则移除其中一个特征"] = 0.9,
+    method: Annotated[Literal["pearson", "spearman", "kendall"], "相关性计算方法"] = "spearman",
+    priority_features: Annotated[list[str] | None, "优先保留的特征列表"] = None,
+    exclude: Annotated[list[str] | None, "不参与计算和过滤的列（如目标列）"] = None,
+    **kwargs,
+) -> pd.DataFrame:
+    """基于相关性阈值过滤高度共线的数值特征（仅删列）。
+
+    仅对数值列计算相关系数矩阵（method 默认 spearman，可切 pearson/kendall），|r| ≥ threshold（默认 0.9）的特征对视为冗余。两两比较后保留 priority_features 中优先项，否则保留方差更大者；exclude 列不参与计算且不被删除。数值列 <2 时原样返回。
+
+    用于"线性模型/可解释模型去除共线特征"场景。threshold∈[0,1]、method 非法均抛 ValueError。
+
+    correlation_filter 用"剔除冗余共线特征"场景，variance_filter 用"剔除低信息量特征"场景，iqr/zscore_detector 用"剔除异常样本（按行）"场景。
+    """
+    # 参数验证
+    if not 0 <= threshold <= 1:
+        raise ValueError(f"threshold must be between 0 and 1, got {threshold}")
+
+    if method not in ["pearson", "spearman", "kendall"]:
+        raise ValueError(f"method must be 'pearson', 'spearman', or 'kendall', got {method}")
+
+    # 记录原始形状
+    original_rows, original_cols = df.shape
+
+    # 识别数值列，并排除指定列
+    exclude_set = set(exclude) if exclude else set()
+    all_numeric_cols = df.select_dtypes(include=["number"]).columns.tolist()
+    numeric_cols = [col for col in all_numeric_cols if col not in exclude_set]
+    excluded_cols = [col for col in all_numeric_cols if col in exclude_set]
+
+    if len(numeric_cols) < 2:
+        logger.debug(
+            f"Less than 2 numeric columns found for correlation analysis ({len(numeric_cols)}), returning original data"
+        )
+        return df.copy()
+
+    # 计算相关性矩阵
+    corr_matrix = df[numeric_cols].corr(method=method)
+
+    # 识别高相关特征对
+    correlated_pairs = _find_correlated_pairs(corr_matrix, threshold=threshold)
+
+    if not correlated_pairs:
+        logger.debug(f"No highly correlated pairs found (threshold={threshold}, method={method})")
+        return df.copy()
+
+    # 确定要移除的特征
+    features_to_remove = _select_features_to_remove(
+        correlated_pairs=correlated_pairs,
+        data=df,
+        priority_features=priority_features or [],
+    )
+
+    # 执行过滤
+    non_numeric_cols = [col for col in df.columns if col not in all_numeric_cols]
+    final_cols = non_numeric_cols + excluded_cols + [col for col in numeric_cols if col not in features_to_remove]
+
+    result = df[final_cols]
+
+    logger.debug(
+        f"CorrelationFilter (threshold={threshold}, method={method}): {original_rows}x{original_cols} -> {result.shape[0]}x{result.shape[1]}, removed {len(features_to_remove)} features"
+    )
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# 内部辅助函数
+# ---------------------------------------------------------------------------
+
+
+def _find_correlated_pairs(
+    corr_matrix: pd.DataFrame,
+    threshold: float,
+) -> list[tuple[str, str, float]]:
+    """识别高相关特征对"""
+    correlated_pairs = []
+
+    for feat1, feat2 in combinations(corr_matrix.columns, 2):
+        corr_value = corr_matrix.loc[feat1, feat2]
+
+        if abs(corr_value) >= threshold:
+            correlated_pairs.append((feat1, feat2, abs(corr_value)))
+
+    correlated_pairs.sort(key=lambda x: x[2], reverse=True)
+
+    return correlated_pairs
+
+
+def _select_features_to_remove(
+    correlated_pairs: list[tuple[str, str, float]],
+    data: pd.DataFrame,
+    priority_features: list[str],
+) -> list[str]:
+    """从高相关特征对中选择要移除的特征
+
+    策略：
+    1. 优先保留 priority_features 中的特征
+    2. 在其余特征中，保留方差更大的特征
+    """
+    features_to_remove = []
+    removed_features = set()
+
+    numeric_cols = data.select_dtypes(include=["number"]).columns
+    feature_variances = data[numeric_cols].var().to_dict()
+
+    priority_set = set(priority_features)
+
+    for feat1, feat2, corr_value in correlated_pairs:
+        if feat1 in removed_features or feat2 in removed_features:
+            continue
+
+        if feat1 in priority_set and feat2 not in priority_set:
+            keep_feat, remove_feat = feat1, feat2
+        elif feat2 in priority_set and feat1 not in priority_set:
+            keep_feat, remove_feat = feat2, feat1
+        else:
+            if feature_variances.get(feat1, 0) >= feature_variances.get(feat2, 0):
+                keep_feat, remove_feat = feat1, feat2
+            else:
+                keep_feat, remove_feat = feat2, feat1
+
+        features_to_remove.append(remove_feat)
+        removed_features.add(remove_feat)
+
+        logger.debug(
+            f"High correlation detected: {feat1} <-> {feat2} (r={corr_value:.3f}), removing '{remove_feat}', keeping '{keep_feat}' (variance: {feature_variances.get(remove_feat, 0):.4f} vs {feature_variances.get(keep_feat, 0):.4f})"
+        )
+
+    return features_to_remove

mflowy/compute/cleaners/filter/variance_filter.py

@@ -0,0 +1,129 @@
+"""方差过滤器 - 实体实现
+
+功能：基于方差阈值过滤列或行
+"""
+
+import logging
+from typing import Annotated
+
+import pandas as pd
+
+from mflowy.driver.config import StepType
+from mflowy.driver.handler import handler
+from mflowy.middlewares.data_inject import inject_df
+from mflowy.middlewares.log_df_diff import df_diff
+
+logger = logging.getLogger(__name__)
+
+
+@handler(StepType.CLEAN, inject_df, df_diff)
+def variance_filter(
+    df: pd.DataFrame,
+    *,
+    axis: Annotated[int, "过滤方向 (0=按列, 1=按行)"] = 0,
+    threshold: Annotated[float, "方差阈值，低于此值将被过滤"] = 0.0,
+    column_thresholds: Annotated[dict[str, float] | None, "按列覆盖的特定阈值"] = None,
+    **kwargs,
+) -> pd.DataFrame:
+    """按方差阈值过滤列（axis=0）或行（axis=1）。
+
+    仅作用于数值列；axis=0 时删除数值列方差 < threshold 的列（保留非数值列），axis=1 时删除数值行方差 < threshold 的行。threshold 默认 0.0（即删除常量列/常量行）。column_thresholds 可按列名/行索引覆盖单一阈值。
+
+    用于"剔除常量或近常量特征/样本"场景，如方差=0 的列无法区分样本。负数阈值抛 ValueError。
+
+    variance_filter 用"按方差筛掉低信息列"场景，correlation_filter 用"按相关性筛掉冗余列"场景，common_filter 用"按业务规则硬选/硬删列名"场景。
+    """
+    # 参数验证
+    if axis not in [0, 1]:
+        raise ValueError(f"axis must be 0 or 1, got {axis}")
+
+    if threshold < 0:
+        raise ValueError(f"threshold must be non-negative, got {threshold}")
+
+    if column_thresholds:
+        for key, value in column_thresholds.items():
+            if value < 0:
+                raise ValueError(f"column_thresholds['{key}'] must be non-negative, got {value}")
+
+    # 记录原始形状
+    original_rows, original_cols = df.shape
+
+    # 执行过滤
+    if axis == 0:
+        result = _filter_columns(df, threshold=threshold, column_thresholds=column_thresholds)
+    else:
+        result = _filter_rows(df, threshold=threshold, column_thresholds=column_thresholds)
+
+    logger.debug(
+        f"VarianceFilter (axis={axis}): {original_rows}x{original_cols} -> {result.shape[0]}x{result.shape[1]}"
+    )
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# 内部辅助函数
+# ---------------------------------------------------------------------------
+
+
+def _filter_columns(
+    data: pd.DataFrame,
+    *,
+    threshold: float,
+    column_thresholds: dict[str, float] | None,
+) -> pd.DataFrame:
+    """过滤低方差列"""
+    df = data.copy()
+
+    numeric_cols = df.select_dtypes(include=["number"]).columns.tolist()
+    if not numeric_cols:
+        logger.debug("No numeric columns found, returning original data")
+        return df
+
+    variances = df[numeric_cols].var()
+
+    columns_to_keep = []
+    columns_to_remove = []
+
+    for col in numeric_cols:
+        col_threshold = column_thresholds.get(col, threshold) if column_thresholds else threshold
+
+        if variances[col] >= col_threshold:
+            columns_to_keep.append(col)
+        else:
+            columns_to_remove.append(col)
+            logger.debug(f"Column '{col}' removed: variance={variances[col]:.4f} < threshold={col_threshold:.4f}")
+
+    non_numeric_cols = [col for col in df.columns if col not in numeric_cols]
+    final_cols = non_numeric_cols + columns_to_keep
+
+    return df[final_cols]
+
+
+def _filter_rows(
+    data: pd.DataFrame,
+    *,
+    threshold: float,
+    column_thresholds: dict[str, float] | None,
+) -> pd.DataFrame:
+    """过滤低方差行"""
+    df = data.copy()
+
+    numeric_cols = df.select_dtypes(include=["number"]).columns.tolist()
+    if not numeric_cols:
+        logger.debug("No numeric columns found, returning original data")
+        return df
+
+    row_variances = df[numeric_cols].var(axis=1)
+
+    rows_to_keep = []
+
+    for idx in df.index:
+        row_threshold = column_thresholds.get(str(idx), threshold) if column_thresholds else threshold
+
+        if row_variances[idx] >= row_threshold:
+            rows_to_keep.append(idx)
+        else:
+            logger.debug(f"Row {idx} removed: variance={row_variances[idx]:.4f} < threshold={row_threshold:.4f}")
+
+    return df.loc[rows_to_keep]

mflowy/compute/cleaners/missing/drop_handler.py

@@ -0,0 +1,51 @@
+"""删除缺失值处理器"""
+
+import logging
+from typing import Annotated
+
+import pandas as pd
+
+from mflowy.driver.config import StepType
+from mflowy.driver.handler import handler
+from mflowy.middlewares.data_inject import inject_df
+from mflowy.middlewares.log_df_diff import df_diff
+
+logger = logging.getLogger(__name__)
+
+
+@handler(StepType.CLEAN, inject_df, df_diff)
+def drop_missing(
+    df: pd.DataFrame,
+    *,
+    threshold: Annotated[float, "[0, 1.0]，全局缺失率门禁， ≥ threshold 的列将被删除"] = 0.6,
+    column_threshold: Annotated[dict[str, float] | None, "为不同列配置不同的缺失率门禁，不配置时，采用全局门禁"] = None,
+    exclude: Annotated[list[str] | None, "不做缺失值门禁检查的列"] = None,
+    **kwargs,
+) -> pd.DataFrame:
+    """按列删除缺失率超阈值的列（按列删除，非按行）。
+
+    仅遍历列、比较 isnull().mean() ≥ 阈值即删列，不删行。threshold 为 [0,1] 全局门禁（默认 0.6）；column_threshold 为单列覆盖；阈值=1 或 <0 时直接返回原表（no-op）。
+
+    用于"剔除数据质量过差的列"场景（如缺失率 ≥60% 的列），不适用于"删除任意含缺失的行"。column_threshold 用于差异化门禁场景（如关键业务列放宽到 0.9、辅助列收紧到 0.3）。
+
+    drop_missing 用"整列丢弃"场景，fill_missing 用"保留行但插补"场景。
+    """
+    column_threshold = column_threshold or {}
+    threshold = min(threshold, 1)
+    if threshold < 0:
+        return df
+    if threshold == 1:
+        return df
+
+    cleaned_df = df
+    missing_rates = cleaned_df.isnull().mean()
+
+    cols_to_drop = []
+    for col, missing_rate in missing_rates.items():
+        gate = column_threshold.get(str(col), threshold)
+        if missing_rate >= gate:
+            cols_to_drop.append(col)
+            logger.debug(f"{col} with missing rate >= {gate} will be Dropped")
+    if cols_to_drop:
+        cleaned_df = cleaned_df.drop(columns=cols_to_drop)
+    return cleaned_df

mflowy/compute/cleaners/missing/fill_handler.py

@@ -0,0 +1,121 @@
+"""填充缺失值处理器"""
+
+import logging
+from typing import Annotated, Literal
+
+import pandas as pd
+
+from mflowy.driver.config import StepType
+from mflowy.driver.handler import handler
+from mflowy.middlewares.data_inject import inject_df
+from mflowy.middlewares.log_df_diff import df_diff
+
+logger = logging.getLogger(__name__)
+
+type _MISSING_STRATEGY = Literal[
+    "mean", "median", "interpolate", "forward", "backward", "mode", "fill", "fill_grouped_mode"
+]
+
+EMPTY_GROUPY_BY = ValueError("缺失值填充策略 fill_grouped_mode 的分组列为空")
+
+
+@handler(StepType.CLEAN, inject_df, df_diff)
+def fill_missing(
+    df: pd.DataFrame,
+    *,
+    strategy: Annotated[_MISSING_STRATEGY, "全局填充策略，默认中位数填充"] = "median",
+    column_strategy: Annotated[
+        dict[str, _MISSING_STRATEGY] | None, "为不同列配置不同的填充策略，不配置时，采用全局填充策略"
+    ] = None,
+    fill_value: Annotated[str, "strategy=fill 时的全局填充值"] = "Unknown",
+    column_fill_value: Annotated[
+        dict[str, str] | None, "strategy=fill 时，为不同列配置不同的填充值，不配置时，采用全局填充值"
+    ] = None,
+    group_by: Annotated[str | list[str] | None, "strategy=fill_grouped_mode 时，使用分组后的众数填充"] = None,
+    missing_indicator: Annotated[bool, r"增加缺失指示器, {col}_is_missing"] = True,
+    **kwargs,
+) -> pd.DataFrame:
+    """按列填充缺失值，missing_indicator=True 默认开启 {col}_is_missing 缺失指示列。
+
+    strategy 全局默认 median；column_strategy / column_fill_value 可对单列覆盖。fallback 路径：数值列遇到 fill/mode 时先回退到全局 strategy、二次失败才落到 median；分类列遇到 median/mean/interpolate/forward/backward 时直接 fallback 用 fill_value 填充。fill_grouped_mode 必须配 group_by，否则抛 EMPTY_GROUPY_BY。
+
+    数值列：mean 用正态分布、近似无离群点的场景，median 用含离群点的稳健场景；forward/backward 用时序相邻填充场景，interpolate 用趋势平滑序列场景。分类列：fill 引入新类别保留缺失信号，mode 用全局众数、fill_grouped_mode 用分组众数。
+    """
+    column_strategy = column_strategy or {}
+    column_fill_value = column_fill_value or {}
+
+    cleaned_df = df
+
+    missing = cleaned_df.isnull()
+    missing_count = missing.sum()
+    missing_cols = missing_count[missing_count > 0].index
+
+    if missing_indicator:
+        indicator_df = missing[missing_cols].astype(int).add_suffix("_is_missing")
+        cleaned_df = pd.concat([df, indicator_df], axis=1)
+
+    def fill_numeric(df: pd.DataFrame, col, fallback_cnt: bool):
+        _strategy = column_strategy.get(str(col), strategy)
+        match _strategy:
+            case "mean":
+                df[col] = df[col].fillna(df[col].mean())
+                logger.debug(f"Filled {col} with mean")
+            case "median":
+                df[col] = df[col].fillna(df[col].median())
+                logger.debug(f"Filled {col} with median")
+            case "forward":
+                df[col] = df[col].ffill()
+                logger.debug(f"Filled {col} with ffill")
+            case "backward":
+                df[col] = df[col].bfill()
+                logger.debug(f"Filled {col} with bfill")
+            case "interpolate":
+                df[col] = df[col].interpolate(method="linear")
+                logger.debug(f"Filled {col} with linear interpolate")
+            case "fill_grouped_mode":
+                if not group_by:
+                    raise EMPTY_GROUPY_BY
+                mode_map = df.groupby(group_by)[col].agg(lambda x: x.mode()[0] if not x.mode().empty else 1e-8)
+                df[col] = df[col].fillna(df[group_by].map(mode_map))
+                logger.debug(f"Filled {col} with fill_grouped_mode")
+            case _:
+                if fallback_cnt := not fallback_cnt:
+                    logger.warning(
+                        f"{col} 类型为 {df[col].dtype}，不支持 {_strategy} 填充策略，回滚到 {strategy} 填充策略"
+                    )
+                    _strategy = strategy
+                    fill_numeric(df, col, fallback_cnt)
+                else:
+                    logger.warning(f"{col} 类型为 {df[col].dtype}，不支持 {_strategy} 填充策略，回滚到 median 填充策略")
+                df[col] = df[col].fillna(df[col].median())
+        return df
+
+    def fill_category(df: pd.DataFrame, col, fallback_cnt: bool):
+        _strategy = column_strategy.get(str(col), strategy)
+        _fill_value = column_fill_value.get(str(col), fill_value)
+        match _strategy:
+            case "fill":
+                df[col] = df[col].fillna(_fill_value)
+                logger.debug(f"Filled {col} with {_fill_value}")
+            case "mode":
+                mode_0 = df[col].mode()[0]
+                df[col] = df[col].fillna(mode_0)
+                logger.debug(f"Filled {col} with {mode_0}")
+            case "fill_grouped_mode":
+                if not group_by:
+                    raise EMPTY_GROUPY_BY
+                mode_map = df.groupby(group_by)[col].agg(lambda x: x.mode()[0] if not x.mode().empty else _fill_value)
+                df[col] = df[col].fillna(df[group_by].map(mode_map))
+                logger.debug(f"Filled {col} with fill_grouped_mode")
+            case _:
+                logger.warning(f"{col} 类型为 {df[col].dtype}，不支持 {_strategy} 填充策略，回滚到 fill 填充策略")
+                df[col] = df[col].fillna(_fill_value)
+
+    for col in missing_cols:
+        fallback_cnt = False
+        if pd.api.types.is_numeric_dtype(cleaned_df[col]):
+            fill_numeric(cleaned_df, col, fallback_cnt)
+        else:
+            fill_category(cleaned_df, col, fallback_cnt)
+
+    return cleaned_df

mflowy/compute/cleaners/outlier/iqr_detector.py

@@ -0,0 +1,106 @@
+"""IQR 异常值检测器"""
+
+import logging
+from typing import Annotated, Literal
+
+import numpy as np
+import pandas as pd
+
+from mflowy.driver.config import StepType
+from mflowy.driver.handler import handler
+from mflowy.middlewares.data_inject import inject_df
+from mflowy.middlewares.log_df_diff import df_diff
+
+logger = logging.getLogger(__name__)
+
+
+@handler(StepType.CLEAN, inject_df, df_diff)
+def iqr_detector(
+    df: pd.DataFrame,
+    *,
+    threshold: Annotated[float, "IQR 倍数阈值"] = 1.5,
+    strategy: Annotated[Literal["remove", "cap", "replace"], "处理方式 (remove/cap/replace)"] = "remove",
+    replace_value: Annotated[float | None, "替换值（strategy=replace 时必填）"] = None,
+    columns: Annotated[list[str] | None, "检测列，None 表示所有数值列"] = None,
+    **kwargs,
+) -> pd.DataFrame:
+    """基于四分位距（IQR）检测数值列异常值并按 strategy 处理。
+
+    按列计算 Q1/Q3，落在 [Q1 - threshold·IQR, Q3 + threshold·IQR] 之外的样本视为异常（threshold 默认 1.5）。columns=None 时检测所有数值列；非数值列与不存在的列被跳过。
+
+    strategy 三分支：remove（删除整行异常样本）、cap（把越界值夹到 IQR 边界，整数列自动转 float）、replace（把异常值替换为 replace_value，缺省抛 ValueError）。
+
+    iqr_detector 用"分布偏斜、有重尾"的非正态场景，zscore_detector 用"近似正态分布"场景。
+    """
+    result = df.copy()
+
+    # 确定检测列
+    if columns is None:
+        columns = result.select_dtypes(include=[np.number]).columns.tolist()
+
+    # ---- 检测阶段 ----
+    outlier_mask = np.zeros(len(result), dtype=bool)
+    skipped: list[str] = []
+
+    for col in columns:
+        if col not in result.columns:
+            skipped.append(col)
+            continue
+        if not pd.api.types.is_numeric_dtype(result[col]):
+            skipped.append(f"{col} (非数值类型)")
+            continue
+
+        Q1 = result[col].quantile(0.25)
+        Q3 = result[col].quantile(0.75)
+        IQR = Q3 - Q1
+        lower_bound = Q1 - threshold * IQR
+        upper_bound = Q3 + threshold * IQR
+
+        col_outliers = (result[col] < lower_bound) | (result[col] > upper_bound)
+        outlier_mask |= col_outliers
+
+    outlier_count = int(outlier_mask.sum())
+
+    if skipped:
+        logger.debug(f"跳过 {len(skipped)} 列: {skipped}")
+
+    logger.debug(f"Detected {outlier_count} outliers using IQR method (threshold={threshold})")
+
+    # ---- 处理阶段 ----
+    if strategy == "remove":
+        result = result[~outlier_mask].copy()
+        logger.info(f"Removed {outlier_count} outlier samples")
+
+    elif strategy == "cap":
+        # IQR 检测器的 cap 始终使用 IQR 边界
+        numeric_cols = result.select_dtypes(include=[np.number]).columns
+
+        for col in numeric_cols:
+            Q1 = result[col].quantile(0.25)
+            Q3 = result[col].quantile(0.75)
+            IQR = Q3 - Q1
+            lower_bound = Q1 - threshold * IQR
+            upper_bound = Q3 + threshold * IQR
+
+            if pd.api.types.is_integer_dtype(result[col]):
+                result[col] = result[col].astype(float)
+            result.loc[result[col] < lower_bound, col] = lower_bound
+            result.loc[result[col] > upper_bound, col] = upper_bound
+
+        logger.debug(f"Capped {outlier_count} outlier values to IQR boundary")
+
+    elif strategy == "replace":
+        if replace_value is None:
+            raise ValueError("replace_value 参数在 strategy='replace' 时必须提供")
+
+        numeric_cols = result.select_dtypes(include=[np.number]).columns
+
+        for col in numeric_cols:
+            result.loc[outlier_mask, col] = replace_value
+
+        logger.debug(f"Replaced {outlier_count} outlier values with {replace_value}")
+
+    else:
+        raise ValueError(f"未知的处理方式: {strategy}")
+
+    return result