Outputs

This page describes what each CLI command writes, how files are named, and what data is stored inside each output artifact.

Commands Overview

The commands fall into two groups:

  • to-modelarray: convert input neuroimaging data into either: - one or more HDF5 files (--backend hdf5), or - one or more TileDB directories (--backend tiledb). The modality (NIfTI, CIFTI, or MIF/fixel) is autodetected from the source file extensions in the cohort file.

  • export-results: convert analysis results stored in an HDF5 file into image files. The modality is inferred from which arguments are provided (--mask for NIfTI, --index-file/--directions-file for MIF, --cohort-file/--example-file for CIFTI).

to-modelarray (volumes)

Triggered when source files in the cohort have .nii or .nii.gz extensions. Requires --mask.

HDF5 output contents:

  • voxels dataset: - transposed voxel table with rows for voxel_id, i, j, k. - attribute column_names = ['voxel_id', 'i', 'j', 'k'].

  • Per scalar: - scalars/<scalar_name>/values with shape (n_subjects, n_voxels). - scalars/<scalar_name>/column_names listing source file names.

TileDB output contents:

  • Per scalar dense array at scalars/<scalar_name>/values with shape (n_subjects, n_voxels).

  • Column names are stored in array metadata (column_names).

When --scalar-columns is provided:

  • Output is split by scalar column name.

  • Example: --scalar-columns alpha beta --output modelarray.h5 writes: - alpha_modelarray.h5 - beta_modelarray.h5

  • The same prefix rule also applies to TileDB output paths.

to-modelarray (CIFTI)

Triggered when source files in the cohort have a CIFTI compound extension (e.g. .dscalar.nii, .pscalar.nii, .pconn.nii).

HDF5 output contents:

  • greyordinates dataset (dscalar): - transposed table with rows for vertex_id and structure_id. - attribute column_names = ['vertex_id', 'structure_id']. - attribute structure_names listing CIFTI brain structures.

  • parcels/parcel_id string dataset (pscalar), or parcels/parcel_id_from and parcels/parcel_id_to (pconn).

  • Per scalar: - scalars/<scalar_name>/values with shape (n_subjects, n_greyordinates). - scalars/<scalar_name>/column_names listing source file names.

TileDB output contents:

  • Per scalar dense array at scalars/<scalar_name>/values with shape (n_subjects, n_greyordinates).

  • Column names metadata is written on each scalar matrix.

  • An explicit TileDB array is also written at scalars/<scalar_name>/column_names.

When --scalar-columns is provided:

  • Output is split by scalar column name.

  • Example: --scalar-columns alpha beta --output modelarray.h5 writes: - alpha_modelarray.h5 - beta_modelarray.h5

  • The same prefix rule also applies to TileDB output paths.

to-modelarray (MIF/fixels)

Triggered when source files in the cohort have a .mif extension. Requires --index-file and --directions-file.

HDF5 output contents:

  • fixels dataset: - transposed fixel table (fixel_id, coordinates/directions metadata from input fixel DB). - attribute column_names containing table column names.

  • voxels dataset: - transposed voxel table with voxel_id, i, j, k. - attribute column_names containing table column names.

  • Per scalar: - scalars/<scalar_name>/values with shape (n_subjects, n_fixels). - scalars/<scalar_name>/column_names listing source file names.

TileDB output contents:

  • Per scalar dense array at scalars/<scalar_name>/values with shape (n_subjects, n_fixels).

  • Column names are stored in array metadata (column_names).

When --scalar-columns is provided:

  • Output is split by scalar column name.

  • Example: --scalar-columns alpha beta --output modelarray.h5 writes: - alpha_modelarray.h5 - beta_modelarray.h5

  • The same prefix rule also applies to TileDB output paths.

export-results (result exporters)

This command reads statistical results from:

  • results/<analysis_name>/results_matrix (shape: (n_results, n_elements)).

Result names are read in this order:

  • results_matrix.attrs['colnames'] (if present),

  • results/<analysis_name>/column_names dataset,

  • results/<analysis_name>/results_matrix/column_names dataset,

  • fallback names: component001, component002, …

Any spaces or / in result names are replaced with _ in filenames.

export-results (NIfTI)

Triggered by providing --mask.

Writes one file per result to --output-dir:

  • <analysis_name>_<result_name>.nii.gz.

  • If a result name contains p.value, an additional file is written: <analysis_name>_<result_name_with_1m.p.value>.nii.gz, containing 1 - p.value.

Each output volume uses --mask to map vectorized results back into 3D space. Pass --no-compress to write uncompressed .nii files instead.

export-results (CIFTI)

Triggered by providing --cohort-file or --example-file (without --mask or --index-file/--directions-file).

Writes one CIFTI file per result to --output-dir, using the extension that matches the example file (e.g. .dscalar.nii, .pscalar.nii, .pconn.nii):

  • <analysis_name>_<result_name>.<ext>.

  • If a result name contains p.value, also writes the 1 - p.value companion file with 1m.p.value in its name.

The header is taken from --example-file (or from the first cohort source_file if --cohort-file is used instead).

export-results (MIF/fixels)

Triggered by providing --index-file and --directions-file.

Writes one MIF file per result to --output-dir:

  • <analysis_name>_<result_name>.mif.gz.

  • If a result name contains p.value, also writes the 1 - p.value companion file with 1m.p.value in its name.

Also copies these files into --output-dir:

  • --index-file

  • --directions-file

The output MIF geometry/header template is taken from --example-file (or from the first cohort source_file if --cohort-file is used instead). Pass --no-compress to write uncompressed output where applicable.