dev_subject.tex

\documentclass{tufte-handout}
\usepackage{../braph2_dev}
%\geometry{showframe} % display margins for debugging page layout

\title{Implement, Export, and Import Groups of Subjects}

\author[The BRAPH~2 Developers]{The BRAPH~2 Developers}

\begin{document}

\maketitle

\begin{abstract}
This is the developer tutorial for implementing, importing, and exporting groups of subjects.
You will learn how to create generator files \fn{*.gen.m} for new subjects and well as to import and export them. All \fn{*.gen.m} files can then be compiled by \code{braph2genesis}. 
All types of subjects are extensions of the base element \code{Subject}. 
You will use as examples the subjects \code{SubjectCON} (subject with connectivity data), \code{SubjectCON\_MP} (subject with connectivity multiplex data), \code{SubjectFUN} (subject with functional data), \code{SubjectFUN\_MP} (subject with functional multiplex data), \code{SubjectST} (subject with structural data), and \code{SubjectST\_MP} (subject with structural multiplex data). 
Furthermore, all importers and exporters are extensions of the base elements \code{Exporter} and \code{Importer}, respectively. Here, you will use as examples \code{ImporterGroupSubjectCON\_TXT} (importing a group of subjects with connectivity data to a series of TXT file),\code{ImporterGroupSubjectCON\_XLS} (importing a group of subjects with connectivity data to a series of XLSX file), \code{ExporterGroupSubjectCON\_TXT} (exporting a group of subjects with connectivity data to a series of TXT file), and \code{ExporterGroupSubjectCON\_XLS} (exporting a group of subjects with connectivity data to a series of XLSX file).
\end{abstract}

\tableofcontents

\clearpage

\section{Implementation of a subject with connectivity data}

\subsection{Subject with connectivity data (\code{SubjectCON})}

You will start by implementing in detail \code{SubjectCON}, which holds a connectivity matrix (for example, obtained from DTI data).

\begin{lstlisting}[
	label=cd:m:SubjectCON:header,
	caption={
		{\bf SubjectCON element header.}
		The \code{header} section of the generator code in \fn{\_SubjectCON.gen.m} provides the general information about the \code{SubjectCON} element.
		}
]
%% ¡header!
SubjectCON < Subject (sub, subject with connectivity matrix) is a subject with connectivity matrix (e.g. DTI). ¥\circled{1}\circlednote{1}{ The element \code{SubjectCON} is defined as a subclass of \code{Subject}. The moniker will be \code{sub}.}¥

%%% ¡description!
Subject with a connectivity matrix (e.g. obtained from DTI).

%%% ¡seealso! ¥\circled{2}\circlednote{2}{ Other related elements.}¥
ImporterGroupSubjectFUN_TXT, ExporterGroupSubjectFUN_TXT, ImporterGroupSubjectFUN_XLS, ExporterGroupSubjectFUN_XLS

%%% ¡build!
1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectCON:prop_update,
	caption={
		{\bf SubjectCON element props update.}
		The \code{props\_update} section of the generator code in \fn{\_SubjectCON.gen.m} updates the properties of the \code{SubjectCON} element. This defines the core properties of the subject.
	}
]
%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the subject.
%%%% ¡default!
'SubjectCON'

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the subject.
%%%% ¡default!
'SubjectCON with a connectivity matrix (e.g. obtained from DTI).'

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the subject.
%%% ¡settings!
'SubjectCON'

%%% ¡prop!
ID (data, string) is a few-letter code for the subject.
%%%% ¡default!
'SubjectCON ID'

%%% ¡prop!
LABEL (metadata, string) is an extended label of the subject.
%%%% ¡default!
'SubjectCON label'

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the subject.
%%%% ¡default!
'SubjectCON notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectCON:props,
	caption={
		{\bf SubjectCON element props.}
		The \code{props} section of the generator code in \fn{\_SubjectCON.gen.m} defines the properties specific for the \code{SubjectCON} element, including the connectivity matrix.
	}
]
%% ¡props!

%%% ¡prop! ¥\circled{1}\circlednote{1}{ defines the brain atlas used for the connectivity matrix.}¥
BA (data, item) is a brain atlas.
%%%% ¡settings!
'BrainAtlas'

%%% ¡prop! 
CON (data, smatrix) is an adjacency matrix.
%%%% ¡check_value!
br_number = sub.get('BA').get('BR_DICT').get('LENGTH'); ¥\circled{2}\circlednote{2}{ determines the number of brain regions from the Brain Atlas.}¥
check = isequal(size(value), [br_number, br_number]); ¥ \circled{3}\circlednote{3}{ checks that the size of \code{value} (\code{value} is the connectivity matrix) is equal to the number of brain regions.}¥
if check ¥ \circled{4}\circlednote{4}{ returns the check information \code{msg} according to the variable \code{check}.}¥
    msg = 'All ok!';
else   
    msg = ['CON must be a square matrix with the dimension equal to the number of brain regions (' int2str(br_number) ').'];
end
%%%% ¡gui! ¥\circled{5}\circlednote{5}{ plots the panel of a property matrix-like with element \code{sub} and the property number \code{SubjectCON.CON}. \code{ROWNAME} and \code{COLUMNNAME} are the name of the brain regions obtained from brain atlas.}¥
pr = PanelPropMatrix('EL', sub, 'PROP', SubjectCON.CON, ...
    'ROWNAME', sub.get('BA').get('BR_DICT').getCallback('KEYS'), ...
    'COLUMNNAME', sub.get('BA').get('BR_DICT').getCallback('KEYS'), ...
    varargin{:});
\end{lstlisting}

\clearpage

\begin{lstlisting}[
	label=cd:m:SubjectCON:tests,
	caption={
		{\bf SubjectCON element tests.}
		The \code{tests} section from the element generator \fn{\_SubjectCON.gen.m}.
		A general test should be prepared to test the properties of the Subject when it is empty and full. Furthermore, additional tests should be prepared for the rules defined.
	}
]			
%% ¡tests!

%%% ¡test!
%%%% ¡name!
GUI ¥\circled{1}\circlednote{1}{ This test checks that the GUI is constructing well.}¥
%%%% ¡probability! ¥\circled{2}\circlednote{2}{ assigns a low test execution probability.}¥
.01
%%%% ¡code!
im_ba = ImporterBrainAtlasXLS('FILE', 'desikan_atlas.xlsx'); ¥\circled{3}\circlednote{3}{ imports the brain atlas \code{desikan} from the file \fn{desikan\_atlas.xlsx}.There are also other atlases in Braph2 folder \fn{atlases}, including \fn{aal90\_atlas.xlsx}, \fn{aal116\_atlas.xlsx}, \fn{bna\_atlas.xlsx}, \fn{craddock\_atlas.xlsx}, \fn{desikan\_subcortical\_atlas.xlsx}, \fn{destrieux\_atlas.xlsx}, \fn{destrieux\_subcortical\_atlas.xlsx},  \fn{schaefer200\_atlas.xlsx} and \fn{subcortical\_atlas.xlsx}.}¥
ba = im_ba.get('BA');  ¥\circled{4}\circlednote{4}{ returns the brain atlas.}¥

gr = Group('SUB_CLASS', 'SubjectCON', 'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON'));  ¥\circled{5}\circlednote{5}{ represents a group of subjects whose class is defined in the property \code{'SUB\_CLASS'}. \code{'SUB\_DICT'} manages the subjects as an indexed dictionary of subjects.}¥
for i = 1:1:50 ¥\circled{6}\circlednote{6}{ construts 50 subjects with random connectivity matrices.}¥
    sub = SubjectCON( ... ¥\circled{7}\circlednote{7}{ defines the \code{'ID'}, \code{'LABEL'}, \code{'NOTES'}, \code{'BA'} (Brain Atlas) and \code{'CON'} (a random adjacency matrix) for a subject.}¥
        'ID', ['SUB CON ' int2str(i)], ...
        'LABEL', ['Subejct CON ' int2str(i)], ...
        'NOTES', ['Notes on subject CON ' int2str(i)], ...
        'BA', ba, ...
        'CON', rand(ba.get('BR_DICT').get('LENGTH')) ...
        );
    sub.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 100 * rand())) ¥\circled{8}\circlednote{8}{ adds a random \code{Numeric} \code{'Age'} as the variable of interest of the subject.}¥
    sub.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', randi(2, 1))) ¥\circled{9}\circlednote{9}{ adds a random \code{Categoric} \code{'Sex'} as the variable of interest of the subject.}¥
    gr.get('SUB_DICT').get('ADD', sub) ¥\circled{10}\circlednote{10}{ adds \code{'sub'} into group.}¥
end

gui = GUIElement('PE', gr, 'CLOSEREQ', false); ¥\circled{11}\circlednote{11}{ constructs the GUI panel from \code{gr}. Setting the \code{'CLOSEREQ'} to \code{false} switched off the confirmation panel for closing the GUI.}¥
gui.get('DRAW') ¥\circled{12}\circlednote{12}{ draws the contents of a GUI before showing it.}¥
gui.get('SHOW') ¥\circled{13}\circlednote{13}{ shows the figure and its dependent figures.}¥

gui.get('CLOSE') ¥\circled{14}\circlednote{14}{ closes the figure and its dependent figures.}¥
\end{lstlisting}

\clearpage

\subsection{Subject with connectivity multiplex data (\code{SubjectCON\_MP})}

You can now use \code{SubjectCON} as the basis to implement the \code{SubjectCON\_MP}. 
{%TEX
The parts of the code that are modified are highlighted.
}%TEX
While the multilayer data allows connections between any nodes across the multiple layers, the \code{SubjectCON\_MP} can also be used for ordinal multilayer data.

\begin{lstlisting}[
	label=cd:m:SubjectCON_MP:header,
	caption={
		{\bf SubjectCON\_MP element header.}
		The \code{header} section of the generator code in \fn{\_SubjectCON\_MP.gen.m} provides the general information about the \code{SubjectCON\_MP} element. \expand{cd:m:SubjectCON:header}
		}
]
¤%% ¡header!
¤SubjectCON_MP¤ < Subject (sub, ¤subject with connectivity multiplex data) is a subject with connectivity multiplex data¤.

%%% ¡description!
¤Subject with L connectivity matrices¤ (e.g. obtained from DTI).

%%% ¡seealso!
¤ImporterGroupSubjectCON_MP_TXT, ExporterGroupSubjectCON_MP_TXT, ImporterGroupSubjectCON_MP_XLS, ExporterGroupSubjectCON_MP_XLS¤

%%% ¡build!
¤1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectCON_MP:prop_update,
	caption={
		{\bf SubjectCON\_MP element props update.}
		The \code{props\_update} section of the generator code in \fn{\_SubjectCON\_MP.gen.m} updates the properties of the \code{Subject} element. \expand{cd:m:SubjectCON:prop_update}
	}
]
¤%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the subject.
%%%% ¡default!
¤'SubjectCON_MP'¤

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the subject.
%%%% ¡default!
'Subject with ¤L connectivity matrices¤ (e.g. obtained from DTI).'

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the subject.
%%% ¡settings!
¤'SubjectCON_MP'¤

%%% ¡prop!
ID (data, string) is a few-letter code for the subject.
%%%% ¡default!
¤'SubjectCON_MP ID'¤

%%% ¡prop!
LABEL (metadata, string) is an extended label of the subject.
%%%% ¡default!
¤'SubjectCON_MP label'¤

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the subject.
%%%% ¡default!
¤'SubjectCON_MP notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectCON_MP:props,
	caption={
		{\bf SubjectCON\_MP element props.}
		The \code{props} section of the generator code in \fn{\_SubjectCON\_MP.gen.m} defines the properties specific for the \code{SubjectCON\_MP} element, including the connectivity matrices for each layer. \expand{cd:m:SubjectCON:props}
	}
]
¤%% ¡props!

%%% ¡prop!
BA (data, item) is a brain atlas.
%%%% ¡settings!
'BrainAtlas'

¤%%% ¡prop! 
L (data, scalar) is the number of layers of subject data. ¥\circled{1}\circlednote{1}{ defines a parameter to determine the number of layers of subject data. This property must be of a scalar parameter.}¥
%%%% ¡default!
2¤ ¥\circled{2}\circlednote{2}{ defines the default option, in this case \code{2}.}¥

¤%%% ¡prop! 
LAYERLABELS (metadata, stringlist) are the layer labels provided by the user.¤ ¥\circled{3}\circlednote{3}{ defines a parameter to determine the labels for each layer. This property must be of string list parameter.}¥

¤%%% ¡prop!
ALAYERLABELS (query, stringlist) returns the processed layer labels.¤ ¥\circled{4}\circlednote{4}{ defines a parameter to determine the processed labels for each layer. This property must be of string list parameter.}¥
%%%% ¡calculate!
value = sub.get('LAYERLABELS'); ¥\circled{5}\circlednote{5}{ defines the \code{value} from the property \code{'LAYERLABELS'} of SubjectCON\_MP.}¥

%%% ¡prop!
¤CON_MP (data, cell) is a cell containing L matrices corresponding connectivity matrices of each layer.¤
%%%% ¡check_value!
br_number = sub.get('BA').get('BR_DICT').get('LENGTH');
¤num_layers = sub.get('L'); ¥\circled{6}\circlednote{6}{ gets the number of layers.}¥
check = (iscell(value) && isequal(length(value), num_layers)  && isequal( cellfun(@(v) size(v, 1), value), ones(1, num_layers) * br_number)  && isequal( cellfun(@(v) size(v, 2), value), ones(1, num_layers) * br_number)) || (isempty(value) && br_number == 0);¤ ¥\circled{7}\circlednote{7}{ checks the size of each layer is equal to the number of brain regions.}¥
if check
    msg = 'All ok!';
else   
    ¤msg = ['CON_MP must be a cell with L square matrices with the dimension equal to the number of brain regions (' int2str(br_number) ').'];¤
end
%%%% ¡gui! 
pr = PanelPropCell('EL', sub, 'PROP', ¤SubjectCON_MP.CON_MP¤, ...
    ¤'TABLE_HEIGHT', s(40), ... ¥\circled{8}\circlednote{8}{ defines the height of table.}¥
    'XSLIDERSHOW', true, ... ¥\circled{9}\circlednote{9}{ shows the x-axis slider.}¥
    'XSLIDERLABELS', sub.getCallback('ALAYERLABELS'), ... ¥\circled{10}\circlednote{10}{ shows the x-axis slider's labels.}¥
    'YSLIDERSHOW', false, ...¤ ¥\circled{11}\circlednote{11}{ does not show the y-axis slider.}¥
    'ROWNAME', sub.get('BA').get('BR_DICT').getCallback('KEYS'), ...
    'COLUMNNAME', sub.get('BA').get('BR_DICT').getCallback('KEYS'), ...
    varargin{:});¤

\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectCON_MP:tests,
	caption={
		{\bf SubjectCON\_MP element tests.}
		The \code{tests} section from the element generator \fn{\_SubjectCON\_MP.gen.m}. \expand{cd:m:SubjectCON:tests}
	}
 ]
¤%% ¡tests!

%%% ¡test!
%%%% ¡name!
GUI
%%%% ¡probability!
.01
%%%% ¡code!
im_ba = ImporterBrainAtlasXLS('FILE', ¤'aal90_atlas.xlsx'¤);
ba = im_ba.get('BA');

gr = Group('SUB_CLASS', ¤'SubjectCON_MP'¤, 'SUB_DICT', IndexedDictionary('IT_CLASS', ¤'SubjectCON_MP'¤));
for i = 1:1:10 
    sub = SubjectCON_MP( ...
        'ID', [¤'SUB CON_MP '¤ int2str(i)], ...
        'LABEL', [¤'Subejct CON_MP '¤ int2str(i)], ...
        'NOTES', [¤'Notes on subject CON_MP '¤ int2str(i)], ...
        'BA', ba, ...
        ¤'L', 3, ... ¥\circled{1}\circlednote{1}{ defines the number of layers.}¥
        'LAYERLABELS', {'L1' 'L2' 'L3'}, ... ¥\circled{2}\circlednote{2}{ defines the label of each layer.}¥
        'CON_MP', {rand(ba.get('BR_DICT').get('LENGTH')), rand(ba.get('BR_DICT').get('LENGTH')), rand(ba.get('BR_DICT').get('LENGTH'))} ...¤
        ); ¥\circled{3}\circlednote{3}{ constructs 3 layers randomly using connectivity matrices with size of brain regions by brain regions.}¥
    sub.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 100 * rand()))
    sub.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', randi(2, 1)))
    gr.get('SUB_DICT').get('ADD', sub)
end

gui = GUIElement('PE', gr, 'CLOSEREQ', false);
gui.get('DRAW')
gui.get('SHOW')

gui.get('CLOSE')
\end{lstlisting}

\clearpage

\section{Implementation of importer and exporter (for \code{SubjectCON})}

\subsection{Importer from TXT (\code{ImporterGroupSubjectCON\_TXT})}

You will start by implementing in detail \code{ImporterGroupSubjectCON\_TXT}. The data should be stored in the folder \fn{Group1} and \fn{Group2}, and the file format is \fn{.txt}.

\begin{lstlisting}[
	label=cd:m:ImporterGroupSubjectCON_TXT:header,
	caption={
		{\bf ImporterGroupSubjectCON\_TXT element header.}
		The \code{header} section of the generator code in \fn{\_ImporterGroupSubjectCON\_TXT.gen.m} provides the general information about the \code{Importer} element.
		}
]
%% ¡header!
ImporterGroupSubjectCON_TXT < Importer (im, importer of CON subject group from TXT) imports a group of subjects with connectivity data from a series of TXT files. ¥\circled{1}\circlednote{1}{ The element \code{ImporterGroupSubjectCON\_TXT} is defined as a subclass of \code{Importer}. The moniker will be \code{im}.}¥

%%% ¡description!
ImporterGroupSubjectCON_XLS imports a group of subjects with connectivity data from a series of XLS/XLSX files contained in a folder named "GROUP_ID". All these files must be in the same folder; also, no other files should be in the folder. Each file contains a table of values corresponding to the adjacency matrix. The variables of interest are from another XLS/XLSX file named "GROUP_ID.vois.xlsx" (if exisitng) consisting of the following columns: Subject ID (column 1), covariates (subsequent columns). The 1st row contains the headers, the 2nd row a string with the categorical variables of interest, and each subsequent row the values for each subject.

%%% ¡seealso!
Group, SunbjectCON, ExporterGroupSubjectCON_TXT

%%% ¡build!
1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:ImporterGroupSubjectCON_TXT:prop_update,
	caption={
		{\bf ImporterGroupSubjectCON\_TXT element props update.}
		The \code{props\_update} section of the generator code in \fn{\_ImporterGroupSubjectCON\_TXT.gen.m} updates the properties of the \code{Importer} element.
	}
]
%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the CON subject group importer from TXT.
%%%% ¡default!
'ImporterGroupSubjectCON_TXT'

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the CON subject group importer from TXT.
%%%% ¡default!
'ImporterGroupSubjectCON_TXT imports a group of subjects with connectivity data from a series of TXT file and their covariates (optional) from another TXT file.'

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the CON subject group importer from TXT.
%%%% ¡settings!
'ImporterGroupSubjectCON_TXT'

%%% ¡prop!
ID (data, string) is a few-letter code for the CON subject group importer from TXT.
%%%% ¡default!
'ImporterGroupSubjectCON_TXT ID'

%%% ¡prop!
LABEL (metadata, string) is an extended label of the CON subject group importer from TXT.
%%%% ¡default!
'ImporterGroupSubjectCON_TXT label'

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the CON subject group importer from TXT.
%%%% ¡default!
'ImporterGroupSubjectCON_TXT notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:ImporterGroupSubjectCON_TXT:props,
	caption={
		{\bf ImporterGroupSubjectCON\_TXT element props.}
		The \code{props} section of the generator code in \fn{\_ImporterGroupSubjectCON\_TXT.gen.m} defines the specific properties of the \code{ImporterGroupSubjectCON\_TXT} element.
	}
]
%% ¡props!

%%% ¡prop!
DIRECTORY (data, string) is the directory containing the CON subject group files from which to load the subject group. 
%%%% ¡default!
fileparts(which('test_braph2'))

%%% ¡prop!
GET_DIR (query, item) opens a dialog box to set the directory from where to load the TXT files of the CON subject group.
%%%% ¡settings!
'ImporterGroupSubjectCON_TXT'
%%%% ¡calculate!
directory = uigetdir('Select directory'); ¥\circled{1}\circlednote{1}{ selects the directory that contains the TXT data.}¥
if ischar(directory) && isfolder(directory)
	im.set('DIRECTORY', directory); ¥\circled{2}\circlednote{2}{ saves the directory into the \code{'DIRECTORY'} property of \code{im}.}¥
end
value = im;

%%% ¡prop!
BA (data, item) is a brain atlas.
%%%% ¡settings!
'BrainAtlas'

%%% ¡prop!
GR (result, item) is a group of subjects with connectivity data.
%%%% ¡settings!
'Group'
%%%% ¡check_value!
check = any(strcmp(value.get(Group.SUB_CLASS_TAG), subclasses('SubjectCON', [], [], true))); ¥\circled{3}\circlednote{3}{ checks that the class of subjects of the group is \code{SubjectCON}.}¥
%%%% ¡default!
Group('SUB_CLASS', 'SubjectCON', 'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON')) ¥\circled{4}\circlednote{4}{ represents a group of subjects whose class is defined in the property \code{'SUB\_CLASS'}. \code{'SUB\_DICT'} manages the subjects as an indexed dictionary of subjects.}¥
%%%% ¡calculate! ¥\circled{5}\circlednote{5}{ constructs an empty \code{Group}.}¥
gr = Group( ...
    'SUB_CLASS', 'SubjectCON', ...
    'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON') ...
    );

gr.lock('SUB_CLASS'); ¥\circled{6}\circlednote{6}{ locks the property \code{'SUB\_CLASS'} irreversibly.}¥

directory = im.get('DIRECTORY'); ¥\circled{7}\circlednote{7}{ returns the data directory that has been saved at \circled{2}.}¥
if isfolder(directory) ¥\circled{8}\circlednote{8}{ checks that directory exists.}¥
    wb = braph2waitbar(im.get('WAITBAR'), 0, 'Reading directory ...'); ¥\circled{9}\circlednote{9}{ creates the waitbar with an initial progress of \code{0} displaying \code{'Reading directory ...'}.}¥
    
    [~, name] = fileparts(directory); ¥\circled{10}\circlednote{10}{ extracts the directory name from its complete path.}¥
    gr.set( ... ¥\circled{11}\circlednote{11}{ sets the properties \code{'ID'}, \code{'LABEL'} and \code{'NOTES'} for the group.}¥
        'ID', name, ...
        'LABEL', name, ...
        'NOTES', ['Group loaded from ' directory] ...
        );

    try
        braph2waitbar(wb, .15, 'Loading subjecy group ...')

        % analyzes directory
        files = dir(fullfile(directory, '*.txt')); ¥\circled{12}\circlednote{12}{ finds all \fn{.txt} files in the \code{directory}.}¥

        if ~isempty(files) 
            % brain atlas
            ba = im.get('BA'); ¥\circled{13}\circlednote{13}{ returns the brain atlas.}¥
            if ba.get('BR_DICT').get('LENGTH') == 0 ¥\circled{14}\circlednote{14}{ checks that the number of nodes in brain atlas is equal to 0.}¥
                br_number = size(readtable(fullfile(directory, files(1).name), 'Delimiter', '\t'), 1); ¥\circled{15}\circlednote{15}{ adds the number of regions of the first file to the brain atlas.}¥
                br_dict = ba.memorize('BR_DICT');
                for j = 1:1:br_number
                    br_dict.get('ADD', BrainRegion('ID', ['br' int2str(j)])) ¥\circled{16}\circlednote{16}{ adds the \code{'ID'} of each brain region.}¥
                end
            end

            % adds subjects
            sub_dict = gr.memorize('SUB_DICT'); ¥\circled{17}\circlednote{17}{ adds the subject to the group.}¥
            for i = 1:1:length(files)
                braph2waitbar(wb, .15 + .85 * i / length(files), ['Loading subject ' num2str(i) ' of ' num2str(length(files)) ' ...']) ¥\circled{18}\circlednote{18}{ updates the waitbar for each file.}¥

		% read file
                [~, sub_id] = fileparts(files(i).name);
                CON = table2array(readtable(fullfile(directory, files(i).name), 'Delimiter', '\t')); ¥\circled{19}\circlednote{19}{ reads each file with a delimiter specified in \code{Delimiter}.}¥
                if size(CON, 1) ~= ba.get('BR_DICT').get('LENGTH') || size(CON, 2) ~= ba.get('BR_DICT').get('LENGTH') ¥\circled{20}\circlednote{20}{ checks that the number of the nodes in the file is equal to the number of nodes in the brain atlas.}¥
                    error( ...
                        [BRAPH2.STR ':' class(im) ':' BRAPH2.ERR_IO], ...
                        [BRAPH2.STR ':' class(im) ':' BRAPH2.ERR_IO '\\n' ...
                        'The file ' sub_id ' should contain a matrix ' int2str(ba.get('BR_DICT').get('LENGTH')) 'x' int2str(ba.get('BR_DICT').get('LENGTH')) ', ' ...
                        'while it is ' int2str(size(CON, 1)) 'x' int2str(size(CON, 2)) '.'] ...
                        )¥\circled{21}\circlednote{21}{ outputs the error information.}¥
                end
                
                sub = SubjectCON( ...
                    'ID', sub_id, ...
                    'BA', ba, ...
                    'CON', CON ...
                );
                sub_dict.get('ADD', sub);
            end
            
            % variables of interest
            if isfile([directory '.vois.txt']) ¥\circled{22}\circlednote{22}{ adds the variables of interest (\code{vois}).}¥
                vois = textread([directory '.vois.txt'], '%s', 'delimiter', '\t', 'whitespace', ''); ¥\circled{23}\circlednote{23}{ reads the file \code{*.vois.txt}.}¥
                vois = reshape(vois, find(strcmp('', vois), 1) - 1, [])'; ¥\circled{24}\circlednote{24}{ reshapes the \code{vois}.}¥
                for i = 3:1:size(vois, 1)
                    sub_id = vois{i, 1};
                    sub = sub_dict.get('IT', sub_id);
                    for v = 2:1:size(vois, 2)
                        voi_id = vois{1, v};
                        if isempty(vois{2, v}) ¥\circled{25}\circlednote{25}{ checks whether the variable is is numeric.}¥
                            sub.memorize('VOI_DICT').get('ADD', ...
                                VOINumeric( ...
                                    'ID', voi_id, ...
                                    'V', str2num(vois{i, v}) ...
                                    ) ...
                                ); ¥\circled{26}\circlednote{26}{ adds the variable of interest with \code{'ID'} and value \code{'V'}.}¥
                        elseif ~isempty(vois{2, v}) ¥\circled{27}\circlednote{27}{ checks whether the variable is categorical.}¥
                            categories = eval(vois{2, v});
                            sub.memorize('VOI_DICT').get('ADD', ...
                                VOICategoric( ...
                                    'ID', voi_id, ...
                                    'CATEGORIES', str2cell(categories), ...
                                    'V', find(strcmp(vois{i, v}, categories)) ...
                                    ) ...
                                );
                        end                        
                    end
                end
            end
        end
    catch e
        braph2waitbar(wb, 'close')
        
        rethrow(e)
    end
    
	braph2waitbar(wb, 'close') ¥\circled{28}\circlednote{28}{ closes the waitbar.}¥
else
    error([BRAPH2.STR ':ImporterGroupSubjectCON_TXT:' BRAPH2.ERR_IO], ...
        [BRAPH2.STR ':ImporterGroupSubjectCON_TXT:' BRAPH2.ERR_IO '\\n' ...
        'The prop DIRECTORY must be an existing directory, but it is ''' directory '''.'] ...
        );
end

value = gr;
\end{lstlisting}

\begin{lstlisting}[	label=cd:m:ImporterGroupSubjectCON_TXT:tests,
	caption={
		{\bf ImporterGroupSubjectCON\_TXT element tests.}
		The \code{tests} section from the element generator \fn{\_ImporterGroupSubjectCON\_TXT.gen.m}. In this section, some example data are created for testing.
	}
]
%% ¡tests!

%%% ¡excluded_props! ¥\circled{1}\circlednote{1}{ List of properties that are excluded from testing.}¥
[ImporterGroupSubjectCON_TXT.GET_DIR]

%%% ¡test!
%%%% ¡name!
Create example files ¥\circled{2}\circlednote{2}{ creates the example files.}¥
%%%% ¡code!
data_dir = [fileparts(which('SubjectCON')) filesep 'Example data CON TXT']; ¥\circled{3}\circlednote{3}{ defines the directory \code{'Example data CON TXT'} where the example data will be contained.}¥
if ~isdir(data_dir)
    mkdir(data_dir); ¥\circled{4}\circlednote{4}{ creates the directory for the example data.}¥

    % Brain Atlas
    im_ba = ImporterBrainAtlasTXT('FILE', 'desikan_atlas.txt'); ¥\circled{5}\circlednote{5}{ imports the brain atlas.}¥
    ba = im_ba.get('BA');
    ex_ba = ExporterBrainAtlasTXT( ... ¥\circled{6}\circlednote{6}{ exports the brain atlas as file 'atlas.txt'.}¥
        'BA', ba, ...
        'FILE', [data_dir filesep() 'atlas.txt'] ...
        );
    ex_ba.get('SAVE')
    N = ba.get('BR_DICT').get('LENGTH'); ¥\circled{7}\circlednote{7}{ returns the number of brain regions.}¥

    % saves RNG
    rng_settings_ = rng(); rng('default') ¥\circled{8}\circlednote{8}{ sets the random number generator (\code{rng}) to \code{'default'}.}¥

    sex_options = {'Female' 'Male'};

    % Group 1 ¥\circled{9}\circlednote{9}{ generates the data for group1.}¥
    K1 = 2; ¥\circled{10}\circlednote{10}{ assigns the degree (mean node degree is 2) for group 1.}¥
    beta1 = 0.3; ¥\circled{11}\circlednote{11}{ assigns the rewiring probability for group 1.}¥
    gr1_name = 'CON_Group_1_TXT';
    gr1_dir = [data_dir filesep() gr1_name];
    mkdir(gr1_dir);
    vois1 = [ ¥\circled{12}\circlednote{12}{ assigns the header with \code{'Subject ID'}, \code{'Age'}, and \code{'Sex'}.}¥
        {{'Subject ID'} {'Age'} {'Sex'}}
        {{} {} {['{' sprintf(' ''%s'' ', sex_options{:}) '}']}}
        ];
    for i = 1:1:50 % subject number ¥\circled{13}\circlednote{13}{ generates 50 subjects.}¥
        sub_id = ['SubjectCON_MP_' num2str(i)];

        h1 = WattsStrogatz(N, K1, beta1); ¥\circled{14}\circlednote{14}{ creates a Watts-Strogatz graph.}¥  

        A1 = full(adjacency(h1)); A1(1:length(A1)+1:numel(A1)) = 0; ¥\circled{15}\circlednote{15}{ extracts the adjacency matrix.}¥ 
        r = 0 + (0.5 - 0)*rand(size(A1)); diffA = A1 - r; A1(A1 ~= 0) = diffA(A1 ~= 0); ¥\circled{16}\circlednote{16}{ makes the adjacency matrix weighted.}¥
        A1 = max(A1, transpose(A1)); ¥\circled{17}\circlednote{17}{ makes the adjacency matrix symmetric.}¥

        writetable(array2table(A1), [gr1_dir filesep() sub_id '.txt'], 'Delimiter', '\t', 'WriteVariableNames', false) ¥\circled{18}\circlednote{18}{ writes the matrix into the file.}¥

        vois1 = [vois1; {sub_id, randi(90), sex_options(randi(2))}]; ¥\circled{19}\circlednote{19}{ creates the variables of interest.}¥
    end
    writetable(table(vois1), [data_dir filesep() gr1_name '.vois.txt'], 'Delimiter', '\t', 'WriteVariableNames', false) ¥\circled{20}\circlednote{20}{ writes the variables of interest.}¥

    % Group 2 ¥\circled{21}\circlednote{21}{ generates the data for group 2.}¥  
    K2 = 2; 
    beta2 = 0.85;
    gr2_name = 'CON_Group_2_TXT';
    gr2_dir = [data_dir filesep() gr2_name];
    mkdir(gr2_dir);
    vois2 = [
        {{'Subject ID'} {'Age'} {'Sex'}}
        {{} {} {['{' sprintf(' ''%s'' ', sex_options{:}) '}']}}
        ];
    for i = 51:1:100
        sub_id = ['SubjectCON_MP_' num2str(i)];

        h2 = WattsStrogatz(N, K2, beta2);

        A2 = full(adjacency(h2)); A2(1:length(A2)+1:numel(A2)) = 0;
        r = 0 + (0.5 - 0)*rand(size(A2)); diffA = A2 - r; A2(A2 ~= 0) = diffA(A2 ~= 0);
        A2 = max(A2, transpose(A2));

        writetable(array2table(A2), [gr2_dir filesep() 'SubjectCON_' num2str(i) '.txt'], 'Delimiter', '\t', 'WriteVariableNames', false)

        % variables of interest
        vois2 = [vois2; {sub_id, randi(90), sex_options(randi(2))}];
    end
    writetable(table(vois2), [data_dir filesep() gr2_name '.vois.txt'], 'Delimiter', '\t', 'WriteVariableNames', false)

    % reset RNG
    rng(rng_settings_) ¥\circled{22}\circlednote{22}{ resets random number generator.}¥  
end

%%% ¡test_functions! 
function h = WattsStrogatz(N,K,beta) ¥\circled{23}\circlednote{23}{ defines a function named \code{WattsStrogatz} that takes three input arguments: \code{N} (number of nodes), \code{K} (number of neighbors for each node), and \code{beta} (rewiring probability).}¥
% H = WattsStrogatz(N,K,beta) returns a Watts-Strogatz model graph with N
% nodes, N*K edges, mean node degree 2*K, and rewiring probability beta.
%
% beta = 0 is a ring lattice, and beta = 1 is a random graph.

% Connect each node to its K next and previous neighbors. This constructs
% indices for a ring lattice.
s = repelem((1:N)',1,K); ¥\circled{24}\circlednote{24}{ creates a matrix \code{s} where each row corresponds to a node, and each column contains the node's number repeated K times.}¥
t = s + repmat(1:K,N,1);  ¥\circled{25}\circlednote{25}{ calculates the target nodes for each node in the ring lattice.}¥
t = mod(t-1,N)+1; ¥\circled{26}\circlednote{26}{ ensures that the indices wrap around, creating a circular lattice.}¥

for source=1:N ¥\circled{27}\circlednote{27}{ rewires the target node of each edge with probability \code{beta}.}¥
    switchEdge = rand(K, 1) < beta; ¥\circled{28}\circlednote{28}{ determines which edges should be rewired based on the probability \code{beta}.}¥

    newTargets = rand(N, 1); ¥\circled{29}\circlednote{29}{ to \circled{30} determines the new target nodes for the edges that are being rewired, ensuring that the new target is not the source node itself or any of its current neighbors.}¥
    newTargets(source) = 0;
    newTargets(s(t==source)) = 0; 
    newTargets(t(source, ~switchEdge)) = 0; 
    
    [~, ind] = sort(newTargets, 'descend');
    t(source, switchEdge) = ind(1:nnz(switchEdge)); ¥\circled{30}¥
end

h = graph(s,t); ¥\circled{31}\circlednote{31}{ creates a graph \code{h} from the source nodes \code{s} and target nodes \code{t}.}¥
end

%%% ¡test!
%%%% ¡name!
GUI
%%%% ¡probability!
.01
%%%% ¡code!
im_ba = ImporterBrainAtlasTXT('FILE', [fileparts(which('SubjectCON')) filesep 'Example data CON TXT' filesep 'atlas.txt']);
ba = im_ba.get('BA');

im_gr = ImporterGroupSubjectCON_TXT( ... ¥\circled{32}\circlednote{32}{ imports the txt file of each subject in the group.}¥
    'DIRECTORY', [fileparts(which('SubjectCON')) filesep 'Example data CON TXT' filesep 'CON_Group_1_TXT'], ...
    'BA', ba, ...
    'WAITBAR', true ...
    );
gr = im_gr.get('GR'); ¥\circled{33}\circlednote{33}{ returns a group of subjects with connectivity data.}¥

gui = GUIElement('PE', gr, 'CLOSEREQ', false); ¥\circled{34}\circlednote{34}{ assigns the panel element without requiring close confirmation.}¥
gui.get('DRAW')
gui.get('SHOW')

gui.get('CLOSE')
\end{lstlisting}

\clearpage

\subsection{Importer from XLS/XLSX (\code{ImporterGroupSubjectCON\_XLS})}

You will now see how to implement in detail \code{ImporterGroupSubjectCON\_XLS} modifying \code{ImporterGroupSubjectCON\_TXT}. The data should be stored in the folders \fn{Group1} and \fn{Group2}, and the file format is \fn{.xls} or \fn{.xlsx}.

\begin{lstlisting}[
	label=cd:m:ImporterGroupSubjectCON_XLS:header,
	caption={
		{\bf ImporterGroupSubjectCON\_XLS element header.}
		The \code{header} section of the generator code in \fn{\_ImporterGroupSubjectCON\_XLS.gen.m} provides the general information about the \code{Importer} element. \expand{cd:m:ImporterGroupSubjectCON_TXT:header}
		}
]
¤%% ¡header!
¤ImporterGroupSubjectCON_XLS¤ < Importer (im, ¤importer of CON subject group from XLS/XLSX) imports a group of subjects with connectivity data from a series of XLS/XLSX file.¤

%%% ¡description!
¤ImporterGroupSubjectCON_XLS imports a group of subjects with connectivity data from a series of XLS/XLSX files contained in a folder named "GROUP_ID". All these files must be in the same folder; also, no other files should be in the folder. Each file contains a table of values corresponding to the adjacency matrix. The variables of interest are from another XLS/XLSX file named "GROUP_ID.vois.xlsx" (if exisitng) consisting of the following columns: Subject ID (column 1), covariates (subsequent columns). The 1st row contains the headers, the 2nd row a string with the categorical variables of interest, and each subsequent row the values for each subject.¤

%%% ¡seealso!
Group, SubjectCON, ¤ExporterGroupSubjectCON_XLS¤

%%% ¡build!
¤1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:ImporterGroupSubjectCON_XLS:prop_update,
	caption={
		{\bf ImporterGroupSubjectCON\_XLS element props update.}
		The \code{props\_update} section of the generator code in \fn{\_ImporterGroupSubjectCON\_XLS.gen.m} updates the properties of the \code{Importer} element. \expand{cd:m:ImporterGroupSubjectCON_TXT:prop_update}
	}
]
¤%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the CON subject group importer from ¤XLS/XLSX¤.
%%%% ¡default!
¤'ImporterGroupSubjectCON_XLS'¤

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the CON subject group importer from ¤XLS/XLSX¤.
%%%% ¡default!
¤'ImporterGroupSubjectCON_XLS imports a group of subjects with connectivity data from a series of XLS/XLSX file. The variables of interest can be loaded from another XLS/XLSX file.'¤

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the CON subject group importer from ¤XLS/XLSX¤.
%%%% ¡settings!
¤'ImporterGroupSubjectCON_XLS'¤

%%% ¡prop!
ID (data, string) is a few-letter code for the CON subject group importer from ¤XLS/XLSX¤.
%%%% ¡default!
¤'ImporterGroupSubjectCON_XLS ID'¤

%%% ¡prop!
LABEL (metadata, string) is an extended label of the CON subject group importer from ¤XLS/XLSX¤.
%%%% ¡default!
¤'ImporterGroupSubjectCON_XLS label'¤

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the CON subject group importer from ¤XLS/XLSX¤.
%%%% ¡default!
¤'ImporterGroupSubjectCON_XLS notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:ImporterGroupSubjectCON_XLS:props,
	caption={
		{\bf ImporterGroupSubjectCON\_XLS element props.}
		The \code{props} section of the generator code in \fn{\_ImporterGroupSubjectCON\_XLS.gen.m} defined the properties specific for \code{ImporterGroupSubjectCON\_XLS}. \expand{cd:m:ImporterGroupSubjectCON_TXT:prop_update}
	}
]
¤%% ¡props!

%%% ¡prop!
DIRECTORY (data, string) is the directory containing the CON subject group files from which to load the subject group.
%%%% ¡default!
fileparts(which('test_braph2'))

%%% ¡prop!
GET_DIR (query, item) opens a dialog box to set the directory from where to load the ¤XLS/XLSX¤ files of the CON subject group.
%%%% ¡settings!
¤'ImporterGroupSubjectCON_XLS'¤
%%%% ¡calculate!
directory = uigetdir('Select directory');
if ischar(directory) && isfolder(directory)
    im.set('DIRECTORY', directory);
end
value = im;

%%% ¡prop!
BA (data, item) is a brain atlas.
%%%% ¡settings!
'BrainAtlas'

%%% ¡prop!
GR (result, item) is a group of subjects with connectivity data.
%%%% ¡settings!
'Group'
%%%% ¡check_value!
check = any(strcmp(value.get(Group.SUB_CLASS_TAG), subclasses('SubjectCON', [], [], true))); ¥\circled{1}\circlednote{1}{ Same as in note \circled{3} of \Coderef{cd:m:ImporterGroupSubjectCON_TXT:prop_update}.}¥
%%%% ¡default!
Group('SUB_CLASS', 'SubjectCON', 'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON')) ¥\circled{2}\circlednote{2}{ Same as in note \circled{4} of \Coderef{cd:m:ImporterGroupSubjectCON_TXT:prop_update}.}¥
%%%% ¡calculate! ¥\circled{3}\circlednote{3}{ Same as in note \circled{5} to \circled{28} in \Coderef{cd:m:ImporterGroupSubjectCON_TXT:prop_update}.}¥
gr = Group( ...
    'SUB_CLASS', 'SubjectCON', ...
    'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON') ...
    );

gr.lock('SUB_CLASS');

directory = im.get('DIRECTORY');
if isfolder(directory)
    wb = braph2waitbar(im.get('WAITBAR'), 0, 'Reading directory ...');
    
    [~, gr_name] = fileparts(directory);
    gr.set( ...
        'ID', gr_name, ...
        'LABEL', gr_name, ...
        'NOTES', ['Group loaded from ' directory] ...
        );

    try
        braph2waitbar(wb, .15, 'Loading subject group ...')
        
        % analyzes directory
        files = [dir(fullfile(directory, ¤'*.xlsx'¤)); dir(fullfile(directory, ¤'*.xls'¤))];
        
        if ~isempty(files)
            % brain atlas
            ba = im.get('BA');
            if ba.get('BR_DICT').get('LENGTH') == 0
                br_number = size(¤xlsread(fullfile(directory, files(1).name))¤, 1);
                br_dict = ba.memorize('BR_DICT');
                for j = 1:1:br_number
                    br_dict.get('ADD', BrainRegion('ID', ['br' int2str(j)]))
                end
            end

            % adds subjects
            sub_dict = gr.memorize('SUB_DICT');
            for i = 1:1:length(files)
                braph2waitbar(wb, .15 + .85 * i / length(files), ['Loading subject ' num2str(i) ' of ' num2str(length(files)) ' ...'])

                % read file
                [~, sub_id] = fileparts(files(i).name);
                
                ¤CON = xlsread(fullfile(directory, files(i).name));¤
                if size(CON, 1) ~= ba.get('BR_DICT').get('LENGTH') || size(CON, 2) ~= ba.get('BR_DICT').get('LENGTH')
                    error( ...
                        [BRAPH2.STR ':' class(im) ':' BRAPH2.ERR_IO], ...
                        [BRAPH2.STR ':' class(im) ':' BRAPH2.ERR_IO '\\n' ...
                        'The file ' sub_id ' should contain a matrix ' int2str(ba.get('BR_DICT').get('LENGTH')) 'x' int2str(ba.get('BR_DICT').get('LENGTH')) ', ' ...
                        'while it is ' int2str(size(CON, 1)) 'x' int2str(size(CON, 2)) '.'] ...
                        )
                end
                
                sub = SubjectCON( ...
                    'ID', sub_id, ...
                    'BA', ba, ...
                    'CON', CON ...
                );
                sub_dict.get('ADD', sub);
            end
            
            % variables of interest
            ¤vois = [];
            if isfile([directory '.vois.xls'])
                [~, ~, vois] = xlsread([directory '.vois.xls']);
            elseif isfile([directory '.vois.xlsx'])
                [~, ~, vois] = xlsread([directory '.vois.xlsx']);
            end
            if ~isempty(vois)¤
                for i = 3:1:size(vois, 1)
                    sub_id = vois{i, 1};
                    sub = sub_dict.get('IT', sub_id);
                    for v = 2:1:size(vois, 2)
                        voi_id = vois{1, v};
                        if isnumeric(vois{2, v}) % VOINumeric
                            sub.memorize('VOI_DICT').get('ADD', ...
                                VOINumeric( ...
                                    'ID', voi_id, ...
                                    'V', vois{i, v} ...
                                    ) ...
                                );
                        elseif ischar(vois{2, v}) % VOICategoric
                            sub.memorize('VOI_DICT').get('ADD', ...
                                VOICategoric( ...
                                    'ID', voi_id, ...
                                    'CATEGORIES', str2cell(vois{2, v}), ...
                                    'V', find(strcmp(vois{i, v}, str2cell(vois{2, v}))) ...
                                    ) ...
                                );
                        end                        
                    end
                end
            end
        end
    catch e
        braph2waitbar(wb, 'close')
        
        rethrow(e)
    end
    
    braph2waitbar(wb, 'close')
else
    error([BRAPH2.STR ':¤ImporterGroupSubjectCON_XLS¤:' BRAPH2.ERR_IO], ...
        [BRAPH2.STR ':¤ImporterGroupSubjectCON_XLS¤:' BRAPH2.ERR_IO '\\n' ...
        'The prop DIRECTORY must be an existing directory, but it is ''' directory '''.'] ...
        );
end

value = gr;
\end{lstlisting}

\clearpage
\begin{lstlisting}[	label=cd:m:ImporterGroupSubjectCON_XLS:tests,
	caption={
		{\bf ImporterGroupSubjectCON\_XLS element tests.}
		The \code{tests} section from the element generator \fn{\_ImporterGroupSubjectCON\_XLS.gen.m}. \expand{cd:m:ImporterGroupSubjectCON_TXT:tests}
	}
]
¤%% ¡tests!

%%% ¡excluded_props!
¤[ImporterGroupSubjectCON_XLS.GET_DIR]¤

%%% ¡test!
%%%% ¡name!
Create example files
%%%% ¡code!
¤data_dir = [fileparts(which('SubjectCON')) filesep 'Example data CON XLS'];¤
if ~isdir(data_dir)
    mkdir(data_dir);

    % Brain Atlas
    im_ba = ImporterBrainAtlasXLS('FILE', 'desikan_atlas.xlsx');
    ba = im_ba.get('BA');
    ex_ba = ExporterBrainAtlasXLS( ...
        'BA', ba, ...
        'FILE', [data_dir filesep() 'atlas.xlsx'] ...
        );
    ex_ba.get('SAVE')
    N = ba.get('BR_DICT').get('LENGTH');

    % saves RNG
    rng_settings_ = rng(); rng('default')

    sex_options = {'Female' 'Male'};

    % Group 1
    K1 = 2; 
    beta1 = 0.3; 
    gr1_name = ¤'CON_Group_1_XLS'¤;
    gr1_dir = [data_dir filesep() gr1_name];
    mkdir(gr1_dir);
    vois1 = [
        {{'Subject ID'} {'Age'} {'Sex'}}
        {{} {} cell2str(sex_options)}
        ];
    for i = 1:1:50 % subject number
        sub_id = ['SubjectCON_' num2str(i)];

        h1 = WattsStrogatz(N, K1, beta1); % create two WS graph

        A1 = full(adjacency(h1)); A1(1:length(A1)+1:numel(A1)) = 0; 
        r = 0 + (0.5 - 0)*rand(size(A1)); diffA = A1 - r; A1(A1 ~= 0) = diffA(A1 ~= 0); 
        A1 = max(A1, transpose(A1)); % make the adjacency matrix symmetric

        writetable(array2table(A1), [gr1_dir filesep() sub_id ¤'.xlsx'¤], 'WriteVariableNames', false)
        vois1 = [vois1; {sub_id, randi(90), sex_options(randi(2))}];
    end
    writetable(table(vois1), [data_dir filesep() gr1_name ¤'.vois.xlsx'¤], 'WriteVariableNames', false)

    % Group 2
    K2 = 2; 
    beta2 = 0.85; 
    gr2_name = ¤'CON_Group_2_XLS'¤;
    gr2_dir = [data_dir filesep() gr2_name];
    mkdir(gr2_dir);
    vois2 = [
        {{'Subject ID'} {'Age'} {'Sex'}}
        {{} {} cell2str(sex_options)}
        ];
    for i = 51:1:100
        sub_id = ['SubjectCON_' num2str(i)];

        h2 = WattsStrogatz(N, K2, beta2);
        % figure(2)
        % plot(h2, 'NodeColor',[1 0 0], 'EdgeColor',[0 0 0], 'EdgeAlpha',0.1, 'Layout','circle');
        % title(['Group 2: Graph with $N = $ ' num2str(N_nodes) ...
        %     ' nodes, $K = $ ' num2str(K2) ', and $\beta = $ ' num2str(beta2)], ...
        %     'Interpreter','latex')
        % axis equal

        A2 = full(adjacency(h2)); A2(1:length(A2)+1:numel(A2)) = 0;
        r = 0 + (0.5 - 0)*rand(size(A2)); diffA = A2 - r; A2(A2 ~= 0) = diffA(A2 ~= 0);
        A2 = max(A2, transpose(A2));

        writetable(array2table(A2), [gr2_dir filesep() sub_id ¤'.xlsx'¤], 'WriteVariableNames', false)

        % variables of interest
        vois2 = [vois2; {sub_id, randi(90), sex_options(randi(2))}];
    end
    writetable(table(vois2), [data_dir filesep() gr2_name ¤'.vois.xlsx'¤], 'WriteVariableNames', false)

    % reset RNG
    rng(rng_settings_)
end

%%% ¡test_functions!
function h = WattsStrogatz(N,K,beta)
% H = WattsStrogatz(N,K,beta) returns a Watts-Strogatz model graph with N
% nodes, N*K edges, mean node degree 2*K, and rewiring probability beta.
%
% beta = 0 is a ring lattice, and beta = 1 is a random graph.

% Connect each node to its K next and previous neighbors. This constructs
% indices for a ring lattice.
s = repelem((1:N)',1,K);
t = s + repmat(1:K,N,1);
t = mod(t-1,N)+1;

% Rewire the target node of each edge with probability beta
for source=1:N
    switchEdge = rand(K, 1) < beta;
    
    newTargets = rand(N, 1);
    newTargets(source) = 0;
    newTargets(s(t==source)) = 0;
    newTargets(t(source, ~switchEdge)) = 0;
    
    [~, ind] = sort(newTargets, 'descend');
    t(source, switchEdge) = ind(1:nnz(switchEdge));
end

h = graph(s,t);
end

%%% ¡test!
%%%% ¡name!
GUI
%%%% ¡probability!
.01
%%%% ¡code!
¤im_ba = ImporterBrainAtlasXLS('FILE', [fileparts(which('SubjectCON')) filesep 'Example data CON XLS' filesep 'atlas.xlsx']);¤
ba = im_ba.get('BA');

¤im_gr = ImporterGroupSubjectCON_XLS( ...
    'DIRECTORY', [fileparts(which('SubjectCON')) filesep 'Example data CON XLS' filesep 'CON_Group_1_XLS'], ...¤
    'BA', ba, ...
    'WAITBAR', true ...
    );
gr = im_gr.get('GR');

gui = GUIElement('PE', gr, 'CLOSEREQ', false);
gui.get('DRAW')
gui.get('SHOW')

gui.get('CLOSE')

\end{lstlisting}

\clearpage

\subsection{Exporter to TXT (\code{ExporterGroupSubjectCON\_TXT})}

In this section, you will see how to implement in detail \code{ExporterGroupSubjectCON\_TXT}. The data will be stored in the folders \fn{Group1} and \fn{Group2}, and the file format is \fn{*.txt}.

\begin{lstlisting}[
	label=cd:m:ExporterGroupSubjectCON_TXT:header,
	caption={
		{\bf ExporterGroupSubjectCON\_TXT element header.}
		The \code{header} section of the generator code in \fn{\_ExporterGroupSubjectCON\_TXT.gen.m} provides the general information about the \code{ExporterGroupSubjectCON\_TXT} element.
		}
]
%% ¡header!
ExporterGroupSubjectCON_TXT < Exporter (ex, exporter of CON subject group in TXT) exports a group of subjects with connectivity data to a series of TXT file. ¥\circled{1}\circlednote{1}{ The element \code{ExporterGroupSubjectCON\_TXT} is defined as a subclass of \code{Exporter}. The moniker will be \code{ex}.}¥

%%% ¡description!
ExporterGroupSubjectCON_TXT exports a group of subjects with connectivity data to a series of tab-separated TXT files contained in a folder named "GROUP_ID". All these files are saved in the same folder. Each file contains a table of values corresponding to the adjacency matrix. The variables of interest (if existing) are saved in another tab-separated TXT file named "GROUP_ID.vois.txt" consisting of the following columns: Subject ID (column 1), covariates (subsequent columns). The 1st row contains the headers, the 2nd row a string with the categorical variables of interest, and each subsequent row the values for each subject.

%%% ¡seealso!
Group, SunbjectCON, ExporterGroupSubjectCON_TXT

%%% ¡bluid!
1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:ExporterGroupSubjectCON_TXT:prop_update,
	caption={
		{\bf ExporterGroupSubjectCON\_TXT element props update.}
		The \code{props\_update} section of the generator code in \fn{\_ExporterGroupSubjectCON\_TXT.gen.m} updates the properties of the \code{Exporter} element.
	}
]
%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the CON subject group exporter in TXT.
%%%% ¡default!
'ExporterGroupSubjectCON_TXT'

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the CON subject group exporter in TXT.
%%%% ¡default!
'ExporterGroupSubjectCON_TXT exports a group of subjects with connectivity data to a series of TXT file and their covariates age and sex (if existing) to another TXT file.'

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the CON subject group exporter in TXT.
%%%% ¡settings!
'ExporterGroupSubjectCON_TXT'

%%% ¡prop!
ID (data, string) is a few-letter code for the CON subject group exporter in TXT.
%%%% ¡default!
'ExporterGroupSubjectCON_TXT ID'

%%% ¡prop!
LABEL (metadata, string) is an extended label of the CON subject group exporter in TXT.
%%%% ¡default!
'ExporterGroupSubjectCON_TXT label'

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the CON subject group exporter in TXT.
%%%% ¡default!
'ExporterGroupSubjectCON_TXT notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:ExporterGroupSubjectCON_TXT:props,
	caption={
		{\bf ExporterGroupSubjectCON\_TXT element props.}
		The \code{props} section of the generator code in \fn{\_ExporterGroupSubjectCON\_TXT.gen.m} defines the properties specific for the \code{ExporterGroupSubjectCON\_TXT} element.
	}
]
%% ¡props!

%%% ¡prop!
GR (data, item) is a group of subjects with connectivity data. 
%%%% ¡settings!
'Group'
%%%% ¡check_value!
check = any(strcmp(value.get(Group.SUB_CLASS_TAG), subclasses('SubjectCON', [], [], true))); ¥\circled{1}\circlednote{1}{ checks that the \code{SUB\_CLASS\_TAG} is equal to \code{'SubjectCON'}.}¥
%%%% ¡default!
Group('SUB_CLASS', 'SubjectCON', 'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON'))

%%% ¡prop!
DIRECTORY (data, string) is the directory name where to save the group of subjects with connectivity data.
%%%% ¡default!
[fileparts(which('test_braph2')) filesep 'default_group_subjects_CON_most_likely_to_be_erased']  ¥\circled{2}\circlednote{2}{ defines the export directory.}¥

%%% ¡prop!
PUT_DIR (query, item) opens a dialog box to set the directory where to save the group of subjects with connectivity data.
%%%% ¡settings!
'ExporterGroupSubjectCON_TXT'
%%%% ¡calculate!
directory = uigetdir('Select directory'); ¥\circled{3}\circlednote{3}{ selects the export directory.}¥
if ischar(directory) && isfolder(directory) ¥\circled{4}\circlednote{4}{ checks the export directory before setting it.}¥
	ex.set('DIRECTORY', directory);
end
value = ex;

%%% ¡prop!
SAVE (result, empty) saves the group of subjects with connectivity data in TXT files in the selected directory.
%%%% ¡calculate!
directory = ex.get('DIRECTORY');

if isfolder(directory) ¥\circled{5}\circlednote{5}{ checks the export directory is a folder.}¥
    wb = braph2waitbar(ex.get('WAITBAR'), 0, 'Retrieving path ...'); ¥\circled{6}\circlednote{6}{ creates the waitbar with an initial progress of \code{0}. Displaying the character \code{'Retrieving path ...'}.}¥
    
    gr = ex.get('GR');

    gr_directory = [directory filesep() gr.get('ID')];
    if ~exist(gr_directory, 'dir')
        mkdir(gr_directory)
    end
    
    braph2waitbar(wb, .15, 'Organizing info ...')
    
    sub_dict = gr.get('SUB_DICT');
    sub_number = sub_dict.get('LENGTH');
    
    for i = 1:1:sub_number
        braph2waitbar(wb, .15 + .85 * i / sub_number, ['Saving subject ' num2str(i) ' of ' num2str(sub_number) '...']) ¥\circled{7}\circlednote{7}{ updates the waitbar.}¥
        
        sub = sub_dict.get('IT', i); ¥\circled{8}\circlednote{8}{ extracts the information of one subject.}¥
        sub_id = sub.get('ID'); ¥\circled{9}\circlednote{9}{ extracts the \code{'ID'} of the subject.}¥
        sub_CON = sub.get('CON'); ¥\circled{10}\circlednote{10}{ extracts the \code{'CON'} of the subject.}¥

        tab = table(sub_CON); ¥\circled{11}\circlednote{11}{ changes the matrix to type of table.}¥

        sub_file = [gr_directory filesep() sub_id '.txt'];

        % save file
        writetable(tab, sub_file, 'Delimiter', '\t', 'WriteVariableNames', false); ¥\circled{12}\circlednote{12}{ writes the table to txt file.}¥
    end
    
    % variables of interest
    voi_ids = {};
    for i = 1:1:sub_number
        sub = sub_dict.get('IT', i);
        voi_ids = unique([voi_ids, sub.get('VOI_DICT').get('KEYS')]); ¥\circled{13}\circlednote{13}{ extracts the keys of the variables of interest.}¥
    end
    if ~isempty(voi_ids)
        vois = cell(2 + sub_number, 1 + length(voi_ids));
        vois{1, 1} = 'Subject ID';
        vois(1, 2:end) = voi_ids;
        for i = 1:1:sub_number
            sub = sub_dict.get('IT', i);
            vois{2 + i, 1} = sub.get('ID');
            
            voi_dict = sub.get('VOI_DICT');
            for v = 1:1:voi_dict.get('LENGTH') ¥\circled{14}\circlednote{14}{ saves the value of each variable of interest.}¥
                voi = voi_dict.get('IT', v);
                voi_id = voi.get('ID');
                if isa(voi, 'VOINumeric') % Numeric
                    vois{2 + i, 1 + find(strcmp(voi_id, voi_ids))} = voi.get('V');
                elseif isa(voi, 'VOICategoric') % Categoric
                    categories = voi.get('CATEGORIES');
                    vois{2, 1 + find(strcmp(voi_id, voi_ids))} = {['{' sprintf(' ''%s'' ', categories{:}) '}']}; 
                    vois{2 + i, 1 + find(strcmp(voi_id, voi_ids))} = categories{voi.get('V')};
                end
            end
        end
        writetable(table(vois), [gr_directory '.vois.txt'], 'Delimiter', '\t', 'WriteVariableNames', false) ¥\circled{15}\circlednote{15}{ writes the table of variable of interest to txt file.}¥
    end
    
    braph2waitbar(wb, 'close') ¥\circled{16}\circlednote{16}{ closes the waitbar.}¥
end
value = [];

\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:ExporterGroupSubjectCON_TXT:tests,
	caption={
		{\bf ExporterGroupSubjectCON\_TXT element tests.}
		The \code{tests} section from the element generator \fn{\_ExporterGroupSubjectCON\_TXT.gen.m}.
	}
]
%% ¡tests!

%%% ¡excluded_props! ¥\circled{1}\circlednote{1}{ List of properties that are excluded from testing.}¥
[ExporterGroupSubjectCON_TXT.PUT_DIR]

%%% ¡test!
%%%% ¡name!
Delete directory TBE ¥\circled{2}\circlednote{2}{ deletes the example files.}¥
%%%% ¡probability!
1
%%%% ¡code!
warning('off', 'MATLAB:DELETE:FileNotFound')
dir_to_be_erased = ExporterGroupSubjectCON_TXT.getPropDefault('DIRECTORY');
if isfolder(dir_to_be_erased)
    rmdir(dir_to_be_erased, 's')
end
warning('on', 'MATLAB:DELETE:FileNotFound')

%%% ¡test!
%%%% ¡name!
Export and import ¥\circled{3}\circlednote{3}{ tests importer and exporter functions.}¥
%%%% ¡probability!
.01
%%%% ¡code!
br1 = BrainRegion( ... ¥\circled{4}\circlednote{4}{ creates the \code{BrainRegion} with \code{'ID'}, \code{'LABEL'}, \code{'NOTES'}, \code{'X'}, \code{'Y'}, and \code{'Z'}.}¥
    'ID', 'ISF', ...
    'LABEL', 'superiorfrontal', ...
    'NOTES', 'notes1', ...
    'X', -12.6, ...
    'Y', 22.9, ...
    'Z', 42.4 ...
    );
br2 = BrainRegion( ...
    'ID', 'lFP', ...
    'LABEL', 'frontalpole', ...
    'NOTES', 'notes2', ...
    'X', -8.6, ...
    'Y', 61.7, ...
    'Z', -8.7 ...
    );
br3 = BrainRegion( ...
    'ID', 'lRMF', ...
    'LABEL', 'rostralmiddlefrontal', ...
    'NOTES', 'notes3', ...
    'X', -31.3, ...
    'Y', 41.2, ...
    'Z', 16.5 ...
    );
br4 = BrainRegion( ...
    'ID', 'lCMF', ...
    'LABEL', 'caudalmiddlefrontal', ...
    'NOTES', 'notes4', ...
    'X', -34.6, ...
    'Y', 10.2, ...
    'Z', 42.8 ...
    );
br5 = BrainRegion( ...
    'ID', 'lPOB', ...
    'LABEL', 'parsorbitalis', ...
    'NOTES', 'notes5', ...
    'X', -41, ...
    'Y', 38.8, ...
    'Z', -11.1 ...
    );

ba = BrainAtlas( ...
    'ID', 'TestToSaveCoolID', ...
    'LABEL', 'Brain Atlas', ...
    'NOTES', 'Brain atlas notes', ...
    'BR_DICT', IndexedDictionary('IT_CLASS', 'BrainRegion', 'IT_LIST', {br1, br2, br3, br4, br5}) ... ¥\circled{5}\circlednote{5}{ merges the 5 created brain regions as the \code{BrainAtlas}.}¥
    );

sub1 = SubjectCON( ... ¥\circled{6}\circlednote{6}{ creates the \code{SubjectCON} with \code{'ID'}, \code{'LABEL'}, \code{'NOTES'}, \code{'BA'}, and \code{'CON'}.}¥
    'ID', 'SUB CON 1', ...
    'LABEL', 'Subejct CON 1', ...
    'NOTES', 'Notes on subject CON 1', ...
    'BA', ba, ...
    'CON', rand(ba.get('BR_DICT').get('LENGTH')) ...
    );
sub1.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 75)) ¥\circled{7}\circlednote{7}{ adds the variables of interest \code{'Age'}.}¥
sub1.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', find(strcmp('Female', {'Female', 'Male'})))) ¥\circled{8}\circlednote{8}{ adds the variables of interest \code{'Sex'}.}¥

sub2 = SubjectCON( ...
    'ID', 'SUB CON 2', ...
    'LABEL', 'Subejct CON 2', ...
    'NOTES', 'Notes on subject CON 2', ...
    'BA', ba, ...
    'CON', rand(ba.get('BR_DICT').get('LENGTH')) ...
    );
sub2.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 70))
sub2.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', find(strcmp('Male', {'Female', 'Male'}))))

sub3 = SubjectCON( ...
    'ID', 'SUB CON 3', ...
    'LABEL', 'Subejct CON 3', ...
    'NOTES', 'Notes on subject CON 3', ...
    'BA', ba, ...
    'CON', rand(ba.get('BR_DICT').get('LENGTH')) ...
    );
sub3.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 50))
sub3.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', find(strcmp('Female', {'Female', 'Male'}))))

gr = Group( ...
    'ID', 'GR CON', ...
    'LABEL', 'Group label', ...
    'NOTES', 'Group notes', ...
    'SUB_CLASS', 'SubjectCON', ...
    'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON', 'IT_LIST', {sub1, sub2, sub3}) ... ¥\circled{9}\circlednote{9}{ merges the 3 created subjects as the \code{Group}.}¥
    );

directory = [fileparts(which('test_braph2')) filesep 'trial_group_subjects_CON_to_be_erased']; ¥\circled{10}\circlednote{10}{ defines the directory of data.}¥
if ~exist(directory, 'dir')
    mkdir(directory)
end

ex = ExporterGroupSubjectCON_TXT( ... ¥\circled{11}\circlednote{11}{ exports the txt files of data.}¥
    'DIRECTORY', directory, ...
    'GR', gr ...
    );
ex.get('SAVE');

im1 = ImporterGroupSubjectCON_TXT( ... ¥\circled{12}\circlednote{12}{ imports the txt files of data.}¥
    'DIRECTORY', [directory filesep() gr.get(Group.ID)], ...
    'BA', ba ...
    );
gr_loaded1 = im1.get('GR');

assert(gr.get('SUB_DICT').get('LENGTH') == gr_loaded1.get('SUB_DICT').get('LENGTH'), ...
	[BRAPH2.STR ':ExporterGroupSubjectCON_TXT:' BRAPH2.FAIL_TEST], ...
    'Problems saving or loading a group.') ¥\circled{13}\circlednote{13}{ checks the size of data is same and get the wrong information if having.}¥
for i = 1:1:max(gr.get('SUB_DICT').get('LENGTH'), gr_loaded1.get('SUB_DICT').get('LENGTH')) ¥\circled{14}\circlednote{14}{ checks each property is same.}¥
    sub = gr.get('SUB_DICT').get('IT', i);
    sub_loaded = gr_loaded1.get('SUB_DICT').get('IT', i);    
    assert( ...¥\circled{15}\circlednote{15}{ checks the properties \code{'ID'}, \code{'BA'}, \code{'Age'}, \code{'Sex'} and \code{'CON'},] between loaded data and saved data are same.}¥
        isequal(sub.get('ID'), sub_loaded.get('ID')) & ...
        isequal(sub.get('BA'), sub_loaded.get('BA')) & ... 
        isequal(sub.get('VOI_DICT').get('IT', 'Age').get('V'), sub_loaded.get('VOI_DICT').get('IT', 'Age').get('V')) & ... 
        isequal(sub.get('VOI_DICT').get('IT', 'Sex').get('V'), sub_loaded.get('VOI_DICT').get('IT', 'Sex').get('V')) & ...
        isequal(round(sub.get('CON'), 10), round(sub_loaded.get('CON'), 10)), ...
        [BRAPH2.STR ':ExporterGroupSubjectCON_TXT:' BRAPH2.FAIL_TEST], ...
        'Problems saving or loading a group.')    
end


im2 = ImporterGroupSubjectCON_TXT( ... ¥\circled{16}\circlednote{16}{ checks the data in group 2. Same as note in \circled{12} to \circled{15}}¥
    'DIRECTORY', [directory filesep() gr.get(Group.ID)] ...
    );
gr_loaded2 = im2.get('GR');

assert(gr.get('SUB_DICT').get('LENGTH') == gr_loaded2.get('SUB_DICT').get('LENGTH'), ...
	[BRAPH2.STR ':ExporterGroupSubjectCON_TXT:' BRAPH2.FAIL_TEST], ...
    'Problems saving or loading a group.')
for i = 1:1:max(gr.get('SUB_DICT').get('LENGTH'), gr_loaded2.get('SUB_DICT').get('LENGTH'))
    sub = gr.get('SUB_DICT').get('IT', i);
    sub_loaded = gr_loaded2.get('SUB_DICT').get('IT', i);
    assert( ...
        isequal(sub.get('ID'), sub_loaded.get('ID')) & ...
        ~isequal(sub.get('BA').get('ID'), sub_loaded.get('BA').get('ID')) & ...
        isequal(sub.get('VOI_DICT').get('IT', 'Age').get('V'), sub_loaded.get('VOI_DICT').get('IT', 'Age').get('V')) & ... 
        isequal(sub.get('VOI_DICT').get('IT', 'Sex').get('V'), sub_loaded.get('VOI_DICT').get('IT', 'Sex').get('V')) & ...
        isequal(round(sub.get('CON'), 10), round(sub_loaded.get('CON'), 10)), ...
        [BRAPH2.STR ':ExporterGroupSubjectCON_TXT:' BRAPH2.FAIL_TEST], ...
        'Problems saving or loading a group.')    
end

rmdir(directory, 's') ¥\circled{17}\circlednote{17}{ deletes the testing data.}¥
\end{lstlisting}

\clearpage

\subsection{Exporter to XLS/XLSX (\code{ExporterGroupSubjectCON\_XLS})}

In this section, you will see how to implement in detail \code{ExporterGroupSubjectCON\_XLS} modifying \code{ExporterGroupSubjectCON\_TXT}. The data should be stored in the folder 'Group1' and 'Group2', and the file format is '.txt'.

\begin{lstlisting}[
	label=cd:m:ExporterGroupSubjectCON_XLS:header,
	caption={
		{\bf ExporterGroupSubjectCON\_XLS element header.}
		The \code{header} section of the generator code in \fn{\_ExporterGroupSubjectCON\_XLS.gen.m} provides the general information about the \code{Exporter} element. \expand{cd:m:ExporterGroupSubjectCON_TXT:header}
		}
]
¤%% ¡header!
¤ExporterGroupSubjectCON_XLS < Exporter (ex, exporter of CON subject group in XLSX) exports a group of subjects with connectivity data to a series of XLSX file.¤

%%% ¡description!
¤ExporterGroupSubjectCON_XLS exports a group of subjects with connectivity data to a series of XLSX files contained in a folder named "GROUP_ID". All these files are saved in the same folder. Each file contains a table of values corresponding to the adjacency matrix.The variables of interest (if existing) are saved in another XLSX file  named "GROUP_ID.vois.xlsx" consisting of the following columns: Subject ID (column 1), covariates (subsequent columns). The 1st row contains the headers, the 2nd row a string with the categorical variables of interest, and each subsequent row the values for each subject.¤

%%% ¡seealso!
Group, SunbjectCON, ¤ImporterGroupSubjectCON_XLS¤

%%% ¡build!
¤1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:ExporterGroupSubjectCON_XLS:prop_update,
	caption={
		{\bf ExporterGroupSubjectCON\_XLS element props update.}
		The \code{props\_update} section of the generator code in \fn{\_ExporterGroupSubjectCON\_XLS.gen.m} updates the properties of the \code{Exporter} element. \expand{cd:m:ExporterGroupSubjectCON_TXT:prop_update}
	}
]
¤%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the CON subject group exporter in ¤XLSX¤.
%%%% ¡default!
¤'ExporterGroupSubjectCON_XLS'¤

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the CON subject group exporter in ¤XLSX¤.
%%%% ¡default!
¤'ExporterGroupSubjectCON_XLS exports a group of subjects with connectivity data to a series of XLSX files. The variables of interest (if existing) are saved in another XLSX file.'¤

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the CON subject group exporter in ¤XLSX¤.
%%%% ¡settings!
¤'ExporterGroupSubjectCON_XLS'¤

%%% ¡prop!
ID (data, string) is a few-letter code for the CON subject group exporter in ¤XLSX¤.
%%%% ¡default!
¤'ExporterGroupSubjectCON_XLS ID'¤

%%% ¡prop!
LABEL (metadata, string) is an extended label of the CON subject group exporter in ¤XLSX¤.
%%%% ¡default!
¤'ExporterGroupSubjectCON_XLS label'¤

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the CON subject group exporter in ¤XLSX¤.
%%%% ¡default!
¤'ExporterGroupSubjectCON_XLS notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:ExporterGroupSubjectCON_XLS:props,
	caption={
		{\bf ExporterGroupSubjectCON\_XLS element props.}
		The \code{props} section of the generator code in \fn{\_ExporterGroupSubjectCON\_XLS.gen.m} defines the properties specific for the \code{ExporterGroupSubjectCON\_XLS} element. \expand{cd:m:ExporterGroupSubjectCON_TXT:props}
	}
]
¤%% ¡props!

%%% ¡prop!
GR (data, item) is a group of subjects with connectivity data.
%%%% ¡settings!
'Group'
%%%% ¡check_value!
check = any(strcmp(value.get(Group.SUB_CLASS_TAG), subclasses('SubjectCON', [], [], true))); % Format.checkFormat(Format.ITEM, value, 'Group') already checked
%%%% ¡default! ¥\circled{1}\circlednote{1}{ Same as in note \circled{1} of \Coderef{cd:m:ExporterGroupSubjectCON_TXT:prop_update}.}¥
Group('SUB_CLASS', 'SubjectCON', 'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON'))

%%% ¡prop!
DIRECTORY (data, string) is the directory name where to save the group of subjects with connectivity data.
%%%% ¡default!
[fileparts(which('test_braph2')) filesep 'default_group_subjects_CON_most_likely_to_be_erased']

%%% ¡prop!
PUT_DIR (query, item) opens a dialog box to set the directory where to save the group of subjects with connectivity data.
%%%% ¡settings!
¤'ExporterGroupSubjectCON_XLS'¤
%%%% ¡calculate!
directory = uigetdir('Select directory');
if ischar(directory) && isfolder(directory)
    ex.set('DIRECTORY', directory);
end
value = ex;

%%% ¡prop!
SAVE (result, empty) saves the group of subjects with connectivity data in ¤XLSX¤ files in the selected directory.
%%%% ¡calculate!
directory = ex.get('DIRECTORY');

if isfolder(directory) ¥\circled{2}\circlednote{2}{ Same as in note \circled{4} to \circled{17} in \Coderef{cd:m:ExporterGroupSubjectCON_TXT:prop_update}.}¥
    wb = braph2waitbar(ex.get('WAITBAR'), 0, 'Retrieving path ...');
    
    gr = ex.get('GR');

    gr_directory = [directory filesep() gr.get('ID')];
    if ~exist(gr_directory, 'dir')
        mkdir(gr_directory)
    end
    
	braph2waitbar(wb, .15, 'Organizing info ...')
    
    sub_dict = gr.get('SUB_DICT');
    sub_number = sub_dict.get('LENGTH');

    for i = 1:1:sub_number
        braph2waitbar(wb, .15 + .85 * i / sub_number, ['Saving subject ' num2str(i) ' of ' num2str(sub_number) ' ...'])
        
        sub = sub_dict.get('IT', i);
        sub_id = sub.get('ID');
        sub_CON = sub.get('CON');
        
        tab = table(sub_CON);

        sub_file = [gr_directory filesep() sub_id ¤'.xlsx'¤];

        % save file
        writetable(tab, sub_file, 'WriteVariableNames', false);
    end
    
    % variables of interest
    voi_ids = {};
    for i = 1:1:sub_number
        sub = sub_dict.get('IT', i);
        voi_ids = unique([voi_ids, sub.get('VOI_DICT').get('KEYS')]);
    end
    if ~isempty(voi_ids)
        vois = cell(2 + sub_number, 1 + length(voi_ids));
        vois{1, 1} = 'Subject ID';
        vois(1, 2:end) = voi_ids;
        for i = 1:1:sub_number
            sub = sub_dict.get('IT', i);
            vois{2 + i, 1} = sub.get('ID');
            
            voi_dict = sub.get('VOI_DICT');
            for v = 1:1:voi_dict.get('LENGTH')
                voi = voi_dict.get('IT', v);
                voi_id = voi.get('ID');
                if isa(voi, 'VOINumeric') % Numeric
                    vois{2 + i, 1 + find(strcmp(voi_id, voi_ids))} = voi.get('V');
                elseif isa(voi, 'VOICategoric') % Categoric
                    categories = voi.get('CATEGORIES');
                    vois{2, 1 + find(strcmp(voi_id, voi_ids))} = cell2str(categories);
                    vois{2 + i, 1 + find(strcmp(voi_id, voi_ids))} = categories{voi.get('V')};
                end
            end
        end
        writetable(table(vois), [gr_directory ¤'.vois.xlsx'¤], 'WriteVariableNames', false)
    end

    braph2waitbar(wb, 'close')
end

value = [];
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:ExporterGroupSubjectCON_XLS:tests,
	caption={
		{\bf ExporterGroupSubjectCON\_XLS element tests.}
		The \code{tests} section from the element generator \fn{\_ExporterGroupSubjectCON\_XLS.gen.m}. \expand{cd:m:ExporterGroupSubjectCON_TXT:tests}
	}
]
¤%% ¡tests!

%%% ¡excluded_props!
¤[ExporterGroupSubjectCON_XLS.PUT_DIR]¤

%%% ¡test!
%%%% ¡name!
Delete directory TBE
%%%% ¡probability!
1
%%%% ¡code!
warning('off', 'MATLAB:DELETE:FileNotFound')
dir_to_be_erased = ¤ExporterGroupSubjectCON_XLS¤.getPropDefault('DIRECTORY');
if isfolder(dir_to_be_erased)
    rmdir(dir_to_be_erased, 's')
end
warning('on', 'MATLAB:DELETE:FileNotFound')

%%% ¡test!
%%%% ¡name!
Export and import
%%%% ¡probability!
.01
%%%% ¡code!
br1 = BrainRegion( ...
    'ID', 'ISF', ...
    'LABEL', 'superiorfrontal', ...
    'NOTES', 'notes1', ...
    'X', -12.6, ...
    'Y', 22.9, ...
    'Z', 42.4 ...
    );
br2 = BrainRegion( ...
    'ID', 'lFP', ...
    'LABEL', 'frontalpole', ...
    'NOTES', 'notes2', ...
    'X', -8.6, ...
    'Y', 61.7, ...
    'Z', -8.7 ...
    );
br3 = BrainRegion( ...
    'ID', 'lRMF', ...
    'LABEL', 'rostralmiddlefrontal', ...
    'NOTES', 'notes3', ...
    'X', -31.3, ...
    'Y', 41.2, ...
    'Z', 16.5 ...
    );
br4 = BrainRegion( ...
    'ID', 'lCMF', ...
    'LABEL', 'caudalmiddlefrontal', ...
    'NOTES', 'notes4', ...
    'X', -34.6, ...
    'Y', 10.2, ...
    'Z', 42.8 ...
    );
br5 = BrainRegion( ...
    'ID', 'lPOB', ...
    'LABEL', 'parsorbitalis', ...
    'NOTES', 'notes5', ...
    'X', -41, ...
    'Y', 38.8, ...
    'Z', -11.1 ...
    );

ba = BrainAtlas( ...
    'ID', 'TestToSaveCoolID', ...
    'LABEL', 'Brain Atlas', ...
    'NOTES', 'Brain atlas notes', ...
    'BR_DICT', IndexedDictionary('IT_CLASS', 'BrainRegion', 'IT_LIST', {br1, br2, br3, br4, br5}) ...
    );

sub1 = SubjectCON( ...
    'ID', 'SUB CON 1', ...
    'LABEL', 'Subejct CON 1', ...
    'NOTES', 'Notes on subject CON 1', ...
    'BA', ba, ...
    'CON', rand(ba.get('BR_DICT').get('LENGTH')) ...
    );
sub1.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 75))
sub1.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', find(strcmp('Female', {'Female', 'Male'}))))

sub2 = SubjectCON( ...
    'ID', 'SUB CON 2', ...
    'LABEL', 'Subejct CON 2', ...
    'NOTES', 'Notes on subject CON 2', ...
    'BA', ba, ...
    'CON', rand(ba.get('BR_DICT').get('LENGTH')) ...
    );
sub2.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 70))
sub2.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', find(strcmp('Male', {'Female', 'Male'}))))

sub3 = SubjectCON( ...
    'ID', 'SUB CON 3', ...
    'LABEL', 'Subejct CON 3', ...
    'NOTES', 'Notes on subject CON 3', ...
    'BA', ba, ...
    'CON', rand(ba.get('BR_DICT').get('LENGTH')) ...
    );
sub3.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 50))
sub3.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', find(strcmp('Female', {'Female', 'Male'}))))

gr = Group( ...
    'ID', 'GR CON', ...
    'LABEL', 'Group label', ...
    'NOTES', 'Group notes', ...
    'SUB_CLASS', 'SubjectCON', ...
    'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON', 'IT_LIST', {sub1, sub2, sub3}) ...
    );

directory = [fileparts(which('test_braph2')) filesep 'trial_group_subjects_CON_to_be_erased'];
if ~exist(directory, 'dir')
    mkdir(directory)
end

ex = ¤ExporterGroupSubjectCON_XLS¤( ...
    'DIRECTORY', directory, ...
    'GR', gr ...
    );
ex.get('SAVE');

im1 = ¤ImporterGroupSubjectCON_XLS¤( ...
    'DIRECTORY', [directory filesep() gr.get(Group.ID)], ...
    'BA', ba ...
    );
gr_loaded1 = im1.get('GR');

assert(gr.get('SUB_DICT').get('LENGTH') == gr_loaded1.get('SUB_DICT').get('LENGTH'), ...
	[BRAPH2.STR ':¤ExporterGroupSubjectCON_XLS¤:' BRAPH2.FAIL_TEST], ...
    'Problems saving or loading a group.')
for i = 1:1:max(gr.get('SUB_DICT').get('LENGTH'), gr_loaded1.get('SUB_DICT').get('LENGTH'))
    sub = gr.get('SUB_DICT').get('IT', i);
    sub_loaded = gr_loaded1.get('SUB_DICT').get('IT', i);    
    assert( ...
        isequal(sub.get('ID'), sub_loaded.get('ID')) & ...
        isequal(sub.get('BA'), sub_loaded.get('BA')) & ... 
        isequal(sub.get('VOI_DICT').get('IT', 'Age').get('V'), sub_loaded.get('VOI_DICT').get('IT', 'Age').get('V')) & ... 
        isequal(sub.get('VOI_DICT').get('IT', 'Sex').get('V'), sub_loaded.get('VOI_DICT').get('IT', 'Sex').get('V')) & ...
        isequal(sub.get('CON'), sub_loaded.get('CON')), ...
        [BRAPH2.STR ':¤ExporterGroupSubjectCON_XLS¤:' BRAPH2.FAIL_TEST], ...
        'Problems saving or loading a group.')    
end

% import with new brain atlas
im2 = ¤ImporterGroupSubjectCON_XLS¤( ...
    'DIRECTORY', [directory filesep() gr.get(Group.ID)] ...
    );
gr_loaded2 = im2.get('GR');

assert(gr.get('SUB_DICT').get('LENGTH') == gr_loaded2.get('SUB_DICT').get('LENGTH'), ...
	[BRAPH2.STR ':¤ExporterGroupSubjectCON_XLS¤:' BRAPH2.FAIL_TEST], ...
    'Problems saving or loading a group.')
for i = 1:1:max(gr.get('SUB_DICT').get('LENGTH'), gr_loaded2.get('SUB_DICT').get('LENGTH'))
    sub = gr.get('SUB_DICT').get('IT', i);
    sub_loaded = gr_loaded2.get('SUB_DICT').get('IT', i);    
    assert( ...
        isequal(sub.get('ID'), sub_loaded.get('ID')) & ...
        ~isequal(sub.get('BA').get('ID'), sub_loaded.get('BA').get('ID')) & ...
        isequal(sub.get('VOI_DICT').get('IT', 'Age').get('V'), sub_loaded.get('VOI_DICT').get('IT', 'Age').get('V')) & ... 
        isequal(sub.get('VOI_DICT').get('IT', 'Sex').get('V'), sub_loaded.get('VOI_DICT').get('IT', 'Sex').get('V')) & ...
        isequal(sub.get('CON'), sub_loaded.get('CON')), ...
        [BRAPH2.STR ':¤ExporterGroupSubjectCON_XLS:' BRAPH2.FAIL_TEST], ...
        'Problems saving or loading a group.')    
end

rmdir(directory, 's')
\end{lstlisting}

\clearpage

\section{Implementation of a subject with functional data}

\subsection{Subject with functional data (\code{SubjectFUN})}

In this section, you will see how to implement in detail \code{SubjectFUN}, which holds timeseries data such as those obtained from fMRI.

\begin{lstlisting}[
	label=cd:m:SubjectFUN:header,
	caption={
		{\bf SubjectFUN element header.}
		The \code{header} section of the generator code in \fn{\_SubjectFUN.gen.m} provides the general information about the \code{SubjectFUN} element.\expand{cd:m:SubjectCON:header}
		}
]
¤%% ¡header!¤
SubjectFUN ¤< Subject (sub, ¤subject with functional matrix) is a subject with functional matrix (e.g. fMRI).¤

%%% ¡description!
¤Subject with a functional matrix (e.g. obtained from fMRI).¤

%%% ¡seealso!
¤ImporterGroupSubjectFUN_TXT, ExporterGroupSubjectFUN_TXT, ImporterGroupSubjectFUN_XLS, ExporterGroupSubjectFUN_XLS¤

%%% ¡build!
¤1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectFUN:prop_update,
	caption={
		{\bf SubjectFUN element props update.}
		The \code{props\_update} section of the generator code in \fn{\_SubjectFUN.gen.m} updates the properties of the \code{Subject} element. \expand{cd:m:SubjectCON:prop_update}
	}
]
¤%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the subject.
%%%% ¡default!
¤'SubjectFUN'¤

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the subject.
%%%% ¡default!
¤'Subject with a functional matrix (e.g. obtained from fMRI).'¤

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the subject.
%%% ¡settings!
¤'SubjectFUN'¤

%%% ¡prop!
ID (data, string) is a few-letter code for the subject.
%%%% ¡default!
¤'SubjectFUN ID'¤

%%% ¡prop!
LABEL (metadata, string) is an extended label of the subject.
%%%% ¡default!
¤'SubjectFUN label'¤

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the subject.
%%%% ¡default!
¤'SubjectFUN notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectFUN:props,
	caption={
		{\bf SubjectFUN element props.}
		The \code{props} section of the generator code in \fn{\_SubjectFUN.gen.m} defines the  properties specific for the \code{SubjectFUN} element. \expand{cd:m:SubjectCON:props}
	}
]
¤%% ¡props!

%%% ¡prop!
BA (data, item) is a brain atlas.
%%%% ¡settings!
'BrainAtlas'

%%% ¡prop!
¤FUN¤ (data, ¤matrix¤) is an adjacency matrix.
%%%% ¡check_value!
br_number = sub.get('BA').get('BR_DICT').get('LENGTH');
¤check = size(value, 2) == br_number; ¥\circled{1}\circlednote{1}{ checks the size of the column of \code{value} is equal to the number of brain regions. The rows of \code{value} represent the time series.}¥¤
if check
    msg = 'All ok!';
else   
    ¤msg = ['FUN must be a matrix with the same number of columns as the brain regions (' int2str(br_number) ').'];¤
end
%%%% ¡gui! ¥\circled{2}\circlednote{2}{ Same as in note \circled{4} of \Coderef{cd:m:SubjectCON:prop_update}.}¥
pr = PanelPropMatrix('EL', sub, 'PROP', ¤SubjectFUN.FUN¤, ...
    ¤'ROWNAME', {'numbered'}, ...¤
    'COLUMNNAME', sub.get('BA').get('BR_DICT').getCallback('KEYS'), ...
    varargin{:});
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectFUN:tests,
	caption={
		{\bf SubjectFUN element tests.}
		The \code{tests} section from the element generator \fn{\_SubjectFUN.gen.m}. \expand{cd:m:SubjectCON:tests}
	}
]
¤%% ¡tests!

%%% ¡test!
%%%% ¡name!
GUI
%%%% ¡probability!
.01
%%%% ¡code!
im_ba = ImporterBrainAtlasXLS('FILE', ¤'aal90_atlas.xlsx'¤);
ba = im_ba.get('BA');

gr = Group('SUB_CLASS', ¤'SubjectFUN'¤, 'SUB_DICT', IndexedDictionary('IT_CLASS', ¤'SubjectFUN'¤));
for i = 1:1:50
    sub = ¤SubjectFUN¤( ...
        'ID', [¤'SUB FUN '¤ int2str(i)], ...
        'LABEL', [¤'Subejct FUN '¤ int2str(i)], ...
        'NOTES', [¤'Notes on subject FUN '¤ int2str(i)], ...
        'BA', ba, ...
        ¤'FUN', rand(10, ba.get('BR_DICT').get('LENGTH')) ...¥\circled{1}\circlednote{1}{ constructs the random adjacency matrix with the size of 10 timepoints by the number of brain regions.}¥¤
        );
    sub.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 100 * rand()))
    sub.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', randi(2, 1)))
    gr.get('SUB_DICT').get('ADD', sub)
end

gui = GUIElement('PE', gr, 'CLOSEREQ', false);
gui.get('DRAW')
gui.get('SHOW')

gui.get('CLOSE')
\end{lstlisting}

\clearpage

\subsection{Subject with functional multiplex data (\code{SubjectFUN\_MP})}

In this section, you will see how to implement in detail \code{SubjectFUN\_MP}, which can hold, for example, multilayer fMRI data.

\begin{lstlisting}[
	label=cd:m:SubjectFUN_MP:header,
	caption={
		{\bf SubjectFUN\_MP element header.}
		The \code{header} section of the generator code in \fn{\_SubjectFUN\_MP.gen.m} provides the general information about the \code{SubjectFUN\_MP} element. \expand{cd:m:SubjectCON_MP:header}
		}
]
¤%% ¡header!
¤SubjectFUN_MP¤ < Subject (sub, ¤subject with functional multiplex data) is a subject with functional multiplex data (e.g. multiplex fMRI)¤.

%%% ¡description!
¤Subject with data for each brain region corresponding to L functional layers (e.g. activation timeseries obtaiend from fMRI or EEG).¤

%%% ¡seealso!
¤ImporterGroupSubjectFUN_MP_TXT, ExporterGroupSubjectFUN_MP_TXT, ImporterGroupSubjectFUN_MP_XLS, ExporterGroupSubjectFUN_MP_XLS¤

%%% ¡build!
¤1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectFUN_MP:prop_update,
	caption={
		{\bf SubjectFUN\_MP element props update.}
		The \code{props\_update} section of the generator code in \fn{\_SubjectFUN\_MP.gen.m} updates the properties of the \code{Subject} element. \expand{cd:m:SubjectCON_MP:prop_update}
	}
]
¤%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the subject.
%%%% ¡default!
¤'SubjectFUN_MP'¤

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the subject.
%%%% ¡default!
¤'Subject with data for each brain region corresponding to L functional layers (e.g. activation timeseries obtaiend from fMRI or EEG).'¤

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the subject.
%%% ¡settings!
¤'SubjectFUN_MP'¤

%%% ¡prop!
ID (data, string) is a few-letter code for the subject.
%%%% ¡default!
¤'SubjectFUN_MP ID'¤

%%% ¡prop!
LABEL (metadata, string) is an extended label of the subject.
%%%% ¡default!
¤'SubjectFUN_MP label'¤

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the subject.
%%%% ¡default!
¤'SubjectFUN_MP notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectFUN_MP:props,
	caption={
		{\bf SubjectFUN\_MP element props.}
		The \code{props} section of the generator code in \fn{\_SubjectFUN\_MP.gen.m} defines the properties specific for the \code{SubjectFUN\_MP} element. \expand{cd:m:SubjectCON_MP:props}
	}
]
¤%% ¡props!

%%% ¡prop!
BA (data, item) is a brain atlas.
%%%% ¡settings!
'BrainAtlas'

%%% ¡prop!
L (data, scalar) is the number of layers of subject data. ¥\circled{1}\circlednote{1}{ Same as in note \circled{1} of \Coderef{cd:m:SubjectCON_MP:prop_update}.}¥
%%%% ¡default!
2

%%% ¡prop!
LAYERLABELS (metadata, stringlist) are the layer labels provided by the user. ¥\circled{2}\circlednote{2}{ Same as in note \circled{2} of \Coderef{cd:m:SubjectCON_MP:prop_update}.}¥

%%% ¡prop!
ALAYERLABELS (query, stringlist) returns the processed layer labels. ¥\circled{3}\circlednote{3}{ Same as in note \circled{3} of \Coderef{cd:m:SubjectCON_MP:prop_update}.}¥
%%%% ¡calculate!
value = sub.get('LAYERLABELS');

%%% ¡prop!
¤FUN_MP (data, cell) is a cell containing L matrices with each column corresponding to the time series of a brain region.¤
%%%% ¡check_value!
br_number = sub.get('BA').get('BR_DICT').get('LENGTH');
¤num_layers = sub.get('L');
check = (iscell(value) && isequal(length(value), num_layers)  && isequal( cellfun(@(v) size(v, 2), value), ones(1, num_layers) * br_number)) || (isempty(value) && br_number == 0); ¤ ¥\circled{4}\circlednote{4}{ checks the size of each layer are equal to the number of brain regions. The size of each layer is the length of time series by the number of regions.}¥
if check
    msg = 'All ok!';
else   
    ¤msg = ['FUN_MP must be a cell with L matrices with the same number of columns as the number of brain regions (' int2str(br_number) ').'];¤
end
%%%% ¡gui! ¥\circled{5}\circlednote{5}{ Same as in notes \circled{8}---\circled{11} of \Coderef{cd:m:SubjectCON_MP:prop_update}.}¥
pr = PanelPropCell('EL', sub, 'PROP', SubjectFUN_MP.FUN_MP, ...
    'TABLE_HEIGHT', s(40), ...
    'XSLIDERSHOW', true, ...
    'XSLIDERLABELS', sub.getCallback('ALAYERLABELS'), ...
    'YSLIDERSHOW', false, ...
    'ROWNAME', {'numbered'}, ...
    'COLUMNNAME', sub.get('BA').get('BR_DICT').getCallback('KEYS'), ...
    varargin{:});¤
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectFUN_MP:tests,
	caption={
		{\bf SubjectFUN\_MP element tests.}
		The \code{tests} section from the element generator \fn{\_SubjectFUN\_MP.gen.m}. \expand{cd:m:SubjectCON_MP:tests}
	}
]
¤%% ¡tests!

%%% ¡test!
%%%% ¡name!
GUI
%%%% ¡probability!
.01
%%%% ¡code!
im_ba = ImporterBrainAtlasXLS('FILE', ¤'aal90_atlas.xlsx'¤);
ba = im_ba.get('BA');

gr = Group('SUB_CLASS', ¤'SubjectFUN_MP'¤, 'SUB_DICT', IndexedDictionary('IT_CLASS', ¤'SubjectFUN_MP'¤));
for i = 1:1:10 ¥\circled{1}\circlednote{1}{ Same as in notes \circled{1}---\circled{3} of \Coderef{cd:m:SubjectCON_MP:tests}.}¥
    sub = ¤SubjectFUN_MP¤( ...
        'ID', [¤'SUB FUN_MP '¤ int2str(i)], ...
        'LABEL', [¤'Subejct FUN_MP '¤ int2str(i)], ...
        'NOTES', [¤'Notes on subject FUN_MP '¤ int2str(i)], ...
        'BA', ba, ...
        'L', 3, ...
        'LAYERLABELS', {'L1' 'L2' 'L3'}, ...
        ¤'FUN_MP', {rand(10, ba.get('BR_DICT').get('LENGTH')), rand(10, ba.get('BR_DICT').get('LENGTH')), rand(10, ba.get('BR_DICT').get('LENGTH'))} ...¤
        );
    sub.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 100 * rand()))
    sub.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', randi(2, 1)))
    gr.get('SUB_DICT').get('ADD', sub)
end

gui = GUIElement('PE', gr, 'CLOSEREQ', false);
gui.get('DRAW')
gui.get('SHOW')

gui.get('CLOSE')¤
\end{lstlisting}

\clearpage

\section{Implementation of a subject with connectivity and functional data}

\subsection{Subject with connectivity and functional multiplex data (\code{SubjectCON\_FUN\_MP})}

In this section, you will see how to implement \code{SubjectCON\_FUN\_MP}. For example, the connectivity data can be obtained from DTI and the functional data can be obtained from fMRI.

\begin{lstlisting}[
	label=cd:m:SubjectCON_FUN_MP:header,
	caption={
		{\bf SubjectCON\_FUN\_MP element header.}
		The \code{header} section of the generator code in \fn{\_SubjectCON\_FUN\_MP.gen.m} provides the general information about the \code{SubjectCON\_FUN\_MP} element. \expand{cd:m:SubjectCON_MP:header}
		}
]
¤%% ¡header!
¤SubjectCON_FUN_MP¤ < Subject (sub, ¤subject with connectivity and functional multiplex data) is a subject with connectivity and functional multiplex data (e.g. DTI and fMRI).¤

%%% ¡description!
¤Subject with connectivity and functional data (e.g. obtained from DTI and fMRI).
The first layer contains a connectivity matrix and the second layer contains functional data.¤

%%% ¡seealso!
¤CombineGroups_CON_FUN_MP, SeparateGroups_CON_FUN_MP¤

%%% ¡build!
¤1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectCON_FUN_MP:prop_update,
	caption={
		{\bf SubjectCON\_FUN\_MP element props update.}
		The \code{props\_update} section of the generator code in \fn{\_SubjectCON\_FUN\_MP.gen.m} updates the properties of the \code{Subject} element. \expand{cd:m:SubjectCON_MP:prop_update}
	}
]
¤%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the subject.
%%%% ¡default!
¤'SubjectCON_FUN_MP'¤

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the subject.
%%%% ¡default!
'Subject with connectivity and functional data (e.g. obtained from DTI and fMRI). The first layer contains a connectivity matrix and the second layer contains functional data.'

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the subject.
%%% ¡settings!
¤'SubjectCON_FUN_MP'¤

%%% ¡prop!
ID (data, string) is a few-letter code for the subject.
%%%% ¡default!
¤'SubjectCON_FUN_MP ID'¤

%%% ¡prop!
LABEL (metadata, string) is an extended label of the subject.
%%%% ¡default!
¤'SubjectCON_FUN_MP label'¤

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the subject.
%%%% ¡default!
¤'SubjectCON_FUN_MP notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectCON_FUN_MP:props,
	caption={
		{\bf SubjectCON\_FUN\_MP element props.}
		The \code{props} section of the generator code in \fn{\_SubjectCON\_FUN\_MP.gen.m} defines the properties specific for the \code{Subject\_FUN\_MP} element. \expand{cd:m:SubjectCON_MP:props}
	}
]
¤%% ¡props!

%%% ¡prop!
BA (data, item) is a brain atlas.
%%%% ¡settings!
'BrainAtlas'

%%% ¡prop!
¤CON (data, smatrix) is an adjacency matrix.¤
%%%% ¡check_value!
br_number = sub.get('BA').get('BR_DICT').get('LENGTH');
check = isequal(size(value), [br_number, br_number]); ¥\circled{1}\circlednote{1}{ Same as in note \circled{2} of \Coderef{cd:m:SubjectCON_MP:prop_update}.}¥
if check
    msg = 'All ok!';
else   
    ¤msg = ['CON must be a square matrix with the dimension equal to the number of brain regions (' int2str(br_number) ').'];¤
end
%%%% ¡gui! ¥\circled{2}\circlednote{2}{ Same as in note \circled{4} of \Coderef{cd:m:SubjectCON_MP:prop_update}.}¥
pr = PanelPropMatrix('EL', sub, 'PROP', SubjectFUN.FUN, ...
    'ROWNAME', {'numbered'}, ...
    'COLUMNNAME', sub.get('BA').get('BR_DICT').getCallback('KEYS'), ...
    varargin{:});

\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectCON_FUN_MP:tests,
	caption={
		{\bf SubjectCON\_FUN\_MP element tests.}
		The \code{tests} section from the element generator \fn{\_SubjectCON\_FUN\_MP.gen.m}. \expand{cd:m:SubjectCON_MP:tests}
	}
]
¤%% ¡tests!

%%% ¡test!
%%%% ¡name!
GUI
%%%% ¡probability!
.01
%%%% ¡code!
im_ba = ImporterBrainAtlasXLS('FILE', ¤'desikan_atlas.xlsx'¤);
ba = im_ba.get('BA');

gr = Group('SUB_CLASS', ¤'SubjectCON_FUN_MP'¤, 'SUB_DICT', IndexedDictionary('IT_CLASS', ¤'SubjectCON_FUN_MP'¤));
for i = 1:1:50 ¥\circled{1}\circlednote{1}{ Same as in note \circled{6} \circled{7} of \Coderef{cd:m:SubjectCON:tests}.}¥
    sub = SubjectCON_FUN_MP( ...
        'ID', ['SUB CON ' int2str(i)], ...
        'LABEL', ['Subejct CON ' int2str(i)], ...
        'NOTES', ['Notes on subject CON ' int2str(i)], ...
        'BA', ba, ...
        'CON', rand(ba.get('BR_DICT').get('LENGTH')), ...¥\circled{2}\circlednote{2}{ constructs connectivity matrix.}¥
        'FUN', rand(10, ba.get('BR_DICT').get('LENGTH')) ...¥\circled{3}\circlednote{3}{ constructs functional matrix.}¥
        );
    sub.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 100 * rand()))
    sub.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', randi(2, 1)))
    gr.get('SUB_DICT').get('ADD', sub)
end

gui = GUIElement('PE', gr, 'CLOSEREQ', false);
gui.get('DRAW')
gui.get('SHOW')

gui.get('CLOSE')¤
\end{lstlisting}

\clearpage

\section{Implementation of a subject with structural data}

\subsection{Subject with structural data (\code{SubjectST})}

In this section, you will see how to implement \code{SubjectST}. For example, the structural data can be obtained from sMRI.

\begin{lstlisting}[
	label=cd:m:SubjectST:header,
	caption={
		{\bf SubjectST element header.}
		The \code{header} section of the generator code in \fn{\_SubjectST.gen.m} provides the general information about the \code{SubjectST} element. \expand{cd:m:SubjectCON:header}
		}
]
¤%% ¡header!
¤SubjectST¤ < Subject (sub, ¤subject with structural data) is a subject with structural data (e.g. sMRI).¤

%%% ¡description!
¤Subject with structural data (e.g. cortical thickness obtaibed from strcutural MRI) for each brain region.¤

%%% ¡seealso!
¤ImporterGroupSubjectST_TXT, ExporterGroupSubjectST_TXT, ImporterGroupSubjectST_XLS, ExporterGroupSubjectST_XLS

%%% ¡build!
¤1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectST:prop_update,
	caption={
		{\bf SubjectST element props update.}
		The \code{props\_update} section of the generator code in \fn{\_SubjectST.gen.m} updates the properties of the \code{Subject} element. \expand{cd:m:SubjectCON:prop_update}
	}
]
¤%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the subject.
%%%% ¡default!
¤'SubjectST'¤

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the subject.
%%%% ¡default!
¤'SubjectST with structural data (e.g. cortical thickness obtaibed from strcutural MRI) for each brain region.'¤

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the subject.
%%% ¡settings!
¤'SubjectST'¤

%%% ¡prop!
ID (data, string) is a few-letter code for the subject.
%%%% ¡default!
¤'SubjectST ID'¤

%%% ¡prop!
LABEL (metadata, string) is an extended label of the subject.
%%%% ¡default!
¤'SubjectST label'¤

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the subject.
%%%% ¡default!
¤'SubjectST notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectST:props,
	caption={
		{\bf SubjectST element props.}
		The \code{props} section of the generator code in \fn{\_SubjectST.gen.m} defines the properties specific for the \code{SubjectST} element. \expand{cd:m:SubjectCON:prop_update}
	}
]
¤%% ¡props!

%%% ¡prop!
BA (data, item) is a brain atlas.
%%%% ¡settings!
'BrainAtlas'

%%% ¡prop!
¤ST (data, cvector) is a column vector with data for each brain region.¤
%%%% ¡check_value!
br_number = sub.get('BA').get('BR_DICT').get('LENGTH');
¤check = (iscolumn(value) && isequal(size(value), [br_number, 1])) || (isempty(value) && br_number == 0);¤ ¥\circled{1}\circlednote{1}{ checks the size of the row of \code{value} is equal to the number of brain regions. The number of column is 1.}¥¤
if check
    msg = 'All ok!';
else   
    ¤msg = ['ST must be a column vector with the same number of element as the brain regions (' int2str(br_number) ').'];¤
end
%%%% ¡gui! ¥\circled{2}\circlednote{2}{ Same as in note \circled{4} of \Coderef{cd:m:SubjectCON:prop_update}.}¥
pr = PanelPropMatrix('EL', sub, 'PROP', SubjectST.ST, ...
    'ROWNAME', sub.get('BA').get('BR_DICT').getCallback('KEYS'), ...
    ¤'COLUMNNAME', {}, ...¤
    varargin{:});
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectST:tests,
	caption={
		{\bf SubjectST element tests.}
		The \code{tests} section from the element generator \fn{\_SubjectST.gen.m}. \expand{cd:m:SubjectCON:tests}
	}
]
¤%% ¡tests!

%%% ¡test!
%%%% ¡name!
GUI
%%%% ¡probability!
.01
%%%% ¡code!
im_ba = ImporterBrainAtlasXLS('FILE', ¤'destrieux_atlas.xlsx'¤);
ba = im_ba.get('BA');

gr = Group('SUB_CLASS', ¤'SubjectST'¤, 'SUB_DICT', IndexedDictionary('IT_CLASS', ¤'SubjectST'¤));
for i = 1:1:50
    sub = SubjectST( ...
        'ID', [¤'SUB ST '¤ int2str(i)], ...
        'LABEL', [¤'Subejct ST '¤ int2str(i)], ...
        'NOTES', [¤'Notes on subject ST '¤ int2str(i)], ...
        'BA', ba, ...
        ¤'ST', rand(ba.get('BR_DICT').get('LENGTH'), 1) ...¤ ¥\circled{1}\circlednote{1}{ constructs the random adjacency matrix with size of the number of brain regions by 1.}¥¤
        );
    sub.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 100 * rand()))
    sub.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', randi(2, 1)))
    gr.get('SUB_DICT').get('ADD', sub)
end

gui = GUIElement('PE', gr, 'CLOSEREQ', false);
gui.get('DRAW')
gui.get('SHOW')

gui.get('CLOSE')¤
\end{lstlisting}

\clearpage

\subsection{Subject with structural multiplex data (\code{SubjectST\_MP})}

In this section‚ you will see how to implement in detail \code{SubjectST\_MP}. For example, the structural data can be obtained from multiple sMRI.

\begin{lstlisting}[
	label=cd:m:SubjectST_MP:header,
	caption={
		{\bf SubjectST\_MP element header.}
		The \code{header} section of the generator code in \fn{\_SubjectST\_MP.gen.m} provides the general information about the \code{SubjectST\_MP} element.\expand{cd:m:SubjectCON_MP:header}
		}
]
¤%% ¡header!
¤SubjectST_MP¤ < Subject (sub,¤ subject with structural multiplex data) is a subject with structural multiplex data (e.g. multiplex sMRI)¤.

%%% ¡description!
¤Subject with data for each brain region corresponding to L structural layers (e.g. cortical thickness obtained from structural MRI).¤

%%% ¡seealso!
¤ImporterGroupSubjectST_MP_TXT, ExporterGroupSubjectST_MP_TXT, ImporterGroupSubjectST_MP_XLS, ExporterGroupSubjectST_MP_XLS

%%% ¡build!
¤1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectST_MP:prop_update,
	caption={
		{\bf SubjectST\_MP element props update.}
		The \code{props\_update} section of the generator code in \fn{\_SubjectST\_MP.gen.m} updates the properties of the \code{Subject} element. \expand{cd:m:SubjectCON_MP:prop_update}
	}
]
¤%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the subject.
%%%% ¡default!
¤'SubjectST_MP'¤

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the subject.
%%%% ¡default!
¤'Subject with data for each brain region correspponding to L structural layers (e.g. cortical thickness obtained from structural MRI).'¤

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the subject.
%%% ¡settings!
¤'SubjectST_MP'¤

%%% ¡prop!
ID (data, string) is a few-letter code for the subject.
%%%% ¡default!
¤'SubjectST_MP ID'¤

%%% ¡prop!
LABEL (metadata, string) is an extended label of the subject.
%%%% ¡default!
¤'SubjectST_MP label'¤

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the subject.
%%%% ¡default!
¤'SubjectST_MP notes'
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectST_MP:props,
	caption={
		{\bf SubjectST\_MP element props.}
		The \code{props} section of the generator code in \fn{\_SubjectST\_MP.gen.m} defines the properties specific for the \code{SubjectST\_MP} element. \expand{cd:m:SubjectCON_MP:props}
	}
]
¤%% ¡props!

%%% ¡prop!
BA (data, item) is a brain atlas.
%%%% ¡settings!
'BrainAtlas'

%%% ¡prop!
L (data, scalar) is the number of layers of subject data. ¥\circled{1}\circlednote{1}{ Same as in note \circled{1} of \Coderef{cd:m:SubjectCON_MP:prop_update}.}¥
%%%% ¡default!
2

%%% ¡prop!
LAYERLABELS (metadata, stringlist) are the layer labels provided by the user. ¥\circled{2}\circlednote{2}{ Same as in note \circled{2} of \Coderef{cd:m:SubjectCON_MP:prop_update}.}¥

%%% ¡prop!
ALAYERLABELS (query, stringlist) returns the processed layer labels. ¥\circled{3}\circlednote{3}{ Same as in note \circled{3} of \Coderef{cd:m:SubjectCON_MP:prop_update}.}¥
%%%% ¡calculate!
value = sub.get('LAYERLABELS');

%%% ¡prop!
¤ST_MP (data, cell) is a cell containing L vectors, each with data for each brain region.¤
%%%% ¡check_value!
br_number = sub.get('BA').get('BR_DICT').get('LENGTH');
num_layers = sub.get('L');
¤check = (iscell(value) && isequal(length(value), num_layers)  && isequal( cellfun(@(v) size(v, 1), value), ones(1, num_layers) * br_number)) || (isempty(value) && br_number == 0); ¤ ¥\circled{4}\circlednote{4}{ checks the size of each layer are equal to the number of brain regions. The size of each layer is the number of regions by 1.}¥
if check
    msg = 'All ok!';
else   
    ¤msg = ['ST_MP must be a column vector with the same number of element as the brain regions (' int2str(br_number) ').'];¤
end
%%%% ¡gui! ¥\circled{5}\circlednote{5}{ Same as in note \circled{8} \circled{9} \circled{10} \circled{11} of \Coderef{cd:m:SubjectCON_MP:prop_update}.}¥
pr = PanelPropCell('EL', sub, 'PROP', ¤SubjectST_MP.ST_MP¤, ...
    'TABLE_HEIGHT', s(40), ...
    'XSLIDERSHOW', true, ...
    'XSLIDERLABELS', sub.getCallback('ALAYERLABELS'), ...
    'YSLIDERSHOW', false, ...
    ¤'ROWNAME', sub.get('BA').get('BR_DICT').getCallback('KEYS'), ...
    'COLUMNNAME', {}, ...¤
    varargin{:});
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:SubjectST_MP:tests,
	caption={
		{\bf SubjectST\_MP element tests.}
		The \code{tests} section from the element generator \fn{\_SubjectST\_MP.gen.m}. \expand{cd:m:SubjectCON_MP:tests}
	}
]
¤%% ¡tests!

%%% ¡test!
%%%% ¡name!
GUI
%%%% ¡probability!
.01
%%%% ¡code!
im_ba = ImporterBrainAtlasXLS('FILE', ¤'destrieux_atlas.xlsx'¤);
ba = im_ba.get('BA');

gr = Group('SUB_CLASS', ¤'SubjectST_MP'¤, 'SUB_DICT', IndexedDictionary('IT_CLASS', ¤'SubjectST_MP'¤));
for i = 1:1:10 ¥\circled{1}\circlednote{1}{ Same as in note \circled{1} \circled{2} \circled{3} of \Coderef{cd:m:SubjectCON_MP:tests}.}¥
    sub = SubjectST_MP( ...
        'ID', [¤'SUB ST_MP '¤ int2str(i)], ...
        'LABEL', [¤'Subejct ST_MP '¤ int2str(i)], ...
        'NOTES', [¤'Notes on subject ST_MP '¤ int2str(i)], ...
        'BA', ba, ...
        'L', 3, ...
        'LAYERLABELS', {'L1' 'L2' 'L3'}, ...
        ¤'ST_MP', {rand(ba.get('BR_DICT').get('LENGTH'), 1), rand(ba.get('BR_DICT').get('LENGTH'), 1), rand(ba.get('BR_DICT').get('LENGTH'), 1)} ...¤
        );
    sub.memorize('VOI_DICT').get('ADD', VOINumeric('ID', 'Age', 'V', 100 * rand()))
    sub.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', randi(2, 1)))
    gr.get('SUB_DICT').get('ADD', sub)
end

gui = GUIElement('PE', gr, 'CLOSEREQ', false);
gui.get('DRAW')
gui.get('SHOW')

gui.get('CLOSE')
\end{lstlisting}

\end{document}