{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6dfd0085",
   "metadata": {},
   "source": [
    "{{ prolog }}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b1f31ab",
   "metadata": {},
   "source": [
    "# Detecting coordinates\n",
    "\n",
    "To create masks regionmask needs to know the x and y (longitude and latitude) coordinates of the grid. There are two ways to pass these to the `mask` and `mask_3D` methods:\n",
    "\n",
    "1. Passing the coordinates explicitly: `region.mask(longitude, latitude)`\n",
    "2. Pass an xarray `DataArray` or `Dataset`: `region.mask(ds)` in which case the coordinates are either auto-detected using [cf_xarray](https://cf-xarray.readthedocs.io/en/latest/coord_axes.html) or determined as `ds[\"lon\"]` and `ds[\"lat\"]`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6acbc290",
   "metadata": {},
   "source": [
    "## Illustration\n",
    "\n",
    "### Preparation\n",
    "\n",
    "Import regionmask and check the version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2906e976",
   "metadata": {},
   "outputs": [],
   "source": [
    "import regionmask\n",
    "\n",
    "print(regionmask.__version__)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c387fe70",
   "metadata": {},
   "source": [
    "Other imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f1091042",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import xarray as xr\n",
    "\n",
    "xr.set_options(display_width=60, display_expand_data=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3df1a876",
   "metadata": {},
   "source": [
    "Get data for examples\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "be26ce8a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# example region\n",
    "region = regionmask.defined_regions.ar6.land\n",
    "\n",
    "# dataset with coordinates named \"lon\" and \"lat\", without cf metadata\n",
    "ds = xr.Dataset(coords={\"lon\": np.arange(0, 360), \"lat\": np.arange(90, 0, -1)})\n",
    "\n",
    "# dataset with coordinates not named \"lon\" and \"lat,\" with cf metadata\n",
    "rasm = xr.tutorial.open_dataset(\"rasm\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5ae6e8bd",
   "metadata": {},
   "source": [
    "### 1. Passing coordinates directly\n",
    "\n",
    "The coordinates can be passed individually - these must be \"array-like\" (typically numpy arrays or xarray DataArrays):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9cd16fbe",
   "metadata": {},
   "outputs": [],
   "source": [
    "mask = region.mask(ds.lon, ds.lat)\n",
    "mask.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f2236e5",
   "metadata": {},
   "source": [
    "### 2. Not using cf_xarray\n",
    "\n",
    "If cf_xarray is not installed, the passed dataset does not have any cf metadata/ attributes, or `use_cf=False` is set, regionmask tries to read the coordinates from `ds[\"lon\"]` and `ds[\"lat\"]` and raises an error otherwise:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0069bd7d",
   "metadata": {},
   "outputs": [],
   "source": [
    "mask = region.mask(ds)\n",
    "mask"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "407f667f",
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    region.mask(rasm, use_cf=False)\n",
    "except KeyError:\n",
    "    print(\"Error raised\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99f4e1c6",
   "metadata": {},
   "source": [
    "### Using cf_xarray\n",
    "\n",
    "[cf_xarray](https://cf-xarray.readthedocs.io) uses [cf metadata](http://cfconventions.org/) saved in the attributes to determine coordinates (see [coordinate-criteria](https://cf-xarray.readthedocs.io/en/latest/coord_axes.html#coordinate-criteria)). For this the cf_xarray needs to be installed but importing it is not necessary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a8ea5701",
   "metadata": {},
   "outputs": [],
   "source": [
    "mask = region.mask_3D(rasm)\n",
    "\n",
    "mask"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "332f0191",
   "metadata": {},
   "source": [
    "## Details\n",
    "\n",
    "regionmask uses the following logic to determine the coordinates:\n",
    "\n",
    "1. Passing the coordinates directly (`region.mask(lon, lat)`) takes precedence.\n",
    "1. If cf_xarray is _not_ installed regionmask will use `ds[\"lon\"]` and `ds[\"lat\"]` or raise a `KeyError`.\n",
    "1. If cf_xarray is installed the behavior is determined via the `use_cf` keyword of the `mask` and `mask_3D` methods:\n",
    "   * `use_cf=None` (default): use the cf metadata to determine the coordinates _or_ use `ds[\"lon\"]` and `ds[\"lat\"]` (raises a `ValueError` if ambiguous).\n",
    "   * `use_cf=True` : use the cf metadata to determine the coordinates\n",
    "   * `use_cf=False`:  use `ds[\"lon\"]` and `ds[\"lat\"]` as coordinates"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:.conda-regionmask-docs]",
   "language": "python",
   "name": "conda-env-.conda-regionmask-docs-py"
  },
  "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}