dev_nn_clas.tex

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

\title{Implement a New Neural Network Classifier}

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

\begin{document}

\maketitle

\begin{abstract}
\noindent
This is the developer tutorial for implementing a new neural network classifier. 
In this tutorial, you will learn how to create the generator file \fn{*.gen.m} for a new neural network classifier, which can then be compiled by \code{braph2genesis}. All kinds of neural network models are (direct or indirect) extensions of the base element \code{NNBase}. Here, you will use as example the neural network classifier \code{NNClassifierMLP} (multi-layer perceptron classifier).
\end{abstract}

\tableofcontents

\clearpage

\section{Implementation of a neural network classifier (\code{NNClassifierMLP})}

You will start by implementing in detail \code{NNClassifierMLP}, which is a direct extension of \code{NNBase}.
A multi-layer perceptron classifier \code{NNClassifierMLP} comprises a multi-layer perceptron classifier model and a given dataset.

\begin{lstlisting}[
	label=cd:m:NNClassifierMLP:header,
	caption={
		{\bf NNClassifierMLP element header.}
		The \code{header} section of the generator code for \fn{\_NNClassifierMLP.gen.m} provides the general information about the \code{NNClassifierMLP} element.
		}
]
%% ¡header!
NNClassifierMLP < NNBase (nn, multi-layer perceptron classifier) comprises a multi-layer perceptron classifier model and a given dataset.  ¥\circled{1}\circlednote{1}{ defines \code{NNClassifierMLP} as a subclass of \code{NNBase}. The moniker will be \code{nn}.}¥

%%% ¡description!
A neural network multi-layer perceptron classifier (NNClassifierMLP) comprises a multi-layer perceptron classifier model and a given dataset. NNClassifierMLP trains the multi-layer perceptron classifier with a formatted inputs ("CB", channel and batch) derived from the given dataset.

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

\begin{lstlisting}[
	label={cd:m:NNClassifierMLP:prop_update},
	caption={
		{\bf NNClassifierMLP element prop update.}
		The \code{props\_update} section of the generator code for \fn{\_NNClassifierMLP.gen.m} updates the properties of the \code{NNClassifierMLP} element. This defines the core properties of the data point.
	}
]
%% ¡props_update!

%%% ¡prop!
NAME (constant, string) is the name of the neural network multi-layer perceptron classifier.
%%%% ¡default!
'NNClassifierMLP'

%%% ¡prop!
DESCRIPTION (constant, string) is the description of the neural network multi-layer perceptron classifier.
%%%% ¡default!
'A neural network multi-layer perceptron classifier (NNClassifierMLP) comprises a multi-layer perceptron classifier model and a given dataset. NNClassifierMLP trains the multi-layer perceptron classifier with a formatted inputs ("CB", channel and batch) derived from the given dataset.'

%%% ¡prop!
TEMPLATE (parameter, item) is the template of the neural network multi-layer perceptron classifier.
%%%% ¡settings!
'NNClassifierMLP'

%%% ¡prop!
ID (data, string) is a few-letter code for the neural network multi-layer perceptron classifier.
%%%% ¡default!
'NNClassifierMLP ID'

%%% ¡prop!
LABEL (metadata, string) is an extended label of the neural network multi-layer perceptron classifier.
%%%% ¡default!
'NNClassifierMLP label'

%%% ¡prop!
NOTES (metadata, string) are some specific notes about the neural network multi-layer perceptron classifier.
%%%% ¡default!
'NNClassifierMLP notes'

%%% ¡prop! ¥\circled{1}\circlednote{1}{ defines \code{NNDataset} which contains the \code{NNDataPoint} to train this classifier.}¥
D (data, item) is the dataset to train the neural network model, and its data point class DP_CLASS defaults to one of the compatible classes within the set of DP_CLASSES.
%%%% ¡settings!
'NNDataset'
%%%% ¡default!
NNDataset('DP_CLASS', 'NNDataPoint_CON_CLA')

%%% ¡prop!
DP_CLASSES (parameter, classlist) is the list of compatible data points. 
%%%% ¡default! ¥\circled{2}\circlednote{2}{ defines the compatible \code{NNDataPoint} classes with this \code{NNClassifierMLP}.}¥
{'NNDataPoint_CON_CLA' 'NNDataPoint_CON_FUN_MP_CLA' 'NNDataPoint_Graph_CLA' 'NNDataPoint_Measure_CLA'}

%%% ¡prop!
INPUTS (query, cell) constructs the data in the CB (channel-batch) format.
%%%% ¡calculate! ¥\circled{3}\circlednote{3}{ is a query that transforms the input data of \code{NNDataPoint} to the CB (channel-batch) format by flattening its included cells.}¥
% inputs = nn.get('inputs', D) returns a cell array with the
%  inputs for all data points in dataset D.
if isempty(varargin)
    value = {};
    return
end
d = varargin{1};
inputs_group = d.get('INPUTS');
if isempty(inputs_group)
    value = {};
else
    flattened_inputs_group = [];
    for i = 1:1:length(inputs_group)
        inputs_individual = inputs_group{i};
        flattened_inputs_individual = [];
        while ~isempty(inputs_individual)
            currentData = inputs_individual{end};  % Get the last element from the stack
            inputs_individual = inputs_individual(1:end-1);   % Remove the last element

            if iscell(currentData)
                % If it's a cell array, add its contents to the stack
                inputs_individual = [inputs_individual currentData{:}];
            else
                % If it's numeric or other data, append it to the vector
                flattened_inputs_individual = [currentData(:); flattened_inputs_individual];
            end
        end
        flattened_inputs_group = [flattened_inputs_group; flattened_inputs_individual'];
    end
    value = {flattened_inputs_group};
end

%%% ¡prop!
TARGETS (query, cell) constructs the targets in the CB (channel-batch) format with one-hot vectors.
%%%% ¡calculate! ¥\circled{4}\circlednote{4}{ is a query that constructs the one-hot vectors for the target classes.}¥
% targets = nn.get('TARGETS', D) returns a cell array with the
%  targets for all data points in dataset D with one-hot vectors.
if isempty(varargin)
    value = {};
    return
end
d = varargin{1};

targets = cellfun(@(target) cell2mat(target),  d.get('TARGETS'), 'UniformOutput', false);
targets = categorical(cell2mat(targets))';
value = onehotencode(targets, 2, "ClassNames", flip(string(unique(targets))));


%%% ¡prop!
MODEL (result, net) is a trained neural network model.
%%%% ¡calculate! ¥\circled{5}\circlednote{5}{ trains the classifier with the defined dataset by the code under \code{¡calculate!}.}¥
inputs = cell2mat(nn.get('INPUTS', nn.get('D'))); ¥\circled{6}¥
targets = nn.get('TARGET_CLASSES', nn.get('D')); ¥\circled{7}\circlednote{6}{ and \circled{7} extract the inputs and targets.}¥
if isempty(inputs) || isempty(targets)
    value = network();
else
    number_features = size(inputs, 2);
    number_targets = size(targets, 2);
    targets = categorical(targets); 
    number_classes = numel(categories(targets));
    
    layers = nn.get('LAYERS'); ¥\circled{8}\circlednote{8}{ defines the neural network architecture with user specified number of neurons and number of layers.}¥
    nn_architecture = [featureInputLayer(number_features, 'Name', 'Input')];
    for i = 1:1:length(layers)
        nn_architecture = [nn_architecture
            fullyConnectedLayer(layers(i), 'Name', ['Dense_' num2str(i)])
            batchNormalizationLayer('Name', ['BatchNormalization_' num2str(i)])
            dropoutLayer('Name', ['Dropout_' num2str(i)])
            ];
    end
    nn_architecture = [nn_architecture
        reluLayer('Name', 'Relu_output')
        fullyConnectedLayer(number_classes, 'Name', 'Dense_output')
        softmaxLayer
        classificationLayer('Name', 'Output')
        ];

    % specify trianing options  ¥\circled{9}\circlednote{9}{ defines the neural network training options.}¥
    options = trainingOptions(nn.get('SOLVER'), ...
        'MiniBatchSize', nn.get('BATCH'), ...
        'MaxEpochs', nn.get('EPOCHS'), ...
        'Shuffle', nn.get('SHUFFLE'), ...
        'Plots', nn.get('PLOT_TRAINING'), ...
        'Verbose', nn.get('VERBOSE'));

    % train the neural network ¥\circled{10}\circlednote{10}{ trains the model with those parameters and the neural network architecture.}¥
    value = trainNetwork(inputs, targets, nn_architecture, options);
end


\end{lstlisting}

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

%%% ¡prop!
TARGET_CLASSES (query, stringlist) constructs the target classes which represent the class of each data point.
%%%% ¡calculate! ¥\circled{1}\circlednote{1}{ is a query that collects all the target class for all data points.}¥
% target_classes = nn.get('TARGET_CLASSES', D) returns a cell array with the
%  target classes for all data points in dataset D.
if isempty(varargin)
    value = {''};
    return
end
d = varargin{1};
dp_dict = d.get('DP_DICT');
if dp_dict.get('LENGTH') == 0
    value = {''};
else
    nn_targets = [];
    for i = 1:1:dp_dict.get('LENGTH')
        target = dp_dict.get('IT', i).get('TARGET_CLASS');
        nn_targets = [nn_targets; target];
    end
    value = nn_targets;
end

%%% ¡prop! ¥\circled{2}\circlednote{2}{ defines the number of neuron per layer. For example, \code{[32 32]} represents two layers, each containing 32 neurons.}¥
LAYERS (data, rvector) defines the number of layers and their neurons.
%%%% ¡default!
[32 32]
%%%% ¡gui!
pr = PanelPropRVectorSmart('EL', nn, 'PROP', NNClassifierMLP.LAYERS, ...
    'MIN', 0, 'MAX', 2000, ...
    'DEFAULT', NNClassifierMLP.getPropDefault('LAYERS'), ...
    varargin{:});

%%% ¡prop!
WAITBAR (gui, logical) detemines whether to show the waitbar.
%%%% ¡default!
true

\end{lstlisting}

\clearpage

\begin{lstlisting}[
	label=cd:m:NNClassifierMLP:tests,
	caption={
		{\bf NNClassifierMLP element tests.}
		The \code{tests} section from the element generator \fn{\_NNClassifierMLP.gen.m}.
		A test for creating example files should be prepared to test the properties of the data point. Furthermore, additional test should be prepared for validating the value of input and target for the data point.
	}
]			
%% ¡tests!

%%% ¡test!
%%%% ¡name!
train the classifier with example data
%%%% ¡code!

% ensure the example data is generated
if ~isfile([fileparts(which('NNDataPoint_CON_CLA')) filesep 'Example data NN CLA CON XLS' filesep 'atlas.xlsx'])
    create_data_NN_CLA_CON_XLS() % create example files
end

% Load BrainAtlas
im_ba = ImporterBrainAtlasXLS( ...
    'FILE', [fileparts(which('NNDataPoint_CON_CLA')) filesep 'Example data NN CLA CON XLS' filesep 'atlas.xlsx'], ...
    'WAITBAR', true ...
    );

ba = im_ba.get('BA');

% Load Groups of SubjectCON
im_gr1 = ImporterGroupSubjectCON_XLS( ...
    'DIRECTORY', [fileparts(which('NNDataPoint_CON_CLA')) filesep 'Example data NN CLA CON XLS' filesep 'CON_Group_1_XLS'], ...
    'BA', ba, ...
    'WAITBAR', true ...
    );

gr1 = im_gr1.get('GR');

im_gr2 = ImporterGroupSubjectCON_XLS( ...
    'DIRECTORY', [fileparts(which('NNDataPoint_CON_CLA')) filesep 'Example data NN CLA CON XLS' filesep 'CON_Group_2_XLS'], ...
    'BA', ba, ...
    'WAITBAR', true ...
    );

gr2 = im_gr2.get('GR');

% create item lists of NNDataPoint_CON_CLA
[~, group_folder_name] = fileparts(im_gr1.get('DIRECTORY'));
it_list1 = cellfun(@(x) NNDataPoint_CON_CLA( ...
    'ID', x.get('ID'), ...
    'SUB', x, ...
    'TARGET_CLASS', {group_folder_name}), ...
    gr1.get('SUB_DICT').get('IT_LIST'), ...
    'UniformOutput', false);

[~, group_folder_name] = fileparts(im_gr2.get('DIRECTORY'));
it_list2 = cellfun(@(x) NNDataPoint_CON_CLA( ...
    'ID', x.get('ID'), ...
    'SUB', x, ...
    'TARGET_CLASS', {group_folder_name}), ...
    gr2.get('SUB_DICT').get('IT_LIST'), ...
    'UniformOutput', false);

% create NNDataPoint_CON_CLA DICT items
dp_list1 = IndexedDictionary(...
        'IT_CLASS', 'NNDataPoint_CON_CLA', ...
        'IT_LIST', it_list1 ...
        );

dp_list2 = IndexedDictionary(...
        'IT_CLASS', 'NNDataPoint_CON_CLA', ...
        'IT_LIST', it_list2 ...
        );

% create a NNDataset containing the NNDataPoint_CON_CLA DICT
d1 = NNDataset( ...
    'DP_CLASS', 'NNDataPoint_CON_CLA', ...
    'DP_DICT', dp_list1 ...
    );

d2 = NNDataset( ...
    'DP_CLASS', 'NNDataPoint_CON_CLA', ...
    'DP_DICT', dp_list2 ...
    );

% combine the two datasets
d = NNDatasetCombine('D_LIST', {d1, d2}).get('D');

nn = NNClassifierMLP('D', d, 'LAYERS', [10 10 10]);
trained_model = nn.get('MODEL');

% Check whether the number of fully-connected layer matches (excluding Dense_output layer) ¥\circled{1}\circlednote{1}{ checks whether the number of layers from the trained model is correctly set.}¥
assert(length(nn.get('LAYERS')) == sum(contains({trained_model.Layers.Name}, 'Dense')) - 1, ...
    [BRAPH2.STR ':NNClassifierMLP:' BRAPH2.FAIL_TEST], ...
    'NNClassifierMLP does not construct the layers correctly. The number of the inputs should be the same as the length of dense layers the property.' ...
    )

\end{lstlisting}

\end{document}