DimlpRul¶

Description¶

The Discretized Interpretable Multi-Layer Perceptron (DIMLP) is a neural network architecture that combines the predictive power of a traditional Multi-Layer Perceptron (MLP) with the ability to extract interpretable rules. Unlike conventional neural networks, DIMLP uses a staircase activation function in the first hidden layer, creating a grid of hyper-rectangles in the feature space. These hyper-rectangles help define discriminant decision boundaries between classes, facilitating the extraction of symbolic rules.

The rule generation process in the DIMLP model relies on inducing a decision tree, where virtual hyperplanes are identified between these hyper-rectangles. The rule extraction algorithm extracts unordered rules in polynomial time using heuristic methods. This process ensures 100% fidelity with respect to the training data, meaning that the extracted rules perfectly match the network's decisions.

DimlpRul generates global explanation rules using the Dimlp algorithm on the training dataset used to train the model with dimlpTrn, and calculates accuracy on a train, test and validation dataset.

Additionally, there is another rule extraction algorithm available in the framework called Fidex, which has a better algorithmic complexity and allows for both local and global rule extraction.

For more details on the Dimlp algorithm, you can refer to this paper.

Arguments list¶

The dimlpRul algorithm works with both required and optional arguments. Each argument has specific properties:

• Is required means whether an argument must be specified when calling the program or not.
• Type specifies the argument datatype.
• CLI argument syntax is the exact name to use if you are writing the argument along with the program call.
• JSON identifier is the exact name to use if you are writing the argument inside a JSON configuration file.
• Default value is the value that will be used by the program if the argument is not specified. If None, it could mean that the argument is not used at all during the algorithm execution or could also mean that you have to specify it yourself.

Show help¶

Display parameters and other helpful information concerning the program usage and terminate it when done.

JSON configuration file¶

File containing the configuration for the algorithm in JSON format (see more about JSON configuration files).

Root folder path¶

Default path from where all the other arguments related to file paths are going to be based. Using this allows you to work with paths relative from this location and avoid writing absolute paths or lengthy relative paths.

Train data file¶

File containing the training portion of the dataset. It can also contain training "true classes" (see Train true classes file).

Train true classes file¶

File containing "true classes" (expected predictions), from the training portion of the dataset used to train the model.

Weights file¶

Path to the file containing the weights of the model trained with dimlpTrn.

Hidden layers file¶

Path to the file containing hidden layers sizes.

Number of attributes¶

Number of attributes in the dataset (should be equal to the number of inputs of the model). Takes values in the range [1,∞[.

Number of classes¶

Number of classes in the dataset (should be equal to the number of outputs of the model). Takes values in the range [2,∞[.

Test data file¶

Path to the file containing the test portion of the dataset.

Test true classes file¶

Path to the file containing the test true classes of the dataset.

Validation data file¶

Path to the file containing the validation portion of the dataset.

Validation true classes file¶

Path to the file containing the validation true classes of the dataset.

Global rules output file¶

Path to the file where the output rule(s) generated by the dimlp algorithm will be stored.

Attributes file¶

File containing attributes (inputs) and classes (outputs) names.

Statistics output file¶

Name of the output file that will contain statistics concerning the algorithm execution.

Logs output file¶

Name of file containing every feedback made by the algorithm during its execution. If not specified, the feedback is displayed into the terminal.

Number of stairs¶

Number of stairs in the staircase activation function used in the Dimlp layer during training. Takes values in the range [3,∞[.

Normalization file¶

File containing the mean and standard deviation for specified attributes that have been normalized. If specified, it is used to denormalize the rules.

Mus¶

Mean or median of each attribute index specified in normalization indices that have been normalized. This argument is used alongside sigmas and normalization indices. If specified, it is used to denormalize the rules. Takes values in the range ]-∞,∞[.

Sigmas¶

Standard deviation of each attribute index specified in normalization indices that have been normalized. This argument is used alongside mus and normalization indices. If specified, it is used to denormalize the rules. Takes values in the range ]-∞,∞[.

Normalization indices¶

Indices of attributes that have been normalized. If specified, it is used to denormalize the rules. Index starts at 0. Each index takes values in the range [0,nb_attributes-1].

Usage example¶

from dimlpfidex.dimlp import dimlpRul

dimlpRul(
"""--train_data_file train_data.txt 
--train_class_file train_class.txt 
--weights_file weights.wts 
--test_data_file test_data.txt 
--test_class_file test_class.txt 
--nb_attributes 16 
--hidden_layers_file hidden_layers.out 
--nb_classes 2 
--global_rules_outfile globalRules.rls 
--stats_file stats.txt 
--root_folder dimlp/datafiles"""
)

./dimlpRul --train_data_file train_data.txt --train_class_file train_class.txt --weights_file weights.wts --test_data_file test_data.txt --test_class_file test_class.txt --nb_attributes 16 --hidden_layers_file hidden_layers.out --nb_classes 2 --global_rules_outfile globalRules.rls --stats_file stats.txt --root_folder ../dimlp/datafiles

Output interpretation¶

Statistics file¶

This file contains accuracy and error measurements on the training, validation, and testing sets (if provided). It offers a clear overview of the model’s performance across different datasets, helping to evaluate how well the model has learned and generalized to unseen data.

Accuracy

Indicates the proportion of correctly classified samples in each dataset (training, validation, or testing).

Sum squared error

Represents the sum of the squared differences between the predicted and actual values for the samples in each dataset. It is a measure of the model’s overall error for a given set.

Global rules output file¶

This file contains all the global rules computed with the Dimlp algorithm. The rules are ordered by their covering size and are followed by the performance metrics of each rule on the training, validation and testing sets. Additionally, the file provides performance statistics of the ruleset and its application on testing data.

Explanation of Each Rule:

Each rule consists of conditions on various attributes, followed by the predicted class, and is accompanied by the number of training and validation samples it covers. Let's break down this rule as an example:

Rule 1: (x1 > 0.653808) (x2 > 0.92407) (x8 < 0.44302) Class = 1 (211)

x1, x2, x8

These represent the variables from the dataset (x1 is the first attribute).

>0.653808, >0.92407, <0.44302

The thresholds that the variable values must meet for the rule to be activated.

Class = 1

The class predicted by the rule when the conditions are met. Here, the rule predicts class 1.

(211)

The number of training and validation samples covered by the rule. Here, the rule covers 211 samples.

Performance Metrics Associated with the Rule:

For each rule and each dataset, there is some performances associated with the rule. It appears like this :

Rule    1:   143   134     9     0.937063       Class = 1

143

The number of samples covered by this rule.

134

The number of samples correctly classified by this rule.

9

The number of samples incorrectly classified by this rule.

0.937063

The accuracy of this rule in correctly classifying the samples it covers.

Class = 1

The class predicted by the rule when the conditions are met. Here, the rule predicts class 1.

It is followed by the global accuracy of the rules on the whole set. That means the accuracy of the ruleset in predicting the correct class for the samples, regardless of the model's predictions. It is accurate when there is a correct fidel activated rule, when no rule is activated and the model is correct, or when the activated rules are incorrect but all agree on the correct class.

Global Statistics:

Number of rules

Indicates the total number of rules in the ruleset.

Number of antecedents

Represents the total number of conditions (antecedents) in the ruleset.

Number of antecedents per rule

Represents the average number of conditions (antecedents) in each rule.

Number of examples per rule

The average number of training and validation samples covered by each rule.

Additional Statistics on testing set:

Fidelity

Measures how accurately the rules mimic the behavior of the model. This rate reflects the proportion of test samples where the rules' predictions match the model's predictions.

Accuracy when rules and network agree

The accuracy of the model when the model's predictions match the predictions made by the activated rules.

Default rule activations rate

The proportion of samples for which no activated rule is found. In such cases, we choose the network's decision.