-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathtutorial.html
More file actions
3480 lines (3241 loc) · 176 KB
/
Copy pathtutorial.html
File metadata and controls
3480 lines (3241 loc) · 176 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="The BIDS Manager tutorial. Walk the full GUI and CLI workflow on a real MRI dataset, end to end.">
<title>Tutorial · BIDS Manager</title>
<link rel="icon" type="image/png" href="assets/brand/app-icon-128.png">
<link rel="stylesheet" href="styles.css">
<!-- Privacy-friendly analytics (GoatCounter, no cookies) -->
<script data-goatcounter="https://bids-manager.goatcounter.com/count"
async src="//gc.zgo.at/count.js"></script>
</head>
<body>
<div data-include="header"></div>
<!-- Persistent left-side page TOC, same component as installation.html. -->
<aside class="page-toc" data-toc aria-label="Page navigation">
<button class="page-toc-toggle" type="button"
aria-expanded="false" aria-controls="page-toc-panel"
aria-label="Toggle page navigation">
<span class="toc-bars" aria-hidden="true">
<span></span><span></span><span></span>
</span>
</button>
<nav id="page-toc-panel" class="page-toc-panel" aria-label="Sections">
<span class="page-toc-title">On this page</span>
<a class="page-toc-link" href="#intro">
<span class="page-toc-dot" aria-hidden="true"></span>
Tutorial intro
</a>
<a class="page-toc-link" href="#paths">
<span class="page-toc-dot" aria-hidden="true"></span>
How the tutorials fit
</a>
<a class="page-toc-link" href="#need">
<span class="page-toc-dot" aria-hidden="true"></span>
What you'll need
</a>
<a class="page-toc-link" href="#workflow">
<span class="page-toc-dot" aria-hidden="true"></span>
Workflow at a glance
</a>
<a class="page-toc-link" href="#datasets">
<span class="page-toc-dot" aria-hidden="true"></span>
Pick a dataset
</a>
<a class="page-toc-link" href="#gui-tour">
<span class="page-toc-dot" aria-hidden="true"></span>
GUI tour
</a>
<a class="page-toc-link" href="#settings-first">
<span class="page-toc-dot" aria-hidden="true"></span>
Settings worth a look
</a>
<div class="page-toc-group" data-toc-group>
<div class="page-toc-group-head">
<a class="page-toc-link" href="#gui-walkthrough">
<span class="page-toc-dot" aria-hidden="true"></span>
GUI walkthrough
</a>
<button class="page-toc-caret" type="button"
aria-expanded="false" aria-controls="toc-steps"
aria-label="Show the seventeen steps">
<span aria-hidden="true">›</span>
</button>
</div>
<div class="page-toc-sublist" id="toc-steps" hidden>
<a class="page-toc-link page-toc-sub" href="#step-create">
<span class="page-toc-dot" aria-hidden="true"></span>
1. Create a project
</a>
<a class="page-toc-link page-toc-sub" href="#step-raw">
<span class="page-toc-dot" aria-hidden="true"></span>
2. Point at raw data
</a>
<a class="page-toc-link page-toc-sub" href="#step-scan">
<span class="page-toc-dot" aria-hidden="true"></span>
3. Run a scan
</a>
<a class="page-toc-link page-toc-sub" href="#step-inventory">
<span class="page-toc-dot" aria-hidden="true"></span>
4. Read the inventory
</a>
<a class="page-toc-link page-toc-sub" href="#step-curate">
<span class="page-toc-dot" aria-hidden="true"></span>
5. Curate the rows
</a>
<a class="page-toc-link page-toc-sub" href="#step-collisions">
<span class="page-toc-dot" aria-hidden="true"></span>
6. Resolve duplicate names
</a>
<a class="page-toc-link page-toc-sub" href="#step-template">
<span class="page-toc-dot" aria-hidden="true"></span>
7. Fill the template
</a>
<a class="page-toc-link page-toc-sub" href="#step-overrides">
<span class="page-toc-dot" aria-hidden="true"></span>
8. Per-recording overrides
</a>
<a class="page-toc-link page-toc-sub" href="#step-companions">
<span class="page-toc-dot" aria-hidden="true"></span>
9. Companions and blood
</a>
<a class="page-toc-link page-toc-sub" href="#step-preview">
<span class="page-toc-dot" aria-hidden="true"></span>
10. Preview the BIDS tree
</a>
<a class="page-toc-link page-toc-sub" href="#step-convert">
<span class="page-toc-dot" aria-hidden="true"></span>
11. Run the conversion
</a>
<a class="page-toc-link page-toc-sub" href="#step-report">
<span class="page-toc-dot" aria-hidden="true"></span>
12. Read the report
</a>
<a class="page-toc-link page-toc-sub" href="#step-editor">
<span class="page-toc-dot" aria-hidden="true"></span>
13. Open the Editor
</a>
<a class="page-toc-link page-toc-sub" href="#step-edit-files">
<span class="page-toc-dot" aria-hidden="true"></span>
14. Edit sidecars and tables
</a>
<a class="page-toc-link page-toc-sub" href="#step-viewers">
<span class="page-toc-dot" aria-hidden="true"></span>
15. Images and signals
</a>
<a class="page-toc-link page-toc-sub" href="#step-validate">
<span class="page-toc-dot" aria-hidden="true"></span>
16. Validate
</a>
<a class="page-toc-link page-toc-sub" href="#step-restructure">
<span class="page-toc-dot" aria-hidden="true"></span>
17. Correct the shape
</a>
<a class="page-toc-link page-toc-sub" href="#step-finish">
<span class="page-toc-dot" aria-hidden="true"></span>
18. Fix and finish
</a>
</div>
</div>
<a class="page-toc-link" href="#cli-ref">
<span class="page-toc-dot" aria-hidden="true"></span>
CLI reference
</a>
<a class="page-toc-link" href="#cli">
<span class="page-toc-dot" aria-hidden="true"></span>
CLI walkthrough
</a>
</nav>
</aside>
<main>
<!-- ============================================================
Section 1. Intro / hero
============================================================ -->
<section class="section" id="intro">
<div class="container container-narrow prose">
<span class="section-eyebrow">Tutorial</span>
<h1>Walk the BIDS Manager GUI and CLI workflow on real data.</h1>
<p class="lead">
One walkthrough from end to end. Seventeen steps take the GUI from
an empty folder to a validated dataset, scanning, curating,
converting, annotating and checking a real MRI dataset, and the
section after them runs the same workflow from the command line.
Read at your own pace, or download one of the six sample datasets
and follow along on your own machine.
</p>
<div class="callout callout-tip">
<div class="callout-icon" aria-hidden="true">▸</div>
<div>
<strong>What makes BIDS Manager different.</strong>
<p><strong>It looks before it converts.</strong> Other tools ask
you to declare up front what each series is, in a heuristic file
or a configuration. BIDS Manager <em>scans the raw data first</em>
and shows you what is actually there: every series, every entity
guess, every confidence score. The table you edit is the same one
the converter consumes, so what you see is what is written into
your BIDS dataset.</p>
<p><strong>It is a curation and annotation tool, not only a
converter.</strong> Getting the files into the right folders is
the easy half. The hard half is describing them: which run is
which, what the task was, what the reference and the ground were,
how much tracer was injected and when. You get a table to curate,
templates that ask each question once for a whole study,
per-recording overrides for the exceptions, and a record of where
every answer came from.</p>
<p><strong>It refuses to lose your data.</strong> If two recordings
would be written to the same BIDS filename, the conversion stops
and tells you which two files, instead of writing one over the
other.</p>
<p><strong>It tells you what is wrong, and where the rule comes
from.</strong> The validator is part of the same application,
reads the same BIDS schema, and cites the schema rule behind
every finding.</p>
</div>
</div>
</div>
</section>
<!-- ============================================================
Section 1b. How the tutorials fit together
============================================================ -->
<section class="section" id="paths">
<div class="container container-narrow prose">
<div class="section-header">
<span class="section-eyebrow">How the tutorials fit together</span>
<h2 class="section-title">Two ways in, and they do not repeat each other.</h2>
</div>
<div class="path-cards">
<div class="path-card path-card-here">
<span class="path-card-tag">You are here</span>
<h3>GUI and CLI overview</h3>
<p>
The complete workflow, explained once, for any modality. Every
step of the interface in order, then the same work from the
command line, then a reference for every command and flag. Where
a step genuinely differs between modalities it carries a tab.
</p>
<p class="path-card-for">
<strong>Read this</strong> to learn the tool, or to look up what a
control does.
</p>
</div>
<div class="path-card">
<span class="path-card-tag">Six of them</span>
<h3>Full tutorials by modality</h3>
<p>
One dataset, start to finish, with the detail that only applies to
that kind of data: how subjects are worked out, which metadata the
conversion can and cannot answer, what the real numbers are, and
what typically needs fixing afterwards.
</p>
<p class="path-card-for">
<strong>Read one</strong> to convert data of your own, alongside a
dataset you can download and follow exactly.
</p>
<p>
<a href="tutorial-mri.html">MRI</a> ·
<a href="tutorial-mri-advanced.html">MRI, advanced</a> ·
<a href="tutorial-pet.html">PET</a> ·
<a href="tutorial-eeg.html">EEG</a> ·
<a href="tutorial-meg.html">MEG</a> ·
<a href="tutorial-multimodal.html">Multimodal</a>
</p>
</div>
</div>
<p>
There is one more page, and it is a task rather than a route:
<a href="tutorial-deface.html"><strong>defacing and skull
stripping</strong></a>. Read it before an MRI or PET dataset leaves
the people who collected it. It applies whichever route you took,
because a face can be removed during the conversion or at any point
afterwards.
</p>
</div>
</section>
<!-- ============================================================
Section 2. What you'll need
============================================================ -->
<section class="section" id="need">
<div class="container container-narrow">
<div class="section-header">
<span class="section-eyebrow">Step 0</span>
<h2 class="section-title">What you'll need.</h2>
</div>
<ul class="checklist">
<li>
<strong>BIDS Manager installed, and nothing else.</strong> The
one-click bootstrap installer is the quickest path, and
<code class="inline">pip install bids-manager</code> works too.
Either way every conversion engine is installed with it, so there
is no second tool to fetch before you start.
See the <a href="installation.html">installation guide</a>.
</li>
<li>
<strong>One raw dataset.</strong> Either one of the six sample
datasets below, each a small download from the University of
Oldenburg cloud, or your own folder of recordings.
</li>
<li>
<strong>About 30 minutes.</strong> The GUI walkthrough runs
seventeen steps and the command-line section runs five commands.
Both drive the same engine, so the order is up to you.
</li>
</ul>
</div>
</section>
<!-- ============================================================
Section 3. Workflow at a glance
============================================================ -->
<section class="section" id="workflow">
<div class="container container-narrow">
<div class="section-header">
<span class="section-eyebrow">Mental model</span>
<h2 class="section-title">The workflow at a glance.</h2>
<p class="section-lead">
You begin by creating or opening a dataset project (the work
is saved into it and is resumable). From there BIDS Manager
runs in eight stages, alternating user-driven and
engine-driven steps. Every step below mirrors what BIDS
Manager does on disk, using the same engine the CLI exposes.
The full interactive diagram is on the
<a href="about.html#how-it-works">About page</a>.
</p>
</div>
<ol class="workflow-mini">
<li><strong>Raw.</strong> Your input folder, scanned into a project.</li>
<li><strong>Scan.</strong> Read metadata from inside every file.</li>
<li><strong>Curate.</strong> Review every acquisition; filter what shouldn't convert.</li>
<li><strong>Convert.</strong> Run the right backend per modality.</li>
<li><strong>Enrich.</strong> Auto-fill required sidecar fields.</li>
<li><strong>Fix-ups.</strong> Open the Editor and fix anything the enrichment couldn't infer.</li>
<li><strong>Validate.</strong> Audit against the BIDS schema.</li>
<li><strong>BIDS.</strong> A schema-compliant dataset, ready to share.</li>
</ol>
</div>
</section>
<!-- ============================================================
Section 4. Pick a dataset (4 cards)
============================================================ -->
<section class="section" id="datasets">
<div class="container">
<div class="section-header">
<span class="section-eyebrow">Pick a dataset</span>
<h2 class="section-title">Six sample datasets, one workflow.</h2>
<p class="section-lead">
The walkthrough below uses the primary MRI dataset
(<em>Oldenburg neuroimaging unit</em>), but any of the six will
follow the same seventeen steps. Each <em>More info</em> link opens
that dataset's own page, with its folder tree, the real numbers
from a full run, and the quirks specific to that modality. Those
pages are also listed under <em>Tutorials</em> in the site
navigation.
</p>
</div>
<div class="modality-grid">
<!-- MRI primary -->
<article class="modality-card mod-mri">
<span class="modality-badge">MRI</span>
<h3>Primary walkthrough.</h3>
<p class="modality-meta">Oldenburg neuroimaging unit · 3 folders / 2 BIDS subjects · 33 inventory rows.</p>
<p class="modality-desc">
Small Siemens MRI dataset with T1w, T2w, BOLD, DWI,
fmap, and physio. The cleanest end-to-end example,
and the one the GUI walkthrough below uses.
</p>
<div class="modality-actions">
<a class="btn btn-primary" href="https://cloud.uol.de/s/g9gMPpwL7Xg49y9/download" data-goatcounter-click="download-dataset-mri" data-goatcounter-title="MRI sample dataset" target="_blank" rel="noopener">Download ZIP</a>
<a class="btn btn-ghost" href="tutorial-mri.html">More info →</a>
</div>
</article>
<!-- EEG -->
<article class="modality-card mod-eeg">
<span class="modality-badge">EEG</span>
<h3>PhysioNet motor imagery.</h3>
<p class="modality-meta">2 subjects · 14 EDF runs each · 28 inventory rows.</p>
<p class="modality-desc">
Shows the task-name override case: filenames carry
only an opaque run token (S001R01...). The user assigns
the real protocol task names in the interactive table
before any conversion runs.
</p>
<div class="modality-actions">
<a class="btn btn-primary" href="https://cloud.uol.de/s/T66zc5mN4eeZPGK/download" data-goatcounter-click="download-dataset-eeg" data-goatcounter-title="EEG sample dataset" target="_blank" rel="noopener">Download ZIP</a>
<a class="btn btn-ghost" href="tutorial-eeg.html">More info →</a>
</div>
</article>
<!-- PET -->
<article class="modality-card mod-pet">
<span class="modality-badge">PET</span>
<h3>One FDG scan, with its paperwork.</h3>
<p class="modality-meta">35 DICOM files · PMOD blood curves · 959 KB</p>
<p class="modality-desc">
A GE Advance phantom acquisition, the two blood curves drawn
during it, and the operator's dose record. Covers the PET metadata
template, attaching arterial blood to the run it belongs to, and
the nine required fields no scanner writes down.
</p>
<div class="modality-actions">
<a class="btn btn-primary" href="https://cloud.uol.de/s/CGcjfTpxzFWnrdz/download"
data-goatcounter-click="download-dataset-pet"
data-goatcounter-title="PET sample dataset"
target="_blank" rel="noopener">Download</a>
<a class="btn btn-ghost" href="tutorial-pet.html">More info →</a>
</div>
</article>
<!-- Multimodal -->
<article class="modality-card mod-multimodal">
<span class="modality-badge">Multimodal</span>
<h3>One participant, four modalities.</h3>
<p class="modality-meta">MRI, PET, EEG and MEG · 10 inventory rows · 57 MB</p>
<p class="modality-desc">
One visit through four machines, in four file formats. Produces a
single inventory, three conversion engines in one pass, and the
problem that makes multimodal hard: four modalities that disagree
about who was scanned.
</p>
<div class="modality-actions">
<a class="btn btn-primary" href="https://cloud.uol.de/s/o6XCk6zH9DYpoes/download"
data-goatcounter-click="download-dataset-multimodal"
data-goatcounter-title="Multimodal sample dataset"
target="_blank" rel="noopener">Download</a>
<a class="btn btn-ghost" href="tutorial-multimodal.html">More info →</a>
</div>
</article>
<!-- MEG -->
<article class="modality-card mod-meg">
<span class="modality-badge">MEG</span>
<h3>Elekta sample data.</h3>
<p class="modality-meta">2 subjects · 23 FIF files · multi-session inference.</p>
<p class="modality-desc">
Shows automatic session inference from date-named
folders. Tasks parse cleanly (driving, rest,
empty-room). Demonstrates the MEG conversion path
through mne-bids.
</p>
<div class="modality-actions">
<a class="btn btn-primary" href="https://cloud.uol.de/s/btGeke5NNkDcs6G/download" data-goatcounter-click="download-dataset-meg" data-goatcounter-title="MEG sample dataset" target="_blank" rel="noopener">Download ZIP</a>
<a class="btn btn-ghost" href="tutorial-meg.html">More info →</a>
</div>
</article>
<!-- MRI advanced -->
<article class="modality-card mod-mri-adv">
<span class="modality-badge">MRI advanced</span>
<h3>Richer Siemens dataset.</h3>
<p class="modality-meta">3 folders / 2 BIDS subjects · 51 inventory rows · 19 skipped.</p>
<p class="modality-desc">
The deep dive. T1w / T2w / T2starw / FLAIR anatomicals,
BOLD plus SBRef, DWI with FA / colFA / trace / TENSOR
derivatives, fmap pairs, Siemens CMRR physio.
</p>
<div class="modality-actions">
<a class="btn btn-primary" href="https://cloud.uol.de/s/ZxaZCtHJPLjtDbR/download" data-goatcounter-click="download-dataset-mri-advanced" data-goatcounter-title="MRI advanced sample dataset" target="_blank" rel="noopener">Download ZIP</a>
<a class="btn btn-ghost" href="tutorial-mri-advanced.html">More info →</a>
</div>
</article>
</div>
</div>
</section>
<!-- ============================================================
Section 5. GUI tour (annotated screenshots of the real app)
============================================================ -->
<div data-include="tutorial-gui-tour"></div>
<!-- ============================================================
Section 6. Convert a dataset with the GUI, step by step
============================================================ -->
<section class="section" id="gui-walkthrough">
<div class="container container-narrow prose">
<div class="section-header">
<span class="section-eyebrow">GUI walkthrough</span>
<h2 class="section-title">The GUI walkthrough, step by step.</h2>
<p class="section-lead">
Eighteen steps, from an empty window to a validated dataset. The
steps are the same for every modality; where a modality genuinely
differs, the step carries a tab for it. Each step is listed
separately in the page navigation, so you can come back to one of
them without scrolling through the rest.
</p>
</div>
<div class="callout callout-info">
<div class="callout-icon" aria-hidden="true">▸</div>
<div>
<strong>One workflow, whatever you are converting.</strong>
<p>
The examples use the primary MRI dataset, because it exercises
anatomical, functional, diffusion, fieldmap and physiological data
in one small folder. Only the engine behind each row changes:
<code class="inline">dcm2niix</code> for DICOM,
<code class="inline">mne-bids</code> for EEG and MEG
recordings, <code class="inline">pet2bids</code> for PET ECAT and
blood curves, and <code class="inline">bidsphysio</code> for the
physiological signals stored inside Siemens MRI DICOM files. For
per-modality detail see the
<a href="tutorial-mri.html">MRI</a>,
<a href="tutorial-pet.html">PET</a>,
<a href="tutorial-eeg.html">EEG</a>,
<a href="tutorial-meg.html">MEG</a> and
<a href="tutorial-multimodal.html">multimodal</a> pages.
</p>
</div>
</div>
</div>
</section>
<!-- ============================================================
Step 1. Create a project
============================================================ -->
<section class="section" id="step-create">
<div class="container container-narrow prose">
<span class="section-eyebrow">Step 1</span>
<h2>Create a project</h2>
<p>
Everything you do lives inside a <strong>project</strong>. A project
is your dataset folder plus a hidden record of every scan you have
run and every edit you have made, so you can close the application
and pick the work up exactly where you left it.
</p>
<p>
On the <strong>Home</strong> tab choose <strong>Create</strong>, give
the dataset a folder and a name, and BIDS Manager scaffolds
<code class="inline">dataset_description.json</code>, a README and a
<code class="inline">.bidsignore</code> for you. If you have worked
on this dataset before, choose <strong>Open</strong>, or pick it from
the recent list.
</p>
<p>
The name you type here is written into
<code class="inline">dataset_description.json</code> as the dataset
title. If you later change that name, BIDS Manager asks whether you
meant to rename the project folder as well, or to keep the folder
name and use the new one as the dataset title. It does not guess.
</p>
<p><strong>What you should see now:</strong> the Converter tab, with an
empty inventory table and the project name in the header.</p>
<figure class="media-figure">
<video class="feature-video" muted loop playsinline preload="metadata"
aria-label="Creating or opening a dataset project on the Home tab"
data-dark="assets/features/create_or_open_a_new_dataset_project_dark.mp4"
data-light="assets/features/create_or_open_a_new_dataset_project_light.mp4"></video>
<figcaption>
<strong>Create</strong> scaffolds a new BIDS dataset, with
<code class="inline">dataset_description.json</code>, a README and a
<code class="inline">.bidsignore</code>, and starts the project that
records everything you do next. <strong>Open</strong> continues a
project you already started, or adopts a dataset created elsewhere.
From this point the BIDS output is fixed to the project you chose,
so there is no second output path to set and no way to convert into
the wrong folder by mistake.
</figcaption>
</figure>
</div>
</section>
<!-- ============================================================
Step 1b. Settings worth knowing about
============================================================ -->
<section class="section" id="settings-first">
<div class="container container-narrow prose">
<span class="section-eyebrow">Before you scan</span>
<h2>Two settings worth a look first.</h2>
<p>
The defaults are chosen so you can convert a dataset without opening
Settings at all, and most of what is in there can wait. Two things are
worth knowing before you start, because they are easier to set now than
to change later. The gear is in the header.
</p>
<h3>Which version of BIDS you are working to</h3>
<p>
The first tab decides which version of the standard this session works
to, and it reaches everything downstream: the fields the metadata forms
ask for, the entities a filename may carry, the
<code class="inline">BIDSVersion</code> written into
<code class="inline">dataset_description.json</code>, and the rules
validation judges the result by.
</p>
<p>
Leave it on the newest for a new dataset. Change it when you are adding
to a dataset that was built against an older version, so the forms ask
for that version's fields and validation does not report changes the
standard made after your data was collected.
</p>
<figure class="media-figure">
<img class="feature-shot" loading="lazy"
alt="The BIDS version tab of the Settings dialog, with a summary of the selected version"
src="assets/features/settings_bids_version_dark.png"
data-light="assets/features/settings_bids_version_light.png">
<figcaption>
<strong>One choice, applied everywhere.</strong> The summary line
under the dropdown says what the selected version actually contains,
here 16 datatypes, 35 entities and 449 metadata fields, so the choice
is not an abstract number. The command line takes the same choice per
run as <code class="inline">--schema</code>.
</figcaption>
</figure>
<h3>What happens automatically after a conversion</h3>
<p>
The <strong>Convert and post-convert</strong> tab holds the chain that
runs after every conversion: generate the metadata, mark what could not
be filled, validate, and write a report. It is all on by default, which
is why the walkthrough below can go straight from converting to reading
findings without a separate step.
</p>
<p>
The setting in the same tab that matters most is <strong>Existing
subjects</strong>. The default, Skip, keeps what is already in the
dataset and adds only what is new, so re-running a conversion is safe.
The others exist for when you deliberately want to replace something.
</p>
<figure class="media-figure">
<img class="feature-shot" loading="lazy"
alt="The Convert and post-convert tab, showing the conversion defaults and the post-conversion chain"
src="assets/features/settings_convert_tab_dark.png"
data-light="assets/features/settings_convert_tab_light.png">
<figcaption>
<strong>The chain, as a hierarchy.</strong> Each step is a checkbox,
and the indented ones belong to the step above them, so turning off
validation turns off the deep checks and the report with it.
</figcaption>
</figure>
<div class="callout callout-info">
<div class="callout-icon" aria-hidden="true">▸</div>
<div>
<strong>The rest can wait.</strong>
<p>
Scan rules, the validation filters, worker counts and the display
options are all covered in the
<a href="gui-tour.html">GUI tour</a>, tab by tab. Nothing in them
needs setting before a first conversion.
</p>
</div>
</div>
</div>
</section>
<!-- ============================================================
Step 2. Point at your raw data
============================================================ -->
<section class="section" id="step-raw">
<div class="container container-narrow prose">
<span class="section-eyebrow">Step 2</span>
<h2>Point at your raw data</h2>
<p>
Press <strong>Scan</strong> and choose the folder holding your raw
recordings. Point at the <em>top</em> of the tree, not at one
subject. The scanner walks down through everything below it and works
out subjects, sessions and series for itself.
</p>
<p>
You do not have to tell it what is in there, and you do not have to
separate the modalities first. A folder holding MRI DICOM, EEG
recordings and PET data all at once produces a single inventory with
every recording in it.
</p>
<div class="callout callout-info">
<div class="callout-icon" aria-hidden="true">▸</div>
<div>
<strong>Nothing is written yet.</strong>
<p>Scanning only reads. No file is converted, moved, renamed or
written to disk until you press Run conversion in Step 11.</p>
</div>
</div>
<figure class="media-figure">
<video class="feature-video" muted loop playsinline preload="metadata"
aria-label="Choosing the raw data input folder"
data-dark="assets/features/choose_a_raw_data_input_folder_dark.mp4"
data-light="assets/features/choose_a_raw_data_input_folder_light.mp4"></video>
<figcaption>
Choosing the raw input folder. It can hold DICOM directories, EDF,
FIF or BrainVision files, CTF <code class="inline">.ds</code>
folders, ECAT files and physiological logs, in any arrangement. The
<strong>Scan</strong> button enables once the path is valid, and
this is the only path you set: the output was fixed when you opened
the project.
</figcaption>
</figure>
</div>
</section>
<!-- ============================================================
Step 3. Run a scan
============================================================ -->
<section class="section" id="step-scan">
<div class="container container-narrow prose">
<span class="section-eyebrow">Step 3</span>
<h2>Run a scan</h2>
<p>
The scan opens every file it finds and reads the metadata inside it.
Not the filenames: the headers. For DICOM that means the acquisition
parameters, the study and series identifiers, the patient identifiers
used to group subjects, and the timestamps. For EEG and MEG it means
channel counts by type, sampling frequency, duration, and the
recording date used to infer sessions.
</p>
<p>
It then classifies each recording, proposing a datatype and a suffix
with a confidence score, and builds one row per recording.
</p>
<h3>Probe convert, and why to leave it on</h3>
<p>
With <strong>probe convert</strong> enabled, the scan additionally
runs the converter once per series and reads the sidecar it produced.
That is how BIDS Manager knows, before you have typed anything, which
metadata fields the conversion is going to answer by itself. Those
fields are then shown to you as already answered rather than asked
for. It costs some scanning time and saves a great deal of typing.
</p>
<p><strong>What you should see now:</strong> the inventory table filled
with rows, and the chips in the toolbar showing how many are valid,
how many carry warnings, and how many were auto-skipped.</p>
<figure class="media-figure">
<video class="feature-video" muted loop playsinline preload="metadata"
aria-label="Scanning the raw data folder"
data-dark="assets/features/scan_raw_data_dark.mp4"
data-light="assets/features/scan_raw_data_light.mp4"></video>
<figcaption>
A scan of the MRI sample dataset. The status line names the stage it
is in, walking the folder, reading headers, grouping subjects, and
the chips settle on their final counts: 21 recordings to keep and 12
localisers and scanner reports skipped automatically, 33 rows in
total. Because the scanner reads inside the files rather than
trusting their names, mixed subjects, repeated takes and residual
volumes all arrive as separate rows you can see.
</figcaption>
</figure>
<div class="tabs" data-tabs>
<div class="tab-buttons" role="tablist" aria-label="Scan behaviour by modality">
<button class="tab-btn is-active" data-tab="mri"
role="tab" aria-selected="true">MRI</button>
<button class="tab-btn" data-tab="pet"
role="tab" aria-selected="false">PET</button>
<button class="tab-btn" data-tab="eegmeg"
role="tab" aria-selected="false">EEG and MEG</button>
</div>
<div class="tab-panel is-active" data-panel="mri" role="tabpanel">
<p>
DICOM is grouped into series by their identifiers, and subjects
are grouped by the patient identifiers rather than by folder, so
two subjects mixed in one folder appear as two rows. Sessions come
from the study identifiers and dates. Probe convert runs dcm2niix
once per series.
</p>
</div>
<div class="tab-panel" data-panel="pet" role="tabpanel">
<p>
Formats are detected by reading the file rather than its
extension, so an ECAT file renamed by your site is still
recognised by its <code class="inline">MATRIX7x</code> signature.
A PET/CT study converts its PET half and excludes the CT with the
reason shown, because BIDS has no CT datatype. A PET/MR study
converts both halves in one pass.
</p>
</div>
<div class="tab-panel" data-panel="eegmeg" role="tabpanel">
<p>
Every recording is opened and asked the same questions mne-bids
will ask: channel counts by type, sampling frequency, duration and
recording type. Subjects come from path heuristics, and sessions
are inferred from the recording date when the path carries no
session token. A format that cannot be read, such as an ANT
<code class="inline">.cnt</code> without its optional reader,
appears as an excluded row with the reason, rather than
disappearing silently.
</p>
</div>
</div>
</div>
</section>
<!-- ============================================================
Step 4. Read the inventory
============================================================ -->
<section class="section" id="step-inventory">
<div class="container container-narrow prose">
<span class="section-eyebrow">Step 4</span>
<h2>Read the inventory</h2>
<p>
One row per recording, whatever produced it. A PET DICOM series, a
Siemens physiological log, an EEGLAB file and a MEG FIF all arrive in
the same table with the same columns, which is what lets you curate a
multimodal study as one piece of work instead of four.
</p>
<figure class="media-figure">
<img class="feature-shot" loading="lazy"
alt="The inventory table with PET, MRI, physiological, EEG and MEG rows together, each with its format and confidence"
src="assets/features/multimodal_inventory_dark.png"
data-light="assets/features/multimodal_inventory_light.png">
<figcaption>
<strong>Four modalities, one table.</strong> Read down the
<em>format</em> column: DICOM, EEGLAB, FIF. Read down
<em>conf</em> and you can see how the classification was reached:
1.00 where the file format itself settles it, 0.85 where the
converter's own guess agreed with the schema, 0.45 where only the
sequence name suggested it. The low ones are the rows worth reading
before you convert.
</figcaption>
</figure>
<p>
Before changing anything, read what the scan found. These are the
columns that carry the most information.
</p>
<div class="table-wrap">
<table class="data-table">
<thead>
<tr><th>Column</th><th>What it tells you</th></tr>
</thead>
<tbody>
<tr><td>the tick box</td><td>Whether this row will be converted. Untick to leave it out.</td></tr>
<tr><td>the status icon</td><td>Valid, warning, error, skipped, or an object with no image data. Hover it for the reason.</td></tr>
<tr><td><code class="inline">id</code></td><td>The subject label this recording was grouped under.</td></tr>
<tr><td><code class="inline">ses</code></td><td>The session, where there is one.</td></tr>
<tr><td><code class="inline">data</code>, <code class="inline">suffix</code></td><td>The datatype and suffix the classifier decided on.</td></tr>
<tr><td><code class="inline">conf</code></td><td>How sure the classifier is. Low values are worth reading.</td></tr>
<tr><td><code class="inline">origin</code></td><td>The source folder the recording came from.</td></tr>
<tr><td><code class="inline">format</code></td><td>DICOM, ECAT, EDF, FIF and so on, so you can see what came from where.</td></tr>
<tr><td><code class="inline">sequence</code></td><td>The original scanner or file label, kept beside the BIDS name so you can check a classification.</td></tr>
<tr><td><code class="inline">predicted basename</code></td><td>The exact BIDS filename this row will produce.</td></tr>
</tbody>
</table>
</div>
<p>
Those are the columns shown by default. There are around forty in all,
and <em>Manage columns</em> below the table shows, hides and reorders
them; the layout is remembered. Channel counts, sampling rate,
duration, patient details and the proposed-issues text are all there,
hidden until you want them. Each carries a description of what it
holds, so an unfamiliar one can be identified without leaving the
dialog.
</p>
<div class="callout callout-info">
<div class="callout-icon" aria-hidden="true">▸</div>
<div>
<strong>Three headings differ from the column behind them.</strong>
<p>
Most of the table's headings are the name of the TSV column, so
<code class="inline">session</code>,
<code class="inline">datatype</code> and
<code class="inline">modality</code> are what you will find in the
file. Three are not:
<code class="inline">subject</code> is
<code class="inline">participant_id</code>,
<code class="inline">suffix</code> is
<code class="inline">bids_guess_suffix</code>, and
<code class="inline">confidence</code> is
<code class="inline">bids_guess_confidence</code>. It matters when
you open the TSV in a spreadsheet, or read the
<a href="#cli-ref">CLI reference</a>, which names the file's
columns rather than the table's headings.
</p>
</div>
</div>
<figure class="media-figure">
<img class="feature-shot" loading="lazy"
alt="Inventory rows the scan set aside, each carrying the reason in the issues column"
src="assets/features/inventory_skipped_dark.png"
data-light="assets/features/inventory_skipped_light.png">
<figcaption>
<strong>What the scan set aside, and why.</strong> The teal row with
the crossed circle is an object carrying no image data at all. The
dimmed rows are localisers, excluded automatically. The blue-ticked
rows below are keepers. Every row's reason is in the
<code class="inline">issues</code> column, hidden by default and shown
here; hovering a row gives the same text as a tooltip.
</figcaption>
</figure>
<h3>What the row colours mean</h3>
<p>
Rows are tinted so that problems are visible without opening
anything. A <strong>red</strong> row has an error that will stop it
converting or that needs your decision. An <strong>amber</strong> row
carries a warning worth reading. A <strong>dimmed</strong> row is
excluded. A <strong>teal</strong> row with a crossed-circle badge is
an object with no image data inside it, such as a Siemens
<code class="inline">TENSOR</code> map or a scanner report, which
cannot be converted at all and has been excluded with the reason
shown. Hover any row to see why it is marked.
</p>
<figure class="media-figure">
<video class="feature-video" muted loop playsinline preload="metadata"
aria-label="Row colour coding in the inspection table"
data-dark="assets/features/inspection_table_color_coding_seqs_dark.mp4"
data-light="assets/features/inspection_table_color_coding_seqs_light.mp4"></video>
<figcaption>
The inventory, one editable row per recording, tinted by status so
that anything needing attention is visible without opening a file.
The sequence column keeps the original scanner label beside the
predicted BIDS name, which is how you check that a classification is
right. Any cell can be edited by clicking it.
</figcaption>
</figure>
</div>
</section>
<!-- ============================================================
Step 5. Curate: include, exclude, rename
============================================================ -->
<section class="section" id="step-curate">
<div class="container container-narrow prose">
<span class="section-eyebrow">Step 5</span>
<h2>Curate: include, exclude, rename</h2>
<p>
This is the step the rest of the workflow depends on. Everything you
decide here is what gets converted, and nothing is written to disk
until you are finished.
</p>
<h3>Excluding what you do not want</h3>
<p>
The first column of the table is a tick box, and it is the only thing
that decides whether a row becomes a file. Untick anything that should
not be in the dataset: localisers, calibration scans, a run that was
aborted and repeated. The scan already excluded what it could
recognise as unconvertible, but only you know that the second T1w was
the one worth keeping.
</p>
<figure class="media-figure">
<img class="feature-shot" loading="lazy"
alt="The inventory table with five rows ticked and four unticked, the unticked ones dimmed and showing no predicted name"
src="assets/features/inventory_include_dark.png"
data-light="assets/features/inventory_include_light.png">
<figcaption>
<strong>The answer is visible without reading the column.</strong>
A ticked row is bright and shows the name it will be written under.
An unticked one is dimmed and shows no name, because it is not going
to have one. Nothing is deleted and nothing is written: unticking is
a decision you can change until you press Run. The teal row is a
different case again, a DICOM object with no image in it, which the
scan set aside for you and explains on hover.
</figcaption>
</figure>
<p>
You can also work from the <strong>Filter / structure</strong> tree on
the left, which shows the same recordings grouped by subject, session
and datatype. Unticking a folder there unticks everything inside it,
which is how you drop a whole session or a whole datatype without
hunting for its rows in the table. It is one model shown two ways, so
a change in either is a change in both.
</p>
<h3>Editing many rows at once</h3>
<p>
Select several rows and use <strong>Bulk edit</strong> to set the
same value on all of them: a task label across fourteen runs, a
session across a whole subject. This is the fastest way to fix a
systematic naming problem.
</p>
<p>
It also <strong>removes</strong> an entity, and both the set and the
remove are applied <strong>row by row</strong>. Select the whole
study and ask for the acquisition label to go: it comes off the rows
that have one and are allowed to lose it, and the rest are left
alone rather than the edit being refused. A
<code class="inline">_bold</code> keeps its
<code class="inline">task</code> because the schema requires it; an
anatomical row does not have to. The dialog says how many rows it
will touch before you tick anything.
</p>
<figure class="media-figure">
<img class="feature-shot" loading="lazy"
alt="The bulk edit dialog with all 56 rows selected and the acquisition entity set to be removed, taking it off the 6 rows that carry one"
src="assets/features/bulk_edit_entities_dark.png"
data-light="assets/features/bulk_edit_entities_light.png">
<figcaption>
<strong>Every row selected, and only six change.</strong> This is
the whole inventory, fifty-six rows across MRI, PET, EEG and MEG,
with the acquisition label set to go. It comes off the six rows
that carry one and every other row is untouched, and the dialog
says so twice before anything is written: in the count under the
tick and on the button. Removing is not the same as
blanking a cell, which used to leave the entity in the filename.