spm_brick_dartel_warp.m

function [in, out, opt] = spm_brick_dartel_warp(in,out,opt)

% This function will register images to existing templates generated by DARTEL. 
%
% IN (structure) wiwth the following fields:
%
%   RC_IMG (structure) with the following fields:
%       GM.<SUBJECT> (string) the imported grey matter image
%       WM.<SUBJECT> (string) the imported white matter image
%       The subject order for the fields GM and WM must be the same, such
%       that the grey matter image for any subject corresponds with the
%       appropriate white matter image.
%
%   TEMPLATE (structure, optional) with the following fields:
%       TEMP_1 (string) full path and filename for an existing template
%       TEMP_2 (string) full path and filename for an existing template
%       TEMP_3 (string) full path and filename for an existing template
%       TEMP_4 (string) full path and filename for an existing template
%       TEMP_5 (string) full path and filename for an existing template
%       TEMP_6 (string) full path and filename for an existing template
%       If specified, the images in IN.ANAT will be warped to match these 
%       templates. Early iterations should ideally use smoother templates 
%       and more regularisation than later iterations (e.g. TEMP_1 should
%       be smoother than TEMP_6).
%       
% OUT (structure, optional) with the following fields:
%       <SUBJECT> (string, default ['u_' RC_IMG.<SUBJECT>]) filename of the 
%       resulting flow fields
%
% OPT.FOLDER_OUT (string, default same as IN.RC_IMG.GM.<SUBJECT>) the folder where 
%       to generate outputs. If left empty, the outputs for a given image
%       in IN.RC_IMG.GM.<SUBJECT> will be written to the same originating path (i.e.
%       path of IN.RC_IMG.GM.<SUBJECT> == path of outputs from IN.RC_IMG.GM.<SUBJECT>).
% OPT.FLAG_TEST (boolean, default false) flag to run a test without 
%       generating outputs.
%
% If OPT.FLAG_TEST is true, the brick does nothing but still updates the
%    default file names in OUT, as well as default options in OPT.
% By default (OUT = struct) the brick generates all output files.
%    If file names are specified in OUT, those will be used over defaults.
%    If a file name 'skip' is specified, the output is not generated.
%
% This is an interface to the DARTEL tools from SPM12.
% It performs non-linear registration. This involves iteratively matching 
% all the selected images to a template generated from their own mean. A 
% series of Template*.nii files are generated, which become increasingly 
% crisp as the registration proceeds. The non-linear registration can also 
% match individual images to pre-existing template data. Start out with 
% smooth templates, and select crisp templates for the later iterations.
%
% _________________________________________________________________________
% Copyright (c) Angela Tam, Yasser Iturria-Medina, Pierre Bellec
% Montreal Neurological Institute, 2017
% Centre de recherche de l'institut de geriatrie de Montreal,
% Department of Computer Science and Operations Research
% University of Montreal, Quebec, Canada, 2017
% Maintainer : pierre.bellec@criugm.qc.ca
% See licensing information in the code.
% Keywords : SPM, DARTEL, nonlinear registration, interface

% Permission is hereby granted, free of charge, to any person obtaining a copy
% of this software and associated documentation files (the "Software"), to deal
% in the Software without restriction, including without limitation the rights
% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
% copies of the Software, and to permit persons to whom the Software is
% furnished to do so, subject to the following conditions:
%
% The above copyright notice and this permission notice shall be included in
% all copies or substantial portions of the Software.
%
% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
% THE SOFTWARE.
global gb_psom_name_job

if ~exist('in','var')||~exist('out','var')
    error('spm:brick','syntax: [IN,OUT,OPT] = SPM_BRICK_DARTEL_WARP(IN,OUT,OPT).\n Type ''help spm_brick_dartel_warp'' for more info.')
end

%% Input
if ~isstruct(in)
  error('IN should be a structure')
end
list_sub = fieldnames(in.rc_img.gm);
[path_f,~,ext_f] = fileparts(in.rc_img.gm.(list_sub{1})); 
if isempty(path_f)
    path_f = '.';
end

if ~isstruct(out)
    error('OUT should be a structure')
end

%% Temporary folder
if ~isempty(gb_psom_name_job)
    path_tmp = [tempdir filesep gb_psom_name_job filesep];
else
    path_tmp = tempdir;
end

%% Files_in
in = psom_struct_defaults(in,...
        { 'rc_img' , 'template' },...
        { NaN      , NaN        });

%% Options
if nargin < 2
  out = '';
end

%% Options
if nargin < 3
  opt = struct;
end
opt = psom_struct_defaults(opt , ...
        { 'flag_test', 'folder_out' },...
        { false      , ''           });
    
%% Building default output names
if isempty(out) || isempty(fieldnames(out))
    for ss = 1:length(list_sub)
        [path_f,name_f,ext_f] = fileparts(in.rc_img.gm.(list_sub{ss}));
        if isempty(path_f)
            path_f = '.';
        end
        out.(list_sub{ss}) = [path_f filesep 'u_' name_f ext_f];
    end
end

%% settings for DARTEL
opt_dartel.settings.rform = 0;
opt_dartel.settings.param(1).its = 3;
opt_dartel.settings.param(1).rparam = [4 2 1e-06];
opt_dartel.settings.param(1).K = 0;
opt_dartel.settings.param(2).its = 3;
opt_dartel.settings.param(2).rparam = [2 1 1e-06];
opt_dartel.settings.param(2).K = 0;
opt_dartel.settings.param(3).its = 3;
opt_dartel.settings.param(3).rparam = [1 0.5 1e-06];
opt_dartel.settings.param(3).K = 1;
opt_dartel.settings.param(4).its = 3;
opt_dartel.settings.param(4).rparam = [0.5 0.25 1e-06];
opt_dartel.settings.param(4).K = 2;
opt_dartel.settings.param(5).its = 3;
opt_dartel.settings.param(5).rparam = [0.25 0.125 1e-06];
opt_dartel.settings.param(5).K = 4;
opt_dartel.settings.param(6).its = 3;
opt_dartel.settings.param(6).rparam = [0.25 0.125 1e-06];
opt_dartel.settings.param(6).K = 6;
opt_dartel.settings.optim.lmreg = 0.01;
opt_dartel.settings.optim.cyc = 3;
opt_dartel.settings.optim.its = 3;
opt_dartel.folder_out = '';
opt_dartel.flag_test = opt.flag_test;

opt = psom_defaults(opt_dartel, opt );

if opt.flag_test == 1
    return
end

%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Brick really starts here
%%%%%%%%%%%%%%%%%%%%%%%%%%%
spm_in = cell(1,2);
spm_in{1} = cell(size(list_sub,1),1);
spm_in{2} = cell(size(list_sub,1),1);
spm_in{1} = struct2cell(in.rc_img.gm);
spm_in{2} = struct2cell(in.rc_img.wm);

opt.images = spm_in;
opt.settings.param(1).template = cellstr(in.template.temp_1);
opt.settings.param(2).template = cellstr(in.template.temp_2);
opt.settings.param(3).template = cellstr(in.template.temp_3);
opt.settings.param(4).template = cellstr(in.template.temp_4);
opt.settings.param(5).template = cellstr(in.template.temp_5);
opt.settings.param(6).template = cellstr(in.template.temp_6);
folder_out = opt.folder_out;
opt = rmfield ( opt , { 'folder_out' , 'flag_test'}); % Get rid of the options not supported by spm dartel functions

%% register to existing templates
spm_dartel_warp(opt);

%% rename the flow_field outputs to user-specified filenames
for ss = 1:length(list_sub)
    f_out = out.(list_sub{ss});
    [path_r,name_r,ext_r] = fileparts(spm_in{1}{ss});
    if isempty(path_r)
        path_r = '.';
    end
    flowfield = [path_r filesep 'u_' name_r ext_r];
    if ~strcmp(f_out, flowfield)
        movefile(jac, f_out);
    end
end

%% move outputs to opt.folder_out if specified
if ~isempty(folder_out)
    for ss = 1:length(list_sub)
        f_out = out.(list_sub{ss});
        [path_r,name_r,ext_r] = fileparts(spm_in{1}{ss});
        if isempty(path_r)
            path_r = '.';
        end
        movefile(f_out, folder_out);
    end
end