# seababy-i/soil_analysis architecture

> Architecture diagram of the GitHub repository seababy-i/soil_analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seababy-i/soil_analysis
- Repository: https://github.com/seababy-i/soil_analysis

## Overview

This repository is a soil analytics project: image classification and structured nutrient-deficiency models produce complementary assessments, with SHAP and Grad-CAM explanations and a hybrid assessment. It also contains a standalone soil recommendation engine. The README documents the ML stages and hybrid flow; the sampled engine excerpt confirms its knowledge-base read. Notebooks and model artifacts are represented at their existing paths; unsampled implementation details are not inferred.

Main entry points: [`notebooks/08_Hybrid_Soil_Analysis.ipynb`](https://github.com/seababy-i/soil_analysis/blob/main/notebooks/08_Hybrid_Soil_Analysis.ipynb) (Late-fusion assessment), [`notebooks/05_Structured_Soil_ML.ipynb`](https://github.com/seababy-i/soil_analysis/blob/main/notebooks/05_Structured_Soil_ML.ipynb) (Nutrient modeling), [`models/efficientnet_soil_classifier_finetuned.keras`](https://github.com/seababy-i/soil_analysis/blob/main/models/efficientnet_soil_classifier_finetuned.keras) (Fine-tuned classifier), [`models/N_deficiency_gradient_boosting.pkl`](https://github.com/seababy-i/soil_analysis/blob/main/models/N_deficiency_gradient_boosting.pkl) (Nitrogen model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_classification["Image Classification"]
  node_image_model["Fine-tuned classifier"]
  node_image_workflow["Image modeling"]
  node_gradcam["Grad-CAM explanations"]
  node_gradcam_outputs["Grad-CAM outputs"]
end

subgraph group_nutrients["Nutrient Assessment"]
  node_structured_workflow["Nutrient modeling"]
  node_n_model["Nitrogen model"]
  node_p_model["Phosphorus model"]
  node_k_model["Potassium model"]
  node_shap["SHAP explanations"]
  node_shap_outputs["SHAP plots"]
end

subgraph group_fusion["Hybrid Assessment"]
  node_hybrid["Late-fusion assessment"]
  node_hybrid_results["Hybrid results<br/>[hybrid_results.csv]"]
end

subgraph group_advisory["Soil Advisory"]
  node_recommendation_engine["Recommendation engine"]
  node_knowledge_base[("Agricultural knowledge")]
  node_crop_suitability[("Crop suitability data")]
end

node_farmer(("Soil analyst"))
node_image["Soil image"]
node_structured["Soil measurements"]

node_farmer -->|"provides image"| node_image
node_farmer -->|"provides measurements"| node_structured
node_image -->|"classifies image"| node_image_model
node_image_workflow -->|"trains model"| node_image_model
node_structured -->|"predicts deficiency"| node_n_model
node_structured -->|"predicts deficiency"| node_p_model
node_structured -->|"predicts deficiency"| node_k_model
node_structured_workflow -->|"trains model"| node_n_model
node_structured_workflow -->|"trains model"| node_p_model
node_structured_workflow -->|"trains model"| node_k_model
node_shap -->|"generates plots"| node_shap_outputs
node_gradcam -->|"visualizes regions"| node_gradcam_outputs
node_image_model -->|"supplies soil type"| node_hybrid
node_n_model -->|"supplies nutrient status"| node_hybrid
node_p_model -->|"supplies nutrient status"| node_hybrid
node_k_model -->|"supplies nutrient status"| node_hybrid
node_hybrid -->|"records results"| node_hybrid_results
node_farmer -.->|"submits soil data"| node_recommendation_engine
node_recommendation_engine -->|"loads guidance"| node_knowledge_base

click node_image_model "https://github.com/seababy-i/soil_analysis/blob/main/models/efficientnet_soil_classifier_finetuned.keras"
click node_image_workflow "https://github.com/seababy-i/soil_analysis/blob/main/notebooks/04_CNN_Soil_Image_Classification.ipynb"
click node_structured_workflow "https://github.com/seababy-i/soil_analysis/blob/main/notebooks/05_Structured_Soil_ML.ipynb"
click node_n_model "https://github.com/seababy-i/soil_analysis/blob/main/models/N_deficiency_gradient_boosting.pkl"
click node_p_model "https://github.com/seababy-i/soil_analysis/blob/main/models/P_deficiency_gradient_boosting.pkl"
click node_k_model "https://github.com/seababy-i/soil_analysis/blob/main/models/K_deficiency_gradient_boosting.pkl"
click node_shap "https://github.com/seababy-i/soil_analysis/blob/main/notebooks/06_SHAP_Explainability.ipynb"
click node_shap_outputs "https://github.com/seababy-i/soil_analysis/tree/main/Outputs/SHAP"
click node_gradcam "https://github.com/seababy-i/soil_analysis/blob/main/notebooks/07_GradCAM_Explainability.ipynb"
click node_gradcam_outputs "https://github.com/seababy-i/soil_analysis/tree/main/Outputs/GradCAM"
click node_hybrid "https://github.com/seababy-i/soil_analysis/blob/main/notebooks/08_Hybrid_Soil_Analysis.ipynb"
click node_hybrid_results "https://github.com/seababy-i/soil_analysis/blob/main/Outputs/Hybrid/hybrid_results.csv"
click node_recommendation_engine "https://github.com/seababy-i/soil_analysis/blob/main/recommendation/recommendation_engine.py"
click node_knowledge_base "https://github.com/seababy-i/soil_analysis/blob/main/recommendation/agricultural_knowledge_base.json"
click node_crop_suitability "https://github.com/seababy-i/soil_analysis/blob/main/recommendation/crop_suitability.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_image_model,node_image_workflow,node_gradcam,node_gradcam_outputs toneBlue
class node_structured_workflow,node_n_model,node_p_model,node_k_model,node_shap,node_shap_outputs toneAmber
class node_hybrid,node_hybrid_results toneMint
class node_recommendation_engine,node_knowledge_base,node_crop_suitability toneRose
class node_farmer,node_image,node_structured toneIndigo
```

## Components

### Image Classification

- [Fine-tuned classifier](https://github.com/seababy-i/soil_analysis/blob/main/models/efficientnet_soil_classifier_finetuned.keras): `models/efficientnet_soil_classifier_finetuned.keras`
- [Image modeling](https://github.com/seababy-i/soil_analysis/blob/main/notebooks/04_CNN_Soil_Image_Classification.ipynb): `notebooks/04_CNN_Soil_Image_Classification.ipynb`
- [Grad-CAM explanations](https://github.com/seababy-i/soil_analysis/blob/main/notebooks/07_GradCAM_Explainability.ipynb): `notebooks/07_GradCAM_Explainability.ipynb`
- [Grad-CAM outputs](https://github.com/seababy-i/soil_analysis/tree/main/Outputs/GradCAM): `Outputs/GradCAM`

### Nutrient Assessment

- [Nutrient modeling](https://github.com/seababy-i/soil_analysis/blob/main/notebooks/05_Structured_Soil_ML.ipynb): `notebooks/05_Structured_Soil_ML.ipynb`
- [Nitrogen model](https://github.com/seababy-i/soil_analysis/blob/main/models/N_deficiency_gradient_boosting.pkl): `models/N_deficiency_gradient_boosting.pkl`
- [Phosphorus model](https://github.com/seababy-i/soil_analysis/blob/main/models/P_deficiency_gradient_boosting.pkl): `models/P_deficiency_gradient_boosting.pkl`
- [Potassium model](https://github.com/seababy-i/soil_analysis/blob/main/models/K_deficiency_gradient_boosting.pkl): `models/K_deficiency_gradient_boosting.pkl`
- [SHAP explanations](https://github.com/seababy-i/soil_analysis/blob/main/notebooks/06_SHAP_Explainability.ipynb): `notebooks/06_SHAP_Explainability.ipynb`
- [SHAP plots](https://github.com/seababy-i/soil_analysis/tree/main/Outputs/SHAP): `Outputs/SHAP`

### Hybrid Assessment

- [Late-fusion assessment](https://github.com/seababy-i/soil_analysis/blob/main/notebooks/08_Hybrid_Soil_Analysis.ipynb): `notebooks/08_Hybrid_Soil_Analysis.ipynb`
- [Hybrid results](https://github.com/seababy-i/soil_analysis/blob/main/Outputs/Hybrid/hybrid_results.csv): `Outputs/Hybrid/hybrid_results.csv`

### Soil Advisory

- [Recommendation engine](https://github.com/seababy-i/soil_analysis/blob/main/recommendation/recommendation_engine.py): `recommendation/recommendation_engine.py`
- [Agricultural knowledge](https://github.com/seababy-i/soil_analysis/blob/main/recommendation/agricultural_knowledge_base.json): `recommendation/agricultural_knowledge_base.json`
- [Crop suitability data](https://github.com/seababy-i/soil_analysis/blob/main/recommendation/crop_suitability.json): `recommendation/crop_suitability.json`

### Other components

- **Soil analyst**
- **Soil image**
- **Soil measurements**

## Connections

- Soil analyst → Soil image: provides image (evidence: `README.md`)
- Soil analyst → Soil measurements: provides measurements (evidence: `README.md`)
- Soil image → Fine-tuned classifier: classifies image (evidence: `README.md`)
- Image modeling → Fine-tuned classifier: trains model (evidence: `README.md`)
- Soil measurements → Nitrogen model: predicts deficiency (evidence: `README.md`)
- Soil measurements → Phosphorus model: predicts deficiency (evidence: `README.md`)
- Soil measurements → Potassium model: predicts deficiency (evidence: `README.md`)
- Nutrient modeling → Nitrogen model: trains model (evidence: `README.md`)
- Nutrient modeling → Phosphorus model: trains model (evidence: `README.md`)
- Nutrient modeling → Potassium model: trains model (evidence: `README.md`)
- SHAP explanations → SHAP plots: generates plots (evidence: `README.md`)
- Grad-CAM explanations → Grad-CAM outputs: visualizes regions (evidence: `README.md`)
- Fine-tuned classifier → Late-fusion assessment: supplies soil type (evidence: `README.md`)
- Nitrogen model → Late-fusion assessment: supplies nutrient status (evidence: `README.md`)
- Phosphorus model → Late-fusion assessment: supplies nutrient status (evidence: `README.md`)
- Potassium model → Late-fusion assessment: supplies nutrient status (evidence: `README.md`)
- Late-fusion assessment → Hybrid results: records results (evidence: `README.md`)
- Soil analyst → Recommendation engine: submits soil data
- Recommendation engine → Agricultural knowledge: loads guidance (evidence: `recommendation/recommendation_engine.py`)
