Upload 10 files

README.md

@@ -1,29 +1,39 @@
+
 # Interpretable-SONAR-Image-Classifier
 
-Explainable AI for Underwater SONAR Image Classifier
+Explainable AI for Underwater SONAR Image Classifier to enhance model interpretability with techniques like LIME, SHAP, and Grad-CAM. It employs transfer learning with popular deep learning models (e.g., VGG16, ResNet50, DenseNet121) to classify images, while providing insights into model predictions, making it suitable for use cases requiring transparency and reliability in SONAR image analysis.
+
+The following guide details the requirements, usage, and examples for running the scripts within the project, along with how to generate explanations for model predictions.
+
 
 ## Prerequisites
 
-- Python 3.6 or higher
+- **Python 3.9**
+- **Conda**: You can create the required environment using `environment.yaml`.
 
-## Running the Scripts
+### Setting Up the Environment
 
-This guide will help you run the `data_loader.py`, `train.py`, `test.py`, `predict.py`, and `classify_image_and_explain.py` scripts directly from the command line or within a Python script.
+1. **Conda Environment**: To ensure all dependencies are correctly installed, create a new environment using the provided `environment.yaml` file.
 
-### Prerequisites
+   ```bash
+   conda env create -f environment.yaml
+   ```
 
-1. **Python Installation**: Ensure you have Python installed. You can download it from [python.org](https://www.python.org/).
+2. **Activate the Environment**:
 
-2. **Required Packages**: Install the required packages using `requirements.txt`.
-   ```sh
-   pip install -r requirements.txt
+   ```bash
+   conda activate Interpretable-SONAR-Image-Classifier
    ```
 
-### Script Descriptions and Usage
+This setup ensures compatibility and includes all necessary packages and versions as defined in the `environment.yaml` file.
+
+### Running the Scripts
+
+The following sections describe each script and its usage. Run these scripts directly from the command line or within a Python script.
 
 #### 1. `data_loader.py`
 
-This script is used to load, process, split datasets (train, val, test), and augment data.
+This script loads, processes, splits datasets (train, val, test), and performs optional data augmentation.
 
 **Command Line Usage:**
 
@@ -33,12 +43,12 @@ python data_loader.py --path <path_to_data> --target_folder <path_to_target_fold
 
 **Arguments:**
 
-- `--path`: Path to the data.
-- `--target_folder`: Path to the target folder where processed data will be saved.
-- `--dim`: Dimension for resizing the images.
+- `--path`: Path to the raw data.
+- `--target_folder`: Directory for processed data.
+- `--dim`: Image resize dimension (e.g., 224 for 224x224).
 - `--batch_size`: Batch size for data loading.
 - `--num_workers`: Number of workers for data loading.
-- `--augment_data` (optional): Flag to enable data augmentation.
+- `--augment_data` (optional): Enables data augmentation.
 
 **Example:**
 
@@ -48,7 +58,7 @@ python data_loader.py --path "./dataset" --target_folder "./processed_data" --di
 
 **Dataset Structure:**
 
-```sh
+```plaintext
 ├── Dataset (Raw)
    ├── class_name_1
    │   └── *.jpg
@@ -62,36 +72,36 @@ python data_loader.py --path "./dataset" --target_folder "./processed_data" --di
 
 #### 2. `train.py`
 
-This script is used for training and storing the models, leveraging transfer learning.
+This script trains models with options for transfer learning and custom base models.
 
 **Command Line Usage:**
 
 ```sh
-python train.py --base_model_names <model_names> --shape <shape> --data_path <data_path> --log_dir <log_dir> --model_dir <model_dir> --epochs <epochs> --optimizer <optimizer> --learning_rate <learning_rate> --batch_size <batch_size>
+python train.py --base_models <model_names> --shape <shape> --data_path <data_path> --log_dir <log_dir> --model_dir <model_dir> --epochs <epochs> --optimizer <optimizer> --learning_rate <learning_rate> --batch_size <batch_size>
 ```
 
 **Arguments:**
 
-- `--base_models`: Comma-separated list of base model names (e.g., 'VGG16, ResNet50').
-- `--shape`: Image shape (size).
-- `--data_path`: Path to the data.
-- `--log_dir`: Path to the log directory.
-- `--model_dir`: Path to the model directory.
-- `--epochs`: Number of training epochs.
-- `--optimizer`: Optimizer type ('adam' or 'sgd').
-- `--learning_rate`: Learning rate for the optimizer.
-- `--batch_size`: Batch size for training.
-- `--patience`: Patience for early stopping (to prevent overfitting).
+- `--base_models`: Comma-separated list of base models (e.g., "VGG16,DenseNet121").
+- `--shape`: Image shape, e.g., `224 224 3`.
+- `--data_path`: Path to processed data.
+- `--log_dir`: Directory for logs.
+- `--model_dir`: Directory to save models.
+- `--epochs`: Number of epochs.
+- `--optimizer`: Optimizer type (`adam` or `sgd`).
+- `--learning_rate`: Learning rate.
+- `--batch_size`: Training batch size.
+- `--patience`: Early stopping patience.
 
 **Example:**
 
 ```sh
-python train.py --base_models "VGG16" "DenseNet121" --shape 224 224 3 --data_path "./processed_data" --log_dir "./logs" --model_dir "./models" --epochs 100 --optimizer "adam" --learning_rate 0.0001 --batch_size 32
+python train.py --base_models "VGG16,DenseNet121" --shape 224 224 3 --data_path "./processed_data" --log_dir "./logs" --model_dir "./models" --epochs 100 --optimizer "adam" --learning_rate 0.0001 --batch_size 32
 ```
 
 #### 3. `test.py`
 
-This script is used for testing and storing the test logs of the above-trained models.
+Tests the trained models and logs the results.
 
 **Command Line Usage:**
 
@@ -101,22 +111,22 @@ python test.py --data_path <data_path> --base_model_name <base_model_name> --mod
 
 **Arguments:**
 
-- `--models_dir` (optional): Path to the models (directory).
-- `--model_path`: Path to the model (.h5/Keras Model).
-- `--img_path`: Path to the image file.
-- `--test_dir`: Path to the test dataset (directory).
-- `--train_dir`: Path to the training data.
-- `--log_dir`: Path to the log directory.
+- `--models_dir` (optional): Path to the models directory.
+- `--model_path`: Specific model path (.h5 file).
+- `--img_path`: Image file path for testing.
+- `--test_dir`: Test dataset directory.
+- `--train_dir`: Directory for training data.
+- `--log_dir`: Directory for logs.
 
 **Example:**
 
 ```sh
-python test.py --model_path "./models/vgg16_model.keras" --test_dir "./test_data" --train_dir "./data/train" --log_dir "./logs"
+python test.py --model_path "./models/vgg16_model.h5" --test_dir "./test_data" --train_dir "./data/train" --log_dir "./logs"
 ```
 
 #### 4. `predict.py`
 
-This script is used for making predictions on new images.
+Makes predictions on new images.
 
 **Command Line Usage:**
 
@@ -126,19 +136,19 @@ python predict.py --model_path <model_path> --img_path <img_path> --train_dir <t
 
 **Arguments:**
 
-- `--model_path`: Path to the model file.
-- `--img_path`: Path to the image file.
-- `--train_dir`: Path to the training dataset (for the label decoder, can be replaced with a CSV file with slight code modifications).
+- `--model_path`: Model file path.
+- `--img_path`: Image file path.
+- `--train_dir`: Directory for label decoding.
 
 **Example:**
 
 ```sh
-python predict.py --model_path "./models/vgg16_model.keras" --img_path "./images/test_image.jpg" --train_dir "./data/train"
+python predict.py --model_path "./models/vgg16_model.h5" --img_path "./images/test_image.jpg" --train_dir "./data/train"
 ```
 
 #### 5. `classify_image_and_explain.py`
 
-This script is used for making predictions on new images and generating explanations using one or more explainers (LIME, SHAP, Grad-CAM). The explanations are saved in the specified output folder, with filenames indicating the method used (e.g., `lime_explanation_1.jpg`, `shap_explanation_1.jpg`, `gradcam_explanation_1.jpg`).
+Makes predictions and generates explanations using LIME, SHAP, or Grad-CAM.
 
 **Command Line Usage:**
 
@@ -148,24 +158,24 @@ python classify_image_and_explain.py --image_path <image_path> --model_path <mod
 
 **Arguments:**
 
-- `--image_path` (required): Path to the input image.
-- `--model_path` (required): Path to the trained model.
-- `--train_directory` (required): Directory containing training images.
-- `--num_samples` (default: 300): Number of samples for LIME.
-- `--num_features` (default: 100): Number of features for LIME.
-- `--segmentation_alg` (default: `quickshift`): Segmentation algorithm for LIME (`quickshift`, `slic`).
-- `--kernel_size` (default: 4): Kernel size for the segmentation algorithm.
-- `--max_dist` (default: 200): Maximum distance for the segmentation algorithm.
-- `--ratio` (default: 0.2): Ratio for the segmentation algorithm.
-- `--max_evals` (default: 400): Maximum evaluations for SHAP.
-- `--batch_size` (default: 50): Batch size for SHAP.
-- `--explainer_types` (default: 'all'): Comma-separated list of explainers to use (`lime`, `shap`, `gradcam`). Use 'all' to include all three explainers.
-- `--output_folder` (optional): Folder to save explanation images.
+- `--image_path`: Path to the image file.
+- `--model_path`: Model file path.
+- `--train_directory`: Directory of training images for label decoding.
+- `--num_samples`: Sample count for LIME.
+- `--num_features`: Feature count for LIME.
+- `--segmentation_alg`: Segmentation algorithm for LIME.
+- `--kernel_size`: Kernel size for segmentation.
+- `--max_dist`: Max distance for segmentation.
+- `--ratio`: Ratio for segmentation.
+- `--max_evals`: Max evaluations for SHAP.
+- `--batch_size`: Batch size for SHAP.
+- `--explainer_types`: Comma-separated list of explainers (`lime`, `shap`, `gradcam`).
+- `--output_folder`: Directory to save explanations.
 
 **Example:**
 
 ```sh
-python classify_image_and_explain.py --image_path "./images/test_image.jpg" --model_path "./models/model.keras" --train_directory "./data/train" --num_samples 300 --num_features 100 --segmentation_alg "quickshift" --kernel_size 4 --max_dist 200 --ratio 0.2 --max_evals 400 --batch_size 50 --explainer_types "lime, gradcam" --output_folder "./explanations"
+python classify_image_and_explain.py --image_path "./images/test_image.jpg" --model_path "./models/model.h5" --train_directory "./data/train" --num_samples 300 --num_features 100 --segmentation_alg "quickshift" --kernel_size 4 --max_dist 200 --ratio 0.2 --max_evals 400 --batch_size 50 --explainer_types "lime,gradcam" --output_folder "./explanations"
 ```
 
 ### Supported Base Models
@@ -186,7 +196,7 @@ The following base models are supported for training:
 - EfficientNetB0
 - EfficientNetB7
 
-### Running Scripts in a Python Script
+### Running Scripts in Jupyter Notebook
 
 You can also run these scripts programmatically using Python's `subprocess` module. Here is an example of how to do this for each script: