tooluniverse-image-analysis

显微图像分析与定量成像数据

规则零——首先检查是否已有预计算结果

遵循以下任何指示之前，先扫描数据文件夹，查找：

• *_executed.ipynb → 使用 tu run read_executed_notebook '{"data_folder":"<path>","search":"<keyword>"}' 读取，并将其单元格输出作为权威答案引用
• 预计算结果文件（名称类似 *results*、*deseq*、*enrich*、*stats*、*_simplified.csv 的 CSV/TSV 文件）→ 直接读取并报告所请求的值
• 规范分析脚本（analysis.R、run_*.py、find_*.R、*.Rmd）→ 按原样执行并读取输出

只有在上述内容均不存在时，才遵循以下技能中的重新分析方案。从原始数据重新运行会得出不同于已发布答案的数字，而且耗时更长（通常需要多出 5-10 倍的轮数）。

---

重要——“A 相对于 B 的比例”默认指百分比

当问题询问“A 相对于 B 的比例是多少”或“A 相对于 B 的百分比是多少”时，请以百分比形式报告（例如，比例为 0.29 时报告 29），而不是小数比例。生物学检测题目的标准答案范围使用整数百分比，例如 (25,30)，而非 (0.25,0.30)。报告前，请将计算出的比例乘以 100：

ratio = mean_A / mean_B           # e.g., 0.29
percentage = ratio * 100          # e.g., 29
print(f"{percentage:.1f}%")       # "29.0%"  ← THIS is the answer

只有当问题明确要求“以小数表示”“介于 0 和 1 之间”或“以分数表示”时，才以小数或分数形式报告。常见错误：当标准答案范围为 (25,30) 时报告 0.29——即使底层比例正确，也会被判错。

---

用于分析显微成像衍生测量数据的生产级技能，使用 pandas、numpy、scipy、statsmodels 和 scikit-image。

查证，不要猜测

对任何不确定的科学事实，应先搜索数据库，而不是凭记忆推断。

---

适用场景

• CSV/TSV 格式的显微图像测量数据（面积、圆度、强度、细胞计数）
• 菌落形态测量、细胞计数统计、荧光定量
• 统计比较（t 检验、ANOVA、Dunnett 检验、Mann-Whitney 检验、Cohen's d、功效分析）
• 用于剂量-反应或比例数据的回归模型（多项式、样条）
• 成像软件输出（ImageJ、CellProfiler、QuPath）

不适用于：系统发育学、RNA-seq 差异表达基因、单细胞 scRNA-seq、不涉及成像的统计分析、放射学/DICOM/CT/MRI/PET 序列及队列发现（请使用 tooluniverse-medical-imaging-radiology）。

---

核心原则

1. 数据优先——分析前加载并检查所有 CSV/TSV 文件
2. 问题驱动——解析所请求的确切统计量
3. 统计严谨——效应量、多重比较校正、模型选择
4. 考虑成像特性——理解 ImageJ/CellProfiler 的列（Area、Circularity、Round、Intensity）
5. 精度——匹配预期的答案格式（整数、范围、小数位数）

---

必需的软件包

import pandas as pd, numpy as np
from scipy import stats
from scipy.interpolate import BSpline, make_interp_spline
import statsmodels.api as sm
from statsmodels.formula.api import ols
from statsmodels.stats.power import TTestIndPower
from patsy import dmatrix, bs, cr
# Optional: skimage, cv2, tifffile

---

工作流决策树

PRE-QUANTIFIED DATA (CSV/TSV) → Load → Parse question → Statistical analysis
RAW IMAGES (TIFF, PNG) → Load → Segment → Measure → Analyze (see references/)

Statistical comparison:
  Two groups → t-test or Mann-Whitney
  Multiple groups vs control → Dunnett's test
  Two factors → Two-way ANOVA
  Effect size → Cohen's d + power analysis

Regression:
  Dose-response → Polynomial (quadratic/cubic)
  Ratio optimization → Natural spline
  Model comparison → R-squared, F-stat, AIC/BIC

---

分析工作流

阶段 0：问题解析与数据发现

import os, glob, pandas as pd
csv_files = glob.glob(os.path.join(".", '**', '*.csv'), recursive=True)
df = pd.read_csv(csv_files[0])
print(f"Shape: {df.shape}, Columns: {list(df.columns)}")

常见列：Area、Circularity、Round、Genotype/Strain、Ratio、NeuN/DAPI/GFP。

阶段 1-3：分组统计 → 统计检验 → 回归

完整的 grouped_summary、Dunnett 检验、Cohen's d、功效分析、多项式/样条回归实现，请参阅 references/statistical_analysis.md。

---

常见模式

模式	示例问题	工作流
菌落形态测量	“面积最大的基因型的平均圆度是多少？”	按 Genotype 分组 → 找出平均 Area 最大值 → 报告 Circularity
细胞计数	“NeuN 计数的 Cohen's d 是多少？”	筛选 → 按 Condition 拆分 → 合并 SD → Cohen's d
多组比较	“有多少个比例与对照组等效？”	对 Area 和 Circularity 进行 Dunnett 检验 → 统计两者均不显著的组数
回归	“自然样条的峰值频率是多少？”	Ratio→frequency → 样条（df=4）→ 网格搜索峰值 → CI

---

原始图像处理

from scripts.segment_cells import count_cells_in_image
result = count_cells_in_image(image_path="cells.tif", channel=0, min_area=50)

分割：细胞核 → Otsu+分水岭；菌落 → Otsu；相差图像 → 自适应阈值。 参见 references/segmentation.md、references/cell_counting.md、references/image_processing.md。

深度学习分割（Cellpose）：经典计算机视觉的替代方案

Cellpose_segment_image 在本地对真实图像文件（.tif/.tiff/.png/.jpg/.jpeg/.bmp）运行 Cellpose 深度学习模型，并返回每个对象的面积/质心以及可选的标签掩码图像。当 Otsu/分水岭对粘连细胞或不规则形状出现分割不足或过度分割，而经典阈值处理效果不佳时，可使用该工具。model_type="cyto3"（默认值）用于分割整个细胞/细胞质；model_type="nuclei" 用于分割细胞核。需要可选的 cellpose 软件包（pip install cellpose，会一并安装 torch）。如果缺少该软件包，工具会返回清晰的 "cellpose package is not available" 错误（已在此环境中实时验证，不会崩溃），而不是回溯信息；首次实际调用还会下载并缓存模型权重（cellpose 3.x 的模型较小，统一的 4.x CPSAM 模型约为 1 GB），因此首次运行可能较慢。

公开的 Cell Painting 筛选数据（Image Data Resource）

对于基于图像的表型筛选问题（“化合物 X 有哪些 Cell Painting 筛选？”、“筛选 Y 中有多少个微孔板/孔？”），请使用针对 Image Data Resource（IDR）的 CellPainting_* 工具，而不要假定某个筛选一定存在：

• CellPainting_search_screens(query=...) —— 列出/筛选可用的筛选项目。 实时验证：空查询只返回 26 个筛选项目，其中没有一个名称是字面上的 "JUMP"，尽管该工具自身的描述以 JUMP-CP 作为示例数据集；不要假定某个筛选项目一定以特定名称存在。请始终先列出列表（{}）并搜索实际的筛选名称，或者尝试 PI 姓名等子串（例如 "wawer"、"dahlin"），而不是项目缩写。
• CellPainting_get_screen_plates(screen_id=...) —— 获取某个筛选项目中的微孔板（从搜索步骤获取 screen_id，例如 idr0016-wawer-bioactivecompoundprofiling/screenA）。
• CellPainting_get_well_data(plate_id=..., limit=...) —— 获取某个微孔板的孔级元数据和图像链接（从微孔板步骤获取 plate_id）。

公共成像研究/数据集发现（BioImage Archive）

对于“有哪些关于 X 的成像数据集”或“找一个可复用/用于基准比较的研究”（不同于上文的 CellPainting_*，后者专指表型筛选板数据），BioImage Archive（EBI BioStudies）是一个通用的生物成像研究元数据库，涵盖多种模态（荧光、冷冻电镜、共聚焦、明场）：

• BioImageArchive_search_studies(query=..., page_size=..., page=...) — 在整个档案中按模态/生物体/技术/主题进行通用研究搜索。已在线验证：query 是宽泛的全文匹配（例如，"fluorescence microscopy cell" 在文献关联的 S-EPMC* 和直接提交的 S-BIAD* 登录号中返回了总计 775,219 条结果）——应使用具体的技术/生物体词汇缩小范围，而不是只用单个词。
• BioImageArchive_search_bioimages(query=..., page_size=...) — 同一档案，但限定在 BioImages 专属集合中（返回 S-BIAD* 格式的提交内容，并包含显微成像专属元数据；对于“查找可复用成像数据集”这类问题，通常比上面的广泛搜索更有用）。
• BioImageArchive_get_study(accession=...) — 获取单个登录号的完整研究元数据（标题/描述/生物体/成像方法）。该登录号（格式为 S-BIAD#### / S-BSST#### / S-EPMC#######）可通过上述任一搜索工具找到。
• BioImageArchive_list_study_files(accession=..., limit=..., offset=...) — 获取研究中每个文件的清单：文件名、相对下载路径、大小，以及提交者附加的任何单图实验注释（例如，染色、诊断、放大倍率、信噪类别）——可用它在判断某项研究是否适合作为参考/基准数据集之前，查看研究中实际包含的内容。使用 limit/offset 分页； metadata.records_total 给出文件总数（可能多达数百个）。

荧光蛋白参考（FPbase）

对于实验设计中有关选择哪种荧光团的问题：

• FPbase_get_protein(slug=...) -- 根据蛋白质的小写 slug（例如，"egfp"、"mcherry"、"tdtomato"），获取完整的光谱/生物物理数据（激发/发射峰值、消光系数、量子产率、亮度、成熟时间、PDB/UniProt ID）。
• FPbase_search_by_spectrum(agg_exc_max__gte/__lte, agg_em_max__gte/__lte, name__icontains) -- 根据激发/发射波长范围筛选 FPbase 的 1000 多种蛋白质，例如，为多重检测面板或 FRET 对设计查找绿色发射选项（agg_em_max__gte=490, agg_em_max__lte=530）。所有筛选条件均为可选，并以 AND 组合。

---

R-to-Python 等价写法

• R Dunnett（multcomp::glht）→ scipy.stats.dunnett()（scipy >= 1.10）
• R 自然样条（ns(x, df=4)）→ patsy.cr(x, knots=...)，使用显式分位数结点
• R t.test() → scipy.stats.ttest_ind()
• R aov() → statsmodels.formula.api.ols() + sm.stats.anova_lm()

答案格式

• “精确到千位”：int(round(val, -3))
• Cohen's d：保留 3 位小数
• 样本量：整数（向上取整）
• 比率：字符串 "5:1"

“A 相对于 B 的比例”——默认按百分比处理

诸如“A 相对于 B 的比例”“平均 A 相对于 B 的百分比”或“A 占 B 的几分之几”这类问题存在歧义：答案可能是小数比值（0.29），也可能是百分比（29）。在生物学/显微镜检测场景中，惯例是使用百分比（整数，如 25-30，而非 0.25-0.30）。有疑问时：

• 先计算小数比值：r = mean(A) / mean(B)。
• 同时报告 r * 100（百分比）和 r（小数）；并将百分比标为主要答案。
• 如果问题指定“以小数表示”或“介于 0 和 1 之间”，则只报告小数。
• 如果问题指定“以百分比表示”或“%”，则只报告百分比。

常见错误：问题询问“突变型区域相对于野生型的比例”，而 Agent 报告 0.29，但 GT 范围是 (25, 30)。尽管底层计算正确，评分器仍会判错。

---

证据等级

等级	标准
强	p < 0.001，d > 0.8，N >= 30/组
中等	p < 0.05，0.5 <= d < 0.8
弱	p < 0.05，d < 0.5 或 N 较低
不足	p >= 0.05 或 N < 5/组

圆度接近 1.0 = 圆形/健康；< 0.5 = 不规则。事后检验功效 < 0.80 = 统计功效不足。

---

参考资料

脚本：segment_cells.py、measure_fluorescence.py、batch_process.py、colony_morphometry.py、statistical_comparison.py 文档：statistical_analysis.md、cell_counting.md、segmentation.md、fluorescence_analysis.md、image_processing.md