跳转到主要内容

脑成像数据结构的验证器

项目描述

Node Tests Python tests bids-examples tests CircleCI Codecov DOI

BIDS-Validator

快速入门

  1. 网络版本
    1. 打开 Google ChromeMozilla Firefox(目前唯一支持的浏览器)
    2. 访问 https://bids-standard.github.io/bids-validator/ 并选择包含您的 BIDS 数据集的文件夹。如果验证器似乎运行时间超过几分钟,请打开 开发者工具 并在 https://github.com/bids-standard/bids-validator/issues 报告错误。
  2. 命令行版本
    1. 安装 Node.js(至少版本 18.0.0)
    2. npm 更新到至少版本 7(npm install --global npm@^7
    3. 从终端运行 npm install -g bids-validator
    4. 运行 bids-validator 以开始验证数据集。
  3. Docker
    1. 安装 Docker
    2. 从终端运行 docker run -ti --rm -v /path/to/data:/data:ro bids/validator /data,但将命令中的 /path/to/data 部分替换为您的机器上的路径。
  4. Python库
    1. 安装 Python
    2. 如果尚未安装,请安装 Python 的包管理器 Pip
    3. 从终端运行 pip install bids_validator 以获取 BIDS Validator PyPI 软件包,或使用 conda install bids-validator 安装 Conda 软件包
    4. 打开 Python 终端并输入: python
    5. 导入 BIDS 验证器包 from bids_validator import BIDSValidator
    6. 检查文件是否兼容 BIDS BIDSValidator().is_bids('/relative/path/to/a/bids/file')
    7. 注意,文件路径必须相对于 BIDS 数据集的根目录,并且必须在文件路径前添加一个引导斜杠 /

支持

BIDS 验证器旨在在浏览器和 Node.js 中运行。我们针对 Node.js 的最新长期稳定(LTS)版本和 Chrome 的最新版本提供支持。

还有一个用 Python 编写的辅助函数库,用于与用此语言编写的 BIDS 兼容应用程序一起使用。

请通过 GitHub 问题跟踪器 报告在使用这些支持目标时遇到的问题。如果您在这些支持环境之外遇到问题,并且认为我们应该扩展我们的目标支持,请自由打开一个新的问题,描述问题、支持目标以及为什么需要扩展支持,我们将根据具体情况处理这些问题。

维护者和贡献者

All Contributors

本项目遵循 all-contributors 规范。欢迎任何形式的贡献!

本项目由 @rwblair 维护,许多贡献者如下所示。(emoji key 表示贡献类型)

请参阅 致谢


Adam Li

💻 ⚠️ 📓 🐛

Adam Thomas

📖

Alexander Jones

💻 ⚠️ 🤔

Ben Beasley

📦

Chris Gorgolewski

🐛 💻 🔣 📖 💡 🤔 🚇 🚧 🧑‍🏫 💬 👀 ⚠️ 📢 📓

Chris Holdgraf

💻

Chris Markiewicz

💻 ⚠️ 🤔 🐛 💬 🔧 🚧

David Nishikawa

💻 ⚠️

Dimitri Papadopoulos Orfanos

💻

Duncan Macleod

🚇

Franklin Feingold

📖

Gregory noack

💻 ⚠️

Horea Christian

💻

Jakub Kaczmarzyk

🚇

Joke Durnez

💻

Mainak Jas

💻 ⚠️ 🤔 👀 📓

Marco Castellaro

💻 ⚠️

Max

💻 🐛

Michael Hanke

📖

Mikael Naveau

💻

Nell Hardcastle

💻 🤔 🚇 💬 👀

Nicolas Traut

💻

Parul Sethi

💻 ⚠️

Patricia Clement

💻

Remi Gau

💻 📖 📓

Richard Höchenberger

💻 📓 ⚠️ 🐛

Robert Oostenveld

💻 🤔 🐛 ⚠️

Rohan Goyal

💻

Ross Blair

🚧 🤔 💻 🐛 🚇 📆 💬 👀 🔧 ⚠️

Russ Poldrack

💻 💵 🔍

Soichi Hayashi

🐛

Stefan Appelhoff

🐛 💻 🔣 📖 💡 🤔 🚇 🚧 🧑‍🏫 💬 👀 ⚠️ 📢 📓

Suyash

💻

Taylor Salo

💻

Teal Hobson-Lowther

💻 ⚠️

Travis Riddle

🐛

VisLab

🤔 💻

Wazeer Zulfikar

📖

Yaroslav Halchenko

🤔 💻 📖 📓

constellates

💻 ⚠️

dewarrn1

💻

dkp

💻

goldmund

💻 ⚠️

使用

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/**"]
}

注意,在路径中添加两个星号**会使验证器识别所有要忽略的文件和子目录。

ignorewarnerror接受问题代码或问题键的列表,并更改这些问题的严重性,以便它们要么被忽略,要么报告为警告或错误。您可以在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_THANECHO_TIME_NOT_DEFINED以及ECHO_TIME1-2_NOT_DEFINEDECHO_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验证器目前通过browserifywebpack在浏览器中工作。您可以通过将验证器克隆到项目中并使用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镜像

Docker Image Version (latest by date)

要使用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库

PyPI version Conda version

存在一个有限的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才能编译。

  1. bids-validator的浏览器版本位于仓库子目录 /bids-validator-web 中。它是一个React.js应用程序,使用了next.js框架。
  2. 要开发 bids-validator 并查看它如何在浏览器中运行,只需在项目根目录中运行 npm run web-dev 并导航到 localhost:3000
  3. 在开发模式下,代码库的更改将自动触发应用程序的重新构建。
  4. 代码库中 /bids-validator 的更改也将反映在Web应用程序中。
  5. 测试使用Jest测试库,应在/bids-validator-web/tests目录下开发。我们始终可以使用更多的测试,所以请随意贡献一个可以减少您修复的任何错误的测试!
  6. 为确保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包而无需发布,并在本地安装该包。

  1. npm -w bids-validator run build
  2. npm -w bids-validator pack
  3. npm install -g bids-validator-*.tgz

发布

使用Lerna进行发布。使用命令npx lerna publish并按照说明设置新版本。

使用lerna publish将创建一个带有更新版本信息的git提交,并为它创建一个版本号标签,然后将标签推送到GitHub,然后发布到NPM和PyPI。GitHub发布是手动进行的。

致谢

许多对bids-validator的贡献是由BIDS社区的成员完成的。请参阅贡献者列表

目前,bids-validator的大部分开发工作由Squishymedia完成,他们通过为BIDS的一般发展提供的不同拨款进行融资。请参阅下面的列表。

开发和贡献是通过以下联邦资助的项目/拨款得到支持的

项目详情


发布历史 发布通知 | RSS源

下载文件

下载适合您平台的文件。如果您不确定该选择哪个,请了解有关安装包的更多信息。

源分布

bids_validator-1.14.7.post0.tar.gz (38.9 kB 查看哈希值)

上传时间

构建分布

bids_validator-1.14.7.post0-py3-none-any.whl (23.6 kB 查看哈希值)

上传时间 Python 3

支持者

AWS AWS 云计算和安全赞助商 Datadog Datadog 监控 Fastly Fastly CDN Google Google 下载分析 Microsoft Microsoft PSF 赞助商 Pingdom Pingdom 监控 Sentry Sentry 错误记录 StatusPage StatusPage 状态页面