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

BETTER_NMA-1.0.1.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.1
+Name: BETTER_NMA
+Version: 1.0.1
+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.1.dist-info}/RECORD

@@ -32,7 +32,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.1.dist-info/METADATA,sha256=F4ZFsCJpeZVeYLJ2sMlDEC1c-gZTdvyfJvUxGxEQ2HQ,5100
+BETTER_NMA-1.0.1.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+BETTER_NMA-1.0.1.dist-info/top_level.txt,sha256=SVRNqWPvCnynWVyXNAYnf9CSQIvMAvE6iyyiGHodQgY,11
+BETTER_NMA-1.0.1.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