Rule Analyzer

This class provides methods for visualizing and analyzing the rules of a trained ANFIS model.

class neuro_fuzzy_toolbox.rule_analyzer.rule_analyzer.RulesAnalyzer(model)[source]

Bases: object

Analysis and interpretability tool for ANFIS rules.

Provides methods for:

  • Identifying the most active rules for specific samples.

  • Exporting rules in human-readable IF-THEN format.

  • Analyzing rule contributions to model predictions.

  • Visualizing and estimating rule similarity.

__init__(model)[source]

Initializes the RulesAnalyzer.

Parameters:

model (ANFIS | h_ANFIS | rule_reduced_ANFIS) – Trained ANFIS model to analyze.

explain_prediction(x, top_k=None, alpha_cut=0.85, sort_by='firing_levels', show=[], output_idx=None)[source]

Generates a textual explanation of the model’s prediction for a given sample, based on the most active rules and their contributions.

Parameters:

  • x (torch.Tensor) – Input sample to analyze.

  • top_k (int, optional) – Number of top rules to include. If None, all rules are included. Defaults to None.

  • alpha_cut (float, optional) – Minimum membership value used to define the membership intervals for each rule’s antecedent. Defaults to 0.85.

  • sort_by (str, optional) – Criterion for ranking the active rules. Available options are 'firing_levels', 'abs_rules_outputs', 'rules_outputs', 'abs_contribution', and 'contribution'. For models with output_type='softmax', the additional options 'leave_one_rule_out', 'logit_margin', and 'logit_margin_mean' are also available. Defaults to 'firing_levels'.

  • show (list[str], optional) – List of additional metrics to display alongside each rule in classification models. Available options are 'leave_one_rule_out', 'logit_margin', and 'logit_margin_mean'. Defaults to [].

  • output_idx (int, optional) – Index of the output to analyze (0-indexed). Defaults to None.

Returns:

Textual explanation of the prediction based on the most active rules and their contributions.

Return type:

str

Note

Regarding output_idx:

  • In regression models (output_type='default'), it is only used when the model has multiple outputs, to indicate which output the explanation refers to. It is ignored for single-output regression models.

  • In classification models (output_type='softmax'), it is ignored entirely, as the explanation always focuses on the predicted class.

For available sorting criteria, see top_activated_rules().

layers_outputs(x)[source]

Returns the relevant intermediate layer outputs of the model for a single input sample.

Note

If the model has output_type='default', the output dictionary includes: 'membership values', 'firing levels', 'norm firing levels', 'consequent outputs', 'rules contribution', and 'final output'. If the model has output_type='softmax', the dictionary additionally includes 'logits' (the output before the softmax function).

Parameters:

x (torch.Tensor) – Input sample of shape (n_features,) or (1, n_features).

Returns:

Dictionary containing the relevant outputs of each layer.

Return type:

dict

show_fuzzy_sets(alpha_cut=0.85)[source]

Generates a textual representation of the fuzzy sets (IF part) of all rules in the model.

Parameters:

alpha_cut (float, optional) – Minimum membership value used to define the membership intervals. Defaults to 0.85.

Returns:

Text containing the antecedents of all rules in the model.

Return type:

str

Note

This method does not depend on a specific input sample. Its purpose is to display the global fuzzy structure of the model, showing the fuzzy sets associated with each rule based on their alpha-cuts.

show_top_fuzzy_sets(x, top_k=None, alpha_cut=0.85, sort_by='firing_levels', show=[], output_idx=None)[source]

Generates a textual representation of the antecedents (IF part) of the most relevant rules for a given input sample.

Parameters:

  • x (torch.Tensor) – Input sample to analyze.

  • top_k (int, optional) – Number of top rules to include. If None, all rules are included. Defaults to None.

  • alpha_cut (float, optional) – Minimum membership value used to define the membership intervals. Defaults to 0.85.

  • sort_by (str, optional) – Criterion for ranking the active rules. Available options are 'firing_levels', 'abs_rules_outputs', 'rules_outputs', 'abs_contribution', and 'contribution'. For models with output_type='softmax', the additional options 'leave_one_rule_out', 'logit_margin', and 'logit_margin_mean' are also available. Defaults to 'firing_levels'.

  • show (list[str], optional) – List of additional metrics to display alongside each rule in classification models. Available options are 'leave_one_rule_out', 'logit_margin', and 'logit_margin_mean'. Defaults to [].

  • output_idx (int, optional) – Index of the output to analyze (0-indexed) in regression models with multiple outputs. If None, the first output is analyzed. Ignored in classification models, where the explanation always focuses on the predicted class. Defaults to None.

Returns:

Text containing the antecedents (IF part) of the most relevant rules.

Return type:

str

Note

This method reuses the ranking criterion of top_activated_rules() and is intended as a compact version of explain_prediction(), showing only the fuzzy sets activated in the rule antecedents.

top_activated_rules(x, top_k=None, output_idx=None, sort_by='firing_levels')[source]

Identifies and ranks the top-k most active rules for a given input sample.

Parameters:

  • x (torch.Tensor) – Input sample of shape (n_features,) or (1, n_features).

  • top_k (int, optional) – Number of top rules to return. If None, all rules are included. Defaults to None.

  • output_idx (int, optional) – Index of the output to analyze. Only used in regression models with multiple outputs; ignored otherwise. Defaults to None.

  • sort_by (str, optional) – Criterion for ranking the active rules. Available options are 'firing_levels', 'abs_rules_outputs', 'rules_outputs', 'abs_contribution', and 'contribution'. For models with output_type='softmax', the additional options 'leave_one_rule_out', 'logit_margin', and 'logit_margin_mean' are also available. Defaults to 'firing_levels'.

Returns:

The return type depends on the model’s output type and the value of output_idx:

  • Regression models (output_type='default'): Returns a pandas.DataFrame with columns 'rule_id', 'firing_level', 'rule_output', and 'contribution' when a single output is analyzed (either because the model has one output or output_idx is specified). Returns a dict[str, pandas.DataFrame] with keys 'output_0', 'output_1', … when the model has multiple outputs and output_idx is None.

  • Classification models (output_type='softmax'): Returns a pandas.DataFrame with columns 'rule_id', 'firing_level', 'rule_output', 'contribution', 'I_logit_margin_max', 'I_logit_margin_mean', and 'I_prob' when output_idx is specified. Returns a dict[str, pandas.DataFrame] with keys 'class_0', 'class_1', … (or custom class label keys if the model uses custom class ids) when output_idx is None.

Return type:

pandas.DataFrame | dict

Note

Available sorting criteria:

  • 'firing_levels': Sorts by normalized firing levels (\(w\)).

  • 'abs_rules_outputs': Sorts by the absolute value of each rule’s individual output before weighting by firing levels (\(f(x)\) without multiplying by \(w\)).

  • 'rules_outputs': Sorts by each rule’s individual output before weighting by firing levels.

  • 'abs_contribution': Sorts by the absolute value of each rule’s contribution to the final output (\(f(x) \cdot w\)).

  • 'contribution': Sorts by each rule’s contribution to the final output.

  • 'leave_one_rule_out' (output_type='softmax' only): Sorts by the impact on the target class probability when the rule is removed, computed as the difference between the full-model probability and the leave-one-out probability.

  • 'logit_margin' (output_type='softmax' only): Sorts by the difference between the rule’s contribution to the target class logit and its contribution to the highest-scoring alternative class.

  • 'logit_margin_mean' (output_type='softmax' only): Sorts by the difference between the rule’s contribution to the target class logit and the mean of its contributions to all other classes.