Export data results

This page contains descriptions and examples to export data results across a range of file formats compatible with several neuroimaging software. These include: .txt/.csv, FreeSurfer/”curv”, .mgh/.mgz, GIfTI/.gii

As an example, we will export the vertexwise data from the previous tutorial. The examples below can be easily modified to export any vertexwise (all formats) or parcellated (.txt/.csv format) data results by simply changing the data array to be saved, the data export path, and the filenames. Here, we exported cortical thickness data to the ENIGMA’s import_export datasets directory.

What about exporting brain surfaces? 🏄🏼‍♀️

Exported data results can be mapped to the surface templates using several other neuroimaging software. Cortical and subcortical surfaces are available here in different file formats (FreeSurfer/surface, GIfTI/.gii, .vtk, .obj).

.txt / .csv

If you want to export your data as text (.txt) or comma-separated values files, then you may use the writetable() (Matlab) or np.savetxt() (Python) functions. If your input data are in a table or dataframe, then you may remove the array2table() function (Matlab) or use the .to_csv() function (Python) functions.

>>> import enigmatoolbox
>>> import numpy as np
>>> import os

>>> # Specify data to be exported
>>> data = CT_schaefer_200_c69

>>> # Define output path and filenames
>>> dpath = os.path.join(os.path.dirname(enigmatoolbox.__file__) + "/datasets/import_export/")
>>> fname_lh = 'lh.schaefer_200_c69_thickness.txt'
>>> fname_rh = 'rh.schaefer_200_c69_thickness.txt'

>>> # Export data as .txt / .csv
>>> np.savetxt(dpath + fname_lh, data[:len(data)//2])
>>> np.savetxt(dpath + fname_rh, data[len(data)//2:])
% Specify data to be exported
data = CT_schaefer_200_c69

% Define output path and filenames
dpath = what('import_export'); dpath = dpath.path;
fname_lh = 'lh.schaefer_200_c69_thickness.txt'
fname_rh = 'rh.schaefer_200_c69_thickness.txt'

% Export data as .txt / .csv
writetable(array2table(data(1:end/2)), [dpath, fname_lh], 'WriteVariableNames', 0)
writetable(array2table(data(end/2+1:end)), [dpath, fname_rh], 'WriteVariableNames', 0)

FreeSurfer / “curv”

If you want to export your data as FreeSurfer “curv” format (e.g., ?h.thickness), then you may use the write_curv() (Matlab) or nib.freesurfer.io.write_morph_data() (Python) functions to load your data. You can get the Matlab function from here.

What is this nfaces business? 🤖

In the write_curv() and nib.freesurfer.io.write_morph_data() functions, users are required to specify the number of faces (or triangles) in the associated surface file. To simplify things, we built a simple function, nfaces(), in which users can specify the surface name (’conte69’, ‘fsa5’) and the hemisphere (’lh’, ‘rh’, ‘both’) to obtain the appropriate number of faces.

>>> import enigmatoolbox
>>> from enigmatoolbox.datasets import nfaces
>>> import nibabel as nib
>>> import os

>>> # Specify data to be exported
>>> data = CT_schaefer_200_c69

>>> # Define output path and filenames
>>> dpath = os.path.join(os.path.dirname(enigmatoolbox.__file__) + "/datasets/import_export/")
>>> fname_lh = 'lh.schaefer_200_c69_thickness'
>>> fname_rh = 'rh.schaefer_200_c69_thickness'

>>> # Export data as FreeSurfer "curv"
>>> nib.freesurfer.io.write_morph_data(dpath + fname_lh, data[:len(data)//2], nfaces('conte69', 'lh'))
>>> nib.freesurfer.io.write_morph_data(dpath + fname_rh, data[len(data)//2:], nfaces('conte69', 'rh'))
% Specify data to be exported
data = CT_schaefer_200_c69

% Define output path and filenames
dpath = what('import_export'); dpath = dpath.path;
fname_lh = 'lh.schaefer_200_c69_thickness'
fname_rh = 'rh.schaefer_200_c69_thickness'

% Export data as FreeSurfer "curv"
write_curv([dpath, fname_lh], data(1:end/2), nfaces('conte69', 'lh'));
write_curv([dpath fname_rh], data(end/2+1:end), nfaces('conte69', 'rh'));

.mgh / .mgz

If you want to export your data as .mgh or .mgz formats, then you may use the load_mgh() (Matlab) or nib.freesurfer.mghformat.MGHImage() (Python) functions to load your data. You can get the Matlab function from here.

What is this getaffine business? 🧜🏼‍♀️

In the save_mgh() and nib.freesurfer.mghformat.MGHImage() functions, users are required to specify a vox2ras transform matrix. To simplify things, we built a simple function, getaffine(), in which users can specify the surface name (’conte69’, ‘fsa5’) and the hemisphere (’lh’, ‘rh’, ‘both’) to obtain the appropriate transform.

>>> import enigmatoolbox
>>> from enigmatoolbox.datasets import getaffine
>>> import nibabel as nib
>>> import numpy as np
>>> import os

>>> # Specify data to be exported
>>> data = CT_schaefer_200_c69

>>> # Define output path and filenames
>>> dpath = os.path.join(os.path.dirname(enigmatoolbox.__file__) + "/datasets/import_export/")
>>> fname_lh = 'lh.schaefer_200_c69_thickness.mgh'
>>> fname_rh = 'rh.schaefer_200_c69_thickness.mgh'

>>> # Export data as .mgh / .mgz
>>> nib.freesurfer.mghformat.MGHImage(np.float32(data[:len(data)//2]),
...                                   getaffine('conte69', 'lh')).to_filename(dpath + fname_lh)
>>> nib.freesurfer.mghformat.MGHImage(np.float32(data[len(data)//2:]),
...                                   getaffine('conte69', 'lh')).to_filename(dpath + fname_rh)
% Specify data to be exported
data = CT_schaefer_200_c69

% Define output path and filenames
dpath = what('import_export'); dpath = dpath.path;
fname_lh = 'lh.schaefer_200_c69_thickness.mgh'
fname_rh = 'rh.schaefer_200_c69_thickness.mgh'

% Export data as .mgh / .mgz
save_mgh(data(1:end/2), [dpath, fname_lh], getaffine('conte69', 'lh'));
save_mgh(data(end/2+1:end), [dpath, fname_rh], getaffine('conte69', 'rh'));

GIfTI / .gii

If you want to export your data as GIfTI/.gii format, then you may use the savegifti() (Matlab) or nib.save (Python) functions to load your data. You can get the Matlab function from here.

Script name change 📛

To avoid confusion with Matlab’s function save(), we renamed the GIfTI Toolbox’s save function as savegifti().

>>> import enigmatoolbox
>>> import nibabel as nib
>>> import os

>>> # Specify data to be exported
>>> data = CT_schaefer_200_c69

>>> # Convert left and right hemisphere data to GIfTI image
>>> data_lh = nib.gifti.gifti.GiftiImage()
>>> data_lh.add_gifti_data_array(nib.gifti.gifti.GiftiDataArray(data=data[:len(data)//2]))
>>> data_rh = nib.gifti.gifti.GiftiImage()
>>> data_rh.add_gifti_data_array(nib.gifti.gifti.GiftiDataArray(data=data[len(data)//2:]))

>>> # Define output path and filenames
>>> dpath = os.path.join(os.path.dirname(enigmatoolbox.__file__) + "/datasets/import_export/")
>>> fname_lh = 'lh.schaefer_200_c69_thickness.gii'
>>> fname_rh = 'rh.schaefer_200_c69_thickness.gii'

>>> # Export data as GIfTI / .gii
>>> nib.save(data_lh, dpath + fname_lh)
>>> nib.save(data_rh, dpath + fname_rh)
% Specify data to be exported
data = gifti(CT_schaefer_200_c69);
data_lh = data; data_lh.cdata = data_lh.cdata(1:end/2);
data_rh = data; data_rh.cdata = data_rh.cdata(end/2+1:end);

% Define output path and filenames
dpath = what('import_export'); dpath = dpath.path;
fname_lh = 'lh.schaefer_200_c69_thickness.gii'
fname_rh = 'rh.schaefer_200_c69_thickness.gii'

% Export data as GIfTI / .gii
savegifti(data_lh, [dpath, fname_lh], 'Base64Binary');
savegifti(data_rh, [dpath, fname_rh], 'Base64Binary');

CIfTI / .dscalar.nii / .dtseries.nii

If you want to export your data as CIfTI/.dscalar.nii/.dtseries.nii format, then you may use the write_cifti() (Matlab and Python) functions to load your data. The Matlab function, however, relies on this toolbox right here.

>>> from enigmatoolbox.datasets import write_cifti
>>> import os

>>> # Specify data to be exported
>>> data = CT_schaefer_200_c69;

>>> # Define output path and filenames
>>> dpath = os.path.join(os.path.dirname(enigmatoolbox.__file__) + "/datasets/import_export/")
>>> fname_lh = 'lh.schaefer_200_c69_thickness.dscalar.nii'
>>> fname_rh = 'rh.schaefer_200_c69_thickness.dscalar.nii'

>>> # Export data as CIfTI / .dscalar.nii / .dtseries.nii
>>> write_cifti(data[:len(data)//2], dpath=dpath, fname=fname_lh, labels=None, surface_name='conte69', hemi='lh')
>>> write_cifti(data[len(data)//2:], dpath=dpath, fname=fname_rh, labels=None, surface_name='conte69', hemi='rh')
% Specify data to be exported
data = CT_schaefer_200_c69;

% Define output path and filenames
dpath = what('import_export'); dpath = dpath.path;
fname_lh = 'lh.schaefer_200_c69_thickness.dscalar.nii'
fname_rh = 'rh.schaefer_200_c69_thickness.dscalar.nii'

% Export data as CIfTI / .dscalar.nii / .dtseries.nii
write_cifti(data(1:end/2), 'dpath', dpath, 'fname', fname_lh, 'surface_name', 'conte69', 'hemi', 'lh')
write_cifti(data(end/2+1:end), 'dpath', dpath, 'fname', fname_rh, 'surface_name', 'conte69', 'hemi', 'rh')