Merge pull request #48 from RicardoRyn/dev

Dev

Author: RicardoRyn

IFLOW.md

@@ -0,0 +1,124 @@
+# IFLOW.md - plotfig项目指南
+
+## 项目概述
+
+`plotfig` 是一个专为认知神经科学设计的Python数据可视化库，基于`matplotlib`、`surfplot`和`plotly`等主流可视化库开发。该项目旨在为科研工作者提供高效、易用且美观的图形绘制工具，特别适用于神经科学和脑连接组学领域的复杂绘图需求。
+
+项目特点：
+- 模块化设计，功能丰富
+- 支持多种科学绘图类型
+- 专门针对神经科学数据可视化需求优化
+
+## 项目结构
+
+```
+plotfig/
+├── src/plotfig/          # 核心源码目录
+│   ├── __init__.py       # 导出所有公共API
+│   ├── bar.py            # 条形图绘制
+│   ├── brain_connection.py # 大脑连接可视化
+│   ├── brain_surface.py  # 脑表面可视化
+│   ├── circos.py         # 弦图可视化
+│   ├── correlation.py    # 相关性矩阵可视化
+│   ├── matrix.py         # 通用矩阵可视化
+│   ├── utils/            # 工具函数模块
+│   └── data/             # 数据文件
+├── tests/                # 测试文件
+├── notebooks/            # Jupyter笔记本示例
+├── docs/                 # 文档文件
+├── pyproject.toml        # 项目配置文件
+└── README.md             # 项目说明文档
+```
+
+## 核心功能模块
+
+### 1. brain_connection.py
+提供大脑连接图的3D可视化功能，支持：
+- 基于NIfTI格式图集的ROI节点定位
+- 使用Plotly创建交互式3D大脑连接图
+- 支持根据连接强度调整线条宽度和颜色
+- 可生成旋转动画帧并制作GIF
+
+主要函数：
+- `plot_brain_connection_figure`: 绘制大脑连接图
+- `save_brain_connection_frames`: 生成旋转动画帧
+- `batch_crop_images`: 批量裁剪图像
+- `create_gif_from_images`: 从图像生成GIF
+
+### 2. correlation.py
+支持两个数据集之间的相关性分析和可视化：
+- 支持Spearman和Pearson相关性计算
+- 可绘制散点图、回归线和置信区间
+- 提供多种轴标签格式化选项
+
+主要函数：
+- `plot_correlation_figure`: 绘制相关性图
+
+### 3. 其他模块
+- `bar.py`: 条形图和小提琴图绘制
+- `matrix.py`: 通用矩阵可视化
+- `brain_surface.py`: 脑表面可视化
+- `circos.py`: 弦图可视化
+
+## 依赖管理
+
+项目要求Python 3.11+版本，关键依赖包括：
+- `matplotlib`: 基础绘图库
+- `plotly`: 交互式3D可视化
+- `surfplot`: 脑表面绘制（需从GitHub安装最新版）
+- `numpy`, `scipy`: 数值计算
+- `nibabel`: 神经影像数据处理
+- `imageio`: 图像处理
+
+## API使用示例
+
+### 大脑连接可视化
+```python
+from plotfig import plot_brain_connection_figure
+
+fig = plot_brain_connection_figure(
+    connectome=connectome_matrix,
+    lh_surfgii_file="lh_surface.gii",
+    rh_surfgii_file="rh_surface.gii", 
+    niigz_file="atlas.nii.gz",
+    scale_method="width_color",
+    line_width=10
+)
+```
+
+### 相关性分析
+```python
+from plotfig import plot_correlation_figure
+
+plot_correlation_figure(
+    data1=[1, 2, 3, 4, 5],
+    data2=[2, 4, 6, 8, 10],
+    stats_method="pearson",
+    ci=True,
+    title_name="Correlation Plot"
+)
+```
+
+## 开发和测试
+
+项目支持开发模式安装：
+```bash
+pip install -e .
+```
+
+测试文件位于`tests/`目录，示例代码在`notebooks/`目录。
+
+## 构建和安装
+
+项目使用Hatchling作为构建后端，通过`pyproject.toml`管理依赖和构建配置。
+
+安装命令：
+- PyPI安装：`pip install plotfig`
+- 源码安装：`pip install .`
+- 开发安装：`pip install -e .`
+
+## 文档和资源
+
+- 在线文档：https://ricardoryn.github.io/plotfig/
+- 源代码：https://github.com/RicardoRyn/plotfig
+- 问题反馈：https://github.com/RicardoRyn/plotfig/issues

pyproject.toml

@@ -9,6 +9,7 @@ authors = [
     { name = "Ricardo Ryn", email = "ricardoRyn1317@gmail.com" }
 ]
 dependencies = [
+    "imageio>=2.37.2",
     "kaleido>=1.0.0",
     "loguru>=0.7.3",
     "matplotlib>=3.10.6",

src/plotfig/bar.py

@@ -383,7 +383,13 @@ def plot_one_group_bar_figure(
         statistic (bool, optional):
             是否进行统计显著性分析. Defaults to False.
         test_method (list[str], optional):
-            统计检验方法列表. Defaults to ["ttest_ind"].
+            统计检验方法列表，包括
+            1. `ttest_ind`,
+            2. `ttest_rel`,
+            3. `ttest_1samp`,
+            4. `mannwhitneyu`,
+            5. `external`.
+            Defaults to ["ttest_ind"].
         p_list (list[float] | None, optional):
             预计算的p值列表，用于显著性标记. Defaults to None.
         popmean (Num, optional):

src/plotfig/brain_surface.py

@@ -50,7 +50,7 @@ def plot_brain_surface_figure(
     ax: Axes | None = None,
     vmin: Num | None = None,
     vmax: Num | None = None,
-    cmap: str = "Reds",
+    cmap: str = "viridis",
     colorbar: bool = True,
     colorbar_location: str = "right",
     colorbar_label_name: str = "",
@@ -75,7 +75,7 @@ def plot_brain_surface_figure(
         ax (Axes | None, optional): matplotlib的坐标轴对象，如果为None则使用当前坐标轴. Defaults to None.
         vmin (Num | None, optional): 颜色映射的最小值，None表示使用数据中的最小值. Defaults to None.
         vmax (Num | None, optional): 颜色映射的最大值，None表示使用数据中的最大值. Defaults to None.
-        cmap (str, optional): 颜色映射方案，如"Reds"、"Blues"、"viridis"等. Defaults to "Reds".
+        cmap (str, optional): 颜色映射方案，如"viridis"、"Blues"、"Reds"等. Defaults to "viridis".
         colorbar (bool, optional): 是否显示颜色条. Defaults to True.
         colorbar_location (str, optional): 颜色条位置，可选"left"、"right"、"top"、"bottom". Defaults to "right".
         colorbar_label_name (str, optional): 颜色条标签名称. Defaults to "".
@@ -131,6 +131,10 @@ def plot_brain_surface_figure(
                     "rh": "atlases/human_BNA/fsaverage.R.BNA.32k_fs_LR.label.gii",
                 },
             },
+            "sulc": {
+                "lh": "surfaces/human_fsLR/100206.L.sulc.32k_fs_LR.shape.gii",
+                "rh": "surfaces/human_fsLR/100206.R.sulc.32k_fs_LR.shape.gii",
+            }
         },
         "chimpanzee": {
             "surf": {
@@ -166,7 +170,12 @@ def plot_brain_surface_figure(
                     "lh": "atlases/macaque_D99/L.d99.label.gii",
                     "rh": "atlases/macaque_D99/R.d99.label.gii",
                 },
+            },
+            "sulc": {
+                "lh": "surfaces/macaque_BNA/SC_06018.L.sulc.32k_fs_LR.shape.gii",
+                "rh": "surfaces/macaque_BNA/SC_06018.R.sulc.32k_fs_LR.shape.gii",
             }
+
         }
     }
 
@@ -179,10 +188,29 @@ def plot_brain_surface_figure(
             raise ValueError(f"Unsupported {atlas} atlas for {species}")
 
     # 创建Plot对象，用于绘制大脑皮层
-    p = Plot(
-        NEURODATA / atlas_info[species]["surf"]["lh"],
-        NEURODATA / atlas_info[species]["surf"]["rh"],
-    )
+    if surf != "flat":
+        p = Plot(
+            NEURODATA / atlas_info[species]["surf"]["lh"],
+            NEURODATA / atlas_info[species]["surf"]["rh"],
+        )
+    else:
+        # NOTE: 目前只有人和猕猴具有flat surface，暂时不支持黑猩猩
+        p = Plot(
+            NEURODATA / atlas_info[species]["surf"]["lh"],
+            NEURODATA / atlas_info[species]["surf"]["rh"],
+            views="dorsal",
+            zoom = 1.2,
+        )
+        lh_sulc_file = NEURODATA / atlas_info[species]["sulc"]["lh"]
+        rh_sulc_file = NEURODATA / atlas_info[species]["sulc"]["rh"]
+        p.add_layer(
+            {
+                "left": nib.load(lh_sulc_file).darrays[0].data,
+                "right": nib.load(rh_sulc_file).darrays[0].data,
+            },
+            cmap="Grays_r",
+            cbar=False
+        )
 
     # 分离左半球和右半球的数据
     hemisphere_data = {}

src/plotfig/data/neurodata/surfaces/human_fsLR/100206.L.sulc.32k_fs_LR.shape.gii

@@ -9,3 +9,10 @@ wb_command -metric-resample ${sulc164k} ${164k_sphere} ${Xk_sphere} ADAP_BARY_AR
 ```
 
 Where `${Xk_sphere}` is the target sphere and `${164k_vaavg}` + `${Xk_vaavg}` are average vertex area maps.
+
+基于HCP样本 `100206` 通过 HCP 处理流程生成的表面数据文件：
+
+- `tpl-fsLR_den-32k_hemi-L_flat.surf.gii`
+- `tpl-fsLR_den-32k_hemi-R_flat.surf.gii`
+- `100206.L.sulc.32k_fs_LR.shape.gii`
+- `100206.R.sulc.32k_fs_LR.shape.gii`

src/plotfig/data/neurodata/surfaces/human_fsLR/100206.R.sulc.32k_fs_LR.shape.gii

@@ -0,0 +1,10 @@
+# macaque_BNA
+
+基于实验室样本 `SC_06018` 通过 HCP_NHP 处理流程生成的表面数据文件：
+
+- `civm.L.flat.32k_fs_LR.surf.gii`
+- `civm.R.flat.32k_fs_LR.surf.gii`
+- `SC_06018.L.sulc.32k_fs_LR.shape.gii`
+- `SC_06018.R.sulc.32k_fs_LR.shape.gii`
+
+其他文件来自`BNA`数据。