Usage

to-modelarray

Convert neuroimaging data to a modelarray HDF5 file. The modality (NIfTI, CIFTI, or MIF/fixel) is autodetected from the source file extensions in the cohort file.

usage: modelarrayio to-modelarray [-h] --cohort-file COHORT_FILE
                                  [--output OUTPUT]
                                  [--scalar-columns SCALAR_COLUMNS [SCALAR_COLUMNS ...]]
                                  [--backend {hdf5,tiledb}]
                                  [--dtype {float32,float64}]
                                  [--compression {gzip,zstd,lzf,none}]
                                  [--compression-level COMPRESSION_LEVEL]
                                  [--no-shuffle]
                                  [--chunk-voxels CHUNK_VOXELS | --target-chunk-mb TARGET_CHUNK_MB]
                                  [--workers WORKERS]
                                  [--s3-workers S3_WORKERS]
                                  [--mask GROUP_MASK_FILE]
                                  [--index-file INDEX_FILE]
                                  [--directions-file DIRECTIONS_FILE]
                                  [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]

Named Arguments

--cohort-file, --cohort_file

Path to a csv with demographic info and paths to data.

--output

Output path. For the hdf5 backend, path to an .h5 file; for the tiledb backend, path to a .tdb directory.

Default: modelarray.h5

--scalar-columns, --scalar_columns

Column names containing scalar file paths when the cohort table is in wide format. If omitted, the cohort file must include “scalar_name” and “source_file” columns.

--backend

Possible choices: hdf5, tiledb

Storage backend for subject-by-element matrix

Default: 'hdf5'

--dtype

Possible choices: float32, float64

Floating dtype for storing values: float32 (default) or float64

Default: 'float32'

--compression

Possible choices: gzip, zstd, lzf, none

Compression filter (default gzip). gzip works for both backends; lzf is HDF5-only; zstd is TileDB-only.

Default: 'gzip'

--compression-level, --compression_level

Compression level (codec-dependent). Default 4.

Default: 4

--no-shuffle

Disable shuffle filter (enabled by default when compression is used).

Default: True

--chunk-voxels, --chunk_voxels

Chunk/tile size along voxel/greyordinate/fixel axis. If 0, auto-compute based on –target-chunk-mb and number of subjects.

Default: 0

--target-chunk-mb, --target_chunk_mb

Target chunk/tile size in MiB when auto-computing the spatial axis length. Default 2.0.

Default: 2.0

--log-level, --log_level

Possible choices: DEBUG, INFO, WARNING, ERROR, CRITICAL

Logging level (default INFO; set to WARNING to reduce verbosity)

Default: 'INFO'

TileDB arguments

--workers

Maximum number of parallel TileDB write workers. Default 1. Has no effect when –backend=hdf5.

Default: 1

S3 arguments

--s3-workers, --s3_workers

Number of parallel worker processes for loading image files. Set > 1 to enable parallel downloads when cohort paths begin with s3://. Default 1 (serial).

Default: 1

NIfTI arguments (required for NIfTI data)

--mask: Path to a NIfTI binary group mask file.

MIF/fixel arguments (required for MIF/fixel data)

--index-file, --index_file: Nifti2 index file.
--directions-file, --directions_file: Nifti2 directions file.

export-results

Export statistical results from an HDF5 modelarray file to neuroimaging format files. The modality (NIfTI, CIFTI, or MIF/fixel) is inferred from the arguments provided.

usage: modelarrayio export-results [-h] --analysis-name ANALYSIS_NAME
                                   --input-hdf5 IN_FILE --output-dir
                                   OUTPUT_DIR [--mask GROUP_MASK_FILE]
                                   [--index-file INDEX_FILE]
                                   [--directions-file DIRECTIONS_FILE]
                                   [--cohort-file COHORT_FILE | --example-file EXAMPLE_FILE]
                                   [--no-compress]
                                   [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]

Named Arguments

--analysis-name, --analysis_name

Name for the statistical analysis results to be saved.

--input-hdf5, --input_hdf5

Name of HDF5 (.h5) file where results outputs are saved.

--output-dir, --output_dir

Directory where outputs will be saved. If the directory does not exist, it will be automatically created.

--log-level, --log_level

Possible choices: DEBUG, INFO, WARNING, ERROR, CRITICAL

Logging level (default INFO; set to WARNING to reduce verbosity)

Default: 'INFO'

NIfTI arguments (required for NIfTI results)

--mask: Path to the NIfTI binary group mask file used during data preparation.

MIF/fixel arguments (required for MIF/fixel results)

--index-file, --index_file: Nifti2 index file used to reconstruct MIF files.
--directions-file, --directions_file: Nifti2 directions file used to reconstruct MIF files.

Template arguments (required for CIFTI and MIF/fixel results)

--cohort-file, --cohort_file: Path to a CSV cohort file. The first source file entry is used as a header template.
--example-file, --example_file: Path to an example source file whose header is used as a template.

Output arguments

--no-compress

Disable compression for output NIfTI or MIF files. Does not affect CIFTI files.

Default: True