From 1fa593247209e67ef1bf3aeb4aa0f13493403b1a Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 15 Apr 2024 14:57:54 +0200 Subject: [PATCH 01/14] try read csv plugin --- mkdocs.yml | 2 ++ requirements.txt | 1 + src/longitudinal-and-multi-site-studies.md | 6 +----- src/tables/longitudinal_sessions.tsv | 3 +++ 4 files changed, 7 insertions(+), 5 deletions(-) create mode 100644 src/tables/longitudinal_sessions.tsv diff --git a/mkdocs.yml b/mkdocs.yml index 114e05c135..01800d3d36 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -98,6 +98,8 @@ extra: extra_javascript: - js/jquery-3.6.0.min.js markdown_extensions: + - tables + - table-reader - toc: anchorlink: true - pymdownx.superfences diff --git a/requirements.txt b/requirements.txt index 25f0520a6a..5002319893 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,5 +4,6 @@ pymdown-extensions>=7.0.0 mkdocs-branchcustomization-plugin~=0.1.3 mkdocs-macros-plugin mkdocs-redirects +mkdocs-table-reader-plugin numpy tools/schemacode/[render] diff --git a/src/longitudinal-and-multi-site-studies.md b/src/longitudinal-and-multi-site-studies.md index bf9cb92eec..f5f387b57b 100644 --- a/src/longitudinal-and-multi-site-studies.md +++ b/src/longitudinal-and-multi-site-studies.md @@ -65,11 +65,7 @@ A guide for using macros can be found at `sub-control01_sessions.tsv` content: -```Text -session_id acq_time systolic_blood_pressure -ses-predrug 2009-06-15T13:45:30 120 -ses-postdrug 2009-06-16T13:45:30 100 -``` +{{ read_csv('tables/longitudinal_sessions.tsv') }} See this [example dataset](https://github.com/bids-standard/bids-examples/tree/master/7t_trt) that has been formatted diff --git a/src/tables/longitudinal_sessions.tsv b/src/tables/longitudinal_sessions.tsv new file mode 100644 index 0000000000..506f4633b3 --- /dev/null +++ b/src/tables/longitudinal_sessions.tsv @@ -0,0 +1,3 @@ +session_id acq_time systolic_blood_pressure +ses-predrug 2009-06-15T13:45:30 120 +ses-postdrug 2009-06-16T13:45:30 100 From 93d876aabe6bd573b13c96562ae9d7235c389993 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 15 Apr 2024 15:18:57 +0200 Subject: [PATCH 02/14] fix --- mkdocs.yml | 2 +- src/longitudinal-and-multi-site-studies.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 01800d3d36..3a6c5d9f7d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -99,7 +99,6 @@ extra_javascript: - js/jquery-3.6.0.min.js markdown_extensions: - tables - - table-reader - toc: anchorlink: true - pymdownx.superfences @@ -107,6 +106,7 @@ markdown_extensions: - pymdownx.details plugins: - search + - table-reader - branchcustomization: update_config: - branch: /(?!^master$)/ diff --git a/src/longitudinal-and-multi-site-studies.md b/src/longitudinal-and-multi-site-studies.md index f5f387b57b..feb4743eae 100644 --- a/src/longitudinal-and-multi-site-studies.md +++ b/src/longitudinal-and-multi-site-studies.md @@ -65,7 +65,7 @@ A guide for using macros can be found at `sub-control01_sessions.tsv` content: -{{ read_csv('tables/longitudinal_sessions.tsv') }} +{{ read_table('tables/longitudinal_sessions.tsv', sep = '\t') }} See this [example dataset](https://github.com/bids-standard/bids-examples/tree/master/7t_trt) that has been formatted From 4ea4997a2f2914cf65a9b0716e54c6874564727e Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 15 Apr 2024 17:02:40 +0200 Subject: [PATCH 03/14] deal with agnostic section --- src/common-principles.md | 6 +---- src/modality-agnostic-files.md | 33 +++++------------------ src/tables/agnostic_participants.tsv | 4 +++ src/tables/agnostic_samples.tsv | 6 +++++ src/tables/agnostic_scans.tsv | 5 ++++ src/tables/agnostic_sessions.tsv | 4 +++ src/tables/principles_tabular_example.tsv | 3 +++ 7 files changed, 29 insertions(+), 32 deletions(-) create mode 100644 src/tables/agnostic_participants.tsv create mode 100644 src/tables/agnostic_samples.tsv create mode 100644 src/tables/agnostic_scans.tsv create mode 100644 src/tables/agnostic_sessions.tsv create mode 100644 src/tables/principles_tabular_example.tsv diff --git a/src/common-principles.md b/src/common-principles.md index 461842ddfc..abdae976fb 100644 --- a/src/common-principles.md +++ b/src/common-principles.md @@ -466,11 +466,7 @@ TSV files MUST be in UTF-8 encoding. Example: -```Text -onset duration response_time trial_type trial_extra -200 20.0 15.8 word 中国人 -240 5.0 17.34e-1 visual n/a -``` +{{ read_table('tables/principles_tabular_example.tsv', sep = '\t') }} !!! warning "Attention" diff --git a/src/modality-agnostic-files.md b/src/modality-agnostic-files.md index fb5b04ee3e..0ccd50b056 100644 --- a/src/modality-agnostic-files.md +++ b/src/modality-agnostic-files.md @@ -246,12 +246,8 @@ available"). `participants.tsv` example: -```Text -participant_id age sex handedness group -sub-01 34 M right read -sub-02 12 F right write -sub-03 33 F n/a read -``` +{{ read_table('tables/agnostic_participants.tsv', sep = '\t') }} + It is RECOMMENDED to accompany each `participants.tsv` file with a sidecar `participants.json` file to describe the TSV column names and properties of their values (see also @@ -320,14 +316,8 @@ and a guide for using macros can be found at `samples.tsv` example: -```Text -sample_id participant_id sample_type derived_from -sample-01 sub-01 tissue n/a -sample-02 sub-01 tissue sample-01 -sample-03 sub-01 tissue sample-01 -sample-04 sub-02 tissue n/a -sample-05 sub-02 tissue n/a -``` +{{ read_table('tables/agnostic_samples.tsv', sep = '\t') }} + It is RECOMMENDED to accompany each `samples.tsv` file with a sidecar `samples.json` file to describe the TSV column names and properties of their values @@ -486,13 +476,7 @@ All such included additional fields SHOULD be documented in an accompanying Example `_scans.tsv`: -```Text -filename acq_time -func/sub-control01_task-nback_bold.nii.gz 1877-06-15T13:45:30 -func/sub-control01_task-motor_bold.nii.gz 1877-06-15T13:55:33 -meg/sub-control01_task-rest_split-01_meg.nii.gz 1877-06-15T12:15:27 -meg/sub-control01_task-rest_split-02_meg.nii.gz 1877-06-15T12:15:27 -``` +{{ read_table('tables/agnostic_scans.tsv', sep = '\t') }} ## Sessions file @@ -522,12 +506,7 @@ and a guide for using macros can be found at `_sessions.tsv` example: -```Text -session_id acq_time systolic_blood_pressure -ses-predrug 2009-06-15T13:45:30 120 -ses-postdrug 2009-06-16T13:45:30 100 -ses-followup 2009-06-17T13:45:30 110 -``` +{{ read_table('tables/agnostic_sessions.tsv', sep = '\t') }} ## Code diff --git a/src/tables/agnostic_participants.tsv b/src/tables/agnostic_participants.tsv new file mode 100644 index 0000000000..42a1c5bcd1 --- /dev/null +++ b/src/tables/agnostic_participants.tsv @@ -0,0 +1,4 @@ +participant_id age sex handedness group +sub-01 34 M right read +sub-02 12 F right write +sub-03 33 F n/a read diff --git a/src/tables/agnostic_samples.tsv b/src/tables/agnostic_samples.tsv new file mode 100644 index 0000000000..2bc4173472 --- /dev/null +++ b/src/tables/agnostic_samples.tsv @@ -0,0 +1,6 @@ +sample_id participant_id sample_type derived_from +sample-01 sub-01 tissue n/a +sample-02 sub-01 tissue sample-01 +sample-03 sub-01 tissue sample-01 +sample-04 sub-02 tissue n/a +sample-05 sub-02 tissue n/a diff --git a/src/tables/agnostic_scans.tsv b/src/tables/agnostic_scans.tsv new file mode 100644 index 0000000000..4a4b64067b --- /dev/null +++ b/src/tables/agnostic_scans.tsv @@ -0,0 +1,5 @@ +filename acq_time +func/sub-control01_task-nback_bold.nii.gz 1877-06-15T13:45:30 +func/sub-control01_task-motor_bold.nii.gz 1877-06-15T13:55:33 +meg/sub-control01_task-rest_split-01_meg.nii.gz 1877-06-15T12:15:27 +meg/sub-control01_task-rest_split-02_meg.nii.gz 1877-06-15T12:15:27 diff --git a/src/tables/agnostic_sessions.tsv b/src/tables/agnostic_sessions.tsv new file mode 100644 index 0000000000..9934dc6f3a --- /dev/null +++ b/src/tables/agnostic_sessions.tsv @@ -0,0 +1,4 @@ +session_id acq_time systolic_blood_pressure +ses-predrug 2009-06-15T13:45:30 120 +ses-postdrug 2009-06-16T13:45:30 100 +ses-followup 2009-06-17T13:45:30 110 diff --git a/src/tables/principles_tabular_example.tsv b/src/tables/principles_tabular_example.tsv new file mode 100644 index 0000000000..5a7f276de3 --- /dev/null +++ b/src/tables/principles_tabular_example.tsv @@ -0,0 +1,3 @@ +onset duration response_time trial_type trial_extra +200 20.0 15.8 word 中国人 +240 5.0 17.34e-1 visual n/a From 93a33e12ec7d474f57334a714c1dc19f971fe68e Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 15 Apr 2024 17:25:40 +0200 Subject: [PATCH 04/14] asl appendix --- src/appendices/arterial-spin-labeling.md | 21 +++------------------ src/appendices/qmri.md | 4 ++-- src/tables/asl_context_case_1.tsv | 6 ++++++ src/tables/asl_context_case_2.tsv | 3 +++ src/tables/asl_context_case_3.tsv | 3 +++ 5 files changed, 17 insertions(+), 20 deletions(-) create mode 100644 src/tables/asl_context_case_1.tsv create mode 100644 src/tables/asl_context_case_2.tsv create mode 100644 src/tables/asl_context_case_3.tsv diff --git a/src/appendices/arterial-spin-labeling.md b/src/appendices/arterial-spin-labeling.md index 4d1253eaab..d56178f010 100644 --- a/src/appendices/arterial-spin-labeling.md +++ b/src/appendices/arterial-spin-labeling.md @@ -26,14 +26,7 @@ and the exact volume_type series should be specified in the `*_aslcontext.tsv`. Example of `*_aslcontext.tsv`: -```Text -volume_type -control -label -control -label -m0scan -``` +{{ read_table('tables/asl_context_case_1.tsv', sep = '\t') }} ### Case 2: `*_asl.nii[.gz]` consists of volume_types `deltam` (scanner does not export `control` or `label` volumes) @@ -44,11 +37,7 @@ In this case, the `deltam` should be included in the `*_asl.nii[.gz]` and specif Example of `*_aslcontext.tsv`: -```Text -volume_type -deltam -m0scan -``` +{{ read_table('tables/asl_context_case_2.tsv', sep = '\t') }} ### Case 3: `*_asl.nii[.gz]` consists of volume_type `cbf` (scanner does not export `control`, `label`, or `deltaM` volumes) @@ -58,11 +47,7 @@ the `cbf` should be included in the `*_asl.nii[.gz]` and specified in the `*_asl Example of `*_aslcontext.tsv`: -```Text -volume_type -cbf -m0scan -``` +{{ read_table('tables/asl_context_case_3.tsv', sep = '\t') }} ## Summary Image of the most common ASL sequences diff --git a/src/appendices/qmri.md b/src/appendices/qmri.md index 162ba798cd..3bd2e56b6a 100644 --- a/src/appendices/qmri.md +++ b/src/appendices/qmri.md @@ -326,7 +326,7 @@ A guide for using macros can be found at `dataset_description.json`: -```text +```json { "Name": "qMRLab Outputs", "BIDSVersion": "1.5.0", @@ -395,7 +395,7 @@ sub-01_T1map.json sub-01_T1map.json: -```text +```json { <> diff --git a/src/tables/asl_context_case_1.tsv b/src/tables/asl_context_case_1.tsv new file mode 100644 index 0000000000..ebe0738464 --- /dev/null +++ b/src/tables/asl_context_case_1.tsv @@ -0,0 +1,6 @@ +volume_type +control +label +control +label +m0scan diff --git a/src/tables/asl_context_case_2.tsv b/src/tables/asl_context_case_2.tsv new file mode 100644 index 0000000000..2aefda8324 --- /dev/null +++ b/src/tables/asl_context_case_2.tsv @@ -0,0 +1,3 @@ +volume_type +deltam +m0scan diff --git a/src/tables/asl_context_case_3.tsv b/src/tables/asl_context_case_3.tsv new file mode 100644 index 0000000000..5711779304 --- /dev/null +++ b/src/tables/asl_context_case_3.tsv @@ -0,0 +1,3 @@ +volume_type +cbf +m0scan From 7dd90a605f82c491b809917a8dda9782d88b0df1 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 15 Apr 2024 17:34:55 +0200 Subject: [PATCH 05/14] derivatives --- src/appendices/hed.md | 6 +----- src/derivatives/imaging.md | 14 ++------------ src/tables/derivatives_imaging_dseg_1.tsv | 4 ++++ src/tables/derivatives_imaging_dseg_2.tsv | 4 ++++ src/tables/hed_events.tsv | 3 +++ 5 files changed, 14 insertions(+), 17 deletions(-) create mode 100644 src/tables/derivatives_imaging_dseg_1.tsv create mode 100644 src/tables/derivatives_imaging_dseg_2.tsv create mode 100644 src/tables/hed_events.tsv diff --git a/src/appendices/hed.md b/src/appendices/hed.md index 4582356ee5..fb53e6947d 100644 --- a/src/appendices/hed.md +++ b/src/appendices/hed.md @@ -44,11 +44,7 @@ meanings in associated JSON sidecar files (`events.json`). (`trial_type`, `response_time`, and `stim_file`) in addition to the required `onset` and `duration` columns. -```Text -onset duration trial_type response_time stim_file -1.2 0.6 go 1.435 images/red_square.jpg -5.6 0.6 stop n/a images/blue_square.jpg -``` +{{ read_table('tables/hed_events.tsv', sep = '\t') }} The `trial_type` column in the above example contains a limited number of distinct values (`go` and `stop`). diff --git a/src/derivatives/imaging.md b/src/derivatives/imaging.md index aea21dbaad..4a255093d4 100644 --- a/src/derivatives/imaging.md +++ b/src/derivatives/imaging.md @@ -524,22 +524,12 @@ and a guide for using macros can be found at An example, custom `dseg.tsv` that defines three labels: -```Text -index name abbreviation color mapping -100 Gray Matter GM #ff53bb 1 -101 White Matter WM #2f8bbe 2 -102 Brainstem BS #36de72 11 -``` +{{ read_table('tables/derivatives_imaging_dseg_1.tsv', sep = '\t') }} The following example `dseg.tsv` defines regions that are not part of the standard BIDS labels: -```Text -index name abbreviation -137 pars opercularis IFGop -138 pars triangularis IFGtr -139 pars orbitalis IFGor -``` +{{ read_table('tables/derivatives_imaging_dseg_2.tsv', sep = '\t') }} diff --git a/src/tables/derivatives_imaging_dseg_1.tsv b/src/tables/derivatives_imaging_dseg_1.tsv new file mode 100644 index 0000000000..af65dd5b95 --- /dev/null +++ b/src/tables/derivatives_imaging_dseg_1.tsv @@ -0,0 +1,4 @@ +index name abbreviation color mapping +100 Gray Matter GM #ff53bb 1 +101 White Matter WM #2f8bbe 2 +102 Brainstem BS #36de72 11 diff --git a/src/tables/derivatives_imaging_dseg_2.tsv b/src/tables/derivatives_imaging_dseg_2.tsv new file mode 100644 index 0000000000..7c3b067465 --- /dev/null +++ b/src/tables/derivatives_imaging_dseg_2.tsv @@ -0,0 +1,4 @@ +index name abbreviation +137 pars opercularis IFGop +138 pars triangularis IFGtr +139 pars orbitalis IFGor diff --git a/src/tables/hed_events.tsv b/src/tables/hed_events.tsv new file mode 100644 index 0000000000..65a732e38e --- /dev/null +++ b/src/tables/hed_events.tsv @@ -0,0 +1,3 @@ +onset duration trial_type response_time stim_file +1.2 0.6 go 1.435 images/red_square.jpg +5.6 0.6 stop n/a images/blue_square.jpg From dc571caab335681026df21bee85e273a374db29d Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 15 Apr 2024 17:48:33 +0200 Subject: [PATCH 06/14] eeg and beh --- .../behavioral-experiments.md | 6 +----- .../electroencephalography.md | 19 ++----------------- src/tables/behavioral_beh.tsv | 3 +++ src/tables/eeg_channels.tsv | 5 +++++ src/tables/eeg_electrodes.tsv | 8 ++++++++ 5 files changed, 19 insertions(+), 22 deletions(-) create mode 100644 src/tables/behavioral_beh.tsv create mode 100644 src/tables/eeg_channels.tsv create mode 100644 src/tables/eeg_electrodes.tsv diff --git a/src/modality-specific-files/behavioral-experiments.md b/src/modality-specific-files/behavioral-experiments.md index aa17cc3757..6ceb581802 100644 --- a/src/modality-specific-files/behavioral-experiments.md +++ b/src/modality-specific-files/behavioral-experiments.md @@ -59,11 +59,7 @@ A guide for using macros can be found at ## Example `_beh.tsv` -```Text -trial response response_time stim_file -congruent red 1.435 images/word-red_color-red.jpg -incongruent red 1.739 images/word-red_color-blue.jpg -``` +{{ read_table('tables/behavioral_beh.tsv', sep = '\t') }} In the accompanying JSON sidecar, the `trial` column might be documented as follows: diff --git a/src/modality-specific-files/electroencephalography.md b/src/modality-specific-files/electroencephalography.md index 6ba02cc13a..888517904d 100644 --- a/src/modality-specific-files/electroencephalography.md +++ b/src/modality-specific-files/electroencephalography.md @@ -274,13 +274,7 @@ Examples of free-form text for field `description` See also the corresponding [`electrodes.tsv` example](#example-electrodestsv). -```Text -name type units description reference status status_description -VEOG VEOG uV left eye VEOG-, VEOG+ good n/a -FDI EMG uV left first dorsal interosseous FDI-, FDI+ good n/a -Cz EEG uV n/a REF bad high frequency noise -UADC001 MISC n/a envelope of audio signal n/a good n/a -``` +{{ read_table('tables/eeg_channels.tsv', sep = '\t') }} ## Electrodes description (`*_electrodes.tsv`) @@ -312,16 +306,7 @@ and a guide for using macros can be found at See also the corresponding [`electrodes.tsv` example](#example-channelstsv). -```Text -name x y z type material -VEOG+ n/a n/a n/a cup Ag/AgCl -VEOG- n/a n/a n/a cup Ag/AgCl -FDI+ n/a n/a n/a cup Ag/AgCl -FDI- n/a n/a n/a cup Ag/AgCl -GND -0.0707 0.0000 -0.0707 clip-on Ag/AgCl -Cz 0.0000 0.0714 0.0699 cup Ag/AgCl -REF -0.0742 -0.0200 -0.0100 cup Ag/AgCl -``` +{{ read_table('tables/eeg_electrodes.tsv', sep = '\t') }} The [`acq-