{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Download MRMS data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initial configuration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pandas import Timestamp, Timedelta\n",
    "import emaremes as mrms"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first step is to configure where the data will be stored locally. By default, the data will be stored in the `emaremes` folder in your home directory.\n",
    "\n",
    "Setting up these paths is done with the `path_config` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "defaultpath: /home/edwin/emaremes\n",
       "prefered: /home/edwin/emaremes"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "path_config = mrms.fetch.path_config\n",
    "path_config"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To set another directory to store GRIB files, you can use the following command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Prefered path to store *new* Gribfiles is  data\n"
     ]
    }
   ],
   "source": [
    "new_dir = \"./data\"\n",
    "path_config.set_prefered(new_dir)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can add other folders where GRIB files are stored. `emaremes` only downloads the files that are not already present in the folder specified in `path_config`. This is useful to connect other local folders with MRMS data like external drives."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The preferred data directory is data\n"
     ]
    }
   ],
   "source": [
    "another_dir = \"./other_data\"\n",
    "path_config.add_path(another_dir)\n",
    "\n",
    "print(f\"The preferred data directory is {path_config.prefered_path}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To list all the paths available, we can print the `all_paths` attribute of `path_config`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{PosixPath('other_data'), PosixPath('data'), PosixPath('/home/edwin/emaremes')}\n"
     ]
    }
   ],
   "source": [
    "print(path_config.all_paths)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Download precipitation rate data\n",
    "\n",
    "MRMS data is available every 2 minutes. We can download the data using the `fetch` module in emaremes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-> 13 files requested...\n",
      "-> 13 *new* files will be downloaded...\n",
      "Saved data/20240928/PrecipRate_00.00_20240928-000000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-210000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-140000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-230000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-220000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-180000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-160000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-190000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-150000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-170000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-200000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-130000.grib2.gz :)\n",
      "Saved data/20240927/PrecipRate_00.00_20240927-120000.grib2.gz :)\n"
     ]
    }
   ],
   "source": [
    "preciprate_files = mrms.fetch.timerange(\n",
    "    \"2024-09-27T12:00:00\",\n",
    "    \"2024-09-28\",\n",
    "    frequency=Timedelta(minutes=60),\n",
    "    verbose=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`fetch.timerange` start and end times are both inclusive:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First file:  /home/edwin/emaremes/20240927/PrecipRate_00.00_20240927-120000.grib2.gz\n",
      "Last file:  data/20240928/PrecipRate_00.00_20240928-000000.grib2.gz\n"
     ]
    }
   ],
   "source": [
    "print(\"First file: \", preciprate_files[0])\n",
    "print(\"Last file: \", preciprate_files[-1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These files are stored locally and new network requests will be skipped if these files are fetched again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-> 13 files requested...\n",
      "Nothing new to download :D\n"
     ]
    }
   ],
   "source": [
    "preciprate_files = mrms.fetch.timerange(\n",
    "    \"2024-09-27T12:00:00\",\n",
    "    \"2024-09-28\",\n",
    "    frequency=Timedelta(minutes=60),\n",
    "    verbose=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Download other `data_type`\n",
    "\n",
    "The `fetch.timerange` function downloads precipiration rate data by default. Besides precipiration rate data, other `data_type` are available, like daily accumulated precipitation and precipitation flags. \n",
    "\n",
    "\n",
    "### Precipitation flags\n",
    "Precipitation flags refer to the following classification, derived from the [mrms-support repo](https://github.com/NOAA-National-Severe-Storms-Laboratory/mrms-support/blob/3edf7c25f503f81a12eb179dbbd3d4dae607e477/GRIB2_TABLES/UserTable_MRMS_PrecipFlags.csv): \n",
    "\n",
    "|Flag|Description|\n",
    "|:-:|:-|\n",
    "|-3|no coverage|\n",
    "|0|no precipitation|\n",
    "|1|warm stratiform rain|\n",
    "|3|snow|\n",
    "|6|convective rain|\n",
    "|7|rain mixed with hail|\n",
    "|10|cold stratiform rain|\n",
    "|91|tropical/stratiform rain mix|\n",
    "|96|tropical/convective rain mix|\n",
    "\n",
    "To download precipitation flags, use the `data_type=\"precip_flag\"` keyword argument:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-> 13 files requested...\n",
      "-> 13 *new* files will be downloaded...\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-160000.grib2.gz :)\n",
      "Saved data/20240928/PrecipFlag_00.00_20240928-000000.grib2.gz :)\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-180000.grib2.gz :)\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-130000.grib2.gz :)\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-200000.grib2.gz :)Saved data/20240927/PrecipFlag_00.00_20240927-120000.grib2.gz :)\n",
      "\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-150000.grib2.gz :)\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-230000.grib2.gz :)\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-210000.grib2.gz :)\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-190000.grib2.gz :)\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-220000.grib2.gz :)\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-170000.grib2.gz :)\n",
      "Saved data/20240927/PrecipFlag_00.00_20240927-140000.grib2.gz :)\n"
     ]
    }
   ],
   "source": [
    "precipflags_files = mrms.fetch.timerange(\n",
    "    \"2024-09-27T12:00:00\",\n",
    "    Timestamp(\"2024-09-28T00:00:00\"),\n",
    "    frequency=Timedelta(minutes=60),\n",
    "    data_type=\"precip_flag\",\n",
    "    verbose=True,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Download accumulated precipitation\n",
    "\n",
    "Accumulates are available for 1, 24 and 72 hours periods. To fetch this data, set `data_type` to `\"precip_accum_1h\"`, `\"precip_accum_24h\"` or `\"precip_accum_72h\"`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "daily_files = mrms.fetch.timerange(\n",
    "    \"2024-09-26T12:00:00\",\n",
    "    \"2024-09-29\",  # <-- If only a date is provided, it defaults to midnight\n",
    "    frequency=Timedelta(days=1),\n",
    "    data_type=\"precip_accum_24h\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the last example, we did not specify `verbose=True`, so no messages were shown about the files that were downloaded. "
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "aenv",
   "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.13.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}