.. image:: https://img.shields.io/pypi/v/nilearn.svg :target: https://pypi.org/project/nilearn/ :alt: PyPI 包

.. image:: https://img.shields.io/pypi/pyversions/nilearn.svg :target: https://pypi.org/project/nilearn/ :alt: PyPI - Python 版本

.. image:: https://github.com/nilearn/nilearn/actions/workflows/build-docs.yml/badge.svg :target: https://github.com/nilearn/nilearn/actions/workflows/build-docs.yml :alt: GitHub Actions 文档构建状态

.. image:: https://github.com/nilearn/nilearn/actions/workflows/test_with_tox.yml/badge.svg?branch=main&event=push :target: https://github.com/nilearn/nilearn/actions/workflows/test_with_tox.yml :alt: GitHub Actions 测试状态

.. image:: https://codecov.io/gh/nilearn/nilearn/graph/badge.svg?token=KpYArSdyXv :target: https://app.codecov.io/gh/nilearn/nilearn :alt: 覆盖率状态

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.8397156.svg :target: https://doi.org/10.5281/zenodo.8397156

.. image:: https://img.shields.io/badge/bluesky-Follow_nilearn-blue?logo=bluesky :target: https://bsky.app/profile/nilearn.bsky.social :alt: Bluesky

.. image:: https://img.shields.io/youtube/channel/subscribers/UCU6BMAi2zOhNFnDkbdevmPw :target: https://www.youtube.com/@nilearnevents5116 :alt: YouTube 频道订阅者

.. image:: https://img.shields.io/mastodon/follow/109669703955432270?domain=https%3A%2F%2Ffosstodon.org%2F :target: https://fosstodon.org/@nilearn :alt: Mastodon

.. image:: https://img.shields.io/discord/711993354929569843 :target: https://discord.com/invite/SsQABEJHkZ :alt: Discord

nilearn

Nilearn 提供了一种易于上手且功能多样的脑影像体积和表面分析方法。它包含统计学和机器学习工具，并配有详尽的文档和友好的社区支持。

该库支持基于一般线性模型（GLM）的分析，并利用 scikit-learn <https://scikit-learn.org>_ Python 工具箱进行多变量统计分析，适用于预测建模、分类、解码或连接性分析等任务。

重要链接

• 官方源代码仓库：https://github.com/nilearn/nilearn/
• HTML 文档（稳定版）：https://nilearn.github.io/

安装

最新版本

1. 设置虚拟环境

我们建议您在虚拟 Python 环境中安装 nilearn，可以使用标准库中的 venv 或 conda（例如 miniconda <https://docs.conda.io/en/latest/miniconda.html>_）。无论哪种方式，请创建并激活一个新的 Python 环境。

使用 venv：

.. code-block:: bash

python3 -m venv /<path_to_new_env>
source /<path_to_new_env>/bin/activate

Windows 用户应将最后一行改为 \<path_to_new_env>\Scripts\activate.bat 以激活虚拟环境。

使用 conda：

.. code-block:: bash

conda create -n nilearn python=3.10
conda activate nilearn

2. 使用 pip 安装 nilearn

在正确的 Python 环境中，在命令提示符或终端中执行以下命令：

.. code-block:: bash

python -m pip install -U nilearn

开发版本

请参阅 贡献指南 <https://nilearn.github.io/stable/development.html#setting-up-your-environment>_ 获取完整的开发环境设置说明。

检查安装

尝试在 Python 或 iPython 会话中导入 nilearn：

.. code-block:: python

import nilearn

如果没有出现错误，则说明您已正确安装 nilearn。

答疑时间

Nilearn 团队定期举办在线答疑活动，解答问题、讨论功能请求或进行任何与 Nilearn 相关的交流。Nilearn 的答疑时间是 每周三下午 4 点至 5 点（UTC），我们确保至少有一名核心开发人员在线。这些活动在 Jitsi Meet <https://meet.jit.si/nilearn-drop-in-hours>_ 上举行，完全开放，欢迎任何人参加！有关更多信息及如何与 Nilearn 团队互动，请参阅 如何获得帮助 <https://nilearn.github.io/stable/development.html#how-to-get-help>_。

依赖项

使用该软件所需的依赖项列于文件 pyproject.toml <https://github.com/nilearn/nilearn/blob/main/pyproject.toml>_ 中。

如果您使用 nilearn 的绘图功能或运行示例，需要 matplotlib >= 3.8.0。

Nilearn 中的一些绘图函数同时支持 matplotlib 和 plotly 作为绘图引擎。要在这些函数中使用 plotly 引擎，您需要安装 plotly 和 kaleido，两者都可以通过 pip 和 anaconda 安装。

如果要运行测试，您需要 pytest >= 6.0.0 和 pytest-cov 用于覆盖率报告。

开发

详细的贡献指南可在以下网址找到： https://nilearn.github.io/stable/development.html

Nilearn 快速上手指南

Nilearn 是一个用于脑成像数据（体积和表面）分析的 Python 库。它提供了统计和机器学习工具，支持基于一般线性模型（GLM）的分析，并深度集成了 scikit-learn，适用于预测建模、分类、解码及连接性分析等任务。

环境准备

• 操作系统：支持 Linux、macOS 和 Windows。
• Python 版本：推荐 Python 3.8 及以上（官方示例常用 3.10+）。
• 前置依赖：
  • 核心功能依赖 numpy, scipy, pandas, scikit-learn, nibabel 等，安装时会自动解决。
  • 绘图功能：若需使用绘图功能或运行示例，需确保 matplotlib >= 3.8.0。
  • 交互式绘图：部分函数支持 plotly 引擎，如需使用需额外安装 plotly 和 kaleido。
• 国内加速建议：建议使用国内镜像源（如清华源、阿里源）加速安装过程。

安装步骤

强烈建议在虚拟环境中安装，以避免依赖冲突。

1. 创建并激活虚拟环境

方式 A：使用 venv (标准库)

# 创建环境
python3 -m venv nilearn_env

# 激活环境 (Linux/macOS)
source nilearn_env/bin/activate

# 激活环境 (Windows)
nilearn_env\Scripts\activate.bat

方式 B：使用 conda

conda create -n nilearn python=3.10
conda activate nilearn

2. 安装 Nilearn

在激活的环境中执行以下命令。推荐使用国内镜像源以提升下载速度：

# 使用清华源安装
python -m pip install -U nilearn -i https://pypi.tuna.tsinghua.edu.cn/simple

(可选) 若需使用 plotly 绘图引擎：

pip install plotly kaleido -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 验证安装

启动 Python 或 IPython 会话，尝试导入库：

import nilearn

若无报错，则说明安装成功。

基本使用

以下示例展示如何加载标准的脑图谱模板并提取数据，这是使用 Nilearn 最常见的起点。

from nilearn import datasets, image, plotting

# 1. 下载并加载标准的 MNI152 脑模板
dataset = datasets.load_mni152_template()
img = image.load_img(dataset)

# 2. 简单的可视化
plotting.plot_anat(img, title="MNI152 Template", display_mode='ortho', cut_coords=(0, 0, 0))
plotting.show()

# 3. 加载哈佛 - 牛津皮质结构图谱 (Harvard-Oxford cortical atlas)
atlas_dataset = datasets.fetch_atlas_harvard_oxford('cort-maxprob-thr25-2mm')
atlas_img = atlas_dataset.maps
labels = atlas_dataset.labels

print(f"图谱包含 {len(labels)} 个区域")
print(f"前五个区域名称：{labels[:5]}")

# 4. 将图谱可视化
plotting.plot_roi(atlas_img, title="Harvard-Oxford Cortical Atlas")
plotting.show()

提示：首次运行上述代码时，Nilearn 会自动从网络下载数据集到本地缓存目录（通常为 ~/nilearn_data），请确保网络连接正常。