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')