Metadata-Version: 2.4
Name: BETTER_NMA
Version: 2.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
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


---

# 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.

* 🌳 **Concept Tree Generation & Plotting**

  * Extract semantic WordNet concept hierarchies from dendrograms.
  * Generic fallback support: custom dictionaries or auto WordNet search.
  * Publication-ready colored concept tree visualization.

* 🧪 **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)

# Build a semantic Concept Tree using WordNet
# Defaults to built-in ImageNet mapping, or fallback text-search if no mapping match
concept_tree = nma.build_concept_tree()

# Plot the resolved Concept Tree
nma.plot_concept_tree(concept_tree, title="Decision Concept Tree")
```

---

## 📚 API Overview

### Dendrogram & Visualization

* `plot(sub_labels=None, ...)` – plot full or partial dendrogram.
* `plot_sub_dendrogram(sub_labels, ...)` – zoom into specific classes.
* `build_concept_tree(custom_mapping=None, allowed_labels=None)` – build resolved Concept Tree.
* `plot_concept_tree(concept_tree, title=...)` – plot colored multi-branch concept hierarchy.

### 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 using logistic regression detector.
* `detect_attack_by_threshold(image, threshold=0.35, ...)` – detect adversarial samples using a specific LCA score threshold.
* `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.

---

## 🌳 Concept Tree Guide

The Concept Tree feature maps your model's classification hierarchy into a human-understandable WordNet semantic tree by resolving intermediate clusters.

### Custom database / label-to-synset mappings
If you are working with a custom dataset or custom labels, you can pass a custom dictionary mapping class labels to WordNet synset IDs:

```python
# Custom mapping: key is label, value is ImageNet/WordNet synset ID (n + 8 digits)
custom_map = {
    "cat": "n02121808",
    "dog": "n02084071",
    "apple": "n07739125",
}

# Build the tree using your custom mapping
concept_tree = nma.build_concept_tree(custom_mapping=custom_map)
nma.plot_concept_tree(concept_tree)
```

If no mapping is provided, NMA will use the default 41-class ImageNet mapping. If a class label doesn't match any mapping, NMA automatically falls back to searching WordNet directly using the label name or sub-words.

---

## 🛠 Requirements

* Python ≥ 3.8
* NumPy, Pandas, Matplotlib, Scikit-learn, SciPy
* NLTK (requires `wordnet` corpus downloaded: `nltk.download('wordnet')`)
* (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.

---

