From c2aaf18f58975f641ecef3a915e84f945372c20d Mon Sep 17 00:00:00 2001 From: Alyssa Dai Date: Tue, 12 Sep 2023 16:56:14 -0400 Subject: [PATCH 1/4] import query tool results TSVs --- mkdocs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index a9c9717f..245ac328 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -83,3 +83,6 @@ plugins: include: [ "docs/api_environment_variables.tsv"] # the branch of the repository to clone branch: "main" + - url: "https://github.com/neurobagel/neurobagel_examples" + include: [ "query-tool-results" ] + branch: "add-query-tsv-examples" From 5ed4a2eddc75f589afb8a764b62de0d7dce9c889 Mon Sep 17 00:00:00 2001 From: Alyssa Dai Date: Tue, 12 Sep 2023 16:56:47 -0400 Subject: [PATCH 2/4] add section describing query tool results TSVs --- docs/query_tool.md | 50 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 46 insertions(+), 4 deletions(-) diff --git a/docs/query_tool.md b/docs/query_tool.md index a00107b0..1f501c19 100644 --- a/docs/query_tool.md +++ b/docs/query_tool.md @@ -66,6 +66,7 @@ You can verify the tool is running once you receive info messages from Nuxt rega ## Usage +### Running a query To define a cohort, set your inclusion criteria using the following: - Age: Minimum and/or maximum age (in years) of participant that should be included in the results. @@ -78,9 +79,50 @@ To define a cohort, set your inclusion criteria using the following: Once you've defined your criteria, submit them as a query and the query tool will display the results. -The query tool offers two different TSV files for results: -- Dataset-level results TSV contains: dataset id, dataset name, dataset portal uri, number of matching subjects, and available imaging modalities -- Participant-level results TSV contains: dataset id, subject id, age, sex, diagnosis, assessment, session id, session file path, number of sessions, and imaging modality +### Downloading query results -The output files can be joined using `DatasetID` as key. +For a given query, the query tool offers two kinds of TSV files for results that users can download. +At least one dataset matching the query must be selected in the interface in order to download the query results. + +#### Dataset-level results + +The dataset-level results TSV describes the datasets that contain subjects matching the user's query. +This TSV contains the following columns: + +- `DatasetID`: unique identifier (UUID) for dataset in the graph. +Note that this ID is not guaranteed to be persistent across versions of a graph/across graphs, but will always be identical across a pair of query tool result files. +_This column can be used as the key to join the dataset-level and participant-level results TSVs for a given query result, if needed._ +- `DatasetName`: human readable name of the dataset +- `PortalURI`: URL to a website or page about the dataset, if available +- `NumMatchingSubjects`: (aggregate variable) number of subjects matching the query within the dataset +- `AvailableImageModalites`: (aggregate variable) list of unique imaging modalities available for the dataset + +Example: + +{{ read_table('./repos/neurobagel_examples/query-tool-results/dataset-level-results.tsv') }} + +#### Participant-level results + +The participant-level results TSV contains the available harmonized participant attributes for subject sessions matching the query in each (selected) matching dataset. +Each row in the TSV corresponds to a single matching subject _session_. + +This TSV contains the following columns: + +- `DatasetID`: unique identifier (UUID) for dataset in the graph. +Note that this ID is not guaranteed to be persistent across versions of a graph/across graphs, but will always be identical across a pair of query tool result files. +_This column can be used as the key to join the dataset-level and participant-level results TSVs for a given query result, if needed._ +- `SubjectID`: subject label +- `Age`: subject age, if available +- `Sex`: subject sex, if available +- `Diagnosis`: list of diagnoses of subject, if available +- `Assessment` : list of assessments completed by subject, if available +- `SessionID`: session label +- `SessionPath`: the path of the session directory relative to the dataset root (for datasets available through DataLad) or root of the filesystem where the dataset is stored +- `NumSessions`: (aggregate variable) total number of available sessions for subject. +This number will be the same across rows corresponding to the same subject. +- `Modality`: imaging modalities acquired in the session, if available + +Example: + +{{ read_table('./repos/neurobagel_examples/query-tool-results/participant-level-results.tsv') }} From 2c97a175c2247db4c86cb256f7a45e8722357495 Mon Sep 17 00:00:00 2001 From: Alyssa Dai Date: Tue, 12 Sep 2023 16:58:12 -0400 Subject: [PATCH 3/4] change imported branch to main --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 245ac328..20b53a81 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,4 +85,4 @@ plugins: branch: "main" - url: "https://github.com/neurobagel/neurobagel_examples" include: [ "query-tool-results" ] - branch: "add-query-tsv-examples" + branch: "main" From 40b647c11f0ab18ea49fb6e393f49ca788b8312d Mon Sep 17 00:00:00 2001 From: Alyssa Dai Date: Tue, 12 Sep 2023 20:57:30 -0400 Subject: [PATCH 4/4] retrigger checks