Skip to content

README_zh.md

Latest commit

 

History

History
246 lines (175 loc) · 7.61 KB

README_zh.md

File metadata and controls

246 lines (175 loc) · 7.61 KB
Raw

NPCloud Python

用于单分子定位显微镜（SMLM）快速鲁棒漂移校正的 NP-Cloud（最近配对云）算法的 Python 实现。

概述

本包是原始 MATLAB 实现的完整 Python 移植版本，基于：

"Fast and robust drift correction for single-molecule localization microscopy"

Python 实现与 MATLAB 版本产生数值上完全相同的结果，已通过全面的对比测试验证。

功能特性

  • 2D 漂移校正：NP-Cloud 和 RR-NP-Cloud 算法
  • 3D 漂移校正：NP-Cloud-3D 和 RR-NP-Cloud-3D 算法
  • MATLAB 对比测试：验证 Python 输出与 MATLAB 完全匹配
  • 可视化工具：对比漂移曲线和渲染的 SMLM 图像

对比结果

Python 实现已针对原始 MATLAB 代码进行验证：

指标 2D (高密度) 3D (高密度)
最大 X 漂移差异 ~1e-2 像素 ~1e-2 像素
最大 Y 漂移差异 ~1e-2 像素 ~1e-2 像素
最大 Z 漂移差异 - ~1e-1 nm

2D 漂移校正对比

漂移曲线对比

2D 漂移曲线对比 2D 漂移曲线：Python vs MATLAB

SMLM 图像对比

2D 图像对比 2D 漂移校正对比：原始图像 vs Python 校正后 vs MATLAB 校正后

高密度数据对比

2D 高密度对比 2D 高密度数据漂移曲线对比

Python vs MATLAB 差异

2D 差异图 2D 校正后图像差异（Python - MATLAB）

3D 漂移校正对比

漂移曲线对比

3D 漂移曲线对比 3D 漂移曲线：Python vs MATLAB（X, Y, Z 三个维度）

SMLM 图像对比（XY 投影）

3D 图像对比 3D 漂移校正对比：原始图像 vs Python 校正后 vs MATLAB 校正后（XY 投影）

高密度数据对比

3D 高密度对比 3D 高密度数据漂移曲线对比

安装

cd npcloud_python
pip install -r requirements.txt

依赖要求

  • Python 3.6+
  • NumPy >= 1.19.0
  • SciPy >= 1.5.0
  • Matplotlib >= 3.3.0
  • pytest >= 6.0.0 (用于测试)

使用方法

2D 漂移校正

from npcloud.npc_rrnpc_2d import npc_rrnpc_call_function
from npcloud.utils import load_smlm_data

# 加载数据（列：Frame, X, Y）
smlm_data = load_smlm_data('your_data.mat')

array_frames = smlm_data[:, 0].astype('int32')
array_x = smlm_data[:, 1].astype('float32')
array_y = smlm_data[:, 2].astype('float32')

# 运行漂移校正
xc, yc, xd1, yd1, xd2, yd2, npc_time, total_time = npc_rrnpc_call_function(
    array_x, array_y, array_frames,
    dc_segment_size=70,           # 每段帧数
    max_search_radius_pix1=0.3,   # 第一轮搜索半径（像素）
    max_search_radius_pix2=0.225, # 第二轮搜索半径（像素）
    resample_fold=12              # 重采样因子
)

# xc, yc: 校正后的位置
# xd2, yd2: 最终漂移曲线（RR-NPC）

3D 漂移校正

from npcloud.npc_rrnpc_3d import npc_rrnpc_3d_call_function

# 加载 3D 数据（列：Frame, X, Y, Z）
# X, Y 单位为像素；Z 单位为 nm

result = npc_rrnpc_3d_call_function(
    array_x, array_y, array_z, array_frames,
    dc_segment_size=100,          # 每段帧数
    max_search_radius_pix1=0.35,  # 第一轮 XY 搜索半径
    max_search_radius_pix2=0.28,  # 第二轮 XY 搜索半径
    tol_z_nm=110,                 # 第一轮 Z 容差（nm）
    tol_z_nm2=90,                 # 第二轮 Z 容差（nm）
    resample_fold=12
)
xc, yc, zc, xd1, yd1, zd1, xd2, yd2, zd2, npc_time, total_time = result

命令行脚本

# 2D 漂移校正
python scripts/run_npc_rrnpc.py --data your_data.mat --name output_folder

# 3D 漂移校正  
python scripts/run_npc_rrnpc_3d.py --data your_3d_data.mat --name output_folder

# 对比 Python vs MATLAB（需要 MATLAB 引擎）
python scripts/compare_matlab_python.py

参数说明

参数 2D 默认值 3D 默认值 描述
dc_segment_size 70 100 每段帧数
max_search_radius_pix1 0.3 0.35 第一轮 XY 搜索半径（像素）
max_search_radius_pix2 0.225 0.28 第二轮 XY 搜索半径（像素）
tol_z_nm - 110 第一轮 Z 容差（nm）
tol_z_nm2 - 90 第二轮 Z 容差（nm）
resample_fold 12 12 RR-NPC 重采样因子

数据格式

  • 2D：3 列 [Frame, X, Y] - X, Y 单位为像素
  • 3D：4 列 [Frame, X, Y, Z] - X, Y 单位为像素，Z 单位为 nm
  • 帧号必须递增（按帧排序）

项目结构

npcloud_python/
├── npcloud/
│   ├── core/
│   │   ├── np_cloud_2d.py          # 2D NP-Cloud 算法
│   │   ├── np_cloud_3d_pass1.py    # 3D Pass 1（Z 通过平均）
│   │   └── np_cloud_3d_pass2.py    # 3D Pass 2（Z 迭代优化）
│   ├── npc_rrnpc_2d.py             # 2D 两轮漂移校正
│   ├── npc_rrnpc_3d.py             # 3D 两轮漂移校正
│   └── utils.py                     # 工具函数
├── scripts/
│   ├── run_npc_rrnpc.py            # 2D 命令行脚本
│   ├── run_npc_rrnpc_3d.py         # 3D 命令行脚本
│   ├── compare_matlab_python.py    # 可视化对比
│   └── comparison_results/         # 对比结果图片
├── tests/                           # MATLAB 对比测试
├── requirements.txt
├── README.md                        # 英文版
└── README_zh.md                     # 中文版（本文件）

文件对应关系（MATLAB 到 Python）

MATLAB 文件 Python 文件
NP_Cloud_NoSort.m npcloud/core/np_cloud_2d.py
NP_Cloud_NoSort_3D_Pass1.m npcloud/core/np_cloud_3d_pass1.py
NP_Cloud_NoSort_3D_Pass2.m npcloud/core/np_cloud_3d_pass2.py
NPC_RRNPC_CallFunction.m npcloud/npc_rrnpc_2d.py
NPC_RRNPC_3D_CallFunction.m npcloud/npc_rrnpc_3d.py
Run_NPC_RRNPC.m scripts/run_npc_rrnpc.py
Run_NPC_RRNPC_3D.m scripts/run_npc_rrnpc_3d.py

测试

运行 Python vs MATLAB 对比测试（需要 MATLAB 引擎）：

# 激活 matlab 环境
conda activate matlab_py36

# 运行所有测试
pytest tests/ -v

# 运行特定测试
pytest tests/test_np_cloud_2d.py -v

算法概述

NP-Cloud（最近配对云）

  1. 构建位移云：对于比较段中的每个分子，在参考段中搜索半径内找到所有分子，并记录位移向量。

  2. 迭代收敛：迭代移动云中心直到收敛，找到真实的漂移。

  3. 最近邻过滤：为每个分子仅保留最近邻配对，以提高精度。

RR-NP-Cloud（重采样参考 NP-Cloud）

两轮方法：

  • 第一轮（NPC）：使用第一段作为参考
  • 第二轮（RR-NPC）：从整个漂移校正后的数据集中重采样作为参考，进行细化

引用

如果使用本代码，请引用原始论文：

@article{NPCloud,
  title={Fast and robust drift correction for single-molecule localization microscopy},
  author={...},
  journal={...},
  year={...}
}

许可证

参见原始 MATLAB 代码许可证。

致谢

本 Python 实现基于 NPCloud 项目的原始 MATLAB 代码。