Tutorials¶
Notebooks¶
Before running the following tutorials, NIAK needs to be properly installed. All the codes are to be executed in the matlab/octave environment. It is generally advised to create a new folder and run the script in this folder, as some datasets may be downloaded, and various images may be generated.
How to test NIAK¶
In order to validate that a computational environment behaves the way it should, NIAK offers a series of tests. To run all NIAK tests, fir create a folder to put all the test results:
psom_mkdir('test_niak')
cd test_niak
Then simply type:
niak_test_all
This command will download the test dataset, as well as a series of results generated on a trusted sy stem. All the pipelines available in NIAK will run. The tests will compare all the results generated locally with those previous results, and produce a series of reports in .csv format.
report_test_regression_connectome_demoniak.csv
report_test_regression_region_growing_demoniak.csv
report_test_regression_connectome_demoniak.csv
Those are spreadsheets formatted as comma-separated values. Each row is about one file of the associa ted pipeline, and includes the following information:
source
(boolean)1: the file exists in the source (generated results).
0: the file is absent in the source (generated results).
target
(boolean)1: the file exists in the target (reference results).
0: the file is absent in the target (reference results).
identical
(boolean or NaN)1: the files are identical (the actual test depends on file type, see the note below).
0: the files are different (the actual test depends on file type, see the note below).
NaN: unsupported file type, or the file exists only on source or target.
same_labels
(boolean or NaN)1: the .csv files have the same labels for rows and columns.
0: the .csv files have different labels for rows or columns.
NaN: not .csv files (the test does not apply, ignore value).
same_variables
(boolean or NaN)1: the .mat files contain the same variables.
0: the .mat files contain different variables.
NaN: not .mat files (the test does not apply, ignore value).
same_header_info
(boolean or NaN)1: the .nii/.mnc files have the same headers.
0: the .nii/.mnc files have different headers.
NaN: not .mnc/.nii files (the test does not apply, ignore value).
same_dim
(boolean or NaN)1: the data inside .nii/.mnc or .csv files have the same dimensions.
0: the data inside .nii/.mnc or .csv files have different dimensions.
NaN: not .mnc/.nii/.csv files (the test does not apply, ignore value).
dice_mask_brain
(scalar in [0,1] or NaN)scalar: the dice coefficient for brain masks generated for two volumes (.nii/.mnc).
NaN: not .mnc/.nii files (the test does not apply, ignore value).
max_diff
(positive scalar or NaN)scalar: the max absolute difference between two volumes (.nii/.mnc) or spreadsheets (.csv).
NaN: not .mnc/.nii/.csv files (the test does not apply, ignore value).
min_diff
(positive scalar or NaN)scalar: the min absolute difference between two volumes (.nii/.mnc) or spreadsheets (.csv).
NaN: not .mnc/.nii/.csv files (the test does not apply, ignore value).
mean_diff
(positive scalar or NaN)scalar: the mean absolute difference between two volumes (.nii/.mnc) or spreadsheets (.csv).
NaN: not .mnc/.nii/.csv files (the test does not apply, ignore value).
max_corr
(scalar in [0,1] or NaN)scalar: the max correlation between the time series of voxels inside the brain masks, for tw o 4D volumes (.nii/.mnc).
NaN: not 4D .mnc/.nii files (the test does not apply, ignore value).
min_corr
(scalar in [0,1] or NaN)scalar: the min correlation between the time series of voxels inside the brain masks, for tw o 4D volumes (.nii/.mnc).
NaN: not 4D .mnc/.nii files (the test does not apply, ignore value).
mean_corr
(scalar in [0,1] or NaN)scalar: the mean correlation between the time series of voxels inside the brain masks, for t wo 4D volumes (.nii/.mnc).
NaN: not 4D .mnc/.nii files (the test does not apply, ignore value).
Two files are identical if they exist in both source and target and
.nii/.mnc files: the headers are identical and the max absolute difference is less than a toler ance value (10^-4).
.csv files: the labels of rows and columns are identical and the max absolute difference is les s than a tolerance value (10^-4, see
opt.eps
inniak_brick_cmp_files
)..mat files: the content is identical up to a tolerance value (10^-4, see
opt.eps
inniak_bri ck_cmp_files
).
The tests fail if any two pairs of file are not identical in the reference results and the generated results. Note that tests can fail if slightly different versions of Matlab/Octave/minc tools are used when generating results as compared to the reference results. When NIAK is executed through docker, perfect replications are expected.
Read and write volumes in NIAK¶
This tutorial shows how to read and write volumes using the NIAK tools, as well as perform some basic operations. It does not generate figures. The script can be downloaded [here](https://raw.githubuser content.com/SIMEXP/niak_tutorials/master/read_write_vol/niak_tutorial_read_write_vol.m).
First download the single subject, preprocessed cambridge dataset.
clear
if ~psom_exist('single_subject_cambridge_preprocessed_nii')
system('wget http://www.nitrc.org/frs/download.php/6784/single_subject_cambridge_preprocessed_nii
.zip')
system('unzip single_subject_cambridge_preprocessed_nii.zip')
psom_clean('single_subject_cambridge_preprocessed_nii.zip')
end
To read the data, use niak_read_vol
.
[hdr,vol] = niak_read_vol('single_subject_cambridge_preprocessed_nii/fmri_sub00156_session1_rest.nii.
gz');
The hdr
output is a structure with a full description of the volume. In particular, hdr.info
cont
ains some basic info found in both nifti and minc.
hdr.info
For example, the voxel size is found in
hdr.info.voxel_size
All the detailed information are contained in hdr.details
. This field will vary based on the format
of the original volume. Here, for nifti, each field corresponds to a nifti field.
hdr.details
The vol
output is the data itself, in either a 3D or a 4D array. Any normalization (min/max) has be
en applied. It is in voxel space however, and no spatial transformation has been applied.
size(vol)
To write volumes, the name of the volume is going into the header.
hdr.file_name = 'mean_vol.nii.gz';
The number of time frames can vary, and is automatically updated. Let’s comupte the average volume
vol_mean = mean(vol,4);
To write the volume, call niak_write_vol
.
niak_write_vol(hdr,vol_mean);