Metadata-Version: 2.4
Name: mdrtreadtool
Version: 2.0.0
Summary: 医疗器械警戒趋势分析工具：把分母表与不良事件表一键生成控制图 / 直方图 / 帕累托图（编译发行版，Windows x64 / Python 3.8+）
Author: sysucai
Maintainer: sysucai
License-Expression: LicenseRef-Proprietary
Keywords: medical-device,vigilance,SPC,control-chart,p-chart,pareto,histogram,trend-analysis,医疗器械,警戒
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: openpyxl
Provides-Extra: image
Requires-Dist: Pillow>=9.0; extra == "image"
Provides-Extra: xls
Requires-Dist: xlrd>=2.0; extra == "xls"
Provides-Extra: all
Requires-Dist: Pillow>=9.0; extra == "all"
Requires-Dist: xlrd>=2.0; extra == "all"
Dynamic: license-file

# mdrtreadtool · 医疗器械警戒趋势分析工具

把「**分母表**（使用基数表）」与「**不良事件表**」两张 Excel 表，一键生成医疗器械警戒趋势报告所需的**三类统计图表**——控制图、直方图、帕累托图。

面向医疗器械注册人 / 不良事件监测人员，依据《医疗器械趋势报告撰写指南》（试行）编制：控制图支持 P / NP / U / C 四种常规控制图与 G 图（稀有事件几何控制图），直方图按「型号比较」口径拆解故障表现 / 伤害表现，帕累托图支持两个时期对比。

本发行版在 PyPI 上提供的是**已编译**的扩展模块（Cython + CPython 稳定 ABI / abi3），**不含 `.py` 业务源码**，与官方 exe 版行为完全一致。

---

## 系统要求

| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10 / 11 / Server（**仅 64 位**） |
| Python | **3.8 及以上**（CPython 3.8 ~ 3.14 均可，同一个轮子通用） |
| 运行依赖 | `numpy`、`pandas`、`matplotlib`、`openpyxl`（`pip` 会自动安装） |

> 轮子的文件名是 `mdrtreadtool-2.0.0-py3-none-win_amd64.whl`。因为随附的 `.pyd` 是以 **CPython 稳定 ABI（abi3）** 编译的，只依赖系统自带的 `python3.dll`，所以一个轮子可在 3.8 ~ 3.14 上直接加载，不必按版本分别编译或分别下载。

---

## 安装

```bash
python -m pip install mdrtreadtool
```

升级到最新版：

```bash
python -m pip install --upgrade mdrtreadtool
```

可选组件（不装也能用，程序会自动降级）：

```bash
python -m pip install "mdrtreadtool[image]"    # Pillow：抗锯齿圆角按钮 + 帮助插图
python -m pip install "mdrtreadtool[xls]"      # xlrd：读取 Excel 97-2003 的 .xls 旧格式
python -m pip install "mdrtreadtool[all]"      # 以上全部
```

---

## 启动

```bash
mdrtreadtool
```

图形界面会直接打开。也可以在 Python 里以模块方式启动：

```bash
python -m mdrtreadtool
```

### 命令行参数

| 命令 | 作用 |
|---|---|
| `mdrtreadtool` | 启动图形界面 |
| `mdrtreadtool --selftest` | 环境自检：检查 Python / 依赖 / 中文字体 / 绘图内核，弹窗显示并写出报告 |
| `mdrtreadtool --selftest --quiet` | 同上，只写报告、不弹窗（适合脚本批量检查） |
| `mdrtreadtool --info` | 不启动界面，只打印模块信息并跑一次纯函数自检（排查问题时最先用这个） |
| `mdrtreadtool --version` | 打印版本号 |
| `mdrtreadtool --no-update` | 本次启动不做自动更新 |

> 程序首次启动时会弹出一个「用户登记」窗口。**直接关闭即可**——不登记不影响任何功能；登记后仅用于接收版本更新通知。

### 自动更新

程序启动时会自动检查 PyPI 上有没有新版本，有的话**通过 pip 自动升级，本次启动即用上新版本**。
整个过程带超时保护：**查询、下载、安装三步各自的超时一到就放弃**，绝不会卡住或影响启动。

- 正常情况**完全静默**；只有真的发生了更新（或更新失败需要你手动处理）才会打印一行提示。
- 为减少等待，联网检查**最长每 6 小时一次**；其余启动不再联网。
- 想看看它到底干了什么：`set MDRTREADTOOL_UPDATE_VERBOSE=1`，或直接 `mdrtreadtool --info`（末行会显示上次检查时间）。
- 想临时/永久关掉：加参数 `--no-update`，或设环境变量 `MDRTREADTOOL_NO_UPDATE=1`。
- 内网镜像 / 离线自测：`set MDRTREADTOOL_PYPI_JSON=<你的 JSON 地址>`。

> **注意**：自动更新**只对 `pip install` 安装的版本生效**。
> 源码运行（`python gen.py`）不涉及；单文件 exe 版**完全不做自动更新**——exe 自带
> Python 运行时与依赖，升级方式就是替换一个新的 exe，程序不会去执行 pip。
> 换句话说，只有在 pip 环境里跑 `mdrtreadtool` 的用户会被自动更新。

---

## 数据准备

导入一个 `.xlsx` 文件，内含两张工作表：**第一张 = 不良事件表**，**第二张 = 分母表**。
（工作表名含「事件 / 不良」或「分母 / 基数」时按名字匹配，否则按上述顺序取；只有一张表时按列判断归属。没有分母表时，「发生率」类指标不可用。）

### 分母表（使用基数表）—— 固定 6 列

| 注册证编号/曾用注册证编号 | 型号 | 规格 | 产品批号 | 月份 | 使用基数 |
|---|---|---|---|---|---|

- 「月份」支持 `2026-01` / `2026/01` / `2026-01-05`，会自动取所属月；
- 一行 = 某注册证下某型号 / 规格 / 批号在某月的使用基数。

### 不良事件表 —— 至少包含

| 报告编码 | 事件发生日期 | 注册证编号/曾用注册证编号 |
|---|---|---|

可选列：`型号`、`规格`、`产品批号`、`器械故障表现`、`伤害表现`（用于直方图与帕累托图的分组维度）。

> 界面上点「下载示例数据」可导出一份符合上述约定的样例文件，照着填即可。

**分母对不齐时**：选「发生率」出图时，若某些取值在分母表中找不到对应记录，程序会先弹窗告诉你具体缺哪些维度、涉及多少条事件，由你决定「忽略这些事件继续生成」还是「取消本次生成」。

---

## 三类图表

### 1. 控制图

按月份 / 季度观察风险表现是否超出控制限。

| 图型 | 适用数据 | 控制限 |
|---|---|---|
| **P 图** | 不良率（二项） | `p̄ ± 3·√( p̄(1-p̄) / nᵢ )` |
| **NP 图** | 不良数（二项） | 同上 × `nᵢ` |
| **U 图** | 单位缺陷数（泊松） | `ū ± 3·√( ū / nᵢ )` |
| **C 图** | 缺陷数（泊松） | 同上 × `nᵢ` |
| **G 图** | 稀有事件·事件间隔（几何分布） | `CL = ln2·ḡ`、`UCL = ḡ + 3·√(ḡ(ḡ+1))`、`LCL ≡ 0` |

- 中心线 `p̄ = Σ风险表现数 / Σ使用基数`（加权汇集，GB/T 17989.2—2020 口径），图下脚注给出与「简单平均」口径的实际差异；
- 控制限随各期分母 `nᵢ` 变化呈锯齿状；仅当分母固定时退化为水平直线；
- G 图方向与 P 图相反：间隔越短 = 事件越密 = 风险升高；配合 1.5×IQR 参考线（探索性离群参考线，**不是**控制限）。

### 2. 直方图（型号比较）

按型号 / 注册证编号分组，拆解故障表现 / 伤害表现作对比（依据《指南》附录 1「直方图法·型号比较」）。

- 指标支持「发生率（需分母表）」「数量」「构成比」，默认发生率；
- 发生率 = 风险表现数 ÷ 使用基数 × 100%；构成比 = 该组该类风险表现数 ÷ 该组全部风险表现数 × 100%（分母不因「展示前 N 组」截断）。

### 3. 帕累托图

按月份 / 季度（或故障 / 伤害表现）排序并叠加累计占比，默认对比「上期 → 本期」两期。

- 期次可按粒度选择，也可用「指定时间段」自定两段日期区间（如 `20240103–20240630` vs `20240701–20241231`）；
- 支持一键导出帕累托数据表（.xlsx）。

### 附带能力

- **参数自动记忆**：所有界面参数保存在 `~/treadtools/setting.json`，下次启动原样回填；
- **数值显示统一口径**：可在「总体设置」里切换百分数 / 小数、自动适配有效数字或手动指定位数，改动即时重绘；
- **数据校验报告**：导入时给出 6 节校验（概况 / 必要列完整性 / 分子表覆盖范围 / 分母表覆盖范围 / 数据质量 / 数据剔除），可导出为 Markdown；
- **统计表与图完全一致**：控制图 / 直方图可「显示表格」「导出表格」，表格口径与图中参考序列严格对齐；
- **容错**：自动绕过 openpyxl 3.1.0~3.1.2 解析 `autoFilter` 的已知缺陷，坏文件里的正常数据照样读得出来。

---

## 常见问题

**Q：装完执行 `mdrtreadtool` 报「不是有效的 Win32 应用程序」？**
A：位数不匹配。本包只提供 64 位版本，请使用 **64 位** Python。

**Q：提示缺少 numpy / pandas？**
A：`pip` 一般会自动装。若公司网络无法直连 PyPI，请配置内网镜像后执行
`python -m pip install numpy pandas matplotlib openpyxl`，或改用 exe 单文件版（免 Python 环境）。

**Q：图里的中文变成方框？**
A：执行 `mdrtreadtool --selftest`，报告里会列出检测到的中文字体；若一个都没检测到，请安装「微软雅黑 / 黑体」等常见中文字体。

**Q：能否拿到源码做二次开发？**
A：不能。本包在 PyPI 上分发的是**编译后的二进制模块**，不包含业务源码，授权为专有授权（见下）。有二次开发或定制需求请联系作者。

**Q：`~/treadtools/setting.json` 是什么？**
A：界面参数（期次、粒度、字段映射、显示口径等）的自动保存文件，删掉即可恢复默认，不影响数据。

---

## 授权

**专有授权（Proprietary License）—— 非开源。**

Copyright (C) 2026 sysucai. All rights reserved.

允许：在授权范围内**免费使用**本软件（含内部业务使用）。
禁止：反向工程、反编译、拆解二进制、再分发、转售、以本软件或其衍生品提供商业服务，以及移除任何版权或授权声明。

完整条款见随包附带的 [`LICENSE`](LICENSE)。下载、安装或使用本软件即视为已阅读并同意该协议。

---

## 说明

- 医疗器械警戒判定涉及法规责任，本工具输出的图表与统计量仅供参考，**最终结论应由具备相应资质的专业人员判断**。
- 报告中所有方法学口径（控制图原理、基线口径、判异规则）均写在程序「帮助文件」页与图下脚注中，可逐条核对。
