Metadata-Version: 2.4
Name: plotfig
Version: 1.3.2
Summary: Scientific plotting package for Cognitive neuroscience
Author-email: Ricardo Ryn <ricardoRyn1317@gmail.com>
License-File: LICENSE
Keywords: neuroscience,plotting,visualization
Requires-Python: >=3.11
Requires-Dist: matplotlib>=3.10.1
Requires-Dist: mne-connectivity>=0.7.0
Requires-Dist: nibabel>=5.3.2
Requires-Dist: numpy>=2.2.4
Requires-Dist: pandas>=2.2.3
Requires-Dist: plotly>=6.0.1
Requires-Dist: scipy>=1.15.2
Requires-Dist: surfplot
Description-Content-Type: text/markdown

# 简介

`plotfig` 是一个专为科学数据可视化设计的 Python 库，致力于为认知神经科研工作人员提供高效、易用且美观的图形绘制工具。
该项目基于业界主流的可视化库—— `matplotlib`、`surfplot` 和 `plotly` 开发，融合了三者的强大功能，能够满足神经科学、脑连接组学、相关性分析、矩阵可视化等多种科研场景下的复杂绘图需求。

![plotfig](https://github.com/RicardoRyn/plotfig/blob/main/docs/assets/plotfig.png)


## 项目结构

项目采用模块化设计，核心代码位于 `src/plotfig/` 目录下，包含如下主要功能模块：

- `bar.py`：条形图绘制，适用于分组数据的对比展示。
- `correlation.py`：相关性矩阵可视化，便于分析变量间的相关性分布。
- `matrix.py`：通用矩阵可视化，支持多种配色和注释方式。
- `brain_surface.py`：脑表面可视化，利用 `surfplot` 实现三维脑表面图集结构的绘制。
- `brain_connection.py`：玻璃脑连接可视化，支持复杂的脑网络结构展示。
- `circos.py`：环状图（Circos）绘制，适合平面展示脑区之间的连接关系。


## 文档与示例

`plotfig` 提供了网页文档和使用示例。具体参见[使用教程](https://ricardoryn.github.io/plotfig/)。

`plotfig` API 设计简洁，参数灵活，适合科研人员和数据分析师快速集成到自己的数据分析流程中。
其模块化架构便于后续功能扩展和自定义开发。
结合 `matplotlib` 支持矢量图或高分辨率位图和交互式 HTML 输出，适合论文发表和学术展示。

# 安装

## 普通安装

`plotfig` 支持通过 `pip` 或源码安装，要求 Python 3.11 及以上版本。


**使用 pip 安装 <small>(推荐)</small>**

```bash
pip install plotfig
```

**使用 GitHub 源码安装**

```bash
git clone https://github.com/RicardoRyn/plotfig.git
cd plotfig
pip install .
```

## 开发版安装

当你希望参与 `plotfig` 的开发，或想在使用过程中尝试尚未正式发布的新功能、最新修复的 bug 时，可以选择以开发模式安装。
该方式会以“可编辑模式（editable mode）”将项目安装到环境中，使你对本地源码的修改可以立即生效，非常适合用于开发、调试和贡献代码。

建议先 Fork 仓库，然后克隆你自己的 Fork：

```bash
git clone -b dev https://github.com/<your-username>/plotfig.git
cd plotfig
pip install -e .
```

## 依赖要求

`plotfig` 依赖若干核心库，这些依赖均会在安装过程中自动处理。

- [matplotlib](https://matplotlib.org/) &ge; 3.10.1  
- [mne-connectivity](https://mne.tools/mne-connectivity/stable/index.html) &ge; 0.7.0  
- [nibabel](https://nipy.org/nibabel/) &ge; 5.3.2  
- [numpy](https://numpy.org/) &ge; 2.2.4  
- [pandas](https://pandas.pydata.org/) &ge; 2.2.3  
- [plotly](https://plotly.com/) &ge; 6.0.1  
- [scipy](https://scipy.org/) &ge; 1.15.2  
- [surfplot](https://github.com/danjgale/surfplot)（使用其 GitHub 仓库最新版，而非 PyPI 发布版本，因后者尚未包含所需功能）
