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: [ val(meta), path(tsv_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: [ val(meta), path(tsv_file) ]		True*.tsv

Outputs

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

Structure: [ path(*.tsv) ]		True*.tsv
figuresfilePNG figures illustrating the harmonization results for each metric and each bundle.

Structure: [ path(img) ]		True*.png
modelfileHarmonization fitted model.

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

Structure: [ path(*bhattacharrya.txt) ]		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 structure:

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


Structure: [ path(*.json) ]		True*.json
versionsfileFile containing software versions

Structure: [ path(versions.yml) ]		Trueversions.yml

Authors

Section titled “Authors”

Maintainers

Section titled “Maintainers”

Last updated : 2026-02-12