From 5775de69ed7f04bb2e167d162bfd2201bce065a5 Mon Sep 17 00:00:00 2001 From: Karl-Koschutnig Date: Mon, 20 Apr 2026 20:53:51 +0200 Subject: [PATCH 1/3] [SCHEMA] Support structured survey data as a BIDS modality Add survey as a first-class BIDS datatype with subject- and session-resolved file structure mirroring other modalities. Changes: - objects/suffixes.yaml: add 'survey' suffix - objects/datatypes.yaml: add 'survey' datatype - objects/modalities.yaml: add 'survey' modality - rules/modalities.yaml: map survey modality to survey datatype - rules/files/raw/survey.yaml: filename rules (sub+task required, ses+run optional) - modality-specific-files/survey.md: documentation chapter - mkdocs.yml: add survey chapter to navigation Reference implementation: https://github.com/MRI-Lab-Graz/prism-studio --- mkdocs.yml | 1 + src/modality-specific-files/survey.md | 145 +++++++++++++++++++++++++ src/schema/objects/datatypes.yaml | 6 + src/schema/objects/modalities.yaml | 4 + src/schema/objects/suffixes.yaml | 8 ++ src/schema/rules/files/raw/survey.yaml | 11 ++ src/schema/rules/modalities.yaml | 3 + 7 files changed, 178 insertions(+) create mode 100644 src/modality-specific-files/survey.md create mode 100644 src/schema/rules/files/raw/survey.yaml diff --git a/mkdocs.yml b/mkdocs.yml index c81a99bc26..bcb750c56f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,6 +18,7 @@ nav: - Intracranial Electroencephalography: modality-specific-files/intracranial-electroencephalography.md - Physiological recordings: modality-specific-files/physiological-recordings.md - Behavioral experiments (with no neural recordings): modality-specific-files/behavioral-experiments.md + - Survey data (instrument-based phenotypic): modality-specific-files/survey.md - Genetic Descriptor: modality-specific-files/genetic-descriptor.md - Positron Emission Tomography: modality-specific-files/positron-emission-tomography.md - Microscopy: modality-specific-files/microscopy.md diff --git a/src/modality-specific-files/survey.md b/src/modality-specific-files/survey.md new file mode 100644 index 0000000000..3f5599cf07 --- /dev/null +++ b/src/modality-specific-files/survey.md @@ -0,0 +1,145 @@ +# Survey data (instrument-based phenotypic) + +Survey data files contain responses collected from standardized questionnaires or +assessment instruments. +They are organized in the same subject- and session-resolved directory hierarchy +as other BIDS modalities, with one `.tsv` data file per instrument administration +and a corresponding `.json` sidecar that documents the instrument and its items. + +This representation complements the aggregated `phenotype/` tables described in +[Phenotypic and assessment data](../modality-agnostic-files/phenotypic-and-assessment-data.md). +Aggregated phenotype tables MAY be generated from subject-resolved survey data +and stored under `phenotype/`, +but the subject-resolved structure is the primary canonical form. + + +{{ MACROS___make_filename_template("raw", datatypes=["survey"]) }} + +Survey files MUST be stored in a `survey` subdirectory of the subject (and +optionally session) directory. +The `task` entity identifies the instrument (for example, `task-pss` for the +Perceived Stress Scale). +The `run` entity MAY be used when the same instrument is administered more than +once within a session. + +## Sidecar JSON (`*_survey.json`) + +Each survey `.tsv` file MUST be accompanied by a JSON sidecar with the same +filename stem. +The sidecar documents the instrument-level metadata and the individual items. + +### Instrument metadata + +The following top-level fields describe the survey instrument and its +administration context. + +| Field | Requirement | Description | +| --- | --- | --- | +| `TaskName` | REQUIRED | Short label identifying the instrument as used in this dataset (MUST match the `task` entity value). | +| `OriginalName` | REQUIRED | Full canonical name of the instrument. | +| `StimulusType` | REQUIRED | MUST be `"Questionnaire"`. | +| `FileFormat` | REQUIRED | MUST be `"tsv"`. | +| `Language` | REQUIRED | Language code for the administered version (for example, `"en"`, `"de-AT"`). | +| `Respondent` | REQUIRED | Who provided the responses (`"self"`, `"clinician"`, `"parent"`, or similar). | +| `ShortName` | OPTIONAL | Common abbreviation of the instrument (for example, `"PSS-10"`). | +| `Version` | OPTIONAL | Version or edition of the instrument. | +| `Authors` | OPTIONAL | Array of instrument authors. | +| `DOI` | OPTIONAL | DOI for the instrument or its primary validation paper. | +| `License` | OPTIONAL | License under which the instrument may be used. | +| `Construct` | OPTIONAL | Psychological or clinical construct measured (for example, `"perceived stress"`). | +| `Instructions` | OPTIONAL | Instructions given to the participant. | +| `AdministrationMethod` | OPTIONAL | How the instrument was administered (`"online"`, `"paper"`, `"interview"`, `"phone"`, or `"mixed"`). | +| `SoftwarePlatform` | OPTIONAL | Software used to administer the instrument (for example, `"LimeSurvey"`, `"REDCap"`). | + +### Item-level metadata + +Any top-level key in the sidecar that is not one of the instrument-level fields +listed above is treated as a column-level variable definition (for example, `"Q01"`, +`"item_1"`). + +| Field | Requirement | Description | +| --- | --- | --- | +| `Description` | REQUIRED | The exact text of the question or item. | +| `Levels` | OPTIONAL | Mapping of response values to their labels (for example, `{"0": "Not at all", "4": "Very often"}`). | +| `MinValue` | OPTIONAL | Minimum expected value. | +| `MaxValue` | OPTIONAL | Maximum expected value. | +| `DataType` | OPTIONAL | Expected data type of the column (`"string"`, `"integer"`, or `"float"`). | +| `Units` | OPTIONAL | Units, if applicable. | + +## Example dataset structure + +```text +study/ +├── dataset_description.json +├── participants.tsv +├── sub-01/ +│ ├── ses-baseline/ +│ │ └── survey/ +│ │ ├── sub-01_ses-baseline_task-pss_run-01_survey.tsv +│ │ └── sub-01_ses-baseline_task-pss_run-01_survey.json +│ └── ses-week04/ +│ └── survey/ +│ ├── sub-01_ses-week04_task-pss_run-01_survey.tsv +│ ├── sub-01_ses-week04_task-pss_run-01_survey.json +│ ├── sub-01_ses-week04_task-pss_run-02_survey.tsv +│ └── sub-01_ses-week04_task-pss_run-02_survey.json +└── phenotype/ + └── pss_summary.tsv +``` + +The `phenotype/` entry in this example is an optional aggregated downstream +view of the subject-resolved survey data. + +## Example `*_survey.tsv` + +```tsv +participant_id Q01 Q02 Q03 +sub-01 2 1 3 +``` + +## Example `*_survey.json` + +```json +{ + "TaskName": "pss", + "OriginalName": "Perceived Stress Scale", + "ShortName": "PSS-10", + "StimulusType": "Questionnaire", + "FileFormat": "tsv", + "Language": "en", + "Respondent": "self", + "AdministrationMethod": "online", + "Q01": { + "Description": "In the last month, how often have you been upset because of something that happened unexpectedly?", + "Levels": { + "0": "Never", + "1": "Almost never", + "2": "Sometimes", + "3": "Fairly often", + "4": "Very often" + }, + "MinValue": 0, + "MaxValue": 4, + "DataType": "integer" + }, + "Q02": { + "Description": "In the last month, how often have you felt that you were unable to control the important things in your life?", + "Levels": { + "0": "Never", + "1": "Almost never", + "2": "Sometimes", + "3": "Fairly often", + "4": "Very often" + }, + "MinValue": 0, + "MaxValue": 4, + "DataType": "integer" + } +} +``` diff --git a/src/schema/objects/datatypes.yaml b/src/schema/objects/datatypes.yaml index b3fdc455e3..53200bf84e 100644 --- a/src/schema/objects/datatypes.yaml +++ b/src/schema/objects/datatypes.yaml @@ -76,3 +76,9 @@ nirs: value: nirs display_name: Near-Infrared Spectroscopy description: Near-Infrared Spectroscopy data organized around the SNIRF format +survey: + value: survey + display_name: Survey data + description: | + Structured instrument-based phenotypic data (questionnaires and assessment + instruments) organized in a subject- and session-resolved directory hierarchy. diff --git a/src/schema/objects/modalities.yaml b/src/schema/objects/modalities.yaml index f363180534..fec377bb1d 100644 --- a/src/schema/objects/modalities.yaml +++ b/src/schema/objects/modalities.yaml @@ -42,3 +42,7 @@ nirs: mrs: display_name: Magnetic Resonance Spectroscopy description: Data acquired with MRS. +survey: + display_name: Survey + description: | + Data collected with standardized questionnaires or assessment instruments. diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml index 37cca59edf..138c597666 100644 --- a/src/schema/objects/suffixes.yaml +++ b/src/schema/objects/suffixes.yaml @@ -891,6 +891,14 @@ uCT: display_name: Micro-CT description: | Micro-CT imaging data +survey: + value: survey + display_name: Survey + description: | + Instrument-based phenotypic survey data. + Responses collected from a structured questionnaire or assessment instrument, + organized as subject- and session-resolved tabular data with a corresponding + JSON sidecar. unloc: value: unloc display_name: Unlocalized spectroscopy diff --git a/src/schema/rules/files/raw/survey.yaml b/src/schema/rules/files/raw/survey.yaml new file mode 100644 index 0000000000..18fc8018be --- /dev/null +++ b/src/schema/rules/files/raw/survey.yaml @@ -0,0 +1,11 @@ +--- +# Instrument-based phenotypic survey data +survey: + $ref: meta.templates.raw.task + suffixes: + - survey + extensions: + - .tsv + - .json + datatypes: + - survey diff --git a/src/schema/rules/modalities.yaml b/src/schema/rules/modalities.yaml index 6aa492a8a0..658a735a87 100644 --- a/src/schema/rules/modalities.yaml +++ b/src/schema/rules/modalities.yaml @@ -37,3 +37,6 @@ nirs: mrs: datatypes: - mrs +survey: + datatypes: + - survey From 083c77df3eab1d3b8ad1a3d112e4f3965878bb86 Mon Sep 17 00:00:00 2001 From: Karl-Koschutnig Date: Tue, 21 Apr 2026 07:24:44 +0200 Subject: [PATCH 2/3] [FIX] Update table formatting for survey instrument metadata in documentation --- src/modality-specific-files/survey.md | 50 +++++++++++++-------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/src/modality-specific-files/survey.md b/src/modality-specific-files/survey.md index 3f5599cf07..1bef840a6d 100644 --- a/src/modality-specific-files/survey.md +++ b/src/modality-specific-files/survey.md @@ -39,23 +39,23 @@ The sidecar documents the instrument-level metadata and the individual items. The following top-level fields describe the survey instrument and its administration context. -| Field | Requirement | Description | -| --- | --- | --- | -| `TaskName` | REQUIRED | Short label identifying the instrument as used in this dataset (MUST match the `task` entity value). | -| `OriginalName` | REQUIRED | Full canonical name of the instrument. | -| `StimulusType` | REQUIRED | MUST be `"Questionnaire"`. | -| `FileFormat` | REQUIRED | MUST be `"tsv"`. | -| `Language` | REQUIRED | Language code for the administered version (for example, `"en"`, `"de-AT"`). | -| `Respondent` | REQUIRED | Who provided the responses (`"self"`, `"clinician"`, `"parent"`, or similar). | -| `ShortName` | OPTIONAL | Common abbreviation of the instrument (for example, `"PSS-10"`). | -| `Version` | OPTIONAL | Version or edition of the instrument. | -| `Authors` | OPTIONAL | Array of instrument authors. | -| `DOI` | OPTIONAL | DOI for the instrument or its primary validation paper. | -| `License` | OPTIONAL | License under which the instrument may be used. | -| `Construct` | OPTIONAL | Psychological or clinical construct measured (for example, `"perceived stress"`). | -| `Instructions` | OPTIONAL | Instructions given to the participant. | -| `AdministrationMethod` | OPTIONAL | How the instrument was administered (`"online"`, `"paper"`, `"interview"`, `"phone"`, or `"mixed"`). | -| `SoftwarePlatform` | OPTIONAL | Software used to administer the instrument (for example, `"LimeSurvey"`, `"REDCap"`). | +| Field | Requirement | Description | +| ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------- | +| `TaskName` | REQUIRED | Short label identifying the instrument as used in this dataset (MUST match the `task` entity value). | +| `OriginalName` | REQUIRED | Full canonical name of the instrument. | +| `StimulusType` | REQUIRED | MUST be `"Questionnaire"`. | +| `FileFormat` | REQUIRED | MUST be `"tsv"`. | +| `Language` | REQUIRED | Language code for the administered version (for example, `"en"`, `"de-AT"`). | +| `Respondent` | REQUIRED | Who provided the responses (`"self"`, `"clinician"`, `"parent"`, or similar). | +| `ShortName` | OPTIONAL | Common abbreviation of the instrument (for example, `"PSS-10"`). | +| `Version` | OPTIONAL | Version or edition of the instrument. | +| `Authors` | OPTIONAL | Array of instrument authors. | +| `DOI` | OPTIONAL | DOI for the instrument or its primary validation paper. | +| `License` | OPTIONAL | License under which the instrument may be used. | +| `Construct` | OPTIONAL | Psychological or clinical construct measured (for example, `"perceived stress"`). | +| `Instructions` | OPTIONAL | Instructions given to the participant. | +| `AdministrationMethod` | OPTIONAL | How the instrument was administered (`"online"`, `"paper"`, `"interview"`, `"phone"`, or `"mixed"`). | +| `SoftwarePlatform` | OPTIONAL | Software used to administer the instrument (for example, `"LimeSurvey"`, `"REDCap"`). | ### Item-level metadata @@ -63,14 +63,14 @@ Any top-level key in the sidecar that is not one of the instrument-level fields listed above is treated as a column-level variable definition (for example, `"Q01"`, `"item_1"`). -| Field | Requirement | Description | -| --- | --- | --- | -| `Description` | REQUIRED | The exact text of the question or item. | -| `Levels` | OPTIONAL | Mapping of response values to their labels (for example, `{"0": "Not at all", "4": "Very often"}`). | -| `MinValue` | OPTIONAL | Minimum expected value. | -| `MaxValue` | OPTIONAL | Maximum expected value. | -| `DataType` | OPTIONAL | Expected data type of the column (`"string"`, `"integer"`, or `"float"`). | -| `Units` | OPTIONAL | Units, if applicable. | +| Field | Requirement | Description | +| ------------- | ----------- | --------------------------------------------------------------------------------------------------- | +| `Description` | REQUIRED | The exact text of the question or item. | +| `Levels` | OPTIONAL | Mapping of response values to their labels (for example, `{"0": "Not at all", "4": "Very often"}`). | +| `MinValue` | OPTIONAL | Minimum expected value. | +| `MaxValue` | OPTIONAL | Maximum expected value. | +| `DataType` | OPTIONAL | Expected data type of the column (`"string"`, `"integer"`, or `"float"`). | +| `Units` | OPTIONAL | Units, if applicable. | ## Example dataset structure From 9c1a560bc5afd9060c22d8e20819188bf701f21d Mon Sep 17 00:00:00 2001 From: Karl-Koschutnig Date: Tue, 21 Apr 2026 07:31:06 +0200 Subject: [PATCH 3/3] [ENH] Update survey documentation and examples for sleep questionnaire --- src/modality-specific-files/survey.md | 75 ++++++++++++++------------- 1 file changed, 40 insertions(+), 35 deletions(-) diff --git a/src/modality-specific-files/survey.md b/src/modality-specific-files/survey.md index 1bef840a6d..d56bbfd457 100644 --- a/src/modality-specific-files/survey.md +++ b/src/modality-specific-files/survey.md @@ -30,8 +30,12 @@ once within a session. ## Sidecar JSON (`*_survey.json`) -Each survey `.tsv` file MUST be accompanied by a JSON sidecar with the same -filename stem. +Each survey `.tsv` file MUST be accompanied by a JSON sidecar. +Following the [Inheritance Principle](../common-principles.md#the-inheritance-principle), +the sidecar MAY be placed at any level of the hierarchy +(for example, at the dataset root as `task-