Skip to content
nf-neuro

harmonization

This harmonization subworkflow essentially is a convenience wrapper around the the harmonization module (e.g. harmonization/clinicalcombat). The combat module requires specific input formats for the tabular stats files. This subworkflow automatically handles the conversion from TSV to CSV format (including pivoting/unpivoting of the metrics) before and after harmonization, using the harmonization/stats2combat and harmonization/combat2stats modules.

Combat currently expects a CSV file with the following columns: “sid,site,bundle,metric,mean,age,sex,handedness,disease”. AND a separate CSV file PER metric.

However, in other nf-neuro modules (e.g. stats/metricsinroi or bundle/stats), the output stats files are in TSV format with the following columns: “sid,roi,<covariates>,metric1,metric2,…”.

You can simply provide the TSV stat files directly coming from bundle/stats or stats/metricsinroi to this subworkflow, and it will take care of formatting them into the CSV format expected by combat, and then re-formatting the harmonized CSV outputs back into a TSV format that can be easily read by MultiQC or other downstream tools.

Keywords : clinical, combat, tsv, csv, format, harmonization, harmonize

Components : harmonization/stats2combat, harmonization/combat2stats, harmonization/clinicalcombat

Inputs

Section titled “Inputs”
TypeDescriptionMandatoryPattern
ch_reference_sitefileThe input channel containing the reference site tractometry TSV stats file with the following columns: “sid,roi,<covariates>,metric1,metric2,…”.

Structure : tuple val(meta), path(tsv_file)
  • meta [map] Metadata map.
  • tsv_file [file] Reference site TSV stats file.
True*.tsv
ch_moving_sitefileThe input channel containing the moving site tractometry TSV stats file with the following columns: “sid,roi,<covariates>,metric1,metric2,…”.

Structure : tuple val(meta), path(tsv_file)
  • meta [map] Metadata map.
  • tsv_file [file] Moving site TSV stats file.
True*.tsv

Outputs

Section titled “Outputs”
TypeDescriptionMandatoryPattern
harmonized_metricsfileHarmonized stats file in TSV format (MultiQC ready format).

Structure : tuple path(harmonized_metrics)
  • harmonized_metrics [file] Harmonized metrics TSV file.
True*.tsv
figuresfilePNG figures illustrating the harmonization results for each metric and each bundle.

Structure : tuple path(img)
  • img [file] Harmonization figures (PNG).
True*.png
modelfileHarmonization fitted model.

Structure : tuple path(model_file)
  • model_file [file] Harmonization model file.
True*.model.csv
qc_reportsfileValues that can be reported in QC reports.

Structure : tuple path(qc_reports)
  • qc_reports [file] QC report file (Bhattacharyya distance).
True*bhattacharrya.txt
qc_plot_data_jsonfileJSON files used to properly plot the harmonization results in a downstream MultiQC report. These files contain the regression curves and the percentiles computed before and after harmonization for all bundles of a given metric. The files have the following layout:

  {
      “bundle_name_1”: {
          “metric1”: {
              “plot_1”: { … },
              “plot_2”: { … },
          }
      },
      “bundle_name_2”: {
          “metric1”: {
              “plot_1”: { … },
              “plot_2”: { … },
          }
    }
  }


Structure : tuple path(qc_plot_data)
  • qc_plot_data [file] QC plot data JSON file.
True*.json
versionsfileFile containing software versions

Structure : tuple path(versions)
  • versions [file] Versions YAML file.
Trueversions.yml

Authors

Section titled “Authors”

Maintainers

Section titled “Maintainers”

Last updated : 2026-03-17