Normative Brain Volumes Stats, multiple datasets

Build normative brain volule stats from one or several datasets.

Description

Use case

The normative stats are used by the process morpho_report. This process is a more complete version of normative_brainvolumes_stats. It is able to handle several normative datasets, several covariables table per dataset, and covariables conversion/transformation.
However its input is a YAML config file which needs to be written beforehand.

Dataset YAML file

The dataset_description file is a YAML dictionary, which is expected to contain a list of datasets descriptions.

Syntax

• <dataset_name>: <dataset_def>
  ...
  

• a <dataset_def> is:

  variables: <variables_def>
  brain_morphometry: <brain_morpho_def>
  

• <variables_def>:

  <variable>: <var_def>
  ...
  

  <variable> may actually be a single name (age) or a coma-separated list of variables, if the definition is the same for all (age, sex). Then the <var_in_csv> items (see later) are applied in the same order as the variables list here.
• <var_def>:

  <filesytem_name>:
      <var_in_csv>: <var_csv_def>
      ...
  

  <filesystem_name> allows to povide a list of alternative places for the dataset files, so that the same definition file may apply to several machines, locations, mount points. Whenever a file is actually found in a filesystem location, the next ones are skipped and not taken into account.
• <var_in_csv> is the column name in the covariables .csv file for the given variable. However it may also contain values translation information:

  <var_in_csv_name>[ (<var_transl>)]
  

• <var_transl> may be a translation dictionary applied to categorical values, or a translation method name applied to values:

  <covar_csv_value>: <final_value>[, ...]
  

  ex: 1: M, 2: F transforms 1 to M, and 2 to F.
  or: month: apply month to year transformation.
• <var_csv_def>: may be either directly a .csv covariables filename, or a dictionary:

  filename: <csv_filename>
  [filter: <filter_def>]
  

• <filter_def> may be used to select data in the covariables tables, for instance to select a precise acquisition:

  <column_label>: <value>
  ...
  

• <brain_morpho_def>:

  <filesystem_name>: <morpho_def>
  ...
  

  As in the variables definition, <filesystem_name> allows to provide several alternative locations for files. Once one file is found in a location, other locations are nor used.
• <morpho_def> may be a single .csv filename, or a dictionary:

  filename: <morpho_filename>
  [sub-prefix: <prefix>]
  

  <prefix> is removed from subjects IDs, if this prefix is present in the morphometyric tables but not in the covariables tables.

Example

ABCD:
  variables:
    age:
      local:
        ab_g_dyn__visit_age:
          filename: /home/denis/data/abcd/phenotype/ab_g_dyn.tsv
          filter:
            session_id: ses-00A
      TGCC irene:
        - ab_g_dyn__visit_age:
            filename: /ccc/workflash/cont003/n4habcd/n4habcd/abcd/phenotype/ab_g_dyn.tsv
            filter:
              session_id: ses-00A
        - interview_age (months): /ccc/workflash/cont003/n4habcd/n4habcd/archives/r5/phenotype/core/abcd-general/abcd_y_lt.csv
    sex:
      local:
        "ab_g_stc__cohort_sex (1: M, 2: F)": /home/denis/data/abcd/phenotype/ab_g_stc.tsv
      TGCC irene:
        - "ab_g_stc__cohort_sex (1: M, 2: F)": /ccc/workflash/cont003/n4habcd/n4habcd/abcd/phenotype/ab_g_stc.tsv
        - demo_sex_v2,demo_gender_id_v2: /ccc/workflash/cont003/n4habcd/n4habcd/archives/r5/phenotype/core/abcd-general/abcd_p_demo.csv

  brain_morphometry:
      local:
        filename: /home/denis/data/abcd/morphometry/brainvolumes_abcd.csv
        sub-prefix: sub-NDARINV
      NS:
        filename: /neurospin/dico/denis/abcd/brainvolumes_abcd.csv
        sub-prefix: sub-NDARINV

UKB:
  variables:
    age, sex:
      local:
        age: /home/denis/data/ukb/participants.tsv
        Sex: /home/denis/data/ukb/participants.tsv
      NS:
        age: /neurospin/dico/data/human/UKBioBank/participants.tsv
        Sex: /neurospin/dico/data/human/UKBioBank/participants.tsv
  brain_morphometry:
    local:
      /home/denis/data/ukb/morphometry/brain_volumes.csv

HCP:
  variables:
    age, sex:
      local:
        Age: /home/denis/data/hcp/participants.csv
        Gender: /home/denis/data/hcp/participants.csv
      NS:
        Age: /neurospin/dico/data/human/hcp/participants.csv
        Gender: /neurospin/dico/data/human/hcp/participants.csv
      TGCC irene:
        Age: /ccc/workflash/cont003/n4hhcp/n4hhcp/hcp/participants.csv
        Gender: /ccc/workflash/cont003/n4hhcp/n4hhcp/hcp/participants.csv
  brain_morphometry:
    local:
      /home/denis/data/hcp/3T_morphologist/morphometry/brain_volumes.csv
    NS:
      /neurospin/dico/data/human/hcp/derivatives/morphologist-2023/morphometry/brain_volumes.csv

Parameters

dataset_description: Text file ( input )

stats: Normative brain volumes stats ( output )

Technical information

Toolbox : Morphologist

User level : 1

Identifier : normative_brainvolumes_stats_mult

File name : brainvisa/toolboxes/morphologist/processes/morphometry/normative_brainvolumes_stats_mult.py

Supported file formats :

dataset_description :

YAML file, JSON file, YAML file

stats :

JSON file, JSON file