---
myst:
html_meta:
"referrer": "no-referrer"
---
# 使用手册
## 平台概览
### 目标
通过这一模块的阅读，您能够对ZJB平台的各项功能有一个初步的了解，这将更好的帮助您利用ZJB平台实现数字孪生脑建模仿真的工作。
### 启动平台进入首页
启动 ZJB 平台，平台界面主要由标题栏、导航栏、窗口区组成。
- 顶部标题栏包含平台名称、logo、新建按钮 
、打开按钮 
和Jupyter按钮 
。
- 左侧导航栏包含按钮：展开导航栏 
、数字孪生脑 
、脑图谱 
、动力学模型 
、作业管理 
、设置页 
，点击按钮可以进入对应内容的目录页。
- 窗口区默认显示Welcome页面，提供新建工作空间 
和打开工作空间 
等操作。
### 新建/打开工作空间
“工作空间”为一个独立的本地数据库，在使用平台进行数字孪生脑仿真时，创建、生成的所有数据，都保存在这个工作空间对应的本地数据库中。因此，使用数字孪生脑的第一步需要您新建或者打开一个工作空间。
1. 新建工作空间
- 可以通过“标题栏->New->New Workspace”或者“Welcome页->New Workspace”进入创建工作空间的窗口。
- 为工作空间取一个名字，并选择工作空间的存储路径，即成功创建工作空间。工作空间名称支持1至20个由数字、大小写字母及下划线组成的字符串。
- 创建完成后，自动打开该工作空间，并在目录列表中显示工作空间的根目录。
2. 打开工作空间
若您已经通过数字孪生脑平台建立了其他的工作空间，可以通过“标题栏->Open->WorkSpace”或者“Welcome页->Open Workspace”操作，打开您本地已有的工作空间。此外，您还可以通过“标题栏->Open”或者“Welcome页->RECENT”快捷的打开您近期打开过的工作空间。
3. 使用默认的工作空间
平台提供了一个包含脑图谱、动力学模型及示例项目的默认工作空间，可以下载并使用
下载资源仓库得到默认的工作空间: https://github.com/ZJBGroup/ZJB-Assets
也可以通过百度网盘下载默认的工作空间：链接：https://pan.baidu.com/s/1a1teYJx4yB0B7HqsKeh4aw?pwd=ZJBW
提取码：ZJBW
解压ZJB-Assets/workspaces/workspace_basic.zip，并在GUI应用首页`Open Workspace`中打开此工作空间并使用.
### 数字孪生脑页面
通过点击导航栏 
按钮，进入到数字孪生脑页面。
- 打开工作空间以后，在目录列表中会陈列您创建的各类数据，数据主要包含五个类别，用不同的图标进行区分。目录最顶层的 
表示当前打开的工作空间“Workspace”，其下包含的所有 
都表示一个项目“Project”；
表示一个被试“Subject”；
表示一个数字孪生脑模型“DTB Model”; 
表示一个数字孪生脑“DTB”。
- 工作空间 Workspace 是一个特殊的项目 Project，他们都包含子Project、Subject、DTB Model、DTB。右键目录列表中的条目可进行新建或删除各类数据的操作。左键点击目录中的各个数据条目能够在右侧窗口区打开该数据的详情页面，所有页面都可以通过tab标签中的按钮进行关闭。左键双击可打开或折叠子目录。
### 脑图谱页面
在打开工作空间的情况下，通过点击导航栏 
按钮，进入到脑图谱页面。点击目录列表中的脑图谱数据 
条目，窗口区会打开该数据的详情页面。如果您的工作空间中有很多脑图谱数据，您可以都将它们在右侧的窗口中打开。
### 动力学模型页面
在打开工作空间的情况下，通过点击导航栏 
按钮，进入到动力学模型页面。平台提供了多种常见的动力学模型，点击对应的条目 
，可以在窗口区查看对应的动力学模型基本信息、相位分析等信息。
通过导航栏New->New Dynamic Model，可以进入创建动力学模型界面，填写完表单中的信息即可创建一个新的动力学模型。
或者您也可以右键点击一个现有的动力学模型，进行copy操作。以此为基础修改其各项参数来创建一个新的动力学模型。同样的右键操作还能够删除一个现有的动力学模型。
### 作业管理页面
在打开工作空间的情况下，通过点击导航栏 
按钮，进入到作业管理页面。作业管理提供了 
“Job List和 
“Worker Manager”两个目录菜单。点击不同的菜单项，进入不同的页面窗口。
- 在“Job List”的窗口中，您能通过列表查看到您工作空间内所有的模拟作业信息，并可以通过作业状态进行筛选显示。点击列表中的条目，会弹窗显示该作业的详细信息。
- 在“ Worker Manager”的窗口中，您可以查看到用于模拟作业的进程信息，每一个Worker卡片表示一个进程。您可以根据您模拟作业的规模，选择批量新增或者删除Worker，上限为您使用的计算机核数。
### 设置页面
通过点击导航栏底部的 
按钮，进入到平台设置页面。在这里您可以个性化的定制平台的界面。
- “Mica effect”：若您的电脑为Windows11系统，可打开该功能，体验平台界面的毛玻璃特效。
- “Application theme”：您可以根据喜好，在这里设置平台的明、暗主题。
- “Theme color”：在这里您可以选择您喜欢的颜色，作为平台主题色。
### 内置Jupyter
如果您想要通过自己编码实现平台未覆盖的功能，可以点击标题栏的“Jupyter”按钮，进入Jupyter解释器页面，在这里实现代码的编写、调试。
## 数字孪生脑建模仿真
### 目标
假设你已经对ZJB平台的各个组件有了一定的了解，你可以通过此部分熟悉如何通过ZJB平台来完成一个基本的建模流程.
如果这是你第一次使用ZJB平台，请移步[平台概览](#h1LuJ)部分的文档.
### 创建一个“数字孪生脑”（dtb）
- 一个数字孪生脑（dtb）指的是由真实大脑信息所约束的数字化大脑. 如图所示，在平台中其主要由数字孪生脑模型（dtb model），被试（subject），及选择的适合的连接信息构成.
- 一个被试表示真实大脑所属的个体，在平台中, 被试用于保存个体信息以及大脑相关的数据等, 如由DTI纤维追踪得到的结构连接矩阵, 来自fMRI的BOLD信号及功能连接, 受体密度分布, 重建的皮层结构等.
- 数字孪生脑模型由图谱（atlas）及节点动力学模型（dynamics model）构成，分别表示大脑的生物分区与各个节点随时间演化的动力学信息.
- 连接信息是数字孪生脑的结构基础, 定义了数字孪生脑中各个脑区之间的连接强度.
#### 创建/选择 项目
工作空间中保存了不同的项目，在创建“数字孪生脑”之前，我们需要先选择一个存放它的项目.
默认的工作空间中已经有了一个示例项目“default”，我们可以选择在它里面进行研究与实验，当然我们也可以[创建属于自己的研究项目（详见示例）.](#EYdSb)
#### 创建/查看 被试
被试指真实大脑所属的个体. 在ZJB平台中, 被试用于保存个体信息以及大脑相关的数据等, 如由DTI纤维追踪得到的结构连接矩阵, 来自fMRI的BOLD信号及功能连接, 受体密度分布, 重建的皮层结构等.
在研究中，往往需要向项目中导入一个或多个被试。默认的工作空间中已经有了一些示例被试，我们可以查看它的信息，当然我们也可以[创建新的被试（详见示例）.](#dGfIz)
平台中，被试页面主要包含以下信息：
- 被试名.
- 被试具体描述.
- 被试中包含的数据，如结构连接、经验功能连接、皮层数据等.
#### 创建/设置 数字孪生脑模型
项目中包含了此项目内所使用到的数字孪生脑模型.
示例的项目中已经有了一个示例数字孪生脑模型“test_model”，是由BNA图谱及动力学模型ReducedWongWangExcInh所构成的，我们可以在它的基础上配置仿真参数信息，当然我们也可以[创建新的数字孪生脑模型（详见示例）.](#Afii4)
平台中，数字孪生脑模型页面主要包含以下部分内容:
- 数字孪生脑模型的名字.
- 数字孪生脑模型所使用的图谱.
- 数字孪生脑模型所使用的动力学模型.
- 数字孪生脑模型的动力学信息，包括变量、参数等，我们可以在此设置变量初值及非默认的动力学参数. 进一步地，我们也可以设置脑区异质性的参数或使用与被试数据关联的参数，同时，我们也可以在这里[对数字孪生脑模型设置刺激（详见示例）.](#DYEut)
- 仿真配置信息
- 我们可以选择不同的微分方程求解器类型，并设置噪声，默认会使用时间步长为0.1(单位取决于动力学模型本身)的欧拉法求解器.
- 添加一个或多个监测器，并设置所观测物理量. 其中`Raw`监测器在每一个时间步进行采样后输出结果; `SubSample`监测器在固定间隔的时间步离散采样并输出结果; `TemporalAverage`在固定间隔的时间步内连续采样并将间隔内的结果平均后输出; `BOLD`监测器在每个时间步进行采样, 将其作为血氧气球模型的输入, 然后在固定间隔的时间步采样血氧气球模型的结果作为输出.
- 设置仿真时长.
#### 创建/使用 数字孪生脑
项目中包含了此项目内所使用到的数字孪生脑.
默认的示例项目中已经有了一个示例数字孪生脑“test_dtb”，是由示例被试“test_sub”、示例数字孪生脑模型“test_model”及结构连接构成。我们可以选择对它进行仿真实验，当然我们也可以[创建新的数字孪生脑（详见示例）.](#NjbsX)
平台中，数字孪生脑页面主要包含以下部分内容：
- 数字孪生脑名字.
- 数字孪生脑所包含的被试、数字孪生脑模型及连接信息.
- 仿真、仿真参数探索（PSE）功能按钮.
- 数字孪生脑中包含的仿真结果数据. 此处，示例数字孪生脑中已经包含了一个基础仿真结果及PSE仿真结果，我们可以查看仿真结果并进行分析.
运行基本的数字孪生脑仿真：
- 点击数字孪生脑页面中的“Simulate”按钮，并对此次仿真进行命名。
- 点击"ADD"按钮，添加监控动态参数（可选）。
- 点击“OK”按钮，执行仿真.
运行仿真参数探索：
- 点击数字孪生脑页面中的“PSE”按钮，并对此次参数探索进行命名. 点击“ADD”按钮并添加所要探索的参数及范围，更多参数输入格式可参考[高效便捷的参数输入（详见示例）](#T07PZ)：
- 点击"OK"按钮，执行仿真
至此，一个具有真实大脑结构约束和ReducedWongWangExcInh动力学的数字孪生脑便已经仿真得到了数字孪生脑的模拟活动.
### 查看/分析 仿真结果
数字孪生脑仿真任务（包括参数探索仿真）的结果会被存放在所仿真的数字孪生脑中，点击仿真结果即可对其中的仿真结果进行可视化或分析：
#### 查看仿真结果
- 点击"Visualization"，进行仿真结果时间序列的可视化页面.
- 此页面展示了时间序列的可视化. 左侧表明大脑皮层不同区域中特定时间活动强度，右侧为所选脑区时间序列的平铺展示. 其中，点击按钮可启动动态时间序列可视化，并通过速度轴改变时间遍历的速度，也可以点击下方时间轴定位到具体时刻的活动水平. 也可以在上方改变展示的ColorBar.
#### 分析仿真结果
- 点击“Analysis”，进行仿真结果的分析. 面板中包含现有对该仿真进行过的分析，点击可对现有分析进行查看，面板中也包含创建新的分析"New Analysis"按钮，点击可创建对该仿真数据新的分析.
- 点击"New Analysis"按钮，进入"新分析"页面.
- 分析页中包含了被分析对象的简要属性信息
- 点击添加新的分析步骤（可多次添加多个分析），选择分析方法，如此处我们使用自相关的方法对仿真结果的时间序列提取连接信息点击“Run Analysis”执行分析：
- 此处，我们得到了相应的连接矩阵，点击“Advanced Visualization”进入连接矩阵的可视化界面，其关联图谱为被分析数据所在的空间所绑定的图谱.
选择不同的脑区后，可展示所选脑区间的相关性矩阵，同时也会展示其中权重前25的弦图.
- 回到分析结果，点击"Save analysis result"将分析的结果保存到用户指定的dtb或subject中，并对分析结果进行命名.
- 多实体分析. 有的分析方法需要引入多个数据，比如对两组数据进行相关性分析时，我们选择“pearson_correlation”：
此时我们可以看到需要选择两组数据，默认为目前的待分析数据. 比如此时我们想计算当前数据与另一个时间序列的相关性，我们便需要导入一个新的数据，如选择此处array_2的Load按钮
所弹出的数据选择对话框需要我们从中一层一层地选取所期望的数据，并进行选择，如此我们便完成了多实体分析下的数据选择，其余流程则和常规分析一致
#### 查看分析结果
在数据中，点击“Analysis”，进行仿真结果的分析. 面板中包含现有对该仿真进行过的分析，点击可对该数据已有的分析进行查看，如上文中我们已经对仿真的时间序列结果提取了仿真的功能连接，此处展示如何对它查看并进行后续分析
- 此处，我们可以对该分析结果进行查看，包含该分析结果的“源信息”（即是由哪一个或哪几个实体所进行的分析）
- 同时，我们可以对此结果进行进一步的分析，添加一个分析并选择皮尔森相关性分析，此处矩阵默认为该分析结果本身，如果我们不读取新的数据直接进行分析，其结果为1。
# 示例
## 创建一个新的研究项目
在平台中，有以下两个方式可以创建一个新的研究项目：
- 点击上方菜单中"New"按钮，选择新建"Project".
命名并选择项目挂载的“工作空间”及“项目”即可. 这样的设计在于，实践中在项目里往往存在不同的子项目，因此平台设计了项目的附属机制.
- 另一个创建研究项目的方法是直接在工作空间目录中，在期望的工作空间/项目名上点击右键，选择新增项目.
## 创建新的被试
与研究项目的创建类似，我们可以通过点击"New Subject"进入被试的创建页面。
命名并选择被试挂载的项目
在被试页面中，可以导入相关的数据
## 创建新的数字孪生脑模型
类似地，我们可以在 工作空间/项目 中创建一个新的“DTB Model”，并设置相应的信息. 数字孪生脑模型由图谱及动力学模型构成，因此我们需要选择研究所要用到的图谱及动力学模型.
随后可以在数字孪生脑模型中修改相关的参数信息
## 创建数字孪生脑
类似地，我们可以在 工作空间/项目 中创建一个新的“DTB”，并设置相应的信息. 数字孪生脑由数字孪生脑、被试、被试数据中的连接信息构成，选择合适的信息来创建一个数字孪生脑.
 
## 在数字孪生脑仿真中施加刺激
在数字孪生脑模型页面中，我们可以对他的参数值支持设置为刺激实例，从而实现数字孪生脑仿真中的刺激功能。
首先，我们需要在数字孪生脑模型页面中的参数部分点击“+Add stimulation”按钮，并进行一些设置：
- 点击按钮，呼出刺激的设置窗口
- 在添加刺激的设置窗口中，选择期望施加刺激的类型以及对应的参数，目前我们内置了高斯刺激、单脉冲刺激、正弦刺激及N周期脉冲刺激，对应的参数分别有幅值、频率、起止点、循环周期次数（0为无限循环）等
 
- Space区域表示可以施加脑区异质性刺激，这是一个很有用的功能，我们点击右侧的“+”号，可以进入脑区异质性的刺激编辑页面。在异质性刺激编辑页面中，在脑区列表中进行选择，或在三维大脑中进行点击选取想要添加刺激的脑区，在右侧列表中进行刺激强度的输入，其中刺激强度可以输入-1到1的数值，结合之前设置窗口中的幅值会为脑区施加相应强度的刺激，最后点击“Create”按钮即可创建脑区异质性的刺激模板，显示在刺激设置面板的“Space”中
- 最后，选择合适的参数予以施加刺激，点击确认，便能将刺激的实例赋给对应参数。
- 如果需要删除该参数下的刺激，只需要在输入框中删除该实体，并设定固定值或初始值即可
最后，让我们看一下添加刺激后的数字孪生脑仿真结果：
动态三维时间序列和二维时间序列都表明，对相关脑区施加刺激后数字孪生脑发生了对应的活动响应
## 高效便捷的参数输入
参数输入中，如PSE仿真设置中，我们需要对不同的参数进行设置：
- 通常，我们可以用类似列表的方式对参数进行增加
- 当涉及到遍历大量数据时，比如对参数_b_e_进行120~150，间隔为1的参数设置时，便可以使用"linspace"语法
## 选择合适的动力学模型
节点动力学模型是仿真的基础，你需要选择一个合适的模型，并提供合适的参数。
对此，平台提供了动力学模型面板，涵盖了不同的动力学分析功能。节点分析模块中调用了BrainPy的相图分析及分岔分析的算法，我们对平台内的模型及使用平台创建的模型做了自动适配，从而兼容这部分功能.
在平台的左侧边栏中选择动力学模型，上方分别有模型信息、相图分析及分岔分析的功能入口，对于任一模型，我们可以同时打开多个相图分析及分岔分析页，修改其中的参数并对比不同的结果.
- 动力学模型信息展示页中，包含模型的微分方程信息、变量初值、参数值及参考文献
- 相图分析中，
1. 选择想要分析的状态变量，并设置范围与步长.
2. 选择轨迹的初值与执行长度.
3. 执行相图分析，展示相图分析的结果，如果有定点，便会给出定点坐标
- 分岔分析中，
1. 选择状态变量并设置范围.
2. 选择想要进行分岔分析的参数并设置范围与步长.
3. 执行分岔分析，分岔分析的结果会展示在下方，此时拖动图像中的坐标轴进行旋转，从而可以全方位地观察到不同参数下定点的状态.
## 添加新的数据分析方法
数据分析是一个很广泛的功能，不同的数据类型具备非常多的分析方法，研究者对不同的数据往往具有不同的分析需求。可以发现我们并没有在平台中直接纳入非常多的分析方法，与之替代地，我们设计了一套便利的分析框架，使用者可以用非常少量的代码便捷地将所设计的分析方法添加至平台中，并可以自动化地展现在GUI内：
首先，在python环境地程序包目录下找到"zjb"库中分析模块的路径（通常是环境路径+"Lib\site-packages\zjb\main\analysis"）中的custom.py文件，并根据提示及示例编写自己的分析方法
```python
"""
此文件用于使用者添加自己的分析方法
1. 在此文件中以函数的形式编写分析方法，参变量需要包含名称及类型，
如果函数中包含参数，需要提供初始值，GUI中，初始值会以默认值的形式体现，
未提供初始值将会在GUI中以被分析对象的数据属性为初始值，并提供“load”按钮
2. 在同级菜单的“__init__.py”文件中暴露该函数接口即可
"""
import numpy as np
# 以下是示例
def array_sum(
array_1: np.ndarray,
array_2: np.ndarray,
weight_1: float = 0.5,
weight_2: float = 0.5,
):
"""自定义分析示例, 计算两个矩阵加权之和, 默认权重为0.5"""
result = array_1 * weight_1 + array_2 * weight_2
return result
```
其次，在分析模块中的“__init__.py”文件中暴露该函数接口，如：
即可完成对自定义分析方法的添加。
我们来看看GUI中会发生什么：
此时当我们选择一个矩阵数据并进行分析，如某一仿真结果提取的功能连接，在分析方法的选择中便会出现所添加的“array_sun”方法：
其中，权重weight_1及weight_2分别表示了两个相加矩阵的权重，可以进行修改，两个矩阵默认为当前分析数据的data属性，点击“load”可以导入项目中已有数据，比如此处我们导入另一功能连接矩阵并运行分析：
如此便成功实现了自定义分析方法的添加！
## 生成并查看仿真的电生理数据
在分析方法中， 我们内置了基于mne库的仿真电生理信号的方法，其本质为对本平台所仿真的神经活动数据通过mne的mne.simulation.simulate_raw方法，根据提供的前导矩阵等信息仿真用户期望的eeg、meg的传感器空间的数据，并可对所得到的数据进一步地进行可视化等处理.
**生成仿真的电生理数据**
对仿真结果中的时间序列进行分析时，分析方法中，我们选择“create_mne_signals”便能够进行电生理数据的生成流程：
从平台内导入映射数据，并导入本地mne正向解文件（或源空间文件及边界元模型文件）及mne的传感器空间数据文件，设置合适的参数后，便可以执行并生成仿真的电生理数据，仿真的电生理数据可以被保存到数字孪生脑中，并进行进一步的查看。
**查看仿真的电生理数据**
点击数字孪生脑中的仿真电生理数据结果进行查看：
平台集成了4种电生理数据的可视化方法，包括
1. ssp projections：信号空间投影的拓扑图
2. channels series：通道时间序列的可视化
3. sensor locations: 传感器位置分布
4. power spectra：功率谱
可视化中可以很好地实现交互功能，包括
1. 对应点显示信息：
2. 在频谱上点击拖动将弹出所选频率范围的头皮的地形图：
