dev_analysis_ensemble.tex

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

\title{Implement a New Ensemble Analysis}

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

\begin{document}

\maketitle

\begin{abstract}
\noindent
This is the developer tutorial for implementing a new ensemble analysis. 
In this tutorial, you will learn how to create a \fn{*.gen.m} for a new ensemble analysis, which can then be compiled by \code{braph2genesis}.
Here, you will use as examples the ensemble analysis \code{AnalyzeEnsemble\_CON\_BUD}, an ensemble-based graph analysis (AnalyzeEnsemble) analyzing connectivity data (CON) using binary undirected multigraphs at fixed densities (BUD).
\end{abstract}

\tableofcontents

\clearpage

\section{Implementation of the ensemble analysis}

You will implement in detail \code{AnalyzeEnsemble\_CON\_BUD}, a direct extension of \code{AnalyzeEnsemble}.
An \code{AnalyzeEnsemble\_CON\_BUD} processes connectivity data to construct binary undirected graphs at fixed densities.

\subsection{Basic properties}
This section focuses on implementing the basic properties required to define \code{AnalyzeEnsemble\_CON\_BUD}, including its class, name, and associated metadata.

\begin{lstlisting}[
	label=cd:m:AnalyzeEnsemble_CON_BUD:header,
	caption={
		{\bf AnalyzeEnsemble\_CON\_BUD element header.}
		The \code{header} section of the generator code in \fn{\_AnalyzeEnsemble\_CON\_BUD.gen.m} provides the general information about the \code{AnalyzeEnsemble\_CON\_BUD} element.
		}
]
%% ¡header!
AnalyzeEnsemble_CON_BUD < AnalyzeEnsemble (a, graph analysis with connectivity data of fixed density) is an ensemble-based graph analysis using connectivity data of fixed density. ¥\circled{1}\circlednote{1}{ defines \code{AnalyzeEnsemble\_CON\_BUD} as a subclass of \code{AnalyzeEnsemble}. The moniker will be \code{a}.}¥

%%% ¡description! ¥\circled{2}\circlednote{2}{ provides a description of this ensemble analysis.}¥
This ensemble-based graph analysis (AnalyzeEnsemble_CON_BUD) analyzes 
connectivity data using binary undirected multigraphs at fixed densities.

%%% ¡seealso!
SubjectCON, MultigraphBUD

%%% ¡build! ¥\circled{3}\circlednote{3}{ defines the build number of the ensemble analysis element.}¥
1
\end{lstlisting}

\begin{lstlisting}[
	label=cd:m:AnalyzeEnsemble_CON_BUD:basic_props,
	caption={
		{\bf Basic properties of AnalyzeEnsemble\_CON\_BUD.}
		This section of the generator code in \fn{\_AnalyzeEnsemble\_CON\_BUD.gen.m} updates the basic properties required to describe the \code{AnalyzeEnsemble\_CON\_BUD} element, including its class, name, description, and other metadata.
	}
]
%% ¡props_update!

%%% ¡prop!
ELCLASS (constant, string) is the class of the ensemble-based graph analysis using connectivity data of fixed density.
%%%% ¡default!
'AnalyzeEnsemble_CON_BUD'

%%% ¡prop!
NAME (constant, string) is the name of the ensemble-based graph analysis using connectivity data of fixed density.
%%%% ¡default!
'Connectivity Binary Undirected at fixed Density Analyze Ensemble'

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the ensemble-based graph analysis using connectivity data of fixed density.
%%%% ¡default!
'This ensemble-based graph analysis (AnalyzeEnsemble_CON_BUD) analyzes connectivity data using binary undirected multigraphs at fixed densities.'

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the ensemble-based graph analysis using connectivity data of fixed density.
%%%% ¡settings!
'AnalyzeEnsemble_CON_BUD'

%%% ¡prop!
ID (data, string) is a few-letter code for the ensemble-based graph analysis using connectivity data of fixed density.
%%%% ¡default!
'AnalyzeEnsemble_CON_BUD ID'

%%% ¡prop!
LABEL (metadata, string) is an extended label of the ensemble-based graph analysis using connectivity data of fixed density.
%%%% ¡default!
'AnalyzeEnsemble_CON_BUD label'

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the ensemble-based graph analysis using connectivity data of fixed density.
%%%% ¡default!
'AnalyzeEnsemble_CON_BUD notes'

\end{lstlisting}

\subsection{Functionality-focused properties}

This section details the implementation of functionality-focused properties that directly enable \code{AnalyzeEnsemble\_CON\_BUD} to perform graph analysis.

\begin{lstlisting}[
	label=cd:m:AnalyzeEnsemble_CON_BUD:implementation_props,
	caption={
		{\bf Implementation properties of AnalyzeEnsemble\_CON\_BUD.}
		This section of the generator code in \fn{\_AnalyzeEnsemble\_CON\_BUD.gen.m} updates the properties to be used, including \code{GR} for defining subjects' data, \code{GRAPH\_TEMPLATE} for specifying graph type and parameters, and \code{G\_DICT} for managing graph instances across subjects.
	}
]

%%% ¡prop! ¥\circled{1}\circlednote{1}{ defines the property \code{GR}, which stores the subjects using \code{SubjectCON} element, containing the subjects' data to be analyzed.}¥
GR (data, item) is the subject group, which also defines the subject class SubjectCON.
%%%% ¡default!
Group('SUB_CLASS', 'SubjectCON')

%%% ¡prop! ¥\circled{2}\circlednote{2}{ Specifies the \code{GRAPH\_TEMPLATE} to define parameters such as \code{DENSITIES}, \code{SEMIPOSITIVIZE\_RULE}, and \code{STANDARDIZE\_RULE}. These settings are applied to all graphs in \circled{3}. Here, the graph element used is \code{MultigraphBUD}.}¥
GRAPH_TEMPLATE (parameter, item) is the graph template to set all graph and measure parameters.
%%%% ¡settings!
'MultigraphBUD'

%%% ¡prop! ¥\circled{3}\circlednote{3}{ creates \code{G\_DICT}, a graph dictionary that contains instances of \code{MultigraphBUD}. These instances are derived from the subjects defined in \circled{1}.}¥
G_DICT (result, idict) is the graph (MultigraphBUD) ensemble obtained from this analysis.
%%%% ¡settings!
'MultigraphBUD'
%%%% ¡calculate!
g_dict = IndexedDictionary('IT_CLASS', 'MultigraphBUD');
gr = a.get('GR');
densities = a.get('DENSITIES'); ¥\circled{4}\circlednote{4}{ retrieves the densities defined in the new properties below, which is used to configure the \code{MultigraphBUD} instances for the analysis.}¥

for i = 1:1:gr.get('SUB_DICT').get('LENGTH') ¥\circled{5}\circlednote{5}{, \circled{6}, \circled{7}, and \circled{8} collectively build the graph dictionary (\code{G\_DICT}). This process begins by iterating over each subject in \code{GR}, constructing an instance of \code{MultigraphBUD} for each subject based on their respective data, applying the specified \code{DENSITIES} parameter, and finally adding the created \code{MultigraphBUD} instances into the dictionary.}¥
	sub = gr.get('SUB_DICT').get('IT', i);
    g = MultigraphBUD( ...¥\circled{6}¥
        'ID', ['graph ' sub.get('ID')], ...
        'B', sub.getCallback('CON'), ...
        'DENSITIES', densities, ... ¥\circled{7}¥
        'LAYERLABELS', cellfun(@(x) [num2str(x) '%'], num2cell(densities), 'UniformOutput', false), ...
        'NODELABELS', a.get('GR').get('SUB_DICT').get('IT', 1).get('BA').get('BR_DICT').get('KEYS') ...
        );
    g_dict.get('ADD', g) ¥\circled{8}¥
end

if ~isa(a.get('GRAPH_TEMPLATE'), 'NoValue')
    for i = 1:1:g_dict.get('LENGTH')
        g_dict.get('IT', i).set('TEMPLATE', a.get('GRAPH_TEMPLATE'))  ¥\circled{9}\circlednote{9}{ ensures that all \code{MultigraphBUD} instances in the dictionary are updated with the pre-defined parameters from the graph template specified in \circled{2}, if explicitly set by the user during initialization of \code{AnalyzeEnsemble\_CON\_BUD}.}¥
    end
end

value = g_dict;

%%% ¡prop!
ME_DICT (result, idict) contains the calculated measures of the graph ensemble.
\end{lstlisting}

\begin{lstlisting}[
label=cd:m:AnalyzeEnsemble_CON_BUD:props,
caption={
	{\bf AnalyzeEnsemble\_CON\_BUD element props.}
	The \code{props} section of the generator code in \fn{\_AnalyzeEnsemble\_CON\_BUD.gen.m} defines the properties to be used in \code{AnalyzeEnsemble\_CON\_BUD}.
}
]
%% ¡props!

%%% ¡prop! ¥\circled{1}\circlednote{1}{ defines the densities for binarizing the connectivity matrix in a binary undirected multigraph, used in \circled{7} of \Coderef{cd:m:AnalyzeEnsemble_CON_BUD:implementation_props}}¥
DENSITIES (parameter, rvector) is the vector of densities.
%%%% ¡default!
[1:1:10]
%%%% ¡gui! ¥\circled{2}\circlednote{2}{ \code{PanelPropRVectorSmart} plots a GUI row vector panel for defining densities, supporting MATLAB expressions and limiting values between MIN and MAX.}¥
pr = PanelPropRVectorSmart('EL', a, 'PROP', AnalyzeEnsemble_CON_BUD.DENSITIES, ...
    'MIN', 0, 'MAX', 100, ...
    'DEFAULT', AnalyzeEnsemble_CON_BUD.getPropDefault('DENSITIES'), ...
    varargin{:});
%%%% ¡postset! ¥\circled{3}\circlednote{3}{ handles postprocessing after \code{DENSITIES} is set, memorizing a \code{GRAPH\_TEMPLATE} with the defined \code{DENSITIES}, applied later in \circled{9} of \Coderef{cd:m:AnalyzeEnsemble_CON_BUD:implementation_props}.}¥
a.memorize('GRAPH_TEMPLATE').set('DENSITIES', a.getCallback('DENSITIES'));
\end{lstlisting}

\subsection{Verification through testing}
This section validates \code{AnalyzeEnsemble\_CON\_BUD} by implementing tests to confirm its functionality via example scripts and ensure GUI integration.

\begin{lstlisting}[
	label=cd:m:AnalyzeEnsemble_CON_BUD:tests,
	caption={
		{\bf AnalyzeEnsemble\_CON\_BUD element tests.}
		The \code{tests} section in the element generator \fn{\_AnalyzeEnsemble\_CON\_BUD.gen.m} includes logic tests, which verify correct functionality using example scripts and simulated datasets, and integration tests, which ensure the instance operation of the direct GUI and associated GUIs.
	}
]	

%% ¡tests!

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

%%% ¡test! ¥\circled{2}\circlednote{2}{ Tests the functionality of \code{AnalyzeEnsemble\_CON\_BUD} using an example script.}¥
%%%% ¡name!
Example
%%%% ¡probability!  ¥\circled{3}\circlednote{3}{ assigns a low test execution probability.}¥
.01
%%%% ¡code!
create_data_CON_XLS() % only creates files if the example folder doesn't already exist

example_CON_BUD

%%% ¡test! ¥\circled{4}\circlednote{4}{ Tests the direct GUI functionality of \code{AnalyzeEnsemble\_CON\_BUD}.}¥
%%%% ¡name!
GUI - Analysis
%%%% ¡probability!
.01
%%%% ¡code!
im_ba = ImporterBrainAtlasXLS('FILE', 'desikan_atlas.xlsx');
ba = im_ba.get('BA'); ¥\circled{5}\circlednote{5}{ and \circled{6} define the necessary objects required to initialize an instance of \code{AnalyzeEnsemble\_CON\_BUD}.}¥

gr = Group('SUB_CLASS', 'SubjectCON', 'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON')); ¥\circled{6}¥
for i = 1:1:50 
    sub = SubjectCON( ...
        'ID', ['SUB CON ' int2str(i)], ...
        'LABEL', ['Subject 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()))
    sub.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', randi(2, 1)))
    gr.get('SUB_DICT').get('ADD', sub)
end

a = AnalyzeEnsemble_CON_BUD('GR', gr, 'DENSITIES', 5:5:20); ¥\circled{7}\circlednote{7}{ initializes an \code{AnalyzeEnsemble\_CON\_BUD} instance using the specified \code{gr} (group) and \code{densities}.}¥

gui = GUIElement('PE', a, 'CLOSEREQ', false);¥\circled{8}\circlednote{8}{, \circled{9}, and \circled{10} test the process of creating a GUI for \code{AnalyzeEnsemble\_CON\_BUD}, drawing it, and showing it on the screen.}¥
gui.get('DRAW') ¥\circled{9}¥
gui.get('SHOW') ¥\circled{10}¥

gui.get('CLOSE') ¥\circled{11}\circlednote{11}{ tests the process of closing the shown GUI.}¥

%%% ¡test! ¥\circled{12}\circlednote{12}{ tests the associated GUI functionality of \code{AnalyzeEnsemble\_CON\_BUD}.}¥
%%%% ¡name!
GUI - Comparison
%%%% ¡probability!
.01
%%%% ¡code!
im_ba = ImporterBrainAtlasXLS('FILE', 'desikan_atlas.xlsx');
ba = im_ba.get('BA');

gr1 = Group('SUB_CLASS', 'SubjectCON', 'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON'));
for i = 1:1:50
    sub = SubjectCON( ...
        'ID', ['SUB CON ' int2str(i)], ...
        'LABEL', ['Subject 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()))
    sub.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', randi(2, 1)))
    gr1.get('SUB_DICT').get('ADD', sub)
end

gr2 = Group('SUB_CLASS', 'SubjectCON', 'SUB_DICT', IndexedDictionary('IT_CLASS', 'SubjectCON'));
for i = 1:1:50
    sub = SubjectCON( ...
        'ID', ['SUB CON ' int2str(i)], ...
        'LABEL', ['Subject 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()))
    sub.memorize('VOI_DICT').get('ADD', VOICategoric('ID', 'Sex', 'CATEGORIES', {'Female', 'Male'}, 'V', randi(2, 1)))
    gr2.get('SUB_DICT').get('ADD', sub)
end

a1 = AnalyzeEnsemble_CON_BUD('GR', gr1, 'DENSITIES', 5:5:20); ¥\circled{13}\circlednote{13}{ Similar to the previous test, this initializes the first \code{AnalyzeEnsemble\_CON\_BUD} with the specified \code{gr} and densities.}¥
a2 = AnalyzeEnsemble\_CON\_BUD('GR', gr2, 'TEMPLATE', a1);¥\circled{14}\circlednote{14}{ initializes the second \code{AnalyzeEnsemble\_CON\_BUD} using the first \code{AnalyzeEnsemble\_CON\_BUD} instance as a template. This setup allows the second instance to have its own \code{gr} data while applying the same parameters, specifically the densities.}¥

c = CompareEnsemble( ...¥\circled{15}\circlednote{15}{ creates a \code{CompareEnsemble} instance with the defined \code{AnalyzeEnsemble\_CON\_BUD} instances.}¥
    'P', 10, ...
    'A1', a1, ...
    'A2', a2, ...
    'WAITBAR', true, ...
    'VERBOSE', false, ...
    'MEMORIZE', true ...
    );

gui = GUIElement('PE', c, 'CLOSEREQ', false);  ¥\circled{16}\circlednote{16}{, \circled{17}, \circled{18}, and \circled{19} test creating, drawing, showing, and closing the GUI of the \code{CompareEnsemble}, which is an associated GUI of \code{AnalyzeEnsemble\_CON\_BUD}}¥
gui.get('DRAW') ¥\circled{17}¥
gui.get('SHOW') ¥\circled{18}¥

gui.get('CLOSE') ¥\circled{19}¥

\end{lstlisting}


\end{document}