imc-histotools 0.1.0__py3-none-any.whl

IMC_HistoTools/__init__.py

@@ -0,0 +1,24 @@
+"""
+IMC-HistoTools — digital pathology analysis toolkit for the Selenium (Se) IMC paper.
+
+Provides:
+  * virtual_IHC            : Beer-Lambert virtual IHC (brightfield-like) rendering
+  * virtual_IHC_ROI        : local-region rendering that keeps original pixel coords
+  * virtual_IHC_annotation : Qupath geojson -> ROI masks
+  * Hscore_threshold       : median-intensity thresholds from Np/Lp/Mp/Hp reference ROIs
+  * pix_Hscore_map         : pixel-wise H-score classification + CSV + figures
+"""
+
+from .virtual_IHC import virtual_IHC, virtual_IHC_ROI
+from .annotation_region import virtual_IHC_annotation, Hscore_threshold
+from .pix_Hscore import pix_Hscore_map
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "virtual_IHC",
+    "virtual_IHC_ROI",
+    "virtual_IHC_annotation",
+    "Hscore_threshold",
+    "pix_Hscore_map",
+]

IMC_HistoTools/annotation_region.py

@@ -0,0 +1,183 @@
+"""
+annotation_region.py — Qupath 圈画 ROI 与 H-score 阈值模块 (IMC-HistoTools)
+
+提供:
+  * ``virtual_IHC_annotation`` : 读取 Qupath geojson 圈画文件 → 栅格化为 ROI mask
+  * ``Hscore_threshold``       : 根据参考 ROI (Np / Lp / Mp / Hp) 计算各层
+                                 像素中位值, 作为 pixel-wise H-score 分层阈值
+
+对应 2610/261003_Pix_Hscore_histopathology.ipynb 中的 geojson → mask 逻辑,
+并扩展为可直接复用的包函数。
+"""
+
+import json
+from pathlib import Path
+
+import numpy as np
+import cv2
+
+
+# ============================================================
+# helper
+# ============================================================
+
+def _as_mask(roi, shape):
+    """把「单个 mask 或 mask 列表」归一化为一个 bool ndarray (列表取并集)."""
+    if roi is None:
+        return None
+    if isinstance(roi, (list, tuple)):
+        m = np.zeros(shape, dtype=bool)
+        for r in roi:
+            if r is None:
+                continue
+            m |= np.asarray(r, dtype=bool)
+        return m
+    return np.asarray(roi, dtype=bool)
+
+
+# ============================================================
+# 1. Qupath geojson → ROI mask
+# ============================================================
+
+def virtual_IHC_annotation(image, geojson_path, region_order=None, name_key='name'):
+    """
+    读取 Qupath geojson 圈画文件, 栅格化为 ROI 区域的布尔 mask。
+
+    仅取每个 polygon 的外环 (第一个坐标环), 用 ``cv2.fillPoly`` 填充;
+    支持 Polygon 与 MultiPolygon。
+
+    Parameters
+    ----------
+    image : 2D ndarray 或 (H, W) tuple
+        用于确定栅格尺寸 H, W (通常传入对应的 virtual IHC / marker 图像)。
+    geojson_path : str or Path
+        Qupath 导出的 .geojson 文件路径。
+    region_order : list of str or None
+        返回结果的 region 顺序; None → 按 geojson 中出现顺序去重。
+    name_key : str
+        feature['properties'] 中用于区分区域名称的键 (默认 'name')。
+
+    Returns
+    -------
+    dict
+        {
+          'polys' : {name: [xy ndarray (N,2), ...]},   # 每个区域的外环顶点 (x, y)
+          'masks' : {name: bool ndarray (H, W)},       # 每个区域的栅格 mask
+          'names' : [按顺序的 region 名],
+        }
+    """
+    image = np.asarray(image)
+    if image.ndim == 2:
+        H, W = image.shape
+    else:
+        H, W = int(image[0]), int(image[1])
+
+    with open(geojson_path) as f:
+        gj = json.load(f)
+
+    region_polys = {}              # name -> [exterior xy array, ...]
+    for feat in gj['features']:
+        name = feat['properties'].get(name_key, 'unknown')
+        geom = feat['geometry']
+        if geom['type'] == 'MultiPolygon':
+            polys = geom['coordinates']
+        else:
+            polys = [geom['coordinates']]
+        for poly in polys:
+            # 外环 (x, y)
+            region_polys.setdefault(name, []).append(
+                np.asarray(poly[0], dtype=np.float64))
+
+    if region_order is None:
+        region_order = list(region_polys.keys())
+
+    region_masks = {}
+    for name in region_order:
+        m = np.zeros((H, W), np.uint8)
+        for xy in region_polys.get(name, []):
+            pts = np.round(xy).astype(np.int32).reshape(-1, 1, 2)   # cv2: (x, y)
+            cv2.fillPoly(m, [pts], 1)
+        region_masks[name] = m.astype(bool)
+
+    return {
+        'polys': {n: region_polys.get(n, []) for n in region_order},
+        'masks': region_masks,
+        'names': region_order,
+    }
+
+
+# ============================================================
+# 2. 参考 ROI → H-score 分层阈值 (中位值)
+# ============================================================
+
+def Hscore_threshold(marker_image, Np=None, Lp=None, Mp=None, Hp=None,
+                     tissue_mask=None, exclude_zero=False, stat='median'):
+    """
+    根据参考 ROI (Np / Lp / Mp / Hp) 统计像素强度, 作为返回的阈值。
+
+    对每个参考 ROI 分别统计:
+      - mean    : 平均值
+      - median  : 中位值
+      - geomean : 几何平均值 (仅正像素)
+      - all     : mean / median / geomean 三者的平均
+
+    Np / Lp / Mp / Hp 分别对应单个或多个设置 ROI 区域 (bool mask 或 mask 列表,
+    列表取并集); 可传 ``tissue_mask`` 以仅统计落在组织内的像素。
+
+    Parameters
+    ----------
+    marker_image : 2D ndarray
+        marker 强度图像 (通常为背景扣除后的图像)。
+    Np, Lp, Mp, Hp : bool ndarray 或 list of bool ndarray, 或 None
+        负 / 低 / 中 / 高 表达的参考 ROI 区域。
+    tissue_mask : bool ndarray or None
+        组织 mask (True=组织); 提供时各 ROI 会与组织求交。
+    exclude_zero : bool
+        是否在统计前排除强度为 0 的像素 (默认 False)。
+    stat : str, {'mean','median','geomean','all'}
+        选择用于 ``thresholds`` 的统计量 (默认 'median')。
+
+    Returns
+    -------
+    dict
+        {
+          'Np' : {'mean','median','geomean','all'} 或 None,
+          'Lp' : {...}, 'Mp' : {...}, 'Hp' : {...},
+          'thresholds' : (T1, T2, T3),   # 由 stat 决定, 对应 Lp/Mp/Hp
+          'stat' : str,
+        }
+    """
+    if stat not in ('mean', 'median', 'geomean', 'all'):
+        raise ValueError(f"stat 必须是 'mean'/'median'/'geomean'/'all', 得到 {stat!r}")
+
+    img = np.asarray(marker_image, dtype=np.float32)
+    shape = img.shape
+
+    def _stats(roi):
+        m = _as_mask(roi, shape)
+        if m is None:
+            return None
+        if tissue_mask is not None:
+            m = m & np.asarray(tissue_mask, dtype=bool)
+        vals = img[m].astype(np.float64)
+        if exclude_zero:
+            vals = vals[vals > 0]
+        if vals.size == 0:
+            return None
+        mean = float(np.mean(vals))
+        median = float(np.median(vals))
+        pos = vals[vals > 0]
+        geomean = float(np.exp(np.mean(np.log(pos)))) if pos.size else 0.0
+        all_ = (mean + median + geomean) / 3.0
+        return {'mean': mean, 'median': median, 'geomean': geomean, 'all': all_}
+
+    stats = {'Np': _stats(Np), 'Lp': _stats(Lp),
+             'Mp': _stats(Mp), 'Hp': _stats(Hp)}
+
+    thresholds = tuple(stats[k][stat] if stats[k] is not None else None
+                       for k in ('Lp', 'Mp', 'Hp'))
+
+    result = dict(stats)
+    result['thresholds'] = thresholds
+    result['stat'] = stat
+    return result

IMC_HistoTools/pix_Hscore.py

@@ -0,0 +1,427 @@
+"""
+pix_Hscore.py — pixel-wise H-score 分类与可视化模块 (IMC-HistoTools)
+
+核心函数 ``pix_Hscore_map``:
+  * 输入 marker 图像与参考 ROI (Np / Lp / Mp / Hp), 调取 ``Hscore_threshold``
+    得到分层阈值
+  * 对每个像素分类为 0/1/2/3 (NP / LP / MP / HP)
+  * 标准返回: 逐像素分类 CSV 文件 + 分类着色图 (colorbar 在图外右侧)
+  * 若 ``tissue_annotation`` 非空, 额外返回各区域 pix H-score 柱状图 + 比例/面积表
+
+对应 2610/261001_CRC_Pix_Hscore.ipynb 与
+2610/261003_Pix_Hscore_histopathology.ipynb 的核心逻辑。
+"""
+
+import os
+from pathlib import Path
+
+import numpy as np
+import cv2
+import matplotlib.pyplot as plt
+from matplotlib.colors import ListedColormap, BoundaryNorm, to_rgba
+from matplotlib.patches import Rectangle
+from matplotlib.ticker import MultipleLocator
+import tifffile
+
+from .annotation_region import Hscore_threshold, _as_mask
+
+
+# ============================================================
+# 常量
+# ============================================================
+SCORE_COLORS = ['#FFFFFF', '#2166AC', '#67AB49', '#FDBF2C', '#D73027']
+SCORE_LABELS = ['0 (Neg)', '1 (Low)', '2 (Mod)', '3 (High)']
+CATEGORY_NAMES = {0: 'NP', 1: 'LP', 2: 'MP', 3: 'HP'}
+_CAT_ARR = np.array(['NP', 'LP', 'MP', 'HP'])
+
+
+# ============================================================
+# helper
+# ============================================================
+
+def _load(img):
+    """ndarray 原样返回; str/Path 视为 tiff 路径读取."""
+    if isinstance(img, (str, Path)):
+        return np.asarray(tifffile.imread(str(img))).astype(np.float32)
+    return np.asarray(img)
+
+
+def _classify(marker_image, thresholds, blur_sigma=None, blur_kernel=None):
+    """阈值分层 (0/1/2/3)。可选高斯模糊。
+
+    thresholds = (T1, T2, T3) = (Lp, Mp, Hp):
+      0  if data <  T1
+      1  if T1 <= data <  T2
+      2  if T2 <= data <  T3
+      3  if data >= T3
+    """
+    data_f = np.asarray(marker_image, dtype=np.float32)
+    if blur_kernel is None or blur_sigma in (None, 0):
+        data_blur = data_f
+    else:
+        if isinstance(blur_kernel, int):
+            blur_kernel = (blur_kernel, blur_kernel)
+        data_blur = cv2.GaussianBlur(data_f, blur_kernel, sigmaX=blur_sigma)
+    T1, T2, T3 = thresholds  # (Lp, Mp, Hp)
+    scores_2d = np.select(
+        [data_blur >= T3, data_blur >= T2, data_blur >= T1],
+        [3, 2, 1], default=0,
+    ).astype(np.uint8)
+    return scores_2d
+
+
+def _hscore_from_scores(scores_2d, sel, thresholds=(0, 0, 0)):
+    """在布尔子集 sel 上计算 pix H-Score 与各层计数/比例。"""
+    sc = scores_2d[sel]
+    total = int(sc.size)
+    counts = {k: int((sc == k).sum()) for k in (0, 1, 2, 3)}
+    NP, LP, MP, HP = (counts[k] for k in (0, 1, 2, 3))
+    pix_h = 100.0 * (3 * HP + 2 * MP + LP) / total if total > 0 else 0.0
+    percents = {k: (100.0 * v / total if total > 0 else 0.0)
+                for k, v in counts.items()}
+    return {'pix_h': pix_h, 'counts': counts, 'percents': percents,
+            'total': total, 'thresholds': thresholds}
+
+
+# ============================================================
+# 主函数
+# ============================================================
+
+def pix_Hscore_map(marker_image,
+                   Hscore_threshold_annotation=None,
+                   tissue_annotation=None,
+                   tissue_mask=None,
+                   thresholds=None,
+                   stat='median',
+                   delta=None,
+                   kernel=None,
+                   # --- 输出 ---
+                   save_dir='.',
+                   base_name='pix_Hscore',
+                   # --- 分类着色图 (map) 样式 ---
+                   map_figsize=(12, 9),
+                   map_title=None,
+                   map_cmap=SCORE_COLORS,
+                   map_show=True,
+                   map_colorbar=True,
+                   map_colorbar_label='Score',
+                   map_colorbar_labels=SCORE_LABELS,
+                   map_tick_step=500,
+                   map_dpi=150,
+                   map_save=True,
+                   xlabel='5μm / pixel',
+                   ylabel='5μm / pixel',
+                   axis_label_fontsize=34,
+                   tick_fontsize=24,
+                   # --- 柱状图 + 表 样式 ---
+                   bar_order=None,
+                   region_colors=None,
+                   pixel_area_um2=25,
+                   bar_figsize=(6, 6.5),
+                   bar_show=True,
+                   bar_save=True,
+                   bar_dpi=150,
+                   # --- CSV ---
+                   csv_format='long'):
+    """
+    Pixel-wise H-score 分类 + 可视化 + 逐像素分类 CSV 导出。
+
+    Parameters
+    ----------
+    marker_image : 2D ndarray 或 tiff 路径
+        marker 强度图像 (建议先做背景扣除)。
+    Hscore_threshold_annotation : dict or None
+        参考 ROI 区域, 用于调取 ``Hscore_threshold`` 计算阈值, 形如
+        ``{'Np': mask, 'Lp': mask, 'Mp': mask, 'Hp': mask}``;
+        每个 value 可为单个 bool mask 或 mask 列表。
+    tissue_annotation : dict or None
+        待统计的区域标注 ``{name: mask 或 mask 列表}``; 非空时返回各区域
+        pix H-score 柱状图 + 比例/面积表。
+    tissue_mask : bool ndarray or None
+        组织 mask (True=组织), 用于排除背景信号。
+    thresholds : (T1, T2, T3) or None
+        显式分层阈值, 顺序为 (Lp, Mp, Hp); None → 由
+        ``Hscore_threshold_annotation`` 计算。
+        分类规则: <T1→0, [T1,T2)→1, [T2,T3)→2, ≥T3→3。
+    stat : str, {'mean','median','geomean','all'}
+        选择用于阈值的统计量 (默认 'median')。
+    delta : float or None
+        分类着色图 (map) 显示前的高斯模糊 sigma (默认 None 不模糊)。
+    kernel : int or tuple or None
+        分类着色图 (map) 显示前的高斯模糊核大小 (默认 None)。
+        统计柱状图/CSV 始终使用非高斯 (非模糊) 分类。
+    save_dir : str, 输出目录。
+    base_name : str, 输出文件前缀。
+    map_* : 分类着色图相关样式 / 是否显示 / 保存。
+    bar_* : 柱状图 + 表相关样式 / 是否显示 / 保存。
+    pixel_area_um2 : float, 每像素面积 (µm²), 默认 25 (5µm × 5µm)。
+    csv_format : str, 'long' (逐像素行 x,y,intensity,score,category)
+                或 'matrix' (2D score 矩阵 CSV)。
+
+    Returns
+    -------
+    dict
+        {
+          'thresholds'  : (T1, T2, T3),
+          'stat'        : 所选统计量 ('mean'/'median'/'geomean'/'all'),
+          'stats'       : Hscore_threshold 返回的完整统计 dict 或 None,
+          'scores_2d'   : 非高斯分类 uint8 ndarray (H, W) (bargraph/CSV 用),
+          'scores_2d_blur' : 高斯模糊分类 uint8 ndarray (H, W) (map 显示用),
+          'csv_path'    : str,
+          'score_tiff_path' : str,
+          'fig_map'     : matplotlib Figure or None,
+          'results'     : {region: {...}} or None (tissue_annotation 非空时),
+          'fig_bar'     : matplotlib Figure or None,
+          'categories'  : {0:'NP',1:'LP',2:'MP',3:'HP'},
+        }
+    """
+    marker_image = _load(marker_image)
+    os.makedirs(save_dir, exist_ok=True)
+
+    # ---- 1) 阈值 ----
+    stats = None
+    if thresholds is None:
+        if not Hscore_threshold_annotation:
+            raise ValueError(
+                "必须提供 thresholds 或 Hscore_threshold_annotation "
+                "(包含 Np/Lp/Mp/Hp 参考 ROI)。")
+        stats = Hscore_threshold(
+            marker_image,
+            Np=Hscore_threshold_annotation.get('Np'),
+            Lp=Hscore_threshold_annotation.get('Lp'),
+            Mp=Hscore_threshold_annotation.get('Mp'),
+            Hp=Hscore_threshold_annotation.get('Hp'),
+            tissue_mask=tissue_mask,
+            stat=stat)
+        thresholds = stats['thresholds']
+
+    thresholds = tuple(thresholds)
+    if len(thresholds) != 3 or any(t is None for t in thresholds):
+        raise ValueError(f"thresholds 必须为 (T1, T2, T3) 三个非 None 值, 得到 {thresholds}")
+
+    # ---- 2) 分类 ----
+    # 非高斯分类: 用于 bargraph 统计与逐像素 CSV
+    scores_2d = _classify(marker_image, thresholds,
+                          blur_sigma=None, blur_kernel=None)
+    # 高斯模糊分类: 仅用于 map 显示 (delta=sigma, kernel=核大小)
+    if kernel is not None and delta not in (None, 0):
+        scores_2d_blur = _classify(marker_image, thresholds,
+                                   blur_sigma=delta, blur_kernel=kernel)
+    else:
+        scores_2d_blur = scores_2d
+
+    # ---- 3) 逐像素分类 CSV + score tiff ----
+    csv_path = os.path.join(save_dir, f"{base_name}_pixels.csv")
+    score_tiff_path = os.path.join(save_dir, f"{base_name}_scores.tiff")
+
+    if csv_format == 'matrix':
+        np.savetxt(csv_path, scores_2d, delimiter=',', fmt='%d')
+    else:  # 'long'
+        if tissue_mask is not None:
+            valid = np.asarray(tissue_mask, dtype=bool)
+        else:
+            valid = np.ones_like(scores_2d, dtype=bool)
+        ys, xs = np.nonzero(valid)
+        ints = marker_image[valid]
+        scs = scores_2d[valid]
+        cats = _CAT_ARR[scs]
+        # 结构化数组一次性写出 (快速, 适合数百万像素)
+        rec = np.empty(len(xs), dtype=[
+            ('x', np.int64), ('y', np.int64),
+            ('intensity', np.float64), ('score', np.int64),
+            ('category', 'U2')])
+        rec['x'] = xs
+        rec['y'] = ys
+        rec['intensity'] = ints
+        rec['score'] = scs
+        rec['category'] = cats
+        np.savetxt(csv_path, rec, delimiter=',',
+                   fmt=['%d', '%d', '%.4f', '%d', '%s'],
+                   header='x,y,intensity,score,category', comments='')
+
+    tifffile.imwrite(score_tiff_path, scores_2d.astype(np.uint8), compression='lzw')
+
+    # ---- 4) 分类着色图 (colorbar 在图外右侧) ----
+    fig_map = None
+    if map_show or map_save:
+        cmap = ListedColormap(map_cmap) if isinstance(map_cmap, (list, tuple)) else map_cmap
+        norm = BoundaryNorm([-1.5, -0.5, 0.5, 1.5, 2.5, 3.5], ncolors=5)
+        disp = scores_2d_blur.astype(np.int8)
+        if tissue_mask is not None:
+            disp[~np.asarray(tissue_mask, dtype=bool)] = -1  # 背景 → 白
+
+        fig_map, ax = plt.subplots(figsize=map_figsize)
+        im = ax.imshow(disp, cmap=cmap, norm=norm, interpolation='nearest')
+
+        ax.xaxis.set_major_locator(MultipleLocator(map_tick_step))
+        ax.yaxis.set_major_locator(MultipleLocator(map_tick_step))
+        ax.tick_params(axis='both', labelsize=tick_fontsize)
+        ax.set_xlabel(xlabel, fontsize=axis_label_fontsize, fontweight='bold')
+        ax.set_ylabel(ylabel, fontsize=axis_label_fontsize, fontweight='bold')
+        ax.grid(True, alpha=0.2, linewidth=2.0)
+        if map_title is not None:
+            ax.set_title(map_title, fontsize=46, fontweight='bold')
+
+        if map_colorbar:
+            cbar = fig_map.colorbar(im, ax=ax, fraction=0.035, pad=0.02,
+                                    ticks=[0, 1, 2, 3])
+            cbar.ax.set_yticklabels(map_colorbar_labels)
+            cbar.set_label(map_colorbar_label, fontsize=34, fontweight='bold',
+                           labelpad=10)
+            cbar.ax.tick_params(labelsize=24)
+
+        fig_map.tight_layout()
+        if map_show:
+            plt.show()
+        if map_save:
+            map_path = os.path.join(save_dir, f"{base_name}_map.png")
+            fig_map.savefig(map_path, dpi=map_dpi, bbox_inches='tight',
+                            facecolor='white')
+            print(f"分类着色图已保存到: {map_path}")
+
+    # ---- 5) 各区域 pix H-score 柱状图 + 表 (tissue_annotation 非空时) ----
+    fig_bar = None
+    results = None
+    if tissue_annotation:
+        region_names = bar_order if bar_order is not None else list(tissue_annotation.keys())
+        results = {}
+        for name in region_names:
+            roi = _as_mask(tissue_annotation[name], marker_image.shape)
+            sel = roi & (np.asarray(tissue_mask, dtype=bool)
+                         if tissue_mask is not None else np.ones_like(roi, bool))
+            res = _hscore_from_scores(scores_2d, sel, thresholds)
+            res['roi_px'] = int(roi.sum()) if roi is not None else 0
+            res['valid_px'] = int(sel.sum())
+            results[name] = res
+
+        fig_bar = _bargraph_table(
+            region_names, results, pixel_area_um2=pixel_area_um2,
+            region_colors=region_colors,
+            figsize=bar_figsize,
+            overall_sel=(np.asarray(tissue_mask, dtype=bool)
+                         if tissue_mask is not None else None),
+            scores_2d=scores_2d, thresholds=thresholds)
+        if bar_show:
+            plt.show()
+        if bar_save:
+            bar_path = os.path.join(save_dir, f"{base_name}_bargraph.png")
+            fig_bar.savefig(bar_path, dpi=bar_dpi, bbox_inches='tight',
+                            facecolor='white')
+            print(f"柱状图 + 表已保存到: {bar_path}")
+
+    print(f"逐像素分类 CSV 已保存到: {csv_path}")
+    print(f"score 图已保存到: {score_tiff_path}")
+
+    return {
+        'thresholds': thresholds,
+        'stat': stat,
+        'stats': stats,
+        'scores_2d': scores_2d,
+        'scores_2d_blur': scores_2d_blur,
+        'csv_path': csv_path,
+        'score_tiff_path': score_tiff_path,
+        'fig_map': fig_map,
+        'results': results,
+        'fig_bar': fig_bar,
+        'categories': dict(CATEGORY_NAMES),
+    }
+
+
+# ============================================================
+# 柱状图 + 比例/面积表 (publication figure)
+# ============================================================
+
+def _bargraph_table(region_names, results, pixel_area_um2=25,
+                    region_colors=None, figsize=(6, 6.5),
+                    overall_sel=None, scores_2d=None, thresholds=(0, 0, 0)):
+    """柱状图 (上) + 各区域 NP/LP/MP/HP 比例与面积表 (下) 的复合图。"""
+    if region_colors is None:
+        default_colors = ['#e8481e', '#808080', '#cc66e6', '#1f77b4',
+                          '#2ca02c', '#ff7f0e', '#d62728', '#17becf']
+        region_colors = {n: default_colors[i % len(default_colors)]
+                         for i, n in enumerate(region_names)}
+
+    bar_width = 0.62
+    tick_fontsize = 15
+    value_fontsize = 16
+    table_fontsize = 14
+    axis_label_fontsize = 18
+
+    names = region_names
+    scores = [results[n]['pix_h'] for n in names]
+    percs = [[results[n]['percents'][k] for k in (0, 1, 2, 3)] for n in names]
+    areas = [results[n]['valid_px'] * pixel_area_um2 / 1e6 for n in names]
+    colors = [region_colors[n] for n in names]
+    n = len(names)
+    x = np.arange(n)
+
+    overall_hscore = None
+    if scores_2d is not None and overall_sel is not None:
+        overall_hscore = _hscore_from_scores(scores_2d, overall_sel, thresholds)['pix_h']
+
+    fig = plt.figure(figsize=figsize)
+    ax_bar = fig.add_axes([0.13, 0.54, 0.84, 0.41])
+    ax_tab = fig.add_axes([0.13, 0.06, 0.84, 0.40])
+
+    # ---- 上: 柱状图 ----
+    ax_bar.bar(x, scores, width=bar_width, color=colors,
+               edgecolor='white', linewidth=0.8, zorder=3)
+    for xi, s in zip(x, scores):
+        ax_bar.text(xi, s + max(scores) * 0.02, f'{s:.1f}',
+                    ha='center', va='bottom', fontsize=value_fontsize,
+                    fontweight='bold')
+    if overall_hscore is not None:
+        ax_bar.axhline(overall_hscore, color='#444444', ls='--', lw=1.4, zorder=2)
+        ax_bar.text(n - 0.5, overall_hscore + max(scores) * 0.015,
+                    f'Overall {overall_hscore:.1f}', ha='right', va='bottom',
+                    fontsize=11, color='#444444', style='italic')
+    ax_bar.set_ylabel('pix H-Score', fontsize=axis_label_fontsize,
+                      fontweight='bold')
+    ax_bar.set_ylim(0, max(scores) * 1.28)
+    ax_bar.set_xlim(-0.5, n - 0.5)
+    ax_bar.set_xticks([])
+    ax_bar.tick_params(axis='y', labelsize=tick_fontsize)
+    for lb in ax_bar.get_yticklabels():
+        lb.set_fontweight('bold')
+    ax_bar.grid(True, axis='y', ls='--', alpha=0.45)
+    ax_bar.set_axisbelow(True)
+    for sp in ax_bar.spines.values():
+        sp.set_linewidth(0.8)
+    ax_bar.spines['top'].set_visible(False)
+    ax_bar.spines['right'].set_visible(False)
+
+    # ---- 下: 比例 / 面积表 ----
+    ROW_LABELS = [r'$N_{P}$', r'$L_{P}$', r'$M_{P}$', r'$H_{P}$', r'Area']
+    n_rows = 5
+    ax_tab.set_xlim(-0.5, n - 0.5)
+    ax_tab.set_ylim(-0.55, n_rows)
+    ax_tab.axis('off')
+    amax = max(areas)
+    for j, name in enumerate(names):
+        rgbc = to_rgba(region_colors[name])[:3]
+        for i in range(n_rows):
+            y = n_rows - 1 - i
+            if i < 4:
+                val = percs[j][i]
+                alpha = 0.10 + 0.80 * (val / 100.0)
+                fc = (*rgbc, alpha)
+                txt = f'{val:.1f}'
+                tcol = 'black' if alpha < 0.6 else 'white'
+            else:
+                alpha = 0.10 + 0.55 * (areas[j] / amax)
+                fc = (0.4, 0.4, 0.4, alpha)
+                txt = f'{areas[j]:.1f}'
+                tcol = 'black' if alpha < 0.55 else 'white'
+            ax_tab.add_patch(Rectangle((j - 0.5, y), 1.0, 1.0, facecolor=fc,
+                                       edgecolor='white', linewidth=1.2))
+            ax_tab.text(j, y + 0.5, txt, ha='center', va='center',
+                        fontsize=table_fontsize, fontweight='bold', color=tcol)
+    for i, lab in enumerate(ROW_LABELS):
+        ax_tab.text(-0.62, n_rows - 1 - i + 0.5, lab, ha='right', va='center',
+                    fontsize=table_fontsize + 2, fontweight='bold')
+    for j, name in enumerate(names):
+        ax_tab.text(j, -0.12, name.replace(' ', '\n'), ha='center', va='top',
+                    fontsize=table_fontsize, fontweight='bold',
+                    color=region_colors[name])
+
+    return fig

IMC_HistoTools/virtual_IHC.py

@@ -0,0 +1,400 @@
+"""
+virtual_IHC.py — 虚拟 IHC 图像生成模块 (IMC-HistoTools)
+
+用 Beer-Lambert 模型将 IMC 多通道数据合成为模拟 IHC 染色的 RGB 图像。
+支持 per-channel gamma 校正以匹配真实 IHC 的颜色深浅对比。
+
+对应 Se_IMC/Pseudo_brightfield.py，调整如下:
+  * ``Virtual_IHC_show_save`` → ``virtual_IHC`` (功能不变)
+  * colorbar ``cbar.set_label(...)`` 的 label / fontsize / fontweight
+    提升为函数输入参数, 便于作图时直接修改
+  * 新增 ``virtual_IHC_ROI``: 显示局部区域但保留原始像素坐标 (不从 0 重排)
+
+用法:
+  from IMC_HistoTools.virtual_IHC import virtual_IHC, virtual_IHC_ROI
+  virtual_IHC(Blue_image=DNA, Brown_image=Se, ...)
+"""
+
+import os
+import numpy as np
+import cv2
+import matplotlib.pyplot as plt
+from matplotlib.colors import LinearSegmentedColormap, Normalize
+from matplotlib.ticker import MultipleLocator
+from matplotlib.cm import ScalarMappable
+import tifffile
+
+
+# ============================================================
+# 颜色常量 (Beer-Lambert 吸收系数)
+# ============================================================
+BLK = [0.0, 0.0, 0.0]              # 背景 (黑色)
+
+BLUE = [9.147, 6.9215, 1.0]        # 蓝色通道 (细胞核 / DNA)
+RED  = [1.0,   15.8,   6.0]        # 红色通道
+BROWN = [3.5,   5.3,   9.0]        # 棕色通道 (Ecadherin 等膜染色)
+
+
+# ============================================================
+# helper
+# ============================================================
+
+def _apply_gamma(img, gamma, ref_percentile=99.9):
+    """对图像做 gamma 校正, 保持强度尺度大致不变.
+
+    归一化到 ref_percentile → 应用 gamma → 缩放回原尺度.
+    gamma=1.0 不做任何改变.
+    """
+    if gamma == 1.0 or img is None or np.all(img == 0):
+        return img
+    ref = np.percentile(img[img > 0], ref_percentile) if np.any(img > 0) else 1.0
+    if ref <= 0:
+        return img
+    img_norm = img / ref
+    img_norm = np.clip(img_norm, 0, None)  # 确保非负
+    return (img_norm ** gamma) * ref
+
+
+# ============================================================
+# 主函数
+# ============================================================
+
+def virtual_IHC(Blue_image, Red_image, Brown_image,
+                blue_name="Blue", red_name="Red", brown_name="Brown",
+                title='',
+                k1=0.001, k2=0.5, k3=0.0075,
+                blue_gamma=1.0, red_gamma=1.0, brown_gamma=1.0,
+                blue_threshold=0.0, red_threshold=0.0, brown_threshold=0.0,
+                blue_lim=(0, 100),
+                red_lim=(0, 100),
+                brown_lim=(0, 100),
+                sigma=1, kernel_size=(3, 3),
+                save_dir='.', figsize=(24, 18),
+                save_dpi=150,
+                Save_raw=False,
+                x_ticks=None, y_ticks=None,
+                tick_step=None,
+                xlim=None, ylim=None,
+                tick_fontsize=10,
+                tick_fontweight='normal',
+                xlabel='5μm / pixel',
+                ylabel='5μm / pixel',
+                axis_label_fontsize=12,
+                axis_label_fontweight='normal',
+                title_fontsize=18,
+                title_fontweight='bold',
+                title_pad=None,
+                grid=False,
+                grid_linewidth=0.5,
+                spine_linewidth=1.5,
+                # --- colorbar ---
+                blue_bar=False,
+                red_bar=False,
+                brown_bar=False,
+                blue_bar_alpha=1.0,
+                red_bar_alpha=1.0,
+                brown_bar_alpha=1.0,
+                blue_bar_depth=1.0,
+                red_bar_depth=1.0,
+                brown_bar_depth=1.0,
+                bar_position='right',
+                bar_pad=0.02,
+                bar_tick_fontsize=9,
+                bar_tick_fontweight='normal',
+                bar_label='Normalized Intensity',
+                bar_label_fontsize=None,
+                bar_label_fontweight=None):
+    """
+    生成虚拟 IHC 图像，显示并保存。
+
+    Beer-Lambert 模型:
+      RGB[c] = BLK[c] + (1-BLK[c]) * exp(
+          - k1*BLUE[c]*Blue_gamma  - k2*RED[c]*Red_gamma  - k3*BROWN[c]*Brown_gamma
+      )
+
+    Parameters
+    ----------
+    Blue_image  : 2D ndarray, 蓝色通道 (细胞核, 不可为 None)
+    Red_image   : 2D ndarray or None, 红色通道
+    Brown_image : 2D ndarray or None, 棕色通道 (膜染色)
+    blue_name, red_name, brown_name : str, 各通道名称
+    title : str, 图像标题 (默认 '' 不显示)
+    k1, k2, k3 : float
+        全局吸收系数, 控制各通道整体强度.
+    blue_gamma, red_gamma, brown_gamma : float
+        各通道 Gamma 校正 (默认 1.0).
+    blue_threshold, red_threshold, brown_threshold : float
+        各通道背景扣除阈值: 强度 < threshold 的像素置 0 (默认 0.0 不扣除).
+        例如 Brown_threshold=0.1 等价于 np.where(Brown_image < 0.1, 0.0, Brown_image).
+    sigma : float, 高斯模糊 sigma
+    kernel_size : tuple, 高斯核大小
+    save_dir : str, 输出目录或完整路径 (.png/.tiff/.pdf/.svg)
+    figsize : tuple, 显示尺寸
+    save_dpi : int, 保存 figure 的分辨率 (默认 150)
+    x_ticks, y_ticks : array-like or None
+        显式坐标轴刻度 (优先于 tick_step). 例如 np.arange(0, 2001, 250).
+    tick_step : int or None
+        坐标轴刻度间隔 (像素). 当 x_ticks/y_ticks 为 None 时, 用
+        MultipleLocator(tick_step) 自动生成刻度; 默认 None 不设置.
+    xlim, ylim : tuple or None
+        坐标轴显示范围 (xmin, xmax) / (ymin, ymax). imshow 默认范围是
+        -0.5 ~ W-0.5, 导致边界刻度(如 2000)被裁掉; 设为 (0, W) 即可显示.
+    tick_fontsize : int, 坐标轴刻度字号
+    tick_fontweight : str, 坐标轴刻度粗细
+    xlabel : str, X 轴标签 (默认 '5μm / pixel')
+    ylabel : str, Y 轴标签 (默认 '5μm / pixel')
+    axis_label_fontsize : int, 坐标轴标签字号
+    axis_label_fontweight : str, 坐标轴标签粗细
+    title_fontsize : int, 标题字号
+    title_fontweight : str, 标题粗细
+    title_pad : float or None
+        标题与图像之间的间距; 默认 None 使用 matplotlib 默认值.
+    grid : bool, 是否显示网格
+    grid_linewidth : float, 网格线宽度 (默认 0.5)
+    spine_linewidth : float, 外边框线宽度 (默认 1.5)
+    blue_bar, red_bar, brown_bar : bool
+        是否显示各通道的 Normalized Intensity [0,1] colorbar.
+    bar_position : str, 'left' / 'right' / 'top' / 'bottom'
+        colorbar 放置位置.
+    bar_pad : float
+        colorbar 与图像的间距 (默认 0.02).
+    bar_tick_fontsize : int
+        colorbar 刻度字号.
+    bar_tick_fontweight : str
+        colorbar 刻度粗细.
+    bar_label : str
+        colorbar 标签文字 (默认 'Normalized Intensity').
+    bar_label_fontsize : int or None
+        colorbar 标签字号; None → bar_tick_fontsize + 8.
+    bar_label_fontweight : str or None
+        colorbar 标签粗细; None → bar_tick_fontweight.
+    """
+    # ---- 背景扣除 (threshold): 低于阈值的像素置 0 ----
+    Blue_image  = np.where(Blue_image < blue_threshold, 0.0, Blue_image)    if Blue_image  is not None else None
+    Red_image   = np.where(Red_image < red_threshold, 0.0, Red_image)      if Red_image   is not None else None
+    Brown_image = np.where(Brown_image < brown_threshold, 0.0, Brown_image) if Brown_image is not None else None
+
+    # ---- gamma 校正 ----
+    Blue_image  = _apply_gamma(Blue_image,  blue_gamma)  if Blue_image  is not None else None
+    Red_image   = _apply_gamma(Red_image,   red_gamma)   if Red_image   is not None else None
+    Brown_image = _apply_gamma(Brown_image, brown_gamma) if Brown_image is not None else None
+
+    # colorbar 用: 从 (阈值扣除 + gamma 校正后) 图像取 lim 百分位作为 [0,1] 映射区间.
+    #   lim=(0, 100) (默认) 时 lo = 最小正像素 (阈值扣除后最小值), hi = 最大正像素,
+    #   即 colorbar 的 0 端 = 阈值扣除后最小像素的颜色, 1 端 = 最大像素的颜色.
+    def _get_lo_hi(img, lim):
+        if img is None or np.all(img == 0):
+            return 0.0, 1.0
+        lo = np.percentile(img[img > 0], lim[0]) if np.any(img > 0) else 0.0
+        hi = np.percentile(img[img > 0], lim[1]) if np.any(img > 0) else 1.0
+        if hi <= lo:
+            hi = lo + 1.0
+        return lo, hi
+
+    _lo_hi = {}
+    _lo_hi['blue']  = _get_lo_hi(Blue_image,  blue_lim)
+    _lo_hi['red']   = _get_lo_hi(Red_image,   red_lim)
+    _lo_hi['brown'] = _get_lo_hi(Brown_image, brown_lim)
+
+    # ---- 输入校验: 从可用图像确定 height/width (优先级 Blue > Red > Brown) ----
+    if Blue_image is not None:
+        height, width = Blue_image.shape
+    elif Red_image is not None:
+        height, width = Red_image.shape
+    elif Brown_image is not None:
+        height, width = Brown_image.shape
+    else:
+        raise ValueError("至少需要提供一个非 None 的图像 (Blue / Red / Brown).")
+
+    if Blue_image is not None:
+        print(f"Blue  image: {blue_name},  shape: {Blue_image.shape}, dtype: {Blue_image.dtype}")
+    else:
+        Blue_image = np.zeros((height, width))
+        print(f"Blue  image: None → 已用全零数组替代")
+
+    if Red_image is None:
+        Red_image = np.zeros((height, width))
+        print(f"Red   image: None → 已用全零数组替代")
+    else:
+        print(f"Red   image: {red_name},   shape: {Red_image.shape}, dtype: {Red_image.dtype}")
+
+    if Brown_image is None:
+        Brown_image = np.zeros((height, width))
+        print(f"Brown image: None → 已用全零数组替代")
+    else:
+        print(f"Brown image: {brown_name}, shape: {Brown_image.shape}, dtype: {Brown_image.dtype}")
+
+    # ---- Beer-Lambert 颜色合成 ----
+    new_image = np.empty([height, width, 3], dtype=np.float64)
+
+    for c in range(3):
+        absorbance = (k1 * BLUE[c]  * Blue_image +
+                      k2 * RED[c]   * Red_image +
+                      k3 * BROWN[c] * Brown_image)
+        new_image[:, :, c] = BLK[c] + (1.0 - BLK[c]) * np.exp(-absorbance)
+
+    # 裁剪到 [0, 1]
+    new_image = np.clip(new_image, 0.0, 1.0)
+
+    # ---- 高斯模糊 ----
+    new_image_blur = cv2.GaussianBlur(
+        new_image, ksize=kernel_size,
+        sigmaX=sigma, sigmaY=sigma,
+        borderType=cv2.BORDER_REFLECT
+    )
+
+    # ---- 显示 ----
+    fig = plt.figure(figsize=figsize)
+    ax = fig.add_subplot(111)
+    ax.imshow(new_image_blur)
+    if title:
+        # title_pad=None → 用 matplotlib 默认间距; 否则显式设定
+        if title_pad is None:
+            ax.set_title(title, fontsize=title_fontsize, fontweight=title_fontweight)
+        else:
+            ax.set_title(title, fontsize=title_fontsize, fontweight=title_fontweight,
+                         pad=title_pad)
+    # 坐标轴刻度: 显式 x_ticks/y_ticks 优先; 否则用 tick_step 自动生成
+    if x_ticks is not None:
+        ax.set_xticks(x_ticks)
+    elif tick_step is not None:
+        ax.xaxis.set_major_locator(MultipleLocator(tick_step))
+    if y_ticks is not None:
+        ax.set_yticks(y_ticks)
+    elif tick_step is not None:
+        ax.yaxis.set_major_locator(MultipleLocator(tick_step))
+    # 坐标轴范围: 让边界刻度(如 2000)可见 —— imshow 默认范围是 -0.5~W-0.5
+    # xlim=(xmin, xmax); ylim=(ymin, ymax) —— 图像 y 轴自上而下,
+    # 故 ylim 反转传入 set_ylim, 保证 (0, 2000) 时 0 在上、2000 在下。
+    if xlim is not None:
+        ax.set_xlim(xlim)
+    if ylim is not None:
+        ax.set_ylim(ylim[1], ylim[0])
+    ax.tick_params(axis='both', labelsize=tick_fontsize)
+    for label in ax.get_xticklabels() + ax.get_yticklabels():
+        label.set_fontweight(tick_fontweight)
+    ax.set_xlabel(xlabel, fontsize=axis_label_fontsize,
+                  fontweight=axis_label_fontweight)
+    ax.set_ylabel(ylabel, fontsize=axis_label_fontsize,
+                  fontweight=axis_label_fontweight)
+    if grid:
+        ax.grid(True, alpha=0.3, linewidth=grid_linewidth)
+    for spine in ax.spines.values():
+        spine.set_linewidth(spine_linewidth)
+
+    # ---- colorbar (Normalized Intensity [0,1] per channel) ----
+    # x → x^gamma → 映射到 [lo, hi] → Beer-Lambert
+    def _make_stain_cmap(absorption, k_val, gamma_val, lo, hi,
+                         bar_alpha=1.0, bar_depth=1.0, n=256):
+        """gamma + lim → Beer-Lambert → 白→最深染色 colormap."""
+        x = np.linspace(0, 1, n)
+        x_eff = x ** gamma_val
+        intensity = lo + x_eff * (hi - lo)
+        absorbance = k_val * bar_depth * np.outer(intensity,
+                                      np.array(absorption, dtype=np.float64))
+        rgb = np.clip(np.exp(-absorbance), 0.0, 1.0)
+        rgba = np.concatenate([rgb, np.full((n, 1), bar_alpha)], axis=1)
+        return LinearSegmentedColormap.from_list('stain', rgba, N=n)
+
+    channel_configs = [
+        (blue_bar,  Blue_image,  _make_stain_cmap(BLUE,  k1, blue_gamma,  *_lo_hi['blue'],  blue_bar_alpha,  blue_bar_depth),   blue_name),
+        (red_bar,   Red_image,   _make_stain_cmap(RED,   k2, red_gamma,   *_lo_hi['red'],   red_bar_alpha,   red_bar_depth),    red_name),
+        (brown_bar, Brown_image, _make_stain_cmap(BROWN, k3, brown_gamma, *_lo_hi['brown'], brown_bar_alpha, brown_bar_depth),  brown_name),
+    ]
+
+    # colorbar label 样式: None → 使用默认 (bar_tick_fontsize + 8 / bar_tick_fontweight)
+    if bar_label_fontsize is None:
+        bar_label_fontsize = bar_tick_fontsize + 8
+    if bar_label_fontweight is None:
+        bar_label_fontweight = bar_tick_fontweight
+
+    # 累加 pad 偏移, 使多个 bar 不重叠
+    pad_offset = 0.0
+    for show, img, cmap, label in channel_configs:
+        if not show or img is None or np.all(img == 0):
+            continue
+
+        sm = ScalarMappable(Normalize(vmin=0, vmax=1), cmap=cmap)
+        sm.set_array([])
+
+        cbar = fig.colorbar(sm, ax=ax, location=bar_position,
+                           pad=bar_pad + pad_offset,
+                           fraction=0.035, shrink=0.85)
+        cbar.set_label(bar_label,
+                       fontsize=bar_label_fontsize,
+                       fontweight=bar_label_fontweight)
+        cbar.ax.tick_params(labelsize=bar_tick_fontsize)
+        for t in cbar.ax.get_yticklabels():
+            t.set_fontweight(bar_tick_fontweight)
+        pad_offset += 0.12  # 下一个 bar 向外偏移
+
+    plt.tight_layout()
+    plt.show()
+
+    # ---- 保存完整 figure (含 title, colorbar, 标注) ----
+    if save_dir.lower().endswith(('.png', '.tiff', '.tif', '.jpg', '.jpeg', '.pdf', '.svg')):
+        filepath = save_dir
+    else:
+        parts = [n for n in [blue_name, red_name, brown_name] if n]
+        filename = '_'.join(parts) + '.png'
+        filepath = os.path.join(save_dir, filename)
+
+    os.makedirs(os.path.dirname(filepath) or '.', exist_ok=True)
+    fig.savefig(filepath, dpi=save_dpi, bbox_inches='tight',
+                facecolor='white', edgecolor='none')
+    print(f"Figure 已保存到: {filepath}  (dpi={save_dpi})")
+
+    # ---- 额外保存 raw 合成图 (无任何标注: 无 title/colorbar/坐标轴/网格) ----
+    if Save_raw:
+        base = os.path.splitext(filepath)[0]
+        raw_filepath = base + "_raw.tiff"
+        image_to_save = (new_image_blur * 65535).astype(np.uint16)
+        tifffile.imwrite(raw_filepath, image_to_save, compression='lzw')
+        print(f"Raw 图像已保存到: {raw_filepath}")
+
+    return fig
+
+
+# ============================================================
+# ROI 版本: 仅显示局部区域, 但保留原始像素坐标 (不从 0 重新开始)
+# ============================================================
+
+def virtual_IHC_ROI(Blue_image, Red_image, Brown_image,
+                    X0=2250, X1=3000,
+                    Y0=1250, Y1=2000,
+                    TICK=250,
+                    **kwargs):
+    """
+    生成虚拟 IHC 图像的局部 ROI 区域，显示并保存。
+
+    在 ``virtual_IHC`` 基础上, 通过 ``xlim``/``ylim`` 仅显示矩形区域
+    [X0, X1) x [Y0, Y1), 但坐标轴刻度保留原始像素坐标 (不从 0 重新开始):
+      X0, X1 : x 像素范围 [X0, X1)
+      Y0, Y1 : y 像素范围 [Y0, Y1)
+      TICK   : 坐标刻度间隔
+
+    Beer-Lambert 模型与 ``virtual_IHC`` 完全一致; 其余参数 (gamma / colorbar /
+    保存选项等) 经 **kwargs 透传给 ``virtual_IHC``。
+
+    Parameters
+    ----------
+    Blue_image  : 2D ndarray, 蓝色通道 (细胞核, 不可为 None)
+    Red_image   : 2D ndarray or None, 红色通道
+    Brown_image : 2D ndarray or None, 棕色通道 (膜染色)
+    X0, X1 : int, x 像素范围 [X0, X1) (默认 2250, 3000)
+    Y0, Y1 : int, y 像素范围 [Y0, Y1) (默认 1250, 2000)
+    TICK   : int, 坐标刻度间隔 (默认 250)
+    **kwargs : 其余参数透传给 ``virtual_IHC`` (title, k1/k2/k3, gamma, lim,
+        sigma, save_dir, figsize, save_dpi, Save_raw, tick/axis 样式,
+        colorbar 样式等)。
+    """
+    # 显式坐标刻度: 保留原始像素坐标 (2250, 2500, 2750, 3000 ...)
+    x_ticks = np.arange(X0, X1 + 1, TICK)
+    y_ticks = np.arange(Y0, Y1 + 1, TICK)
+
+    return virtual_IHC(Blue_image, Red_image, Brown_image,
+                       xlim=(X0, X1),
+                       ylim=(Y0, Y1),
+                       x_ticks=x_ticks,
+                       y_ticks=y_ticks,
+                       **kwargs)

imc_histotools-0.1.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: imc-histotools
+Version: 0.1.0
+Summary: Digital pathology analysis tools for the Selenium (Se) IMC paper: virtual IHC rendering, Qupath ROI annotation, and pixel-wise H-score classification.
+Author: Guojun Han Laboratory @PKU
+License: MIT
+Project-URL: Homepage, https://github.com/gjhan100/IMC-HistoTools
+Project-URL: Repository, https://github.com/gjhan100/IMC-HistoTools
+Project-URL: Issues, https://github.com/gjhan100/IMC-HistoTools/issues
+Keywords: IMC,imaging mass cytometry,digital pathology,virtual IHC,H-score,pixel-wise H-score,Qupath,geojson,selenium
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: opencv-python>=4.5
+Requires-Dist: matplotlib>=3.4
+Requires-Dist: tifffile>=2021.0
+Dynamic: license-file
+
+<p align="center"><img src="https://raw.githubusercontent.com/gjhan100/IMC-HistoTools/main/assets/261013_Github.png" width="700"></p>
+
+[![Python Versions](https://img.shields.io/badge/python-3.8+-brightgreen.svg)](https://pypi.org/project/imc-histotools)
+[![PyPI](https://img.shields.io/pypi/v/imc-histotools.svg?color=brightgreen&style=flat)](https://pypi.org/project/imc-histotools)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**IMC-HistoTools** is a digital-pathology toolkit that bridges **imaging mass cytometry (IMC)** and **histopathology**, developed for the Selenium (Se) IMC study. It turns raw IMC channels into brightfield-like virtual IHC images, quantifies marker expression as **pixel-wise H-scores** on Qupath annotations, and renders **virtual multiplex** images from consecutive sections.
+
+# Functionality
+
+| Function | Description |
+| --- | --- |
+| `virtual_IHC` | Synthesise an IHC / brightfield-like RGB image from IMC channels using the Beer–Lambert absorbance model (per-channel gamma, background threshold, stain colour bar). |
+| `virtual_IHC_ROI` | Same as above but zooms into a local region while **keeping the original pixel coordinates**. |
+| `virtual_IHC_annotation` | Rasterise Qupath `.geojson` polygon annotations into ROI boolean masks. |
+| `Hscore_threshold` | Build classification thresholds from reference ROIs (Negative / Low / Medium / High) using **mean / median / geometric-mean / all**. |
+| `pix_Hscore_map` | Classify every pixel into NP / LP / MP / HP, export a per-pixel CSV, and produce publication figures (classification map + bar chart & table). |
+
+# Install IMC-HistoTools
+
+### Using pip [![PyPI](https://img.shields.io/pypi/v/imc-histotools.svg?color=brightgreen&style=flat)](https://pypi.org/project/imc-histotools)
+```console
+pip install imc-histotools
+```
+
+### From GitHub [![GitHub](https://img.shields.io/badge/github-source-blue.svg)](https://github.com/gjhan100/IMC-HistoTools)
+```console
+git clone https://github.com/gjhan100/IMC-HistoTools.git
+cd IMC-HistoTools
+pip install -e .
+```
+
+# Usage
+
+<details>
+<summary><strong>1. Virtual IHC from IMC raw tiff</strong></summary>
+
+Render a brightfield-like IHC image from raw (or [0,1]-normalised) IMC channels.
+`Blue` is typically the nuclear marker (DNA); `Brown`/`Red` are membrane / lineage markers.
+
+```python
+import numpy as np
+import tifffile
+from IMC_HistoTools import virtual_IHC, virtual_IHC_ROI
+
+# read IMC channels
+dna = tifffile.imread("ROI_001_193Ir-DNA_cor.tiff").astype(np.float32)   # nuclear
+se  = tifffile.imread("ROI_001_Se-Ecadherin_cor.tiff").astype(np.float32) # membrane
+
+# full-image virtual IHC  (Blue = DNA, Brown = E-cadherin-Se)
+virtual_IHC(
+    Blue_image=dna, Red_image=None, Brown_image=se,
+    blue_name="DNA", brown_name="E-cadherin (Se)",
+    brown_threshold=0.1,          # background removal (< threshold -> 0)
+    brown_bar=True,               # show stain colour bar
+    save_dir="out/virtual_IHC.png",
+)
+
+# local region, keeping original pixel coordinates
+virtual_IHC_ROI(
+    Blue_image=dna, Red_image=None, Brown_image=se,
+    X0=2250, X1=3000, Y0=1250, Y1=2000, TICK=250,
+    save_dir="out/virtual_IHC_ROI.png",
+)
+```
+</details>
+
+<details>
+<summary><strong>2. Pixel-wise H-score with Qupath annotation</strong></summary>
+
+Load tissue-region and reference-ROI annotations exported from Qupath, calibrate the
+thresholds from the Negative / Low / Medium / High reference ROIs, then classify every
+pixel and export a CSV + figures.
+
+```python
+from IMC_HistoTools import virtual_IHC_annotation, Hscore_threshold, pix_Hscore_map
+
+marker = tifffile.imread("Normalize/ROI_001_Se_crop_normal.tiff").astype(np.float32)
+tissue = tifffile.imread("Mask/mask_crop.tiff") > 0
+
+# 1) tissue-region annotations (Normal mucosa / Tumor center / Invasive front / ...)
+ann = virtual_IHC_annotation(marker, "tissue_regions.geojson")
+
+# 2) reference ROIs (Negative / Low / Medium / High) for threshold calibration
+ref = virtual_IHC_annotation(marker, "reference_ROIs.geojson",
+                             region_order=["Negative", "Low", "Medium", "High"])
+
+# 3) thresholds from the reference ROIs  (stat: 'mean'/'median'/'geomean'/'all')
+thr = Hscore_threshold(
+    marker,
+    Np=ref["masks"]["Negative"], Lp=ref["masks"]["Low"],
+    Mp=ref["masks"]["Medium"],   Hp=ref["masks"]["High"],
+    tissue_mask=tissue, stat="median",
+)
+print(thr["thresholds"])          # (Lp, Mp, Hp)
+
+# 4) per-pixel H-score map + CSV + bar chart / table
+res = pix_Hscore_map(
+    marker,
+    Hscore_threshold_annotation=ref["masks"],   # Lp / Mp / Hp reference ROIs
+    tissue_annotation=ann["masks"],             # non-empty -> bar chart + table
+    tissue_mask=tissue,
+    stat="median",
+    delta=2, kernel=(5, 5),                     # Gaussian blur for the map display only
+    save_dir="out/",
+)
+res["csv_path"]        # per-pixel classification: x, y, intensity, score, category
+```
+
+Classification: `intensity < Lp` → 0 (NP), `[Lp, Mp)` → 1 (LP), `[Mp, Hp)` → 2 (MP),
+`>= Hp` → 3 (HP). The bar-chart statistics always use the **non-blurred** classification.
+</details>
+
+<details>
+<summary><strong>3. Virtual multiplexing from consecutive sections</strong></summary>
+
+Feed registered channels from consecutive sections into the three colour channels of
+`virtual_IHC` to obtain a single virtual-multiplex image (blue / red / brown).
+
+```python
+from IMC_HistoTools import virtual_IHC
+
+virtual_IHC(
+    Blue_image=dna,     # section A — DNA        (nuclear,    blue)
+    Red_image=cd45,     # section B — CD45       (red)
+    Brown_image=ecad,   # section C — E-cadherin (membrane,   brown)
+    blue_name="DNA", red_name="CD45", brown_name="E-cadherin",
+    blue_bar=True, red_bar=True, brown_bar=True,
+    save_dir="out/virtual_multiplex.png",
+)
+```
+</details>
+
+# Citation
+
+If you use **IMC-HistoTools** in your research, please cite the Se IMC paper (citation
+to be added upon publication).
+
+# License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file.

imc_histotools-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+IMC_HistoTools/__init__.py,sha256=1fDaHiUHHD_yOpZQufQM2tQBiiTcI0F971yPO-GBmnY,821
+IMC_HistoTools/annotation_region.py,sha256=nGnwsE6maM7fGCk0ekQFot4l8UmYC86U9UnIu5BRVjQ,6435
+IMC_HistoTools/pix_Hscore.py,sha256=UposEy9g0ztw_vEUq3dgErjq_8j_qpBVom7spEJTrJg,17923
+IMC_HistoTools/virtual_IHC.py,sha256=aXYYvzbJhGmLJCvSwyOkp7eZDwnGuImpo5uPG2xwnzg,17441
+imc_histotools-0.1.0.dist-info/licenses/LICENSE,sha256=54qAOLjcTi4Dt9HUb2suxT1XFMeGtO5XbWC40Sl7oOA,1083
+imc_histotools-0.1.0.dist-info/METADATA,sha256=IiS61o5w2f_Re47ZtWOWqeAVyqaQfPlxXL6V8anvbrs,7229
+imc_histotools-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+imc_histotools-0.1.0.dist-info/top_level.txt,sha256=apPuZlTq6741pNrz50hbucde2nwH3cgUwa-4Vrc60T4,15
+imc_histotools-0.1.0.dist-info/RECORD,,

imc_histotools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

imc_histotools-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guojun Han Laboratory @PKU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imc_histotools-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+IMC_HistoTools