{
 "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": [
    "# Create your own region"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Creating own regions is straightforward. Import regionmask and check the version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cartopy.crs as ccrs\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "import regionmask\n",
    "\n",
    "regionmask.__version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Assume you have two custom regions in the US, you can easily use these to create `Regions`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "US1 = np.array([[-100.0, 30], [-100, 40], [-120, 35]])\n",
    "US2 = np.array([[-100.0, 30], [-80, 30], [-80, 40], [-100, 40]])\n",
    "\n",
    "regionmask.Regions([US1, US2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{note}\n",
    "\n",
    "Set ``overlap=True`` if some of the regions overlap. See the tutorial on [overlapping regions](overlap) for details.\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to set the `names` and `abbrevs` yourself you can still do that:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "names = [\"US_west\", \"US_east\"]\n",
    "abbrevs = [\"USw\", \"USe\"]\n",
    "\n",
    "USregions = regionmask.Regions([US1, US2], names=names, abbrevs=abbrevs, name=\"US\")\n",
    "USregions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again we can plot the outline of the defined regions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ax = USregions.plot(label=\"abbrev\")\n",
    "\n",
    "# fine tune the extent\n",
    "ax.set_extent([225, 300, 25, 45], crs=ccrs.PlateCarree())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and obtain a mask:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "# define lat/ lon grid\n",
    "lon = np.arange(200.5, 330, 1)\n",
    "lat = np.arange(74.5, 15, -1)\n",
    "\n",
    "mask = USregions.mask(lon, lat)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ax = plt.subplot(111, projection=ccrs.PlateCarree())\n",
    "\n",
    "h = mask.plot(\n",
    "    transform=ccrs.PlateCarree(),\n",
    "    cmap=\"Paired\",\n",
    "    add_colorbar=False,\n",
    "    vmax=12,\n",
    ")\n",
    "\n",
    "ax.coastlines()\n",
    "\n",
    "# add the outlines of the regions\n",
    "USregions.plot_regions(ax=ax, add_label=False)\n",
    "\n",
    "ax.set_extent([225, 300, 25, 45], crs=ccrs.PlateCarree())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Use shapely Polygon\n",
    "\n",
    "You can also define the region with shapely polygons (see [geopandas tutorial](geopandas) how to work with shapefiles)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from shapely.geometry import MultiPolygon, Polygon\n",
    "\n",
    "US1_poly = Polygon(US1)\n",
    "US2_poly = Polygon(US2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "USregions_poly = regionmask.Regions([US1_poly, US2_poly])\n",
    "\n",
    "USregions_poly"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create Regions with MultiPolygon and interiors\n",
    "\n",
    "Create two discontiguous regions and combine them to one. Add a hole to one of the regions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "US1_shifted = US1 - (5, 0)\n",
    "US2_hole = np.array([[-98.0, 33], [-92, 33], [-92, 37], [-98, 37], [-98.0, 33]])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create `Polygons`, a `MultiPolygon`, and finally `Regions`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "US1_poly = Polygon(US1_shifted)\n",
    "US2_poly = Polygon(US2, holes=[US2_hole])\n",
    "\n",
    "US_multipoly = MultiPolygon([US1_poly, US2_poly])\n",
    "\n",
    "USregions_poly = regionmask.Regions([US_multipoly])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "USregions_poly.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a mask:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mask = USregions_poly.mask(lon, lat)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and plot it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ax = plt.subplot(111, projection=ccrs.PlateCarree())\n",
    "\n",
    "mask.plot(transform=ccrs.PlateCarree(), add_colorbar=False)\n",
    "\n",
    "ax.coastlines()\n",
    "\n",
    "# fine tune the extent\n",
    "ax.set_extent([225, 300, 25, 45], crs=ccrs.PlateCarree())"
   ]
  }
 ],
 "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.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}