tutorials/notebooks/22_stac_df_labeling.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# STACDataFrame labeling"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we want to generate STAC metadata from a imagery dataset through EOTDL, we must generate a STACDataFrame, as seen in this [notebook](20_stac.ipynb). When generating the STACDataFrame, there is a needed parameter called `labeling_strategy`. In this notebook we are going to dive in it.\n",
    "\n",
    "Uncomment the following line to install eotdl if needed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# !pip install eotdl"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `labeling_strategy` parameter defines the strategy to extract a label from the filename of an image, to assign a label to it when creating the `STACDataframe`. By default, we have implemented 2 strategies, but if you want to implement your own `labeling_strategy`, you can check this [notebook](32_create_your_own_df_labeler.ipynb) for further information about how to contribute.\n",
    "\n",
    "- `UnlabeledStrategy`: we will use it when the images do not have a label that identifies them or that has been placed on purpose.\n",
    "\n",
    "<p align=\"center\">\n",
    "        <img src=\"assets/structured_parser.png\" alt=\"Structured parser typical folder structure\" style=\"height:170px; width:200px;\"/>\n",
    "</p>\n",
    "\n",
    "- `LabeledStrategy`: we will use it when the images are labeled with labels in their filenames. An example would be that in a folder the images were called, for example, River_1.png, River_2.png, River_3.png, and so on. The file name must be the pattern `<label>_<number>`. \n",
    "\n",
    "<p align=\"center\">\n",
    "        <img src=\"assets/unestructured_parser.png\" alt=\"Structured parser typical folder structure\" style=\"height:200px; width:200px;\"/>\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's see some examples. In all of them we are going to use the `UnestructuredParser` as `item_parser`. For further information about this feature, see the \n",
    "[next notebook](23_stac_item_parsers.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from eotdl.curation.stac.dataframe_labeling import UnlabeledStrategy, LabeledStrategy\n",
    "from eotdl.curation.stac.parsers import UnestructuredParser\n",
    "from eotdl.curation.stac.stac import STACGenerator"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the first example we are going to generate a `STACDataFrame` from the dataset in `jaca_dataset`, which images simply are named as `Jaca_1`, `Jaca_2`, and so on. This is a perfect example for an Unlabeled dataset to use the `UnlabeledStrategy` with, as `Jaca` is not a label itself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>image</th>\n",
       "      <th>label</th>\n",
       "      <th>ix</th>\n",
       "      <th>collection</th>\n",
       "      <th>extensions</th>\n",
       "      <th>bands</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_1.tif</td>\n",
       "      <td>Jaca_1</td>\n",
       "      <td>0</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_2.tif</td>\n",
       "      <td>Jaca_2</td>\n",
       "      <td>1</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_3.tif</td>\n",
       "      <td>Jaca_3</td>\n",
       "      <td>2</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>example_data/jaca_dataset/Jaca_4.tif</td>\n",
       "      <td>Jaca_4</td>\n",
       "      <td>3</td>\n",
       "      <td>example_data/jaca_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                  image   label  ix  \\\n",
       "0  example_data/jaca_dataset/Jaca_1.tif  Jaca_1   0   \n",
       "1  example_data/jaca_dataset/Jaca_2.tif  Jaca_2   1   \n",
       "2  example_data/jaca_dataset/Jaca_3.tif  Jaca_3   2   \n",
       "3  example_data/jaca_dataset/Jaca_4.tif  Jaca_4   3   \n",
       "\n",
       "                         collection extensions bands  \n",
       "0  example_data/jaca_dataset/source       None  None  \n",
       "1  example_data/jaca_dataset/source       None  None  \n",
       "2  example_data/jaca_dataset/source       None  None  \n",
       "3  example_data/jaca_dataset/source       None  None  "
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "stac_generator = STACGenerator(item_parser=UnestructuredParser,\n",
    "                               labeling_strategy=UnlabeledStrategy,\n",
    "                               image_format='tif'\n",
    "                               )\n",
    "df = stac_generator.get_stac_dataframe('example_data/jaca_dataset')\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> Note: for this concrete dataset we could also have used the `LabeledStrategy`, as we have seen in this [notebook](20_stac.ipynb), but it is also a clear example of `UnlabeledStratefgy`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the second example we are going to generate a `STACDataFrame` from the dataset in `eurosat_rgb_dataset`, which images simply are named as `River_1`, `Forest_1`, and so on. This is a perfect example for an labeled dataset to use the `LabeledStrategy` with, as `River`, `Forest` or `AnnualCrop` are labels."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>image</th>\n",
       "      <th>label</th>\n",
       "      <th>ix</th>\n",
       "      <th>collection</th>\n",
       "      <th>extensions</th>\n",
       "      <th>bands</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>example_data/eurosat_rgb_dataset/Forest/Forest...</td>\n",
       "      <td>Forest</td>\n",
       "      <td>0</td>\n",
       "      <td>example_data/eurosat_rgb_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>example_data/eurosat_rgb_dataset/River/River_1...</td>\n",
       "      <td>River</td>\n",
       "      <td>1</td>\n",
       "      <td>example_data/eurosat_rgb_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>example_data/eurosat_rgb_dataset/Highway/Highw...</td>\n",
       "      <td>Highway</td>\n",
       "      <td>2</td>\n",
       "      <td>example_data/eurosat_rgb_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>example_data/eurosat_rgb_dataset/AnnualCrop/An...</td>\n",
       "      <td>AnnualCrop</td>\n",
       "      <td>3</td>\n",
       "      <td>example_data/eurosat_rgb_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>example_data/eurosat_rgb_dataset/SeaLake/SeaLa...</td>\n",
       "      <td>SeaLake</td>\n",
       "      <td>4</td>\n",
       "      <td>example_data/eurosat_rgb_dataset/source</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                               image       label  ix  \\\n",
       "0  example_data/eurosat_rgb_dataset/Forest/Forest...      Forest   0   \n",
       "1  example_data/eurosat_rgb_dataset/River/River_1...       River   1   \n",
       "2  example_data/eurosat_rgb_dataset/Highway/Highw...     Highway   2   \n",
       "3  example_data/eurosat_rgb_dataset/AnnualCrop/An...  AnnualCrop   3   \n",
       "4  example_data/eurosat_rgb_dataset/SeaLake/SeaLa...     SeaLake   4   \n",
       "\n",
       "                                collection extensions bands  \n",
       "0  example_data/eurosat_rgb_dataset/source       None  None  \n",
       "1  example_data/eurosat_rgb_dataset/source       None  None  \n",
       "2  example_data/eurosat_rgb_dataset/source       None  None  \n",
       "3  example_data/eurosat_rgb_dataset/source       None  None  \n",
       "4  example_data/eurosat_rgb_dataset/source       None  None  "
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "stac_generator = STACGenerator(item_parser=UnestructuredParser,\n",
    "                               labeling_strategy=LabeledStrategy,\n",
    "                               image_format='jpg'   # the images are jpg\n",
    "                               )\n",
    "df = stac_generator.get_stac_dataframe('example_data/eurosat_rgb_dataset')\n",
    "df.head()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "sen12floods",
   "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.11.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}