脑成像数据结构的验证器
项目描述
BIDS-Validator
快速入门
- 网络版本
- 打开 Google Chrome 或 Mozilla Firefox(目前唯一支持的浏览器)
- 访问 https://bids-standard.github.io/bids-validator/ 并选择包含您的 BIDS 数据集的文件夹。如果验证器似乎运行时间超过几分钟,请打开 开发者工具 并在 https://github.com/bids-standard/bids-validator/issues 报告错误。
- 命令行版本
- 安装 Node.js(至少版本 18.0.0)
- 将
npm
更新到至少版本 7(npm install --global npm@^7
) - 从终端运行
npm install -g bids-validator
- 运行
bids-validator
以开始验证数据集。
- Docker
- 安装 Docker
- 从终端运行
docker run -ti --rm -v /path/to/data:/data:ro bids/validator /data
,但将命令中的/path/to/data
部分替换为您的机器上的路径。
- Python库
- 安装 Python
- 如果尚未安装,请安装 Python 的包管理器 Pip。
- 从终端运行
pip install bids_validator
以获取 BIDS Validator PyPI 软件包,或使用conda install bids-validator
安装 Conda 软件包。 - 打开 Python 终端并输入:
python
- 导入 BIDS 验证器包
from bids_validator import BIDSValidator
- 检查文件是否兼容 BIDS
BIDSValidator().is_bids('/relative/path/to/a/bids/file')
- 注意,文件路径必须相对于 BIDS 数据集的根目录,并且必须在文件路径前添加一个引导斜杠
/
。
支持
BIDS 验证器旨在在浏览器和 Node.js 中运行。我们针对 Node.js 的最新长期稳定(LTS)版本和 Chrome 的最新版本提供支持。
还有一个用 Python 编写的辅助函数库,用于与用此语言编写的 BIDS 兼容应用程序一起使用。
请通过 GitHub 问题跟踪器 报告在使用这些支持目标时遇到的问题。如果您在这些支持环境之外遇到问题,并且认为我们应该扩展我们的目标支持,请自由打开一个新的问题,描述问题、支持目标以及为什么需要扩展支持,我们将根据具体情况处理这些问题。
维护者和贡献者
本项目遵循 all-contributors 规范。欢迎任何形式的贡献!
本项目由 @rwblair 维护,许多贡献者如下所示。(emoji key 表示贡献类型)
请参阅 致谢。
使用
API
BIDS Validator有一个主要方法,该方法接受一个目录作为路径(node)或通过文件输入选择目录时给出的对象(browser),一个选项对象和一个回调函数。
可用选项包括
- ignoreWarnings - (布尔值 - 默认为false)
- ignoreNiftiHeaders - (布尔值 - 默认为false)
例如
validate.BIDS(directory, {ignoreWarnings: true}, function (issues, summary) {console.log(issues.errors, issues.warnings);});
如果您想测试单个文件,可以使用我们提供的特定于文件的检查。
- validate.BIDS()
- validate.JSON()
- validate.TSV()
- validate.NIFTI()
此外,您可以使用validate.reformat()
方法,根据新的配置重新格式化存储的错误。
.bidsignore
可选地,您可以在数据集根目录中包含一个.bidsignore
文件。此文件列出模式(与.gitignore语法兼容),定义了应该由验证器忽略的文件。当验证的数据集包含BIDS规范尚未支持的文件类型时,此选项非常有用。
*_not_bids.txt
extra_data/
配置
您可以通过传递带有-c
或--config
标志的json配置文件来配置错误的严重性,或将配置对象定义为在javascript使用期间传递的选项对象。
如果没有指定路径,将使用默认路径.bids-validator-config.json
。您可以将此文件添加到您的数据集中以共享特定于数据集的验证配置。要禁用此行为,请使用--no-config
,并将使用默认配置。
以下概述了基本配置格式。所有配置都是可选的。
{
"ignore": [],
"warn": [],
"error": [],
"ignoredFiles": []
}
ignoredFiles
接受一个要忽略的文件路径或glob模式的列表。例如,我们想忽略/derivatives/
下所有文件和子目录。这与
{
"ignoredFiles": ["/derivatives/**"]
}
注意,在路径中添加两个星号**
会使验证器识别所有要忽略的文件和子目录。
ignore
、warn
和error
接受问题代码或问题键的列表,并更改这些问题的严重性,以便它们要么被忽略,要么报告为警告或错误。您可以在utils/issues/list中找到所有可用问题的列表。
某些问题默认可能被忽略,但可以提升为警告或错误。这些提供了一种检查比BIDS兼容性更具体的一些常见事情的方法。例如,检查T1w模态的存在。如果数据集中没有找到T1W图像,以下将引发错误。
{
"error": ["NO_T1W"]
}
除了问题代码和键之外,这些列表还可以包含具有"and"或"or"属性的对象,这些属性设置为代码或键的数组。这些允许在配置问题时使用一定程度的条件逻辑。例如
{
"ignore": [
{
"and": [
"ECHO_TIME_GREATER_THAN",
"ECHO_TIME_NOT_DEFINED"
]
}
]
}
在上面的示例中,只有当两个问题在验证期间都被触发时,这两个问题才会被忽略。
{
"ignore": [
{
"and": [
"ECHO_TIME_GREATER_THAN",
"ECHO_TIME_NOT_DEFINED"
{
"or": [
"ECHO_TIME1-2_NOT_DEFINED",
"ECHO_TIME_MUST_DEFINE"
]
}
]
}
]
}
在这个例子中,如果验证期间触发ECHO_TIME_GREATER_THAN
、ECHO_TIME_NOT_DEFINED
以及ECHO_TIME1-2_NOT_DEFINED
或ECHO_TIME_MUST_DEFINE
中的任何一个,则忽略列出的这些问题。
"or"数组在最低级别不受支持,因为它不会增加任何功能。例如,以下是不受支持的。
{
"ignore": [
{
"or": [
"ECHO_TIME_GREATER_THAN",
"ECHO_TIME_NOT_DEFINED"
]
}
]
}
因为它在功能上与以下相同
{
"ignore": [
"ECHO_TIME_GREATER_THAN",
"ECHO_TIME_NOT_DEFINED"
]
}
当使用命令行上的bids-validator传递配置时,您可以使用以下样式来忽略空文件错误(99)和无法读取的文件(44)
bids-validator --config.ignore=99 --config.ignore=44 path/to/bids/dir
这种使用方式对您所需的配置有限制,因此对于复杂场景,我们建议用户创建一个专门的配置文件,其内容如上所述。
在浏览器中
BIDS验证器目前通过browserify或webpack在浏览器中工作。您可以通过将验证器克隆到项目中并使用browserify语法const validate = require('bids-validator');
或ES2015 webpack导入import validate from 'bids-validator'
来将其添加到项目中。
在服务器上
BIDS验证器像大多数npm包一样工作。您可以通过运行npm install bids-validator
来安装它。
通过命令行
如果您使用npm install -g bids-validator
全局安装bids validator,您将能够将其用作命令行工具。安装后,您应该能够运行bids-validator /path/to/your/bids/directory
并看到任何验证问题记录到终端。不提供目录路径运行bids-validator
以查看可用选项。
Docker镜像
要使用bids验证器与docker一起使用,您只需在您的系统上安装docker即可。
然后从终端运行
docker run -ti --rm bids/validator --version
以打印docker镜像的版本docker run -ti --rm bids/validator --help
以打印帮助信息docker run -ti --rm -v /path/to/data:/data:ro bids/validator /data
以在您的宿主机上验证数据集/path/to/data
关于这些命令的简要说明请见此处
docker run
是告诉docker运行某个docker镜像的命令,通常形式为docker run <IMAGENAME> <COMMAND>
- 的
-ti
标志表示接受输入并将输出打印到终端 - 的
--rm
标志表示在运行后不保存docker容器的状态 - 的
-v
标志是将您的本地数据添加到docker容器中(绑定挂载)。重要的是,-v
标志后面的输入由三个用冒号分隔的字段组成:- 第一个字段是宿主机上目录的路径:
/path/to/data
- 第二个字段是目录在容器中挂载的路径
- 第三个字段是可选的。在我们的例子中,我们使用
ro
来指定挂载的数据是只读的
- 第一个字段是宿主机上目录的路径:
Python库
存在一个有限的Python编写的辅助函数库。主函数确定文件扩展名是否符合BIDS规范。您可以在库中找到可用的函数及其描述,此处。要安装,运行 pip install -U bids_validator
(需要python和pip)或 conda install bids-validator
(需要conda环境)。
示例
from bids_validator import BIDSValidator
validator = BIDSValidator()
filepaths = ["/sub-01/anat/sub-01_rec-CSD_T1w.nii.gz", "/sub-01/anat/sub-01_acq-23_rec-CSD_T1w.exe"]
for filepath in filepaths:
print(validator.is_bids(filepath)) # will print True, and then False
注意,文件路径必须相对于 BIDS 数据集的根目录,并且必须在文件路径前添加一个引导斜杠 /
。
开发
要本地开发,克隆项目并在项目根目录中运行 npm install
。这将安装外部依赖项。如果您希望全局安装 bids-validator
(以便您可以在其他文件夹中运行它),请使用以下命令全局安装它:cd bids-validator && npm install -g
(对于Windows用户,如果在不同的驱动器上,请添加 /d,例如 cd /d F:\bids-validator && npm install -g
)
有关更多详细信息,请参阅CONTRIBUTING.md
捆绑
bids-validator与esbuild捆绑在一起。在开发过程中,脚本 bids-validator/bin/bids-validator
将在每次运行时自动捆绑项目。要测试不发布构建的构建,请运行 npm -w bids-validator run build
。这将生成包含本地构建的 bids-validator/dist
目录,并且 bids-validator/bin/bids-validator
将使用此构建。要返回每次运行时自动捆绑,请删除dist目录。
在浏览器中本地运行
关于OS X的注意事项,浏览器依赖项需要名为node-gyp的npm包,该包需要安装xcode才能编译。
bids-validator
的浏览器版本位于仓库子目录/bids-validator-web
中。它是一个React.js应用程序,使用了next.js框架。- 要开发
bids-validator
并查看它如何在浏览器中运行,只需在项目根目录中运行npm run web-dev
并导航到localhost:3000
。 - 在开发模式下,代码库的更改将自动触发应用程序的重新构建。
- 代码库中
/bids-validator
的更改也将反映在Web应用程序中。 - 测试使用Jest测试库,应在
/bids-validator-web/tests
目录下开发。我们始终可以使用更多的测试,所以请随意贡献一个可以减少您修复的任何错误的测试! - 为确保Web应用程序在生产中成功编译,请运行
npm run web-export
测试
如果是您第一次运行测试,请先使用命令git submodule update --init --depth 1
来拉取测试示例数据。此仓库包含bids-examples github仓库作为子模块。
要从项目根目录启动测试套件,请运行npm run test
。在更改时运行测试,npm run test -- --watch
非常有用。使用npm run coverage
可以查看覆盖率报告。
要运行检查代码规范的linter,请运行npm run lint
。
从开发分支全局安装
不建议在开发中使用全局安装,因为可能会导致Node.js项目之间的包冲突。如果您确实需要从开发树中全局安装以进行测试,请按照以下步骤生成NPM包而无需发布,并在本地安装该包。
npm -w bids-validator run build
npm -w bids-validator pack
npm install -g bids-validator-*.tgz
发布
使用Lerna进行发布。使用命令npx lerna publish
并按照说明设置新版本。
使用lerna publish将创建一个带有更新版本信息的git提交,并为它创建一个版本号标签,然后将标签推送到GitHub,然后发布到NPM和PyPI。GitHub发布是手动进行的。
致谢
许多对bids-validator
的贡献是由BIDS社区的成员完成的。请参阅贡献者列表。
目前,bids-validator
的大部分开发工作由Squishymedia完成,他们通过为BIDS的一般发展提供的不同拨款进行融资。请参阅下面的列表。
开发和贡献是通过以下联邦资助的项目/拨款得到支持的
项目详情
下载文件
下载适合您平台的文件。如果您不确定该选择哪个,请了解有关安装包的更多信息。
源分布
构建分布
bids_validator-1.14.7.post0.tar.gz 的哈希值
算法 | 哈希摘要 | |
---|---|---|
SHA256 | e6005a500b75f8a961593fb67d46085107dadb116f59a5c3b524aa0697945b66 |
|
MD5 | 2c432444a5cdd0f868bae5898bdc9a5f |
|
BLAKE2b-256 | df9106fcaf0e86a00ff8a01bb7beb63d8d4c9690c2e4ed140589dd1af640550f |
bids_validator-1.14.7.post0-py3-none-any.whl 的哈希值
算法 | 哈希摘要 | |
---|---|---|
SHA256 | a1ee196eae8e5cf3b3fe9fd1985e03997e3e21a40ea3bcb494ff1e0dcec86a89 |
|
MD5 | c81b3c3e21cc3a2845da2da096e2c799 |
|
BLAKE2b-256 | 7cfa67c9788fef9d11c21ea0ea9991a1048b6f48f425a83cef7efd791785df10 |