wtclean 0.1.0__tar.gz

wtclean-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, wtclean contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

wtclean-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: wtclean
+Version: 0.1.0
+Summary: Wind turbine SCADA power-curve data cleaning via iterative bin + MAD filtering
+License: BSD-3-Clause
+Keywords: wind-energy,wind-turbine,scada,power-curve,outlier-detection,data-cleaning
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# wtclean
+
+风电机组 SCADA 功率曲线数据清洗工具：用「迭代分箱 + MAD（中位数绝对偏差）」把**正常运行数据**从原始 SCADA 数据中初筛出来。
+
+## 这个包是做什么的
+
+输入**一台风机**的 SCADA 数据（至少要含风速、有功功率两列，通常为 10 分钟统计记录）。
+
+`PowerCurveFiltering.process()` 会把数据按行切分成两份返回：
+
+- **`normal_df`**：风机**正常运行**的数据点——功率落在该风速区间应有的功率带内。**后续做功率曲线建模、工况分析、机器学习等时主要用这一份**。
+- **`abnormal_df`**：其余所有被剔除的点。⚠️ **它不是"严格异常集"**，而是混了多种情况：停机、故障、限电/降载、桨距控制等**其它工况**、以及真正的传感器/数据异常。想区分异常类型，需要后续用更高阶方法（如 GAM/sigmoid 拟合、时间维度分析）处理。
+
+单台风机的整条清洗流水线分三步：
+
+1. **去停机**：风速 ≥ 切入风速、但功率 ≤ 1 kW 的点（风机已停机）→ 剔除。
+2. **高风低功率粗洗**：风速 ≥ 额定风速、但功率 < `low_power_ratio × 额定功率` 的点（限电、降载、桨距/故障等非正常发电）→ 剔除。
+3. **迭代 bin+MAD 精洗**：按 `bin_interval` 把风速分箱，对每箱算功率中位数与 MAD，箱内功率落在 `中位数 ± z_coeff × MAD` 带外的点 → 剔除。剔除后**重新分箱再剔**，重复 `filter_cycle` 轮（每轮带会随数据变干净而收窄）。
+
+几个内置的判定约定（避免误杀正常点）：
+
+- 箱内样本 < 3，或功率离散度为 0（典型如额定功率平台），该箱**不判定、直接保留**；
+- 风速低于切入风速的点默认保留（近零功率属正常待机）；
+- 恒定功率的"水平聚集"类异常（如某段时间被固定在某一功率）**bin+MAD 识别不出来**，这是本方法的能力上限，应交给后续更精细的方案。
+
+## 安装
+
+```bash
+git clone <this-repo>
+cd wtclean
+pip install -r requirements.txt
+pip install .
+```
+
+## 快速开始（单台风机）
+
+```python
+import pandas as pd
+from wtclean import PowerCurveFiltering
+
+df = pd.read_csv("data.csv")
+turbine = df[df["Wind_turbine_name"] == "R80721"]   # 取单台风机
+
+pc_filter = PowerCurveFiltering(
+    windspeed_label="Ws_avg",     # 风速列名
+    power_label="P_avg",          # 有功功率列名
+    df=turbine,                   # 单台风机数据
+    cut_in_speed=3.5,             # 切入风速（厂商参数，必填）
+    rated_wind_speed=14.5,        # 额定风速（厂商参数，必填）
+    rated_power=2050,             # 额定功率 kW（厂商参数，必填）
+    low_power_ratio=0.9,          # 高风低功率粗洗阈值（默认 0.9）
+    bin_interval=0.5,             # 风速分箱宽度（默认 0.5）
+    z_coeff=2.5,                  # 正常带宽度系数（默认 2.5）
+    filter_cycle=3,               # 迭代轮数（默认 3）
+    return_fig=False,             # 是否保存功率曲线图
+    image_path="",                # 出图时的完整输出文件路径
+)
+
+normal_df, abnormal_df = pc_filter.process()
+```
+
+运行时会逐轮打印删除情况，例如：
+
+```
+iteration 1: removed 3864 (7.21%), remaining 49724
+iteration 2: removed 1655 (3.33%), remaining 48069
+iteration 3: removed 904 (1.88%), remaining 47165
+```
+
+每轮删除数也会记录在 `pc_filter.removal_history`（list[int]），方便你审计或画收敛曲线。
+
+## 多台风机
+
+`PowerCurveFiltering` 一次只处理一台；多台由调用方 `groupby` 后循环调用：
+
+```python
+from wtclean import PowerCurveFiltering, estimate_machine_parameters
+
+results = {}
+for name, group in df.groupby("Wind_turbine_name"):
+    params = estimate_machine_parameters(group, "Ws_avg", "P_avg")  # 先反推厂商参数
+    pcf = PowerCurveFiltering(
+        "Ws_avg", "P_avg", group,
+        cut_in_speed=params["cut_in_speed"],
+        rated_wind_speed=params["rated_wind_speed"],
+        rated_power=params["rated_power"],
+    )
+    results[name] = pcf.process()   # (normal_df, abnormal_df)
+```
+
+## 厂商参数不知道怎么办
+
+`cut_in_speed` / `rated_wind_speed` / `rated_power` 是**风机机型物理参数，必填**。若拿不到厂商技术参数，可先从 SCADA 数据反推（`estimate_machine_parameters` 会估计全部三个值），再把结果传给构造函数：
+
+```python
+from wtclean import estimate_machine_parameters
+
+params = estimate_machine_parameters(turbine, "Ws_avg", "P_avg")
+# -> {"cut_in_speed": 3.78, "rated_wind_speed": 13.59, "rated_power": 1985.3}
+```
+
+> 注意：反推值来自（通常是 10 分钟统计的）SCADA 数据，是"软"值——例如反推的额定风速约 13 m/s，会低于厂商标称的约 14.5 m/s，因为时间平均会把功率曲线拐点往左拉。生产使用前建议与厂商功率曲线表交叉核对；正式项目优先填厂商标称值。
+
+## 参数说明
+
+| 参数 | 默认 | 含义 |
+| --- | --- | --- |
+| `windspeed_label` | — | 风速列名（必填）。 |
+| `power_label` | — | 有功功率列名（必填）。 |
+| `df` | — | **单台**风机的 SCADA DataFrame（必填）。 |
+| `cut_in_speed` | — | 切入风速 m/s（厂商参数，必填）。低于该风速默认保留；停机判定从该风速起算。 |
+| `rated_wind_speed` | — | 额定风速 m/s（厂商参数，必填）。风速 ≥ 它时风机应接近额定功率，是"高风低功率粗洗"的起点。 |
+| `rated_power` | — | 额定功率 kW（厂商参数，必填）。高风区各类比例阈值都以此为基准。 |
+| `low_power_ratio` | `0.9` | 高风低功率粗洗阈值：风速 ≥ 额定风速时，功率 < 该比例×额定功率 即剔除。 |
+| `bin_interval` | `0.5` | 风速分箱宽度 m/s。越小分箱越细（样本少的区段统计越不稳），越大越粗。 |
+| `z_coeff` | `2.5` | 正常带宽度 = `中位数 ± z_coeff × MAD`。见下方调参建议。 |
+| `filter_cycle` | `3` | bin+MAD 迭代精洗的轮数上限。见下方调参建议。 |
+| `return_fig` | `False` | 是否保存一张功率曲线清洗结果散点图（蓝=Normal / 橙=Abnormal）。 |
+| `image_path` | `""` | `return_fig=True` 时输出图片的**完整文件路径**（含文件名，如 `./images/turbine_pc.png`）；目录不存在会自动创建。 |
+
+## 调参建议（最终决策权在你）
+
+**"保留多少 / 洗得多纯"没有绝对正确的值**，取决于你拿到 `normal_df` 后要干什么——拿去给高阶模型精洗可以放宽一点（尽量保点），指望初筛结果直接用就得收紧。每次调参都是"保点 vs 纯净"的权衡，建议结合输出图与逐轮打印来判断。以下给出方向和量级参考。
+
+### `z_coeff`——正常带多宽（影响最大，决定"删多少"）
+
+含义：功率偏离该箱中位数多少个 MAD 算正常。**MAD 用原始值、未乘 1.4826**，所以不能直接当"σ 倍数"读；换算成高斯直觉（原始 MAD ≈ 0.675σ）：
+
+| z_coeff | 正常带约 | 高斯下保留比例 | 档位 |
+| --- | --- | --- | --- |
+| `2.0` | ±1.35σ | ~82% | 激进（洗得纯，易误删） |
+| `2.5`（默认） | ±1.69σ | ~91% | 居中 |
+| `3.0` | ±2.02σ | ~96% | 偏宽松 |
+| `4.0` | ±2.70σ | ~99% | 很宽松（基本只剔粗洗） |
+
+- **越大 → 带越宽 → 保留越多**（正常点误删少，但漏进 `normal_df` 的真异常变多）；
+- **越小 → 带越窄 → 删得越多**（`normal_df` 更纯，但可能误删边界正常点）。
+
+实测参考（La Haute Borne，MM82，`filter_cycle=3`）：`z_coeff=2.5` 时 abnormal 约 13–15%；`z_coeff=4.0` 时骤降到约 3%（此时 MAD 层每轮只删 ~1%，第 2、3 轮基本空转）。也就是说 `z_coeff=4` 已接近"纯粗洗"。
+
+建议：后续要做 GAM/sigmoid/时间维度精洗时，可把 `z_coeff` 放到 3~4 先把明显离群点去掉；若想让这一层初筛就尽量干净、愿意接受少部分正常点损失，用 2~2.5。
+
+### `filter_cycle`——迭代几轮
+
+机制：第 1 轮删得最多（清掉最明显的离群点），之后每轮重新分箱、带变窄，**删除量快速递减**——后面几轮主要是在不断收窄正常带，**可能开始误删边界正常点**。
+
+- 实测各数据集上，多数风机的删除量到第 3~5 轮已降到每轮 <1%（可看逐轮打印确认）。
+- 想要**更保守、尽量保留正常点**：`2` 就够，甚至 `1`（只粗洗 + 单轮 MAD）；
+- 想**更彻底**（如训练样本允许损失一部分）：`5`，但要警惕过度清洗；
+- 反正每轮都会打印删除量与比例，看到某轮删除已经趋近 0，就说明再加轮次意义不大。
+
+### 其它参数
+
+- **`low_power_ratio`**：只影响额定风速以上的"限电/降载"粗洗。想多剔除降载工况就调小（如 0.85），想更保险保留就调大。注意别设太低，否则额定平台上的轻微降载会漏掉。
+- **`bin_interval`**：高风速区样本稀的话可适当调大（如 1.0）提高该区段 MAD 稳定性；低风速区样本极多时调小能更精细。默认 0.5 对多数 10 分钟数据够用。
+- **`cut_in_speed`/`rated_wind_speed`/`rated_power`**：这三个是物理参数，**不要拿来当清洗旋钮调**。设错会直接让粗洗规则失效（比如额定风速设太低会把正常爬坡段误当"高风低功率"整段删掉）。拿不准就反推，再和厂商表核对。
+
+## 出图（`return_fig=True`）
+
+会画一张风速-功率散点图：蓝色 = Normal（`normal_df`），橙色 = Abnormal（`abnormal_df`），图例已标注。图片保存到 `image_path` 指定的完整文件路径。建议每次调参都出一张图，肉眼确认"边界处"是否删得合理。
+
+## 测试
+
+```bash
+python -m unittest discover -s test -v
+```
+
+当前测试覆盖：正常/异常切分、重复索引不膨胀、粗洗（停机、高风低功率）、非法参数与空数据校验、出图、迭代删除记录。

wtclean-0.1.0/README.md

@@ -0,0 +1,168 @@
+# wtclean
+
+风电机组 SCADA 功率曲线数据清洗工具：用「迭代分箱 + MAD（中位数绝对偏差）」把**正常运行数据**从原始 SCADA 数据中初筛出来。
+
+## 这个包是做什么的
+
+输入**一台风机**的 SCADA 数据（至少要含风速、有功功率两列，通常为 10 分钟统计记录）。
+
+`PowerCurveFiltering.process()` 会把数据按行切分成两份返回：
+
+- **`normal_df`**：风机**正常运行**的数据点——功率落在该风速区间应有的功率带内。**后续做功率曲线建模、工况分析、机器学习等时主要用这一份**。
+- **`abnormal_df`**：其余所有被剔除的点。⚠️ **它不是"严格异常集"**，而是混了多种情况：停机、故障、限电/降载、桨距控制等**其它工况**、以及真正的传感器/数据异常。想区分异常类型，需要后续用更高阶方法（如 GAM/sigmoid 拟合、时间维度分析）处理。
+
+单台风机的整条清洗流水线分三步：
+
+1. **去停机**：风速 ≥ 切入风速、但功率 ≤ 1 kW 的点（风机已停机）→ 剔除。
+2. **高风低功率粗洗**：风速 ≥ 额定风速、但功率 < `low_power_ratio × 额定功率` 的点（限电、降载、桨距/故障等非正常发电）→ 剔除。
+3. **迭代 bin+MAD 精洗**：按 `bin_interval` 把风速分箱，对每箱算功率中位数与 MAD，箱内功率落在 `中位数 ± z_coeff × MAD` 带外的点 → 剔除。剔除后**重新分箱再剔**，重复 `filter_cycle` 轮（每轮带会随数据变干净而收窄）。
+
+几个内置的判定约定（避免误杀正常点）：
+
+- 箱内样本 < 3，或功率离散度为 0（典型如额定功率平台），该箱**不判定、直接保留**；
+- 风速低于切入风速的点默认保留（近零功率属正常待机）；
+- 恒定功率的"水平聚集"类异常（如某段时间被固定在某一功率）**bin+MAD 识别不出来**，这是本方法的能力上限，应交给后续更精细的方案。
+
+## 安装
+
+```bash
+git clone <this-repo>
+cd wtclean
+pip install -r requirements.txt
+pip install .
+```
+
+## 快速开始（单台风机）
+
+```python
+import pandas as pd
+from wtclean import PowerCurveFiltering
+
+df = pd.read_csv("data.csv")
+turbine = df[df["Wind_turbine_name"] == "R80721"]   # 取单台风机
+
+pc_filter = PowerCurveFiltering(
+    windspeed_label="Ws_avg",     # 风速列名
+    power_label="P_avg",          # 有功功率列名
+    df=turbine,                   # 单台风机数据
+    cut_in_speed=3.5,             # 切入风速（厂商参数，必填）
+    rated_wind_speed=14.5,        # 额定风速（厂商参数，必填）
+    rated_power=2050,             # 额定功率 kW（厂商参数，必填）
+    low_power_ratio=0.9,          # 高风低功率粗洗阈值（默认 0.9）
+    bin_interval=0.5,             # 风速分箱宽度（默认 0.5）
+    z_coeff=2.5,                  # 正常带宽度系数（默认 2.5）
+    filter_cycle=3,               # 迭代轮数（默认 3）
+    return_fig=False,             # 是否保存功率曲线图
+    image_path="",                # 出图时的完整输出文件路径
+)
+
+normal_df, abnormal_df = pc_filter.process()
+```
+
+运行时会逐轮打印删除情况，例如：
+
+```
+iteration 1: removed 3864 (7.21%), remaining 49724
+iteration 2: removed 1655 (3.33%), remaining 48069
+iteration 3: removed 904 (1.88%), remaining 47165
+```
+
+每轮删除数也会记录在 `pc_filter.removal_history`（list[int]），方便你审计或画收敛曲线。
+
+## 多台风机
+
+`PowerCurveFiltering` 一次只处理一台；多台由调用方 `groupby` 后循环调用：
+
+```python
+from wtclean import PowerCurveFiltering, estimate_machine_parameters
+
+results = {}
+for name, group in df.groupby("Wind_turbine_name"):
+    params = estimate_machine_parameters(group, "Ws_avg", "P_avg")  # 先反推厂商参数
+    pcf = PowerCurveFiltering(
+        "Ws_avg", "P_avg", group,
+        cut_in_speed=params["cut_in_speed"],
+        rated_wind_speed=params["rated_wind_speed"],
+        rated_power=params["rated_power"],
+    )
+    results[name] = pcf.process()   # (normal_df, abnormal_df)
+```
+
+## 厂商参数不知道怎么办
+
+`cut_in_speed` / `rated_wind_speed` / `rated_power` 是**风机机型物理参数，必填**。若拿不到厂商技术参数，可先从 SCADA 数据反推（`estimate_machine_parameters` 会估计全部三个值），再把结果传给构造函数：
+
+```python
+from wtclean import estimate_machine_parameters
+
+params = estimate_machine_parameters(turbine, "Ws_avg", "P_avg")
+# -> {"cut_in_speed": 3.78, "rated_wind_speed": 13.59, "rated_power": 1985.3}
+```
+
+> 注意：反推值来自（通常是 10 分钟统计的）SCADA 数据，是"软"值——例如反推的额定风速约 13 m/s，会低于厂商标称的约 14.5 m/s，因为时间平均会把功率曲线拐点往左拉。生产使用前建议与厂商功率曲线表交叉核对；正式项目优先填厂商标称值。
+
+## 参数说明
+
+| 参数 | 默认 | 含义 |
+| --- | --- | --- |
+| `windspeed_label` | — | 风速列名（必填）。 |
+| `power_label` | — | 有功功率列名（必填）。 |
+| `df` | — | **单台**风机的 SCADA DataFrame（必填）。 |
+| `cut_in_speed` | — | 切入风速 m/s（厂商参数，必填）。低于该风速默认保留；停机判定从该风速起算。 |
+| `rated_wind_speed` | — | 额定风速 m/s（厂商参数，必填）。风速 ≥ 它时风机应接近额定功率，是"高风低功率粗洗"的起点。 |
+| `rated_power` | — | 额定功率 kW（厂商参数，必填）。高风区各类比例阈值都以此为基准。 |
+| `low_power_ratio` | `0.9` | 高风低功率粗洗阈值：风速 ≥ 额定风速时，功率 < 该比例×额定功率 即剔除。 |
+| `bin_interval` | `0.5` | 风速分箱宽度 m/s。越小分箱越细（样本少的区段统计越不稳），越大越粗。 |
+| `z_coeff` | `2.5` | 正常带宽度 = `中位数 ± z_coeff × MAD`。见下方调参建议。 |
+| `filter_cycle` | `3` | bin+MAD 迭代精洗的轮数上限。见下方调参建议。 |
+| `return_fig` | `False` | 是否保存一张功率曲线清洗结果散点图（蓝=Normal / 橙=Abnormal）。 |
+| `image_path` | `""` | `return_fig=True` 时输出图片的**完整文件路径**（含文件名，如 `./images/turbine_pc.png`）；目录不存在会自动创建。 |
+
+## 调参建议（最终决策权在你）
+
+**"保留多少 / 洗得多纯"没有绝对正确的值**，取决于你拿到 `normal_df` 后要干什么——拿去给高阶模型精洗可以放宽一点（尽量保点），指望初筛结果直接用就得收紧。每次调参都是"保点 vs 纯净"的权衡，建议结合输出图与逐轮打印来判断。以下给出方向和量级参考。
+
+### `z_coeff`——正常带多宽（影响最大，决定"删多少"）
+
+含义：功率偏离该箱中位数多少个 MAD 算正常。**MAD 用原始值、未乘 1.4826**，所以不能直接当"σ 倍数"读；换算成高斯直觉（原始 MAD ≈ 0.675σ）：
+
+| z_coeff | 正常带约 | 高斯下保留比例 | 档位 |
+| --- | --- | --- | --- |
+| `2.0` | ±1.35σ | ~82% | 激进（洗得纯，易误删） |
+| `2.5`（默认） | ±1.69σ | ~91% | 居中 |
+| `3.0` | ±2.02σ | ~96% | 偏宽松 |
+| `4.0` | ±2.70σ | ~99% | 很宽松（基本只剔粗洗） |
+
+- **越大 → 带越宽 → 保留越多**（正常点误删少，但漏进 `normal_df` 的真异常变多）；
+- **越小 → 带越窄 → 删得越多**（`normal_df` 更纯，但可能误删边界正常点）。
+
+实测参考（La Haute Borne，MM82，`filter_cycle=3`）：`z_coeff=2.5` 时 abnormal 约 13–15%；`z_coeff=4.0` 时骤降到约 3%（此时 MAD 层每轮只删 ~1%，第 2、3 轮基本空转）。也就是说 `z_coeff=4` 已接近"纯粗洗"。
+
+建议：后续要做 GAM/sigmoid/时间维度精洗时，可把 `z_coeff` 放到 3~4 先把明显离群点去掉；若想让这一层初筛就尽量干净、愿意接受少部分正常点损失，用 2~2.5。
+
+### `filter_cycle`——迭代几轮
+
+机制：第 1 轮删得最多（清掉最明显的离群点），之后每轮重新分箱、带变窄，**删除量快速递减**——后面几轮主要是在不断收窄正常带，**可能开始误删边界正常点**。
+
+- 实测各数据集上，多数风机的删除量到第 3~5 轮已降到每轮 <1%（可看逐轮打印确认）。
+- 想要**更保守、尽量保留正常点**：`2` 就够，甚至 `1`（只粗洗 + 单轮 MAD）；
+- 想**更彻底**（如训练样本允许损失一部分）：`5`，但要警惕过度清洗；
+- 反正每轮都会打印删除量与比例，看到某轮删除已经趋近 0，就说明再加轮次意义不大。
+
+### 其它参数
+
+- **`low_power_ratio`**：只影响额定风速以上的"限电/降载"粗洗。想多剔除降载工况就调小（如 0.85），想更保险保留就调大。注意别设太低，否则额定平台上的轻微降载会漏掉。
+- **`bin_interval`**：高风速区样本稀的话可适当调大（如 1.0）提高该区段 MAD 稳定性；低风速区样本极多时调小能更精细。默认 0.5 对多数 10 分钟数据够用。
+- **`cut_in_speed`/`rated_wind_speed`/`rated_power`**：这三个是物理参数，**不要拿来当清洗旋钮调**。设错会直接让粗洗规则失效（比如额定风速设太低会把正常爬坡段误当"高风低功率"整段删掉）。拿不准就反推，再和厂商表核对。
+
+## 出图（`return_fig=True`）
+
+会画一张风速-功率散点图：蓝色 = Normal（`normal_df`），橙色 = Abnormal（`abnormal_df`），图例已标注。图片保存到 `image_path` 指定的完整文件路径。建议每次调参都出一张图，肉眼确认"边界处"是否删得合理。
+
+## 测试
+
+```bash
+python -m unittest discover -s test -v
+```
+
+当前测试覆盖：正常/异常切分、重复索引不膨胀、粗洗（停机、高风低功率）、非法参数与空数据校验、出图、迭代删除记录。

wtclean-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wtclean-0.1.0/setup.py

@@ -0,0 +1,34 @@
+import setuptools
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setuptools.setup(
+    name="wtclean",
+    version="0.1.0",
+    description="Wind turbine SCADA power-curve data cleaning via iterative bin + MAD filtering",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    license="BSD-3-Clause",
+    license_files=["LICENSE"],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "License :: OSI Approved :: BSD License",
+        "Operating System :: OS Independent",
+        "Topic :: Scientific/Engineering",
+    ],
+    packages=setuptools.find_packages(exclude=["test", "examples"]),
+    python_requires=">=3.10",
+    install_requires=["numpy", "pandas", "matplotlib"],
+    keywords=[
+        "wind-energy",
+        "wind-turbine",
+        "scada",
+        "power-curve",
+        "outlier-detection",
+        "data-cleaning",
+    ],
+)

wtclean-0.1.0/test/test_power_curve_filtering.py

@@ -0,0 +1,118 @@
+"""PowerCurveFiltering 单元测试（unittest，无 pytest 依赖）。"""
+
+import os
+import tempfile
+import unittest
+
+import numpy as np
+import pandas as pd
+
+from wtclean import PowerCurveFiltering
+
+CUT_IN = 3.0
+RATED_WS = 12.0
+RATED_PWR = 2000.0
+
+
+def _clean_df(n=2000, seed=0):
+    """构造一条理想功率曲线（切入~额定线性爬升，额定以上平台）+ 小噪声。"""
+    rng = np.random.default_rng(seed)
+    ws = rng.uniform(CUT_IN, 25.0, n)
+    power = np.where(
+        ws < RATED_WS,
+        RATED_PWR * (ws - CUT_IN) / (RATED_WS - CUT_IN),
+        RATED_PWR,
+    )
+    power += rng.normal(0, 20, n)
+    return pd.DataFrame({"ws": ws, "pw": power})
+
+
+def _pcf(df, **kwargs):
+    return PowerCurveFiltering(
+        windspeed_label="ws",
+        power_label="pw",
+        df=df,
+        cut_in_speed=CUT_IN,
+        rated_wind_speed=RATED_WS,
+        rated_power=RATED_PWR,
+        **kwargs,
+    )
+
+
+class TestPowerCurveFiltering(unittest.TestCase):
+    def test_partition_and_outlier_detection(self):
+        df = _clean_df()
+        df["is_outlier"] = False
+        # 注入两个明确异常：高风低功率、高风停机
+        df.loc[len(df)] = {"ws": 20.0, "pw": 100.0, "is_outlier": True}
+        df.loc[len(df)] = {"ws": 15.0, "pw": 0.0, "is_outlier": True}
+
+        normal_df, abnormal_df = _pcf(df).process()
+
+        self.assertEqual(len(normal_df) + len(abnormal_df), len(df))
+        self.assertTrue(set(normal_df.index).isdisjoint(set(abnormal_df.index)))
+
+        outlier_idx = set(df.index[df["is_outlier"]].tolist())
+        self.assertTrue(outlier_idx.issubset(set(abnormal_df.index)))
+        self.assertTrue(outlier_idx.isdisjoint(set(normal_df.index)))
+
+    def test_duplicate_index_no_expansion(self):
+        df = _clean_df(n=500)
+        # 人为制造重复 index，旧实现 loc[list] 会膨胀
+        df.index = np.arange(len(df)) // 2
+
+        normal_df, abnormal_df = _pcf(df).process()
+
+        self.assertEqual(len(normal_df) + len(abnormal_df), len(df))
+
+    def test_high_wind_low_power_removed(self):
+        df = _clean_df()
+        df.loc[len(df)] = {"ws": 20.0, "pw": 0.5 * RATED_PWR}
+        _, abnormal_df = _pcf(df).process()
+        self.assertIn(len(df) - 1, abnormal_df.index.tolist())
+
+    def test_downtime_removed(self):
+        df = _clean_df()
+        df.loc[len(df)] = {"ws": 10.0, "pw": 0.0}
+        _, abnormal_df = _pcf(df).process()
+        self.assertIn(len(df) - 1, abnormal_df.index.tolist())
+
+    def test_return_fig_saves_file(self):
+        df = _clean_df(n=300)
+        with tempfile.TemporaryDirectory() as tmp:
+            out = os.path.join(tmp, "nested", "dir", "turbine_pc.png")
+            _pcf(df, return_fig=True, image_path=out).process()
+            self.assertTrue(os.path.exists(out))
+
+    def test_invalid_params(self):
+        df = _clean_df(n=100)
+
+        with self.assertRaises(ValueError):
+            PowerCurveFiltering("bad_col", "pw", df, CUT_IN, RATED_WS, RATED_PWR)
+        with self.assertRaises(ValueError):
+            PowerCurveFiltering("ws", "pw", df, 0, RATED_WS, RATED_PWR)
+        with self.assertRaises(ValueError):
+            PowerCurveFiltering("ws", "pw", df, CUT_IN, CUT_IN, RATED_PWR)
+        with self.assertRaises(ValueError):
+            PowerCurveFiltering(
+                "ws", "pw", df, CUT_IN, RATED_WS, RATED_PWR, low_power_ratio=1.5
+            )
+        with self.assertRaises(ValueError):
+            PowerCurveFiltering(
+                "ws", "pw", df, CUT_IN, RATED_WS, RATED_PWR, bin_interval=0
+            )
+
+    def test_empty_df(self):
+        df = _clean_df(n=10).iloc[0:0]
+        with self.assertRaises(ValueError):
+            _pcf(df)
+
+    def test_removal_history_recorded(self):
+        df = _clean_df(n=500)
+        pcf = _pcf(df, filter_cycle=3)
+        pcf.process()
+        self.assertEqual(len(pcf.removal_history), 3)
+
+
+if __name__ == "__main__":
+    unittest.main()

wtclean-0.1.0/wtclean/__init__.py

@@ -0,0 +1,9 @@
+__version__ = "0.1.0"
+
+from wtclean.modules.power_curve_filtering import PowerCurveFiltering
+from wtclean.utils.machine_parameter_estimation import estimate_machine_parameters
+
+__all__ = [
+    "PowerCurveFiltering",
+    "estimate_machine_parameters",
+]

wtclean-0.1.0/wtclean/modules/__init__.py

@@ -0,0 +1,3 @@
+from wtclean.modules.power_curve_filtering import PowerCurveFiltering
+
+__all__ = ["PowerCurveFiltering"]

wtclean-0.1.0/wtclean/modules/power_curve_filtering.py

@@ -0,0 +1,230 @@
+"""
+该模块对 SCADA 数据应用迭代 bin + MAD（中位数绝对偏差）过滤，
+在风速-功率曲线上把正常运行点与异常点分开。
+"""
+
+import os
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+from wtclean.utils.binning_function import binning_func
+
+
+class PowerCurveFiltering:
+    """对风速-功率曲线做迭代 bin + MAD 过滤。
+
+    Attributes:
+        windspeed_label: 风速列名。
+        power_label: 有功功率列名。
+        df: 单台风机的 SCADA DataFrame。
+        cut_in_speed: 切入风速（厂商机型参数，必填）。
+        rated_wind_speed: 额定风速，高于此风速功率应接近额定功率（厂商机型参数，必填）。
+        rated_power: 风机额定功率（厂商机型参数，必填）。
+        low_power_ratio: 额定功率的比例，高风区功率低于该比例即被粗洗。
+        bin_interval: 风速分箱宽度。
+        z_coeff: bin MAD 的倍数，用于界定正常带。
+        filter_cycle: 迭代过滤轮数。
+        return_fig: 是否保存功率曲线图。
+        image_path: 保存图片的目录。
+
+    """
+
+    def __init__(
+        self,
+        windspeed_label: str,
+        power_label: str,
+        df: pd.DataFrame,
+        cut_in_speed: float,
+        rated_wind_speed: float,
+        rated_power: float,
+        low_power_ratio: float = 0.9,
+        bin_interval: float = 0.5,
+        z_coeff: float = 2.5,
+        filter_cycle: int = 3,
+        return_fig: bool = False,
+        image_path: os.PathLike | str = "",
+    ) -> None:
+
+        for col in (windspeed_label, power_label):
+            if col not in df.columns:
+                raise ValueError(f"DataFrame 缺少列: {col}")
+        if df.empty:
+            raise ValueError("DataFrame 为空")
+
+        if cut_in_speed <= 0:
+            raise ValueError(f"cut_in_speed must be > 0, got {cut_in_speed}")
+        if rated_wind_speed <= cut_in_speed:
+            raise ValueError(
+                f"rated_wind_speed must be > cut_in_speed, got "
+                f"cut_in_speed={cut_in_speed}, rated_wind_speed={rated_wind_speed}"
+            )
+        if rated_power <= 0:
+            raise ValueError(f"rated_power must be > 0, got {rated_power}")
+        if not 0 < low_power_ratio <= 1:
+            raise ValueError(f"low_power_ratio must be in (0, 1], got {low_power_ratio}")
+        if bin_interval <= 0:
+            raise ValueError(f"bin_interval must be > 0, got {bin_interval}")
+        if z_coeff <= 0:
+            raise ValueError(f"z_coeff must be > 0, got {z_coeff}")
+        if filter_cycle < 1:
+            raise ValueError(f"filter_cycle must be >= 1, got {filter_cycle}")
+
+        self.windspeed_label = windspeed_label
+        self.power_label = power_label
+        self.df = df
+        self.cut_in_speed = cut_in_speed
+        self.rated_wind_speed = rated_wind_speed
+        self.rated_power = rated_power
+        self.low_power_ratio = low_power_ratio
+        self.bin_interval = bin_interval
+        self.z_coeff = z_coeff
+        self.filter_cycle = filter_cycle
+        self.return_fig = return_fig
+        self.image_path = image_path
+
+    def remove_downtime_events(self, df: pd.DataFrame) -> pd.DataFrame:
+        """剔除停机事件（风速达到切入风速及以上但功率接近零）。"""
+        return df[
+            ~(
+                (df[self.power_label] <= 1)
+                & (df[self.windspeed_label] >= self.cut_in_speed)
+            )
+        ]
+
+    def remove_high_wind_low_power(self, df: pd.DataFrame) -> pd.DataFrame:
+        """粗洗高风低功率点。
+
+        达到额定风速及以上时风机本应接近额定功率；该区域内功率远低于
+        ``low_power_ratio * rated_power`` 的点视为非正常工况（限电、降载、桨距/故障），
+        为功率曲线基线建模而被剔除。这是粗洗，不是故障检测。
+        """
+        return df[
+            ~(
+                (df[self.power_label] < self.low_power_ratio * self.rated_power)
+                & (df[self.windspeed_label] >= self.rated_wind_speed)
+            )
+        ]
+
+    def secondary_filter(self, df: pd.DataFrame) -> list:
+        """使用 bin + MAD 阈值（``z_coeff``）过滤单台风机数据。
+
+        Returns:
+            该台风机保留（正常）数据点的 ``_row_id`` 列表。
+        """
+        no_dt_per_turbine_df = df.copy()
+
+        no_dt_per_turbine_df.loc[:, "windspeed_bin"] = np.floor(
+            no_dt_per_turbine_df[self.windspeed_label] / self.bin_interval
+        ).astype("Int64")
+
+        if self.filter_cycle < 1:
+            self.filter_cycle = 1
+
+        self.removal_history: list[int] = []
+        prev = len(no_dt_per_turbine_df)
+
+        for i in range(int(self.filter_cycle)):
+            binned_turb_df = binning_func(
+                turbine_data=no_dt_per_turbine_df,
+                windspeed_label=self.windspeed_label,
+                power_label=self.power_label,
+                bin_interval=self.bin_interval,
+            )
+
+            bins_cols = ["windspeed_bin_median", "pwr_bin_median", "pwr_bin_mad", "n"]
+            if set(no_dt_per_turbine_df.columns).issuperset(set(bins_cols)):
+                no_dt_per_turbine_df.drop(bins_cols, axis=1, inplace=True)
+
+            no_dt_per_turbine_df = pd.merge(
+                no_dt_per_turbine_df, binned_turb_df, how="left", on="windspeed_bin"
+            )
+
+            no_dt_per_turbine_df.loc[:, "pwr_low_thresh"] = (
+                no_dt_per_turbine_df["pwr_bin_median"]
+                - self.z_coeff * no_dt_per_turbine_df["pwr_bin_mad"]
+            ).clip(lower=0)
+
+            no_dt_per_turbine_df.loc[:, "pwr_high_thresh"] = (
+                no_dt_per_turbine_df["pwr_bin_median"]
+                + self.z_coeff * no_dt_per_turbine_df["pwr_bin_mad"]
+            )
+
+            in_band = (
+                no_dt_per_turbine_df[self.power_label]
+                > no_dt_per_turbine_df["pwr_low_thresh"]
+            ) & (
+                no_dt_per_turbine_df[self.power_label]
+                < no_dt_per_turbine_df["pwr_high_thresh"]
+            )
+            below_cutin = no_dt_per_turbine_df[self.windspeed_label] < self.cut_in_speed
+            unknown = no_dt_per_turbine_df["pwr_bin_mad"].isna()
+
+            no_dt_per_turbine_df = no_dt_per_turbine_df[in_band | below_cutin | unknown]
+
+            removed = prev - len(no_dt_per_turbine_df)
+            self.removal_history.append(removed)
+            print(
+                f"iteration {i + 1}: removed {removed} "
+                f"({removed / prev:.2%}), remaining {len(no_dt_per_turbine_df)}"
+            )
+            prev = len(no_dt_per_turbine_df)
+
+        return no_dt_per_turbine_df["_row_id"].tolist()
+
+    def process(self) -> tuple[pd.DataFrame, pd.DataFrame]:
+        """运行完整过滤流程，返回正常与异常两个子集。
+
+        Returns:
+            元组 ``(normal_df, abnormal_df)``，按行划分原始 ``df``。
+        """
+        work = self.df.copy()
+        work["_row_id"] = np.arange(len(work))
+
+        no_dt_df = self.remove_downtime_events(work)
+
+        # 从剩余的非停机数据中剔除高风低功率点
+        no_dt_df = self.remove_high_wind_low_power(no_dt_df)
+
+        normal_id_list = self.secondary_filter(no_dt_df)
+
+        keep = work["_row_id"].isin(set(normal_id_list))
+
+        assert keep.sum() == len(normal_id_list)
+
+        normal_df = work[keep].drop(columns="_row_id")
+        abnormal_df = work[~keep].drop(columns="_row_id")
+
+        if self.return_fig:
+            self.normal_df = normal_df.copy()
+            self.abnormal_df = abnormal_df.copy()
+
+            self.normal_df.loc[:, "Abnormal"] = "No"
+            self.abnormal_df.loc[:, "Abnormal"] = "Yes"
+
+            self.processed_data = pd.concat([self.normal_df, self.abnormal_df])
+
+            if self.image_path and not os.path.exists(os.path.dirname(self.image_path)):
+                os.makedirs(os.path.dirname(self.image_path), exist_ok=True)
+
+            fig, ax = plt.subplots(figsize=(18, 6))
+            for flag, color, label in (("No", "blue", "Normal"), ("Yes", "orange", "Abnormal")):
+                sub = self.processed_data[self.processed_data["Abnormal"] == flag]
+                ax.scatter(
+                    sub[self.windspeed_label],
+                    sub[self.power_label],
+                    s=6,
+                    c=color,
+                    label=label,
+                )
+            ax.set_title("Operational power curve", fontsize=16)
+            ax.legend()
+            ax.set_xlabel("Wind Speed", fontsize=14)
+            ax.set_ylabel("Power", fontsize=14)
+            ax.tick_params(labelsize=14)
+            
+            fig.savefig(self.image_path)
+            plt.close(fig)
+
+        return normal_df, abnormal_df

wtclean-0.1.0/wtclean/utils/__init__.py

@@ -0,0 +1,4 @@
+from wtclean.utils.binning_function import binning_func
+from wtclean.utils.machine_parameter_estimation import estimate_machine_parameters
+
+__all__ = ["binning_func", "estimate_machine_parameters"]

wtclean-0.1.0/wtclean/utils/binning_function.py

@@ -0,0 +1,129 @@
+"""
+Function for calculating the median power and median absolute deviation (MAD) of power
+for each wind speed bin of a given turbine.
+"""
+
+import numpy as np
+import pandas as pd
+
+
+def binning_func(
+    turbine_data: pd.DataFrame,
+    windspeed_label: str,
+    power_label: str,
+    bin_interval: float = 0.5,
+) -> pd.DataFrame:
+    """Computes per-bin statistics (sample count, median wind speed, median power, MAD).
+
+    Bins wind speed into integer groups of width ``bin_interval`` using
+    ``floor(ws / bin_interval)``, which decouples the bin count from ``bin_interval`` and
+    covers all wind speeds without out-of-range drops.
+
+    Note:
+        The MAD is intentionally kept raw (no 1.4826 scaling); ``z_coeff`` in
+        ``PowerCurveFiltering`` is therefore an empirical MAD multiplier, not a
+        standard-deviation-equivalent z-score.
+
+    Note:
+        Bins with fewer than 3 samples, or whose power has zero spread (MAD == 0), get
+        ``pwr_bin_mad = NaN`` so the filtering layer treats them as "undecidable" rather
+        than flagging every point (e.g. the rated-power plateau).
+
+    Args:
+        turbine_data: DataFrame containing the ``windspeed_label`` and ``power_label`` columns.
+        windspeed_label: Column name of the wind speed.
+        power_label: Column name of the active power.
+        bin_interval: Wind speed bin width, default 0.5. Must be positive.
+
+    Returns:
+        DataFrame with columns ``windspeed_bin``, ``n``, ``windspeed_bin_median``,
+        ``pwr_bin_median``, and ``pwr_bin_mad``.
+
+    Raises:
+        ValueError: If ``bin_interval`` is not positive.
+    """
+    if bin_interval <= 0:
+        raise ValueError("bin_interval must be > 0")
+
+    ws = turbine_data[windspeed_label]
+
+    # NaN-safe integer bin label: floor(ws / bin_interval), NA preserved via Int64.
+    bin_label = np.floor(ws / bin_interval).astype("Int64")
+
+    binned = (
+        turbine_data.assign(windspeed_bin=bin_label)
+        .groupby("windspeed_bin", sort=True)
+        .agg(
+            n=(power_label, "size"),
+            windspeed_bin_median=(windspeed_label, "median"),
+            pwr_bin_median=(power_label, "median"),
+            pwr_bin_mad=(power_label, lambda x: (x - x.median()).abs().median()),
+        )
+        .reset_index()
+    )
+
+    # Undecidable bins: too few samples, or zero spread (e.g. rated-power plateau).
+    binned.loc[(binned["n"] < 3) | (binned["pwr_bin_mad"] == 0), "pwr_bin_mad"] = np.nan
+
+    return binned[
+        ["windspeed_bin", "n", "windspeed_bin_median", "pwr_bin_median", "pwr_bin_mad"]
+    ]
+
+
+def test_binning_func() -> None:
+    """Self-check for ``binning_func`` against hand-computed expectations."""
+
+    df = pd.DataFrame(
+        {
+            "ws": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 1.0, 1.1, np.nan],
+            "pw": [10, 20, 30, 40, 100, 100, 100, 50, 60, 5],
+        }
+    )
+
+    out = binning_func(df, "ws", "pw", bin_interval=0.5)
+
+    # 输出列与顺序
+    assert list(out.columns) == [
+        "windspeed_bin",
+        "n",
+        "windspeed_bin_median",
+        "pwr_bin_median",
+        "pwr_bin_mad",
+    ]
+
+    # bin 0: ws in [0.0, 0.5) -> n=4, 风速中位 0.25, 功率中位 25, MAD 10
+    b0 = out[out["windspeed_bin"] == 0].iloc[0]
+    assert b0["n"] == 4
+    assert b0["windspeed_bin_median"] == 0.25
+    assert b0["pwr_bin_median"] == 25
+    assert b0["pwr_bin_mad"] == 10
+
+    # bin 1: 功率恒定 -> MAD == 0 -> 置 NaN（不判定）
+    b1 = out[out["windspeed_bin"] == 1].iloc[0]
+    assert b1["n"] == 3
+    assert b1["pwr_bin_median"] == 100
+    assert pd.isna(b1["pwr_bin_mad"])
+
+    # bin 2: n=2（<3）-> MAD 置 NaN（不判定）
+    b2 = out[out["windspeed_bin"] == 2].iloc[0]
+    assert b2["n"] == 2
+    assert b2["pwr_bin_median"] == 55
+    assert pd.isna(b2["pwr_bin_mad"])
+
+    # NaN 风速的行被排除在统计之外（n 总和 = 9，而非 10）
+    assert out["n"].sum() == 9
+
+    # bin_interval <= 0 抛出 ValueError
+    for bad in (0, -0.5):
+        try:
+            binning_func(df, "ws", "pw", bin_interval=bad)
+        except ValueError:
+            pass
+        else:
+            raise AssertionError(f"bin_interval={bad} 应抛出 ValueError")
+
+    print("binning_func 自测通过：所有断言均满足")
+
+
+if __name__ == "__main__":
+    test_binning_func()

wtclean-0.1.0/wtclean/utils/machine_parameter_estimation.py

@@ -0,0 +1,154 @@
+import numpy as np
+import pandas as pd
+
+from wtclean.utils.binning_function import binning_func
+
+
+def estimate_machine_parameters(
+    df: pd.DataFrame,
+    windspeed_label: str,
+    power_label: str,
+    bin_interval: float = 0.5,
+    min_bin_samples: int = 20,
+    plateau_ratio: float = 0.97,
+    rated_power_ratio: float = 0.95,
+    cutin_power_fraction: float = 0.01,
+    consecutive_bins: int = 2,
+) -> dict[str, float]:
+    """从单台风机的 SCADA 风速-功率数据估计切入风速、额定风速与额定功率（三个全部估计）。
+
+    Args:
+        df: 含 ``windspeed_label`` 与 ``power_label`` 列的**单台风机** SCADA DataFrame。
+        windspeed_label: 风速列名。
+        power_label: 有功功率列名。
+        bin_interval: 风速分箱宽度，默认 0.5。
+        min_bin_samples: 参与统计的最小 bin 样本数，低于该值的 bin 被丢弃（抗稀疏）。
+        plateau_ratio: 判定"额定平台"的比例阈值：bin 中位功率达到全风速
+            ``plateau_ratio * 峰值中位功率`` 即视为平台点。
+        rated_power_ratio: 额定风速的判定标准：bin 中位功率首次达到
+            ``rated_power_ratio * 额定功率`` 所对应的风速。
+        cutin_power_fraction: 切入风速的判定标准：bin 中位功率首次达到
+            ``cutin_power_fraction * 额定功率`` 所对应的风速（观测口径的有效出力起始风速，
+            非厂商切入风速定义）。
+        consecutive_bins: 达标判定的连续 bin 数（≥1），且要求这些 bin 在风速上物理连续
+            （相邻 bin 中位风速间隔 ≤ ``bin_interval * 1.1``），避免单个噪声 bin 造成误判。
+
+    Returns:
+        ``{"cut_in_speed": ..., "rated_wind_speed": ..., "rated_power": ...}``，
+        三项全部由数据估计得出。
+
+    Raises:
+        ValueError: 列缺失、数据为空、或数据无法支撑估计（如额定平台无法判定、
+            无法找到连续达标的风速段）。
+
+    Example:
+        >>> params = estimate_machine_parameters(g, "Ws_avg", "P_avg")
+        >>> params  # {"cut_in_speed": 3.77, "rated_wind_speed": 12.72, "rated_power": 1985.3}
+    """
+    for col in (windspeed_label, power_label):
+        if col not in df.columns:
+            raise ValueError(f"DataFrame 缺少列: {col}")
+    if df.empty:
+        raise ValueError("DataFrame 为空，无法估计参数")
+    if bin_interval <= 0:
+        raise ValueError(f"bin_interval must be > 0, got {bin_interval}")
+    if not 0 < plateau_ratio <= 1:
+        raise ValueError(f"plateau_ratio must be in (0, 1], got {plateau_ratio}")
+    if not 0 < rated_power_ratio <= 1:
+        raise ValueError(
+            f"rated_power_ratio must be in (0, 1], got {rated_power_ratio}"
+        )
+    if not 0 < cutin_power_fraction <= 1:
+        raise ValueError(
+            f"cutin_power_fraction must be in (0, 1], got {cutin_power_fraction}"
+        )
+    if consecutive_bins < 1:
+        raise ValueError(f"consecutive_bins must be >= 1, got {consecutive_bins}")
+
+    binned = binning_func(df, windspeed_label, power_label, bin_interval)
+    binned = binned[binned["n"] >= min_bin_samples].sort_values("windspeed_bin_median")
+    if len(binned) < 3:
+        raise ValueError(
+            f"样本过少：满足 n>={min_bin_samples} 的风速 bin 仅 {len(binned)} 个，无法估计参数"
+        )
+
+    xs = binned["windspeed_bin_median"].to_numpy(dtype=float)
+    ys = binned["pwr_bin_median"].to_numpy(dtype=float)
+
+    def _sustained_cross(target: float) -> float | None:
+        """寻找中位功率曲线首次在风速上连续达到 target 的位置。
+
+        连续条件同时要求：
+        - 连续 ``consecutive_bins`` 个 bin 的功率均 >= target；
+        - 这些 bin 在风速轴上物理连续（相邻中位风速间隔 ≤ bin_interval * 1.1）。
+
+        若找不到满足条件的风速段，返回 None。
+        """
+        cond = ys >= target
+        n = len(cond)
+
+        for i in range(n):
+            end = i + consecutive_bins
+            if end > n:
+                break
+
+            # 检查窗口内风速是否物理连续
+            if not np.all(np.diff(xs[i:end]) <= bin_interval * 1.1):
+                continue
+
+            # 检查窗口内功率是否全部达标
+            if not cond[i:end].all():
+                continue
+
+            # 找到首个连续达标段，计算交叉风速
+            if i == 0:
+                return float(xs[0])
+
+            x0, y0 = xs[i - 1], ys[i - 1]
+            x1, y1 = xs[i], ys[i]
+
+            # 前一个 bin 与当前 bin 间隔过大时，不做跨间隙插值，直接取当前 bin 中位风速
+            if x1 - x0 > bin_interval * 1.1:
+                return float(x1)
+
+            if y1 == y0:
+                return float(x1)
+
+            # 线性插值得到目标功率对应的风速
+            return float(x0 + (target - y0) / (y1 - y0) * (x1 - x0))
+
+        return None
+
+    # 额定功率：最高平台（>= plateau_ratio * 峰值）上 bin 中位功率的中位数。
+    peak = float(np.nanmax(ys))
+    plateau = ys >= plateau_ratio * peak
+    if not plateau.any():
+        raise ValueError("无法从数据中判定额定功率平台")
+    rated_power = float(np.median(ys[plateau]))
+
+    # 额定风速：中位功率首次连续达到 rated_power_ratio * 额定功率。
+    crossing = _sustained_cross(rated_power_ratio * rated_power)
+    if crossing is None:
+        raise ValueError(
+            f"无法从功率曲线中估计 rated_wind_speed："
+            f"没有连续 {consecutive_bins} 个有效 bin 达到 "
+            f"{rated_power_ratio:.0%} 额定功率"
+        )
+    rated_wind_speed = crossing
+
+    # 切入风速：中位功率首次连续达到 cutin_power_fraction * 额定功率。
+    # 设置一个最小阈值 1.0 kW，避免绝对零值附近噪声的影响。
+    crossing = _sustained_cross(max(cutin_power_fraction * rated_power, 1.0))
+    if crossing is None:
+        raise ValueError(
+            f"无法从功率曲线中估计 cut_in_speed："
+            f"没有连续 {consecutive_bins} 个有效 bin 达到 "
+            f"{cutin_power_fraction:.0%} 额定功率"
+        )
+    cut_in_speed = crossing
+
+    return {
+        "cut_in_speed": round(cut_in_speed, 2),
+        "rated_wind_speed": round(rated_wind_speed, 2),
+        "rated_power": round(rated_power, 2),
+    }

wtclean-0.1.0/wtclean.egg-info/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: wtclean
+Version: 0.1.0
+Summary: Wind turbine SCADA power-curve data cleaning via iterative bin + MAD filtering
+License: BSD-3-Clause
+Keywords: wind-energy,wind-turbine,scada,power-curve,outlier-detection,data-cleaning
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# wtclean
+
+风电机组 SCADA 功率曲线数据清洗工具：用「迭代分箱 + MAD（中位数绝对偏差）」把**正常运行数据**从原始 SCADA 数据中初筛出来。
+
+## 这个包是做什么的
+
+输入**一台风机**的 SCADA 数据（至少要含风速、有功功率两列，通常为 10 分钟统计记录）。
+
+`PowerCurveFiltering.process()` 会把数据按行切分成两份返回：
+
+- **`normal_df`**：风机**正常运行**的数据点——功率落在该风速区间应有的功率带内。**后续做功率曲线建模、工况分析、机器学习等时主要用这一份**。
+- **`abnormal_df`**：其余所有被剔除的点。⚠️ **它不是"严格异常集"**，而是混了多种情况：停机、故障、限电/降载、桨距控制等**其它工况**、以及真正的传感器/数据异常。想区分异常类型，需要后续用更高阶方法（如 GAM/sigmoid 拟合、时间维度分析）处理。
+
+单台风机的整条清洗流水线分三步：
+
+1. **去停机**：风速 ≥ 切入风速、但功率 ≤ 1 kW 的点（风机已停机）→ 剔除。
+2. **高风低功率粗洗**：风速 ≥ 额定风速、但功率 < `low_power_ratio × 额定功率` 的点（限电、降载、桨距/故障等非正常发电）→ 剔除。
+3. **迭代 bin+MAD 精洗**：按 `bin_interval` 把风速分箱，对每箱算功率中位数与 MAD，箱内功率落在 `中位数 ± z_coeff × MAD` 带外的点 → 剔除。剔除后**重新分箱再剔**，重复 `filter_cycle` 轮（每轮带会随数据变干净而收窄）。
+
+几个内置的判定约定（避免误杀正常点）：
+
+- 箱内样本 < 3，或功率离散度为 0（典型如额定功率平台），该箱**不判定、直接保留**；
+- 风速低于切入风速的点默认保留（近零功率属正常待机）；
+- 恒定功率的"水平聚集"类异常（如某段时间被固定在某一功率）**bin+MAD 识别不出来**，这是本方法的能力上限，应交给后续更精细的方案。
+
+## 安装
+
+```bash
+git clone <this-repo>
+cd wtclean
+pip install -r requirements.txt
+pip install .
+```
+
+## 快速开始（单台风机）
+
+```python
+import pandas as pd
+from wtclean import PowerCurveFiltering
+
+df = pd.read_csv("data.csv")
+turbine = df[df["Wind_turbine_name"] == "R80721"]   # 取单台风机
+
+pc_filter = PowerCurveFiltering(
+    windspeed_label="Ws_avg",     # 风速列名
+    power_label="P_avg",          # 有功功率列名
+    df=turbine,                   # 单台风机数据
+    cut_in_speed=3.5,             # 切入风速（厂商参数，必填）
+    rated_wind_speed=14.5,        # 额定风速（厂商参数，必填）
+    rated_power=2050,             # 额定功率 kW（厂商参数，必填）
+    low_power_ratio=0.9,          # 高风低功率粗洗阈值（默认 0.9）
+    bin_interval=0.5,             # 风速分箱宽度（默认 0.5）
+    z_coeff=2.5,                  # 正常带宽度系数（默认 2.5）
+    filter_cycle=3,               # 迭代轮数（默认 3）
+    return_fig=False,             # 是否保存功率曲线图
+    image_path="",                # 出图时的完整输出文件路径
+)
+
+normal_df, abnormal_df = pc_filter.process()
+```
+
+运行时会逐轮打印删除情况，例如：
+
+```
+iteration 1: removed 3864 (7.21%), remaining 49724
+iteration 2: removed 1655 (3.33%), remaining 48069
+iteration 3: removed 904 (1.88%), remaining 47165
+```
+
+每轮删除数也会记录在 `pc_filter.removal_history`（list[int]），方便你审计或画收敛曲线。
+
+## 多台风机
+
+`PowerCurveFiltering` 一次只处理一台；多台由调用方 `groupby` 后循环调用：
+
+```python
+from wtclean import PowerCurveFiltering, estimate_machine_parameters
+
+results = {}
+for name, group in df.groupby("Wind_turbine_name"):
+    params = estimate_machine_parameters(group, "Ws_avg", "P_avg")  # 先反推厂商参数
+    pcf = PowerCurveFiltering(
+        "Ws_avg", "P_avg", group,
+        cut_in_speed=params["cut_in_speed"],
+        rated_wind_speed=params["rated_wind_speed"],
+        rated_power=params["rated_power"],
+    )
+    results[name] = pcf.process()   # (normal_df, abnormal_df)
+```
+
+## 厂商参数不知道怎么办
+
+`cut_in_speed` / `rated_wind_speed` / `rated_power` 是**风机机型物理参数，必填**。若拿不到厂商技术参数，可先从 SCADA 数据反推（`estimate_machine_parameters` 会估计全部三个值），再把结果传给构造函数：
+
+```python
+from wtclean import estimate_machine_parameters
+
+params = estimate_machine_parameters(turbine, "Ws_avg", "P_avg")
+# -> {"cut_in_speed": 3.78, "rated_wind_speed": 13.59, "rated_power": 1985.3}
+```
+
+> 注意：反推值来自（通常是 10 分钟统计的）SCADA 数据，是"软"值——例如反推的额定风速约 13 m/s，会低于厂商标称的约 14.5 m/s，因为时间平均会把功率曲线拐点往左拉。生产使用前建议与厂商功率曲线表交叉核对；正式项目优先填厂商标称值。
+
+## 参数说明
+
+| 参数 | 默认 | 含义 |
+| --- | --- | --- |
+| `windspeed_label` | — | 风速列名（必填）。 |
+| `power_label` | — | 有功功率列名（必填）。 |
+| `df` | — | **单台**风机的 SCADA DataFrame（必填）。 |
+| `cut_in_speed` | — | 切入风速 m/s（厂商参数，必填）。低于该风速默认保留；停机判定从该风速起算。 |
+| `rated_wind_speed` | — | 额定风速 m/s（厂商参数，必填）。风速 ≥ 它时风机应接近额定功率，是"高风低功率粗洗"的起点。 |
+| `rated_power` | — | 额定功率 kW（厂商参数，必填）。高风区各类比例阈值都以此为基准。 |
+| `low_power_ratio` | `0.9` | 高风低功率粗洗阈值：风速 ≥ 额定风速时，功率 < 该比例×额定功率 即剔除。 |
+| `bin_interval` | `0.5` | 风速分箱宽度 m/s。越小分箱越细（样本少的区段统计越不稳），越大越粗。 |
+| `z_coeff` | `2.5` | 正常带宽度 = `中位数 ± z_coeff × MAD`。见下方调参建议。 |
+| `filter_cycle` | `3` | bin+MAD 迭代精洗的轮数上限。见下方调参建议。 |
+| `return_fig` | `False` | 是否保存一张功率曲线清洗结果散点图（蓝=Normal / 橙=Abnormal）。 |
+| `image_path` | `""` | `return_fig=True` 时输出图片的**完整文件路径**（含文件名，如 `./images/turbine_pc.png`）；目录不存在会自动创建。 |
+
+## 调参建议（最终决策权在你）
+
+**"保留多少 / 洗得多纯"没有绝对正确的值**，取决于你拿到 `normal_df` 后要干什么——拿去给高阶模型精洗可以放宽一点（尽量保点），指望初筛结果直接用就得收紧。每次调参都是"保点 vs 纯净"的权衡，建议结合输出图与逐轮打印来判断。以下给出方向和量级参考。
+
+### `z_coeff`——正常带多宽（影响最大，决定"删多少"）
+
+含义：功率偏离该箱中位数多少个 MAD 算正常。**MAD 用原始值、未乘 1.4826**，所以不能直接当"σ 倍数"读；换算成高斯直觉（原始 MAD ≈ 0.675σ）：
+
+| z_coeff | 正常带约 | 高斯下保留比例 | 档位 |
+| --- | --- | --- | --- |
+| `2.0` | ±1.35σ | ~82% | 激进（洗得纯，易误删） |
+| `2.5`（默认） | ±1.69σ | ~91% | 居中 |
+| `3.0` | ±2.02σ | ~96% | 偏宽松 |
+| `4.0` | ±2.70σ | ~99% | 很宽松（基本只剔粗洗） |
+
+- **越大 → 带越宽 → 保留越多**（正常点误删少，但漏进 `normal_df` 的真异常变多）；
+- **越小 → 带越窄 → 删得越多**（`normal_df` 更纯，但可能误删边界正常点）。
+
+实测参考（La Haute Borne，MM82，`filter_cycle=3`）：`z_coeff=2.5` 时 abnormal 约 13–15%；`z_coeff=4.0` 时骤降到约 3%（此时 MAD 层每轮只删 ~1%，第 2、3 轮基本空转）。也就是说 `z_coeff=4` 已接近"纯粗洗"。
+
+建议：后续要做 GAM/sigmoid/时间维度精洗时，可把 `z_coeff` 放到 3~4 先把明显离群点去掉；若想让这一层初筛就尽量干净、愿意接受少部分正常点损失，用 2~2.5。
+
+### `filter_cycle`——迭代几轮
+
+机制：第 1 轮删得最多（清掉最明显的离群点），之后每轮重新分箱、带变窄，**删除量快速递减**——后面几轮主要是在不断收窄正常带，**可能开始误删边界正常点**。
+
+- 实测各数据集上，多数风机的删除量到第 3~5 轮已降到每轮 <1%（可看逐轮打印确认）。
+- 想要**更保守、尽量保留正常点**：`2` 就够，甚至 `1`（只粗洗 + 单轮 MAD）；
+- 想**更彻底**（如训练样本允许损失一部分）：`5`，但要警惕过度清洗；
+- 反正每轮都会打印删除量与比例，看到某轮删除已经趋近 0，就说明再加轮次意义不大。
+
+### 其它参数
+
+- **`low_power_ratio`**：只影响额定风速以上的"限电/降载"粗洗。想多剔除降载工况就调小（如 0.85），想更保险保留就调大。注意别设太低，否则额定平台上的轻微降载会漏掉。
+- **`bin_interval`**：高风速区样本稀的话可适当调大（如 1.0）提高该区段 MAD 稳定性；低风速区样本极多时调小能更精细。默认 0.5 对多数 10 分钟数据够用。
+- **`cut_in_speed`/`rated_wind_speed`/`rated_power`**：这三个是物理参数，**不要拿来当清洗旋钮调**。设错会直接让粗洗规则失效（比如额定风速设太低会把正常爬坡段误当"高风低功率"整段删掉）。拿不准就反推，再和厂商表核对。
+
+## 出图（`return_fig=True`）
+
+会画一张风速-功率散点图：蓝色 = Normal（`normal_df`），橙色 = Abnormal（`abnormal_df`），图例已标注。图片保存到 `image_path` 指定的完整文件路径。建议每次调参都出一张图，肉眼确认"边界处"是否删得合理。
+
+## 测试
+
+```bash
+python -m unittest discover -s test -v
+```
+
+当前测试覆盖：正常/异常切分、重复索引不膨胀、粗洗（停机、高风低功率）、非法参数与空数据校验、出图、迭代删除记录。

wtclean-0.1.0/wtclean.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+setup.py
+test/test_power_curve_filtering.py
+wtclean/__init__.py
+wtclean.egg-info/PKG-INFO
+wtclean.egg-info/SOURCES.txt
+wtclean.egg-info/dependency_links.txt
+wtclean.egg-info/requires.txt
+wtclean.egg-info/top_level.txt
+wtclean/modules/__init__.py
+wtclean/modules/power_curve_filtering.py
+wtclean/utils/__init__.py
+wtclean/utils/binning_function.py
+wtclean/utils/machine_parameter_estimation.py

wtclean-0.1.0/wtclean.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

wtclean-0.1.0/wtclean.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy
+pandas
+matplotlib

wtclean-0.1.0/wtclean.egg-info/top_level.txt

@@ -0,0 +1 @@
+wtclean