{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "04e0612f-4319-4261-ad7e-61fd03e8dc67",
   "metadata": {},
   "source": [
    "# Plot density maps"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "08ce99d0-2f34-4288-bdc0-e9b85eefd504",
   "metadata": {},
   "source": [
    "In this example, we show how to plot density maps (track density, genesis density, lysis density, whichever) with HuracanPy, and how to customize them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8ab3d052-d18b-4452-8582-638cd69860b4",
   "metadata": {},
   "outputs": [],
   "source": [
    "import huracanpy\n",
    "\n",
    "import cartopy.crs as ccrs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2e233e5a-e767-426e-a313-31582ff26006",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load data (example : ibtracs)\n",
    "tracks = huracanpy.load(source=\"ibtracs\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "261ee449-f5e8-442b-994c-73d608829204",
   "metadata": {},
   "source": [
    "## Basic routine\n",
    "After you loaded the data, plotting density maps is done in two very simple steps: \n",
    "1. Computing the density;\n",
    "2. Plotting it!\n",
    "\n",
    "It can even be done in only one line with the accessor function. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "52c8c157-0af5-4368-b370-b30fbdbd2c38",
   "metadata": {},
   "outputs": [],
   "source": [
    "## Density plot from accessor: Most direct\n",
    "tracks.hrcn.plot_density()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a5c041bf-cf40-44d6-97ba-6cce60e42e9c",
   "metadata": {},
   "outputs": [],
   "source": [
    "## Routine with function calls\n",
    "# 1. Compute track density\n",
    "D = huracanpy.calc.density(tracks.lon, tracks.lat)\n",
    "# D, the track density, is a 2D map stored in xarray\n",
    "\n",
    "# 2. Plot the track density\n",
    "huracanpy.plot.density(D)\n",
    "# (NB: because D is an xarray object, you can also use D.plot() directly)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e6f9e77-1e09-41d5-b505-96fcda94dcbc",
   "metadata": {},
   "source": [
    "## Different density options\n",
    "In `huracanpy.calc.density`, the `method` argument allows you to choose how the density is computed: \n",
    "* As a 2D histogram (`histogram`)\n",
    "* Using scipy's kernel density estimation (`kde`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b5dbc0c4-b85a-4f14-9870-9b2b98578932",
   "metadata": {},
   "outputs": [],
   "source": [
    "# 2D histogram: Track points are binned in 2D bins defined by `bin_size`\n",
    "D = huracanpy.calc.density(tracks.lon, tracks.lat, method=\"histogram\", bin_size=10)\n",
    "D.plot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "39f264ba-7483-4379-be47-ee8aa6a3acd7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Kernel density estimation (kde):\n",
    "# The 2D distribution of points is estimated using scipy's kernel density estimator,\n",
    "# which results in a smooth function.\n",
    "# Then, this density is re-interpolated on a grid size of resolution `bin_size`.\n",
    "# Using a small bin_size and plotting the result as a contour is the best way to use\n",
    "# this method.\n",
    "# (It yield similar results as if you ran seaborn's \"kdeplot\")\n",
    "D = huracanpy.calc.density(tracks.lon, tracks.lat, method=\"kde\", bin_size=2)\n",
    "D.plot.contour()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7d322fe-9d22-4147-a403-26373e2e7336",
   "metadata": {},
   "source": [
    "## Customization"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3c035e4-69b2-40cc-a03a-8a25ea12c082",
   "metadata": {},
   "source": [
    "### Bin size"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d565d25-8c48-4321-a36b-fea62ece433b",
   "metadata": {},
   "source": [
    "`bin_size` : The size of the boxes over which the track density is computed, in degrees."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1271d02c-59b9-414e-b229-8844408ecce0",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Setting a smaller bin_size\n",
    "D = huracanpy.calc.density(tracks.lon, tracks.lat, bin_size=1)\n",
    "D.plot()\n",
    "D"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "abb6c39b-100a-4f95-be9b-868c56564df5",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Setting a larger bin_size\n",
    "D = huracanpy.calc.density(tracks.lon, tracks.lat, bin_size=10)\n",
    "D.plot()\n",
    "D"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1a200209-83ec-45a7-864e-8da1444cacfa",
   "metadata": {},
   "source": [
    "### Plotting"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "64adaac9-dc53-4d56-8791-37a6cc9fcc4f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# With huracanpy's function\n",
    "## The function is based on matplotlib's contourf, so you can use its options\n",
    "huracanpy.plot.density(D, contourf_kws=dict(cmap=\"tab20c_r\", levels=20))\n",
    "## Changing the projection with subplot_kws\n",
    "huracanpy.plot.density(D, subplot_kws=dict(projection=ccrs.Mollweide()))\n",
    "## Changing the figure's properties\n",
    "huracanpy.plot.density(D, fig_kws=dict(figsize=(15, 5)))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}