Fidex¶

Description¶

The Fidex algorithm is an approach to rule extraction that can be applied to supervised neural networks and their ensembles, convolutional neural networks, decision tree ensembles, and support vector machines. The name of the algorithm is a contraction of fidelity and explainability. Fidelity refers to how well an extracted rule mimics the behavior of a given model.

The core idea behind Fidex is to identify discriminant hyperplanes in the feature space that separate different classes. By leveraging the staircase activation function in models containing a DIMLP layer or using generated decision tree rules from Random Forest and Gradiend Boosting models, Fidex can precisely identify these hyperplanes, allowing it to generate propositional rules in a computationally efficient manner. The algorithm’s complexity is linear with respect to the product of the problem’s dimensionality, the number of training samples, and the maximal number of rule antecedents, making it highly scalable.

Fidex is particularly effective at extracting local rules for individual samples by optimizing fidelity, ensuring that the rules it generates accurately reflect the decisions made by the model. The method applies a step-by-step process to iteratively improve the fidelity of the rule until it reaches a predefined threshold.

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

Arguments list¶

The Fidex 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 used to train the model, from which the ruleset/weights belong. It can also contain training "true classes" (see Train true classes file).

Train predictions file¶

File containing the predictions from the training portion of the dataset used to train the model.

Train true classes file¶

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

Test data file¶

File containing the testing portion of the dataset used to train the model. It can also contain training "true classes" and training predictions (see Test true classes file and Test predictions files).

Weights file¶

File containing the model trained weights.

Rules file¶

File containing the model trained rules.

Rules output file¶

Name of the file containing rules generated by Fidex.

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 predictions file¶

File containing the predictions from the testing portion of the dataset.

Test true classes file¶

File containing "true classes" (expected predictions), from the testing portion of the dataset.

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.

Maximum number of iterations¶

Maximum number of Fidex iterations allowed. Also the maximum possible number of antecedents in a rule. Takes values in the range [1,∞[.

Minimum covering¶

Minimal number of samples covered by every generated rule. Takes values in the range [1,∞[.

Use dichotomic search¶

Whether or not the algorithm uses a dichotomic strategy to compute a rule. This occurs when the algorithm fails to find a rule with the minimum covering value used.

Maximum number of failed attempts¶

Number of attempts allowed to compute a rule that could not be found by the algorithm. Takes values in the range [0,∞[.

Minimum fidelity¶

Lowest fidelity score allowed for a rule to be selected. Takes values in the range [0,1].

Minimum generated fidelity¶

Lowest fidelity score to which we agree to go down when a rule must be generated. Takes values in the range [0,1].

Dimension dropout¶

Percentage of dimensions that are ignored during an iteration. Takes values in the range [0,1].

Hyperplane dropout¶

Percentage of hyperplanes that are ignored during an iteration. Takes values in the range [0,1].

Number of stairs¶

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

Decision threshold¶

Threshold for predictions to be considered as correct. Takes values in the range [0,1].

Positive class index¶

Index of positive class for the usage of decision threshold, index starts at 0. Takes values in the range [0,nb_classes-1].

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].

Seed¶

Number to feed the random generator. If 0, the randomness cannot be reproduced. If any other number x is used, you can reproduce the same output if x is re-used. Takes values in the range [0,∞[.

Usage example¶

from dimlpfidex.fidex import fidex

fidex(
"""--root_folder dimlp/datafiles 
--train_data_file train_data.txt 
--train_pred_file predTrain.out 
--train_class_file train_class.txt 
--test_data_file test_data.txt 
--test_class_file test_class.txt 
--test_pred_file predTest.out 
--nb_attributes 16 
--nb_classes 2 
--weights_file weights.wts 
--rules_outfile output_rules.rls 
--stats_file output_stats.txt"""
)

./fidex --root_folder ../dimlp/datafiles --train_data_file train_data.txt --train_pred_file predTrain.out --train_class_file train_class.txt --test_data_file test_data.txt --test_class_file test_class.txt --test_pred_file predTest.out --nb_attributes 16 --nb_classes 2 --weights_file weights.wts --rules_outfile output_rules.rls --stats_file output_stats.txt

Output interpretation¶

Statistics file¶

This file contains statistics computed on rules created for a test set. For each sample in the test set, a corresponding rule is generated using a fixed training set. The statistics provide insights into the rules' coverage, fidelity, accuracy, and confidence based on the training data. All metrics are averages of the statistics calculated for each test sample, with all values derived from the training set.

Decision threshold

Indicates whether a decision threshold was used for prediction and specifies the threshold if applicable.

The mean covering size per rule

The average number of training samples covered by each rule.

The mean number of antecedents per rule

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

The mean rule fidelity rate

The average fidelity of the rules across the training set. A fidelity rate of 1 means that, on average, the rules perfectly match the model's predictions for all the samples they cover.

The mean rule accuracy

The average accuracy of the rules in correctly classifying the training samples they cover.

The mean rule confidence

This is the average confidence score of the model’s predictions for the training samples covered by the rules. It is based on the prediction scores of the covered samples, indicating the model’s confidence in its classifications.

Rules output file¶

Rule 1: X0>=0.65839 X1>=0.423139 X8>=0.105399 -> class 0
    Train Covering size : 121
    Train Fidelity : 1
    Train Accuracy : 0.950413
    Train Confidence : 0.97161

{
    "accuracy": 1.0,
    "antecedents": [
        {
            "attribute": 8,
            "inequality": false,
            "value": 0.07228972839342673
        },
        {
            "attribute": 3,
            "inequality": true,
            "value": 0.6969069765088105
        }
    ],
    "confidence": 0.991161,
    "coveredSamples": [
        67,
        213,
        567
    ],
    "coveringSize": 3,
    "fidelity": 1.0,
    "outputClass": 1
}