Function dimlpRul(const std::string&)

Function Documentation

int dimlpRul(const std::string &command = "")

Executes the Dimlp rule extraction process with specified parameters to obtain explaining rules and statistics for train, test and validation datasets for a model trained with dimlpTrn.

The function performs the following steps:

  1. Parses the command string to extract parameters.

  2. Sets up the neural network and other necessary objects.

  3. Loads the weights from the provided weights file.

  4. Computes the error and accuracy on the training, validation, and test datasets if provided.

  5. Extracts rules from the trained network.

  6. Saves the rules and the total execution time.

Notes:

  • Each file is located with respect to the root folder dimlpfidex or to the content of the ‘root_folder’ parameter if specified.

  • It’s mandatory to specify the number of attributes and classes in the data, as well as the training dataset and weights file.

  • The hidden layers configuration file must also be provided to specify the network architecture.

  • True train class labels must be provided, either within the data file or separately through a class file. Test and validation classes are given the same way if present.

  • Normalization parameters can be specified to denormalize the Dimlp explaining rules if data were normalized beforehand.

  • Parameters can be defined directly via the command line or through a JSON configuration file.

  • Providing no command-line arguments or using -h/--help displays usage instructions, detailing both required and optional parameters for user guidance.

Outputs:

  • global_rules_outfile: File containing the extracted explaining rules with statistics.

  • stats_file: If specified, contains accuracy statistics for training, validation, and test datasets if provided.

  • console_file: If specified, contains the console output.

File formats:

  • Data files: These files should contain one sample per line, with numbers separated either by spaces, tabs, semicolons, or commas. Supported formats:

    1. Only attributes (floats).

    2. Attributes (floats) followed by an integer class ID.

    3. Attributes (floats) followed by one-hot encoded class.

  • Class files: These files should contain one class sample per line, with integers separated either by spaces, tabs, semicolons, or commas. Supported formats:

    1. Integer class ID.

    2. One-hot encoded class.

  • Weights file: This file should be obtained by training with DimlpTrn and not with DimlpBT(!). The first row represents bias values of the Dimlp layer and the second row are values of the weight matrix between the previous layer and the Dimlp layer. Each value is separated by a space. As an example, if the layers are of size 4, the biases are: b1 b2 b3 b4 and the weights are w1 w2 w3 w4.

  • Hidden layers file

    : This file contains the number of nodes in each hidden layer. In each line there is the layer id and the number of its nodes separated by a space. Ex :

    1 16

    2 5

  • Attributes file: Each line corresponds to one attribute, each attribute must be specified. Classes can be specified after the attributes but are not mandatory. Each attribute or class must be in one word without spaces (you can use _ to replace a space). The order is important as the first attribute/class name will represent the first attribute/class in the dataset.

  • Normalization file

    : Each line contains the mean/median and standard deviation for an attribute.

    Format: ‘2 : original mean: 0.8307, original std: 0.0425’

    Attribute indices (index 2 here) can be replaced with attribute names, then an attribute file is required.

Example of how to call the function:

from dimlpfidex import dimlp

dimlp.dimlpRul('--train_data_file datanormTrain.txt --train_class_file dataclass2Train.txt --weights_file dimlpDatanorm.wts --test_data_file datanormTest.txt --test_class_file dataclass2Test.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')

Parameters:

command – A single string containing either the path to a JSON configuration file with all specified arguments, or all arguments for the function formatted like command-line input. This includes file paths, rule extraction parameters, and options for output.

Returns:

Returns 0 for successful execution, -1 for errors encountered during the process.