BETTER-NMA 1.0.0__tar.gz → 1.0.1__tar.gz

better_nma-1.0.1/BETTER_NMA.egg-info/PKG-INFO

@@ -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.1/BETTER_NMA.egg-info/requires.txt

@@ -0,0 +1,9 @@
+tensorflow>=2.10.0
+pandas>=1.3.0
+python-igraph>=0.10.0
+numpy>=1.21.0
+scikit-learn>=1.0.0
+matplotlib>=3.5.0
+nltk>=3.7
+keras>=2.10.0
+Pillow>=8.0.0

better_nma-1.0.1/PKG-INFO

@@ -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.1/README.md

@@ -0,0 +1,144 @@
+
+---
+
+# 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.1/setup.py

@@ -0,0 +1,46 @@
+from setuptools import setup, find_packages
+
+try:
+    with open("README.md", "r", encoding="utf-8") as fh:
+        long_description = fh.read()
+except FileNotFoundError:
+    long_description = "Network Model Analysis for adversarial detection and explanation"
+
+setup(
+    name="BETTER_NMA",
+    version="1.0.1",
+    author="BETTER_XAI",
+    author_email="BETTERXAI2025@gmail.com",
+    description="NMA: Dendrogram-based model analysis, white-box testing, and adversarial detection",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    classifiers=[  
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "Intended Audience :: Science/Research",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    ],
+    python_requires=">=3.8",
+    packages=find_packages(),
+    install_requires=[
+        "tensorflow>=2.10.0",
+        "pandas>=1.3.0",
+        "python-igraph>=0.10.0", 
+        "numpy>=1.21.0",
+        "scikit-learn>=1.0.0",
+        "matplotlib>=3.5.0",
+        "nltk>=3.7",
+        "keras>=2.10.0",
+        "Pillow>=8.0.0",
+    ],
+)
+
+

better_nma-1.0.0/BETTER_NMA.egg-info/PKG-INFO

@@ -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

better_nma-1.0.0/BETTER_NMA.egg-info/requires.txt

@@ -1,8 +0,0 @@
-tensorflow
-pandas
-igraph
-numpy
-scikit-learn
-matplotlib
-nltk
-keras

better_nma-1.0.0/PKG-INFO

@@ -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

better_nma-1.0.0/README.md

@@ -1,18 +0,0 @@
-# BETTER-Package
-
-### changes from previous code: 
-- no attacks types
-- no datasets
-- GraphType -> ExplanationMethod
-- No available dataset info / train / test sets 
-- No local files saving - no eages df, no CSVs etc..
-
-
-## Functionalities to add - untill Sunday 31/8 
-- API for calculating the LCA of two given classes 
-- API for givin the user the score of one image 
-- Plotting with cluster names - in two stages - return a json (1) and then plot the info from the json (2) (so that the user could modify the cluster names before plotting)
-- Automatic WBT - problematic connections identification
-
-## TODO: 
-- search for a package that plots with cluster names 

better_nma-1.0.0/setup.py

@@ -1,19 +0,0 @@
-from setuptools import setup, find_packages
-
-setup(
-    name="BETTER_NMA",
-    version="1.0.0",
-    packages=find_packages(),
-    install_requires=[
-        "tensorflow",
-        "pandas",
-        "igraph",
-        "numpy",
-        "scikit-learn",
-        "matplotlib",
-        "nltk",
-        "keras",
-    ],
-)
-
-