{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "hide-cell"
    ]
   },
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "\n",
    "from matplotlib import rcParams\n",
    "\n",
    "rcParams[\"figure.dpi\"] = 300\n",
    "rcParams[\"font.size\"] = 8\n",
    "\n",
    "import warnings\n",
    "\n",
    "warnings.filterwarnings(\"ignore\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "{{ prolog }}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Plotting\n",
    "\n",
    "Every region has two plotting functions, which draw the outlines of all regions:\n",
    "\n",
    "- `plot`: draws the region polygons on a cartopy GeoAxes (map)\n",
    "- `plot_regions`: draws the the region polygons only"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import regionmask and check the version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import regionmask\n",
    "\n",
    "regionmask.__version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We use the srex regions to illustrate the plotting:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "srex = regionmask.defined_regions.srex\n",
    "srex"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot all regions\n",
    "\n",
    "Calling `plot()` on any region without any arguments draws the default map with a `PlateCarree()` projection and includes the coastlines:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "srex.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot options\n",
    "\n",
    "The `plot` method has a large number of arguments to adjust the layout of the axes. For example, you can pass a custom projection, the labels can display the abbreviation instead of the region number, the ocean can be colored, etc.. This example also shows how to use `matplotlib.patheffects` to ensure the labels are easily readable without covering too much of the map (compare to the map above):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cartopy.crs as ccrs\n",
    "import matplotlib.patheffects as pe\n",
    "\n",
    "text_kws = dict(\n",
    "    bbox=dict(color=\"none\"),\n",
    "    path_effects=[pe.withStroke(linewidth=2, foreground=\"w\")],\n",
    "    color=\"#67000d\",\n",
    "    fontsize=8,\n",
    ")\n",
    "\n",
    "ax = srex.plot(\n",
    "    projection=ccrs.Robinson(), label=\"abbrev\", add_ocean=True, text_kws=text_kws\n",
    ")\n",
    "\n",
    "ax.set_global()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot only a Subset of Regions\n",
    "\n",
    "To plot a selection of regions subset them using indexing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# regions can be selected by number, abbreviation or long name\n",
    "regions = [11, \"CEU\", \"S. Europe/Mediterranean\"]\n",
    "\n",
    "# choose a good projection for regional maps\n",
    "projection = ccrs.LambertConformal(central_longitude=15)\n",
    "\n",
    "ax = srex[regions].plot(\n",
    "    add_ocean=True,\n",
    "    resolution=\"50m\",\n",
    "    projection=projection,\n",
    "    label=\"abbrev\",\n",
    "    text_kws=text_kws,\n",
    ")\n",
    "\n",
    "# fine tune the extent\n",
    "ax.set_extent([-15, 45, 28, 76], crs=ccrs.PlateCarree())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting the region polygons only (no map)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "srex.plot_regions();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{note}\n",
    "\n",
    "This does *not* create a cartopy GeoAxes.\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To achieve this, you need to explicitly create the axes: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "f, ax = plt.subplots(subplot_kw=dict(projection=ccrs.Robinson()))\n",
    "\n",
    "srex.plot_regions(ax=ax, line_kws=dict(lw=1), text_kws=text_kws)\n",
    "\n",
    "ax.coastlines()\n",
    "ax.set_global()"
   ]
  }
 ],
 "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.10.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}