BETTER-NMA 1.0.0__py3-none-any.whl → 1.0.2__py3-none-any.whl

BETTER_NMA/explaination_score.py

@@ -0,0 +1,52 @@
+from .utilss.classes.score_calculator import ScoreCalculator
+from itertools import combinations
+
+def get_explaination_score(dendrogram, class_names, normalize=True):
+    """
+    Get the score of the entire dendrogram based on pairwise LCA ancestor counts.
+
+    Parameters:
+    - dendrogram: The hierarchical clustering dendrogram
+    - class_names: List of class names corresponding to model outputs
+
+    Returns:
+    - score: The explanation score of the dendrogram
+    """
+    score_calculator = ScoreCalculator(dendrogram.Z, class_names)
+    
+    total_count = 0
+    num_classes = len(class_names)
+
+    # Get all combinations of 2 labels from class_names
+    for label1, label2 in combinations(class_names, 2):
+        try:
+            idx1 = class_names.index(label1)
+            idx2 = class_names.index(label2)
+            count, _ = score_calculator.count_ancestors_to_lca(idx1, idx2)
+            total_count += count
+        except ValueError as e:
+            print(f"Error processing pair ({label1}, {label2}): {e}")
+            continue
+
+    total_combinations = len(list(combinations(class_names, 2)))
+    print(f"Total combinations processed: {total_combinations}")
+    print(f"Total ancestor count sum: {total_count}")
+    
+    if normalize:
+        # Maximum ancestors = height of dendrogram tree
+        max_ancestors_per_pair = num_classes - 1  # Maximum tree height
+        theoretical_max = total_combinations * max_ancestors_per_pair
+        
+        if theoretical_max == 0:
+            normalized_score = 0
+        else:
+            # Invert the score so higher ancestor counts = lower explanation quality
+            # and normalize to 0-100%
+            normalized_score = max(0, (1 - (total_count / theoretical_max)) * 100)
+        
+        print(f"Theoretical maximum: {theoretical_max}")
+        print(f"Normalized score: {normalized_score:.2f}%")
+        
+        return normalized_score
+    else:
+        return total_count

BETTER_NMA/main.py

@@ -8,6 +8,7 @@ from .detect_attack import detect_adversarial_image
 from .query_image import query_image
 from .utilss.verbal_explanation import get_verbal_explanation
 from .white_box_testing import analyze_white_box_results, get_white_box_analysis
+from .explaination_score import get_explaination_score
 from .adversarial_score import get_adversarial_score
 from .find_lca import get_lca
 
@@ -212,6 +213,10 @@ class NMA:
         score = get_adversarial_score(image, self.model, self.dendrogram_object.Z, self.labels, top_k=top_k)
         return score
 
+    def explanation_score(self, normalize=True):
+        return get_explaination_score(self.dendrogram_object, self.labels, normalize=normalize)
+
+
     ## query and explanation functions: ##
 
     def query_image(self, image, top_k=5):

BETTER_NMA/utilss/classes/adversarial_dataset.py

@@ -13,32 +13,27 @@ class AdversarialDataset:
         scores = []
         labels = []
 
-        print("getting preprocess function...")
-
         try:
             for image in self.clear_images[:50]:
                 # Add batch dimension for model prediction
                 image_batch = np.expand_dims(image, axis=0)
-                score = self.score_calculator.calculate_adversarial_score(self.model.predict(image_batch))
+                score = self.score_calculator.calculate_adversarial_score(self.model.predict(image_batch, verbose=0))
                 scores.append(score)
                 labels.append(0)
         except Exception as e:
-            print(f"Error processing clean image: {e}")
+            print(f"Error processing clean images: {e}")
         
         # Generate features for PGD attacks
-        print("Generating attack features...")
         try:
             for adv_image in self.adversarial_images[:50]:
                 # Add batch dimension for model prediction
                 adv_image_batch = np.expand_dims(adv_image, axis=0)
-                score = self.score_calculator.calculate_adversarial_score(self.model.predict(adv_image_batch))
+                score = self.score_calculator.calculate_adversarial_score(self.model.predict(adv_image_batch, verbose=0))
                 scores.append(score)
                 labels.append(1)
         except Exception as e:
-            print(f"Error processing PGD attack on image: {e}")
+            print(f"Error processing attacked images: {e}")
 
-        print("labels:", labels)
-        print("scores:", scores)
         
         # Convert to numpy arrays
         X = np.array(scores)

BETTER_NMA/utilss/classes/preprocessing/batch_predictor.py

@@ -11,7 +11,7 @@ class BatchPredictor:
         self.buffer_results = []  # To store batch results
 
     def get_top_predictions(self, X, labels, top_k, graph_threshold):
-        batch_preds = self.model.predict(np.array(X))
+        batch_preds = self.model.predict(np.array(X), verbose=0)
         batch_results = []
         for pred in batch_preds:
             top_indices = pred.argsort()[-top_k:][::-1]

BETTER_NMA/utilss/classes/score_calculator.py

@@ -134,7 +134,6 @@ class ScoreCalculator:
                 
                 # Calculate semantic distance
                 rank_count, _ = self.count_ancestors_to_lca(idx1, idx2)
-                print(f"Rank Count for {label1} and {label2}: {rank_count}")
                 
                 # Calculate product of probabilities and distance
                 prob_product = prob1 * prob2

BETTER_NMA/utilss/photos_uitls.py

@@ -24,10 +24,10 @@ def get_preprocess_function(model):
     model_config = model.get_config()
     if "name" in model_config:
         model_name = model_config["name"].lower()
-        print(f"Model name: {model_name}")
+        # print(f"Model name: {model_name}")
         for key in preprocess_map.keys():
             if key in model_name:
-                print(f"Detected model type: {key}")
+                # print(f"Detected model type: {key}")
                 return preprocess_map[key]
 
     for layer in model.layers:
@@ -35,7 +35,7 @@ def get_preprocess_function(model):
         print(f"Checking layer: {layer_name}")
         for model_name in preprocess_map.keys():
             if model_name in layer_name:
-                print(f"Detected model type: {model_name}")
+                # print(f"Detected model type: {model_name}")
                 return preprocess_map[model_name]
 
     print("No supported model type found in the configuration. Falling back to generic normalization.")

BETTER_NMA/utilss/photos_utils.py

@@ -25,15 +25,15 @@ def get_preprocess_function(model):
     model_config = model.get_config()
     if "name" in model_config:
         model_name = model_config["name"].lower()
-        print(f"Model name: {model_name}")
+        # print(f"Model name: {model_name}")
         for key in preprocess_map.keys():
             if key in model_name:
-                print(f"Detected model type: {key}")
+                # print(f"Detected model type: {key}")
                 return preprocess_map[key]
 
     for layer in model.layers:
         layer_name = layer.name.lower()
-        print(f"Checking layer: {layer_name}")
+        # print(f"Checking layer: {layer_name}")
         for model_name in preprocess_map.keys():
             if model_name in layer_name:
                 print(f"Detected model type: {model_name}")

BETTER_NMA-1.0.2.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.1
+Name: BETTER_NMA
+Version: 1.0.2
+Summary: NMA: Dendrogram-based model analysis, white-box testing, and adversarial detection
+Author: BETTER_XAI
+Author-email: BETTERXAI2025@gmail.com
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: tensorflow>=2.10.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: python-igraph>=0.10.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: nltk>=3.7
+Requires-Dist: keras>=2.10.0
+Requires-Dist: Pillow>=8.0.0
+
+
+---
+
+# NMA – Near Misses Analysis
+
+NMA (**Near Misses Analysis**) is a Python package for analyzing machine learning models through **dendrogram-based hierarchical clustering**, **white-box testing**, and **adversarial attack detection**.
+
+It provides visualization, explanation, and diagnostic tools to help developers and researchers understand their models’ decision boundaries, identify vulnerabilities, and detect adversarial inputs.
+
+---
+
+## ✨ Features
+
+* 📊 **Dendrogram construction & visualization**
+
+  * Build hierarchical trees from model predictions.
+  * Plot full dendrograms or **sub-dendrograms** for specific labels.
+
+* 🧪 **White-box testing**
+
+  * Identify problematic training samples likely to cause misclassification.
+  * Run structured analysis across source/target label pairs.
+
+* 🛡 **Adversarial attack detection**
+
+  * Train a logistic regression adversarial detector.
+  * Detect adversarial images and compute adversarial scores.
+
+* 🔎 **Model querying & explanations**
+
+  * Query images for predictions with hierarchical context.
+  * Generate **verbal explanations** of model predictions.
+
+* 🧩 **Cluster analysis tools**
+
+  * Find lowest common ancestors (LCA) in the dendrogram.
+  * Rename clusters for more meaningful interpretation.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install BETTER_NMA
+```
+
+---
+
+## 🚀 Quickstart
+
+```python
+from BETTER_NMA import NMA
+import numpy as np
+
+# Example data (replace with your dataset/model)
+x_train = np.random.rand(100, 32, 32, 3)
+y_train = np.random.randint(0, 2, size=100)
+labels = ["cat", "dog"]
+
+# Your pre-trained model (e.g., Keras, PyTorch wrapper with predict)
+model = my_model  
+
+# Initialize NMA
+nma = NMA(
+    x_train=x_train,
+    y_train=y_train,
+    labels=labels,
+    model=model,
+    explanation_method="similarity", 
+    save_connections=True
+)
+
+# Plot dendrogram
+nma.plot(title="Model Decision Hierarchy")
+
+# Run white-box testing
+issues = nma.white_box_testing(["cat"], ["dog"], analyze_results=True)
+
+# Train adversarial detector
+nma.train_adversarial_detector(authentic_images, adversarial_images)
+
+# Detect if a new image is adversarial
+result = nma.detect_attack(test_image)
+
+# Get verbal explanation of an image
+explanation = nma.verbal_explanation(test_image)
+print(explanation)
+```
+
+---
+
+## 📚 API Overview
+
+### Dendrogram & Visualization
+
+* `plot(sub_labels=None, ...)` – plot full or partial dendrogram.
+* `plot_sub_dendrogram(sub_labels, ...)` – zoom into specific classes.
+
+### White-box Testing
+
+* `white_box_testing(source_labels, target_labels, ...)` – find problematic images.
+* `get_white_box_analysis(source_labels, target_labels, ...)` – detailed analysis.
+
+### Adversarial Detection
+
+* `train_adversarial_detector(authentic_images, attacked_images)` – train detector.
+* `detect_attack(image, plot_result=False)` – detect adversarial samples.
+* `adversarial_score(image, top_k=5)` – compute adversarial score.
+
+### Query & Explanation
+
+* `query_image(image, top_k=5)` – get predictions & explanation.
+* `verbal_explanation(image)` – generate natural language explanation.
+
+### Cluster Analysis
+
+* `find_lca(label1, label2)` – lowest common ancestor.
+* `change_cluster_name(cluster_id, new_name)` – rename clusters.
+
+---
+
+## 🛠 Requirements
+
+* Python ≥ 3.8
+* NumPy, Pandas, Matplotlib, Scikit-learn
+* (Optional) PyTorch / TensorFlow for model support
+
+---
+
+## 📖 Use Cases
+
+* **Research** – interpret model predictions via hierarchical clustering.
+* **Robustness testing** – identify adversarial vulnerabilities.
+* **Explainability** – provide visual + verbal explanations.
+* **Debugging** – detect mislabeled or problematic training samples.
+
+---
+
+## 📜 License
+
+MIT License – free to use and modify.
+
+---
+

{BETTER_NMA-1.0.0.dist-info → BETTER_NMA-1.0.2.dist-info}/RECORD

@@ -2,8 +2,9 @@ BETTER_NMA/__init__.py,sha256=ePaQnto0n4hccz2490Z7bxwcbtONVAa6nWqg7SL4W1Y,428
 BETTER_NMA/adversarial_score.py,sha256=qgScTqS-aJ2q4kFom505hBtonVzKK67fGS09J1_-G3o,875
 BETTER_NMA/change_cluster_name.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 BETTER_NMA/detect_attack.py,sha256=s7YwTVMJFABSMt2aISR-zaIUxFaSWm9oODc9yF12KPY,4327
+BETTER_NMA/explaination_score.py,sha256=GWtncYjIj8UF94g1UxtNRnyK7Cvh3PqVcShle_vLhUM,2003
 BETTER_NMA/find_lca.py,sha256=UlyftOJmbSPuXzxvcheRb_IrdCqBsaSQHLchIRZIR-0,812
-BETTER_NMA/main.py,sha256=73MH7v6LAs2kQexumLBDykVnhH774P-HPrnhV1LZ7MM,11318
+BETTER_NMA/main.py,sha256=2d3O8Nc6J9YTWXIsqIGIIWDkL1V3pWN1hhcDde873Nc,11525
 BETTER_NMA/nma_creator.py,sha256=M-LlZGRkxhGYLHpaXTNoZj9AUH7uvev7hq7tbILWMLI,5137
 BETTER_NMA/plot.py,sha256=nj2ca-ybzGMlo6HhCngyjGUNaJDmfsPxF5ad9xpxzvE,4383
 BETTER_NMA/query_image.py,sha256=13AQ9-8QdzaIwH5-ELX3z3iJBP8nTDe-SMtwQve-1ek,906
@@ -11,19 +12,19 @@ BETTER_NMA/train_adversarial_detector.py,sha256=nMaQ-Pm2vP84qNR1GoKQiVPpmMC3rdor
 BETTER_NMA/white_box_testing.py,sha256=zfhK8G-2cJH1AMevPywVnc05IhSqttf3YxQ6abdpM78,3524
 BETTER_NMA/utilss/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 BETTER_NMA/utilss/models_utils.py,sha256=gBXY2LFH4iR-2GZmHeUnnB5n9t3VdjIc9sugHDrD3AM,671
-BETTER_NMA/utilss/photos_uitls.py,sha256=mPe0zXTqN1RvkfDf0eiwzsniybicbomBkCQdTA-W8qQ,3160
-BETTER_NMA/utilss/photos_utils.py,sha256=K6VWOSo3fY00LIW0yZPrI0MH0NrY5SPZh46RrtF0mj0,4406
+BETTER_NMA/utilss/photos_uitls.py,sha256=wxmIIKFgAKYkcYaK95UMjtY-LZS6NDVveKrHBQV8Q70,3166
+BETTER_NMA/utilss/photos_utils.py,sha256=4EjDHbMjrJ8P9y-X4H05P4wez4uKNit60UGnu3sKsys,4412
 BETTER_NMA/utilss/verbal_explanation.py,sha256=_hrYZUjBUYOfuGr7t5r-DACooR5d60dRtGfUj7FbeZw,549
 BETTER_NMA/utilss/wordnet_utils.py,sha256=_A_gbdR7tf5tiyN2Oe5sB4vvBkWnr4KUl5e9iq5ft8c,5535
 BETTER_NMA/utilss/classes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-BETTER_NMA/utilss/classes/adversarial_dataset.py,sha256=6LrL_KrmUYuhsSGTmV1DBuV2sVAR9nIydUAW6FbPR8c,2447
+BETTER_NMA/utilss/classes/adversarial_dataset.py,sha256=LKmyseQetyBdoKrl7Q4MaTc7EzMZcMgqNdtCsdAvKHA,2299
 BETTER_NMA/utilss/classes/adversarial_detector.py,sha256=BE_SxNEwcvuHERBiefefOmk1k6NJSo6juehkAjkEHuQ,2331
 BETTER_NMA/utilss/classes/dendrogram.py,sha256=vtKBFfwzcz8k01Goc83pZlWC2pO86endTJURlkUWVQI,5141
 BETTER_NMA/utilss/classes/edges_dataframe.py,sha256=q-RQ6beOeZeIgdEzwi8T5Ag2NBFySv7-ITD5m989nl4,1896
-BETTER_NMA/utilss/classes/score_calculator.py,sha256=4ZyTA2BnWh2XhnjA5AoYAbbA7AOCDvUikToz6m5m4nM,6005
+BETTER_NMA/utilss/classes/score_calculator.py,sha256=zgZaFgFJeok2RzXFm9OE5pOuXY3euIXEiLGI44q30JM,5927
 BETTER_NMA/utilss/classes/whitebox_testing.py,sha256=4WSEjQ5gl6f8xzWADAagZ3WtMHE889rW-zcYld9REnw,1367
 BETTER_NMA/utilss/classes/preprocessing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-BETTER_NMA/utilss/classes/preprocessing/batch_predictor.py,sha256=baUsz_oj_JLEpUoy_o08m_AK0uaWb5RB_cavk5Itg1A,946
+BETTER_NMA/utilss/classes/preprocessing/batch_predictor.py,sha256=Cw5yzxLCPYGCTvOWclyCLT4qNgCCTSbyr-BNHapkwn0,957
 BETTER_NMA/utilss/classes/preprocessing/graph_builder.py,sha256=ILumiBY9BUIOxrIvq8C-8n945pK-t94Et6gZwJB-364,1672
 BETTER_NMA/utilss/classes/preprocessing/heap_processor.py,sha256=KblmkVWVfMYtpZa4Wy1Ry0lVfdSr6h8LySt4S-lvIGo,1064
 BETTER_NMA/utilss/classes/preprocessing/hierarchical_clustering_builder.py,sha256=YAIElJS_fSffIb3D2N1OZu9U6z7RYrHQTfB6bH4-VPI,4027
@@ -32,7 +33,7 @@ BETTER_NMA/utilss/classes/preprocessing/z_builder.py,sha256=T8ETfL7mMOgEj7oYNsw6
 BETTER_NMA/utilss/enums/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 BETTER_NMA/utilss/enums/explanation_method.py,sha256=Ang-rjvxO4AJ1IH4mwS8sNpSwt9jn3PlqFbPPT-R9I8,150
 BETTER_NMA/utilss/enums/heap_types.py,sha256=0z1d2qu1ZCbpWRXKD1dTopn3M4G1CxRQW9HWxVxyPIA,88
-BETTER_NMA-1.0.0.dist-info/METADATA,sha256=XouVuHepQ1tDjgxeQKesgEREOrVzN9oFP-iYBafHNfU,251
-BETTER_NMA-1.0.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-BETTER_NMA-1.0.0.dist-info/top_level.txt,sha256=SVRNqWPvCnynWVyXNAYnf9CSQIvMAvE6iyyiGHodQgY,11
-BETTER_NMA-1.0.0.dist-info/RECORD,,
+BETTER_NMA-1.0.2.dist-info/METADATA,sha256=9_3kUtQ3Cw2TL_3wq4l0ICWgJtNncp197lFQUrsCfas,5100
+BETTER_NMA-1.0.2.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+BETTER_NMA-1.0.2.dist-info/top_level.txt,sha256=SVRNqWPvCnynWVyXNAYnf9CSQIvMAvE6iyyiGHodQgY,11
+BETTER_NMA-1.0.2.dist-info/RECORD,,

BETTER_NMA-1.0.0.dist-info/METADATA

@@ -1,11 +0,0 @@
-Metadata-Version: 2.1
-Name: BETTER_NMA
-Version: 1.0.0
-Requires-Dist: tensorflow
-Requires-Dist: pandas
-Requires-Dist: igraph
-Requires-Dist: numpy
-Requires-Dist: scikit-learn
-Requires-Dist: matplotlib
-Requires-Dist: nltk
-Requires-Dist: keras