Brain Imaging Data Structure (BIDS)

Estrutura de Dados de Neuroimagem (BIDS)

Visão Geral

A Estrutura de Dados de Neuroimagem (BIDS) é um padrão comunitário para organizar e descrever conjuntos de dados de neurociência e pesquisa biomédica. Ela define uma convenção consistente de nomenclatura de arquivos, hierarquia de diretórios e esquema de metadados, de modo que os conjuntos de dados sejam imediatamente compreensíveis tanto por humanos quanto por ferramentas de software. O BIDS é regido pela Especificação BIDS (atualmente v1.11.x) e é mantido pela comunidade por meio da organização BIDS-Standard no GitHub.

Embora o BIDS tenha se originado para MRI, ele cresceu muito além da neuroimagem. A especificação agora cobre 11 modalidades que abrangem imagem, eletrofisiologia e dados comportamentais:

• Imagem: MRI (estrutural, funcional, difusão, fieldmap, perfusão/ASL), PET, microscopia
• Eletrofisiologia: EEG, MEG, iEEG (EEG intracraniano), EMG
• Outras: NIRS (espectroscopia de infravermelho próximo), captura de movimento, dados comportamentais (sem imagem), espectroscopia de RM

BEPs ativos estão estendendo ainda mais o BIDS — notavelmente o BEP032 (eletrofisiologia com microeletrodos) adicionará suporte para gravações extracelulares, incluindo sondas Neuropixels, trazendo o BIDS para uma metodologia predominante em pesquisa de neurociência animal (veja também a skill neuropixels-analysis).

A adoção é obrigatória ou fortemente incentivada pelos principais repositórios de dados (OpenNeuro, DANDI), periódicos de destaque (NeuroImage, Human Brain Mapping, Scientific Data) e agências de fomento (NIH, ERC).

O ecossistema Python para BIDS centra-se no PyBIDS (pybids) para consulta e indexação de conjuntos de dados BIDS, e no bids-validator (baseado em Deno, disponível como pacote PyPI bids-validator-deno ou diretamente via Deno) para verificação de conformidade. A conversão de DICOM geralmente é feita com HeuDiConv, dcm2bids ou BIDScoin.

Quando Usar Esta Skill

Aplique esta skill quando:

• Organizar dados brutos de neurociência (imagem, eletrofisiologia, comportamentais) em estruturas de diretórios compatíveis com BIDS
• Consultar um conjunto de dados BIDS existente para encontrar arquivos específicos por sujeito, sessão, tarefa, execução ou modalidade
• Validar um conjunto de dados em relação à especificação BIDS antes de compartilhar ou submeter
• Converter dados DICOM de scanners para o formato BIDS
• Escrever ou editar arquivos de metadados JSON sidecar
• Criar derivados compatíveis com BIDS (dados pré-processados, saídas de análise)
• Configurar um dataset_description.json para um novo conjunto de dados
• Trabalhar com entidades BIDS (sujeito, sessão, tarefa, aquisição, execução, etc.)
• Configurar .bidsignore para excluir arquivos da validação
• Preparar dados para upload para OpenNeuro, DANDI ou outros repositórios que reconhecem BIDS

Instalação

# Biblioteca principal de consulta BIDS
uv pip install pybids

# Validador BIDS (baseado em Deno, instalado via wrapper PyPI)
uv pip install bids-validator-deno
# Alternativa: instalar diretamente via Deno
# deno install -g -A npm:bids-validator

# Conversores DICOM-para-BIDS (instale conforme necessário)
uv pip install heudiconv       # HeuDiConv - conversão DICOM baseada em heurística
uv pip install dcm2bids        # dcm2bids - conversão baseada em arquivo de configuração
# BIDScoin: uv pip install bidscoin

# Complementos úteis
uv pip install nibabel         # E/S de arquivos de neuroimagem NIfTI/outros
uv pip install pydicom         # Leitura de arquivos DICOM (usado por conversores)

Workflows Principais

Doze áreas de workflow, cada uma com código prático, estão documentadas em references/core_workflows.md:

1. Estrutura de diretórios BIDS — o layout obrigatório e onde cada modalidade pertence.
2. dataset_description.json — os campos obrigatórios e como gerá-lo.
3. Consulta com PyBIDS — BIDSLayout, filtros de entidade, metadados sidecar com herança automática e construção de caminhos a partir de entidades.
4. Validação — bids-validator via wrapper PyPI (recomendado), via Deno diretamente, o validador Node legado e uso de .bidsignore para excluir arquivos.
5. Entidades e nomenclatura de arquivos — a ordem das entidades e a gramática de nomenclatura.
6. Conversão DICOM para BIDS — HeuDiConv (incluindo o caminho turnkey ReproIn e a sequência reconhecimento → heurística → conversão) e dcm2bids (baseado em arquivo de configuração).
7. Sidecars de metadados — campos JSON obrigatórios e recomendados por modalidade.
8. Arquivos de eventos — temporização de eventos de tarefa fMRI e convenções de colunas.
9. Arquivo de participantes — participants.tsv e seu dicionário de dados.
10. Derivados — o layout de derivados e seu dataset_description.json.
11. PyBIDS avançado — cache de índice, inclusão de derivados, regressores de confundimento e saída em DataFrame.
12. BIDS-Apps — o padrão de invocação, e fMRIPrep, MRIQC e QSIPrep.

Valide cedo e frequentemente: o PyBIDS valida a estrutura quando indexa um conjunto de dados, portanto, uma falha na indexação geralmente significa um problema de nomenclatura ou metadados, em vez de um bug de código.

Materiais de Referência

Esta skill inclui documentação de referência detalhada:

• bids_schema.json: Esquema BIDS legível por máquina (de https://bids-specification.readthedocs.io/en/stable/schema.json). Esta é a fonte autoritativa para definições de entidades, regras de ordenação, modelos de nomes de arquivo, sufixos permitidos por tipo de dados e requisitos de campos de metadados. Esquemas específicos de BEP estão em https://github.com/bids-standard/bids-schema/tree/main/BEPs.
• beps.yml: Lista atual de todas as Propostas de Extensão BIDS com títulos, líderes, status e links (do bids-website)
• bids_specification.md: Resumo legível por humanos da tabela de entidades, referência de tipos de dados, regras de estrutura de diretórios, espaços de modelo e changelog da especificação
• metadata_fields.md: Campos JSON sidecar obrigatórios e recomendados para cada modalidade BIDS (anat, func, dwi, fmap, eeg, meg, pet, etc.)
• conversion_tools.md: Workflows detalhados para HeuDiConv, dcm2bids e BIDScoin, incluindo exemplos de heurística/configuração e solução de problemas

Atualize esquema e BEPs com: python scripts/update_schema.py

Problemas Comuns e Soluções

1. Validador relata "Não é um conjunto de dados BIDS"

Causa: dataset_description.json ausente na raiz. Correção: Crie o arquivo com no mínimo {"Name": "...", "BIDSVersion": "1.10.0"}.

2. Aviso de sujeitos inconsistentes

Causa: Nem todos os sujeitos têm o mesmo conjunto de arquivos (alguns faltando sessões, execuções, etc.). Correção: Isso é um aviso, não um erro. Use --ignoreSubjectConsistency se intencional. Documente dados ausentes em participants.tsv ou scans.tsv.

3. SliceTiming ausente

Causa: dcm2niix não conseguiu extrair a temporização de slice dos cabeçalhos DICOM. Correção: Determine a ordem dos slices a partir do protocolo de varredura e adicione manualmente ao sidecar JSON. Padrões comuns: ascendente, descendente, intercalado (ímpar primeiro ou par primeiro).

4. Confusão na direção de codificação de fase

Causa: Rótulos de eixo (i/j/k vs x/y/z vs LR/AP/SI) são confusos. Correção: No BIDS, use eixos de imagem NIfTI: i=primeiro eixo, j=segundo, k=terceiro. - significa direção negativa. Para aquisições axiais padrão: j é tipicamente anteroposterior. Verifique com o protocolo de aquisição.

5. PyBIDS lento em grandes conjuntos de dados

Causa: Indexação completa do sistema de arquivos a cada chamada BIDSLayout(). Correção: Use database_path para armazenar em cache o índice em um arquivo SQLite:

layout = BIDSLayout("/data", database_path="/data/.pybids_cache.db")

6. Derivados não encontrados pelo PyBIDS

Causa: Diretório de derivados sem seu próprio dataset_description.json. Correção: Todo diretório de derivados deve ter dataset_description.json com "DatasetType": "derivative".

7. Temporização do arquivo de eventos incorreta

Causa: Os tempos onset são relativos à referência errada (por exemplo, tempo de trigger vs primeiro volume). Correção: Os onsets devem estar em segundos relativos ao primeiro volume daquela execução da aquisição. Considere varreduras dummy se foram descartadas.

8. Arquivos TSV falham na validação

Causa: Problemas de codificação ou delimitador (espaços em vez de tabulações, caracteres BOM, finais de linha do Windows). Correção: Garanta valores separados por tabulação com codificação UTF-8 e finais de linha Unix (\n). Use n/a (não NA, NaN ou vazio) para valores ausentes.

Melhores Práticas

1. Valide cedo e frequentemente — Execute o validador BIDS após cada conversão ou modificação. Corrija erros antes que se acumulem.

2. Use herança de metadados — Coloque metadados compartilhados (por exemplo, TaskName, parâmetros do scanner) em arquivos sidecar de nível superior, em vez de duplicar no diretório de cada sujeito.

3. Mantenha dados de origem — Armazene os dados DICOM (ou outros brutos) originais em sourcedata/ para que as conversões sejam reproduzíveis. Adicione sourcedata/ ao .bidsignore.

4. Use nomenclatura consistente desde o início — Defina seu esquema de nomenclatura BIDS antes da coleta de dados. Use a convenção de nomenclatura ReproIn para protocolos de varredura para permitir conversão automática.

5. Documente seu conjunto de dados — Escreva um README completo descrevendo o desenho do estudo, parâmetros de aquisição, problemas conhecidos e quaisquer desvios do BIDS.

6. Use scans.tsv para metadados no nível de execução — Registre tempos de aquisição por execução e notas de qualidade:

   filename	acq_time	quality
   func/sub-01_task-rest_bold.nii.gz	2025-01-15T10:30:00	good
   

7. Versionamento do conjunto de dados — Use CHANGES para documentar modificações. Considere o DataLad para controle de versão completo de conjuntos de dados grandes.

8. Desfaceie imagens anatômicas — Remova características faciais de imagens T1w/T2w antes de compartilhar (por exemplo, usando pydeface, mri_deface ou afni_refacer). Armazene versões desfaceadas como dados primários ou use arquivos _defacemask.

9. Use URIs BIDS para proveniência — Em derivados, referencie arquivos de origem usando URIs BIDS: bids::sub-01/anat/sub-01_T1w.nii.gz.

10. Prefira ferramentas comunitárias — Use BIDS-Apps estabelecidos (fMRIPrep, MRIQC, QSIPrep) em vez de pipelines personalizados quando possível. Eles manipulam corretamente E/S BIDS e produzem derivados compatíveis com BIDS.

11. Estude bids-examples — O repositório bids-examples é a coleção canônica de conjuntos de dados BIDS prototípicos cobrindo diferentes modalidades e casos de uso (MRI, fMRI, DWI, EEG, MEG, iEEG, PET, ASL, genética, derivados e muito mais). Use-o como referência ao estruturar seu próprio conjunto de dados, como dados de teste para ferramentas BIDS ou para entender como uma modalidade específica deve ser organizada. Cada exemplo passa pelo validador BIDS.

Propostas de Extensão BIDS (BEPs)

BEPs são propostas orientadas pela comunidade para estender o BIDS a novas modalidades, derivados ou metadados. A lista completa com status, líderes e links está em references/beps.yml (buscada do bids-website). Visualizações de esquema específicas de BEP são renderizadas em https://github.com/bids-standard/bids-schema/tree/main/BEPs.

BEPs atuais (a partir da atualização do esquema):

BEP	Título	Conteúdo	Status
004	Imagem ponderada por susceptibilidade	raw	Procurando novo líder
011	Derivados de pré-processamento estrutural	derivative	Tem PR (#518)
012	Derivados de pré-processamento funcional	derivative	Tem PR (#519), esquema implementado
014	Transformações afins e deformações de campo não lineares	derivative	Desenvolvimento do formato X5
016	Derivados de imagem ponderada por difusão	derivative	Tem PR (#2211)
017	Esquema genérico de dados de conectividade BIDS	derivative	Em desenvolvimento
021	Derivados eletrofisiológicos comuns	derivative	Em desenvolvimento
023	Derivados de pré-processamento PET	derivative	Em desenvolvimento
024	Tomografia computadorizada	raw	Procurando contribuidores
026	Gravações com microeletrodos	raw	Procurando novo líder
028	Proveniência	metadata	Tem PR (#2099)
032	Eletrofisiologia com microeletrodos	raw	Tem PR (#2307), visualização disponível — cobre Neuropixels e outras sondas extracelulares; relacionado à skill neuropixels-analysis
033	Imagem ponderada por difusão avançada	raw	Procurando contribuidores
034	Modelagem computacional	derivative	Tem PR (#967)
035	Megaanálises com derivados não conformes	derivative	Em desenvolvimento
036	Diretrizes de dados fenotípicos	raw	Revisão comunitária
037	Estimulação cerebral não invasiva	raw	Em desenvolvimento
039	Redes baseadas em redução de dimensionalidade	raw	Em desenvolvimento
040	Ultrassom funcional	raw	Em desenvolvimento
041	Derivados de modelos estatísticos	derivative	Coletando feedback
043	Mapeamento de termos BIDS	metadata	Coletando feedback
044	Estímulos	raw	Tem PR (#2022), revisão comunitária
045	Gravações fisiológicas periféricas	raw	Tem PR (#2267)
046	Tratografia de difusão	derivative	Em desenvolvimento
047	Gravações de áudio/vídeo para experimentos comportamentais	raw	Tem PR (#2231)

Padrões relacionados:

• BIDS-Stats Models: Especificação JSON para definir análises de neuroimagem baseadas em GLM
• BIDS-Derivatives (BEP003): Padrão para saídas pré-processadas/de análise (parcialmente mesclado na especificação)

Ecossistema de Ferramentas Relacionadas

Ferramenta	Propósito
fMRIPrep	Pré-processamento de fMRI (produz derivados BIDS)
MRIQC	Controle de qualidade de MRI (produz derivados BIDS)
QSIPrep	Pré-processamento de MRI de difusão
TemplateFlow	Modelos e atlas de neuroimagem com nomenclatura semelhante a BIDS
Fitlins	Implementação de BIDS Stats Models
DataLad	Controle de versão para grandes conjuntos de dados, integra-se com BIDS
OpenNeuro	Repositório gratuito de conjuntos de dados BIDS
DANDI	Arquivo de dados de neurofisiologia (usa BIDS para algumas modalidades)
HeuDiConv	DICOM-para-BIDS com arquivos Python heurísticos
dcm2bids	DICOM-para-BIDS com configuração JSON
BIDScoin	DICOM-para-BIDS com GUI e configuração YAML
nwb2bids	Converter arquivos NWB (Neurodata Without Borders) para BIDS
CuBIDS	Curadoria e harmonização de conjuntos de dados BIDS
bids2table	Indexação tabular eficiente de conjuntos de dados BIDS
bids-examples	Coleção canônica de conjuntos de dados BIDS prototípicos para todas as modalidades