FidexGloRules¶

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.

FidexGloRules uses Fidex to generate one rule for each sample in the dataset. These local rules are then aggregated to form a global ruleset that explains the overall behavior of the model. The key idea remains identifying discriminant hyperplanes in the feature space that separate different classes. This is achieved through the staircase activation function in models containing a DIMLP layer, or by leveraging decision tree rules generated from Random Forest and Gradiend Boosting models. The global ruleset is refined using a heuristic to remove redundant rules while ensuring full coverage of the training dataset.

FidexGloRules retains the efficiency of Fidex in terms of computational complexity, but due to the need to generate one rule per sample and aggregate them into a global ruleset, the complexity becomes quadratic with respect to the number of samples. Specifically, it scales quadratically with the product of the problem's dimensionality, the number of training samples, and the maximal number of rule antecedents.

This approach is particularly effective for providing a comprehensive explanation of a model's decision-making process across an entire dataset, rather than just for individual samples. By optimizing fidelity and reducing the rule set through heuristic techniques, FidexGloRules produces a concise and interpretable global explanation.

For more details on the Fidex and FidexGloRules (called FidexGlo) algorithms, you can refer to this paper.

Arguments list¶

The FidexGloRules 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 to 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.

Weights file¶

File containing the model trained weights.

Rules file¶

File containing the model trained rules.

Global Rules output file¶

Name of the file containing global rules generated by the algorithm.

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,∞[.

Heuristic¶

Defines which heuristic to use when executing the algorithm. Values can be:

• 1: optimal rule generation. Gets the best of the algorithm capabilities but can be time-consuming depending on the size of your dataset.
• 2: Faster rules generation. Computes rules faster while keeping a good (but not as good as heuristic 1) rule quality.
• 3: Fastest rules generation. Gets a set of decent (but not as good as heuristic 2) global rules in the fastest way possible.

Attributes file¶

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

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,∞[.

Number of threads¶

Threads used to compute the algorithm. This parameter has no effect if the heuristic used is not 1 or 2. Takes values in the range [1,nb_cores].

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 fidexGloRules

fidexGloRules(
"""--root_folder dimlp/datafiles 
--train_data_file train_data.txt 
--train_pred_file predTrain.out 
--train_class_file train_class.txt 
--nb_attributes 16 
--nb_classes 2 
--weights_file weights.wts 
--global_rules_outfile globalRules.rls 
--heuristic 1
--nb_threads 4"""
)

./fidexGloRules --root_folder ../dimlp/datafiles --train_data_file train_data.txt --train_pred_file predTrain.out --train_class_file train_class.txt  --nb_attributes 16 --nb_classes 2 --weights_file weights.wts --global_rules_outfile globalRules.rls --heuristic 1 --nb_threads 4

Output interpretation¶

Global 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
}