demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Demo Notebook: Flood Detection with Sen1Floods11 Dataset on SharingHub\n",
    "\n",
    "## Objective\n",
    "\n",
    "This notebook demonstrates how to organize, train, and use a deep learning model for image segmentation through the flood detection using the [**Sen1Floods11 dataset**](https://github.com/cloudtostreet/Sen1Floods11?tab=readme-ov-file), leveraging the [**SharingHub**](https://sharinghub.p2.csgroup.space/#/) platform.\n",
    "\n",
    "### Key Features of this Demo:\n",
    "1. **Dataset Management**: Retrieve datasets stored on SharingHub, using DVC and GitLab integration.\n",
    "2. **Experiment Tracking**: Configure and use MLflow for tracking training experiments, directly linked to the GitLab repository.\n",
    "3. **Model Training**: Train the flood detection model with data downloaded from its DVC remote.\n",
    "4. **Model Inference**: Use the trained model to perform segmentation on unseen data, predicting flooded areas.\n",
    "5. **Automation**: Streamline operations with Docker containers and CWL workflows for reproducibility.\n",
    "\n",
    "---\n",
    "\n",
    "## Workflow Overview\n",
    "\n",
    "### 1. **Sen1Floods11 Dataset**\n",
    "- Dataset presentation.\n",
    "- Dataset access.\n",
    "\n",
    "### 2. **Training the Model**\n",
    "- Process data.\n",
    "- Store the model in onnx format.\n",
    "- Get metrics to evaluate the model performances.\n",
    "- Track the model’s performance using the metrics on MLflow UI.\n",
    "\n",
    "### 3. **Inference**\n",
    "- Perform segmentation on Sentinel-1 images to detect flooded areas.\n",
    "- Visualize results to evaluate model performance.\n",
    "\n",
    "### 4. **Reproducibility**\n",
    "- Use Docker containers and CWL workflows for consistent environment setup and execution.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### **prerequisite**\n",
    "\n",
    "Install your poetry environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!poetry install --no-root"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1. **Sen1Floods11 Dataset**\n",
    "\n",
    "### **Presentation**\n",
    "\n",
    "Sen1Floods11: a georeferenced dataset to train and test deep learning flood algorithms for Sentinel-1 (Example). This data was generated by Cloud to Street, a Public Benefit Corporation: https://www.cloudtostreet.info/. For questions about this dataset or code please email support@cloudtostreet.info. Please cite this data as:\n",
    "\n",
    "Bonafilia, D., Tellman, B., Anderson, T., Issenberg, E. 2020. Sen1Floods11: a georeferenced dataset to train and test deep learning flood algorithms for Sentinel-1. The IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR) Workshops, 2020, pp. 210-211.\n",
    "\n",
    "Available Open access at: http://openaccess.thecvf.com/content_CVPRW_2020/html/w11/Bonafilia_Sen1Floods11_A_Georeferenced_Dataset_to_Train_and_Test_Deep_Learning_CVPRW_2020_paper.html\n",
    "\n",
    "### **Dataset Access**\n",
    "setup credentials"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cd sen1floods11-dataset/ && dvc remote modify --local sharinghub access_key_id <your_access_token> or <your_personal_gitlab_token>  && dvc remote modify --local sharinghub secret_access_key none"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then pull the data. With DVC[s3] we can fetch the data stored in a s3 bucket."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cd sen1floods11-dataset/ && dvc pull"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2. **Training the model**\n",
    "Setup credentials for _mlflow_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!export MLFLOW_TRACKING_TOKEN=<your_access_token> or <your_personal_gitlab_token>\n",
    "!export LOGNAME=<username>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Run training session"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!poetry run python3 src/train.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3. **Inference**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!poetry run python3 src/inference.py checkpoints/Sen1Floods11_0_0.5194225907325745.onnx inference/India_80221_S1Hand.tif"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4. **Reproducibility**\n",
    "## **Docker**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create docker image for training from Dockerfile.train"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add your credentials in a .env file and run the docker image:\n",
    "-   MLFLOW_TRACKING_TOKEN=\n",
    "-   LOGNAME=\n",
    "-    ACCESS_KEY_ID= \n",
    "-    SECRET_ACCESS_KEY= \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!docker build -f Dockerfile.train -t train ."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Streaming Mode in `train`\n",
    "\n",
    "The *streaming* mode in `train` allows data to be downloaded on the fly, image by image, during training. Then the downloaded data is stored in the cache. This eliminates the need to download the **entire** dataset, saving both time and storage space. Data is progressively loaded from remote storage via DVC, reducing memory usage and optimizing the training process. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### No Cache Mode in `train`\n",
    "\n",
    "If *no cache* mode in `train` is enabled with the *streaming mode*, the data is downloaded on the fly, but not saved locally in the cache. This mode is ideal for handling large datasets without overwhelming local resources."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!docker run -it --env-file .env train bash"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create docker image for inference from Dockerfile.inf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!docker build -f Dockerfile.inf --build-arg ONNX_PATH=checkpoints/Sen1Floods11_0_0.5313226580619812.onnx -t inference ."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Run the docker image for inference\n",
    "#### Mount your own image for inference"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!docker run --rm -v <path/to/input>:/app/inference/input.tif inference inference/input.tif"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## **CWL**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Run the docker image using cwl with custom parameters saved in run_inference_input.yml"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cwltool run_inference.cwl run_inference_input.yml "
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "sen1floods11-isRT4Uh--py3.12",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}