{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "91f14b8f-669d-4258-bf5a-5215e4ca1b37",
   "metadata": {},
   "source": [
    "# The `hrcn` accessor\n",
    "\n",
    "HuracanPy implements an xarray accessor. This means that when your tracks are loaded\n",
    "as an `xarray.Dataset` (e.g. when you have loaded tracks with `huracanpy.load`), you can\n",
    "call HuracanPy functions by typing:\n",
    "\n",
    "`tracks.hrcn.{{function name}}`\n",
    "\n",
    "This provides a useful shorthand for calling functions in HuracanPy. For example\n",
    "selecting an individual track by track_id"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "97763c21-8fe9-46df-9e5d-1c7af01ef0d3",
   "metadata": {},
   "outputs": [],
   "source": [
    "import huracanpy\n",
    "\n",
    "tracks = huracanpy.load(huracanpy.example_csv_file)\n",
    "\n",
    "# Calling sel_id from the module\n",
    "track = huracanpy.sel_id(tracks, tracks.track_id, 0)\n",
    "\n",
    "# Shorthand with hrcn accessor\n",
    "track = tracks.hrcn.sel_id(0)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "61d08f5c-98c1-4fcf-82f2-42d5f2852c94",
   "metadata": {},
   "source": [
    "## Naming conventions\n",
    "For top-level functions in `huracanpy`, such as `sel_id` the accessor name matches the\n",
    "function name. Functions in other modules are named differently. For the full set of\n",
    "functions implemented by the accessor, see the [accessor API](../api/hrcn.rst)\n",
    "\n",
    "### get_ and add_ functions\n",
    "The functions in `huracanpy.info`, `huracanpy.calc`, and `huracanpy.tc` are implemented\n",
    "as `get_` and `add_` functions separately e.g."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e1884653-e8cb-4891-9026-7a81b07f7b23",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Getting is_land from the module\n",
    "is_land = huracanpy.info.is_land(tracks.lon, tracks.lat)\n",
    "\n",
    "# Shorthand with hrcn accessor\n",
    "is_land = tracks.hrcn.get_is_land()\n",
    "\n",
    "# Add is_land to the tracks using xarray syntax\n",
    "# Note that this creates a new Dataset with the variable added\n",
    "tracks_ = tracks.assign(is_land=huracanpy.info.is_land(tracks.lon, tracks.lat))\n",
    "\n",
    "# Shorthand with hrcn accessor\n",
    "# Note that this follows the xarray convention of returning a new dataset\n",
    "tracks_ = tracks.hrcn.add_is_land()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8db01112-34b1-424a-b391-ce0fadb87256",
   "metadata": {},
   "source": [
    "### Plot functions\n",
    "The functions from `huracanpy.plot` are named `plot_`. e.g."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5122f7c5-769c-49bc-9ecf-9b87c0b5ed35",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Plot using the module function\n",
    "huracanpy.plot.tracks(tracks.lon, tracks.lat, intensity_var=tracks.wind10)\n",
    "\n",
    "# Shorthand with the hrcn accessor\n",
    "tracks.hrcn.plot_tracks(intensity_var_name=\"wind10\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d4a3841-fd91-475e-be67-4c5c163bb0f5",
   "metadata": {},
   "source": [
    "### Not implemented functions\n",
    "Some functions are not included with the hrcn accessor following these naming conventions.\n",
    "These are:\n",
    "\n",
    "- `load`\n",
    "- `add_` functions that would have output with a different shape\n",
    "    - `add_apex_vals`\n",
    "    - `add_gen_vals`\n",
    "    - `add_density`\n",
    "    - `add_track_duration`\n",
    "    - `add_ace` and `add_pace` with the `sum_by` keyword\n",
    "- `plot_` functions that are for multiple datasets\n",
    "    - `plot_doughnut`\n",
    "    - `plot_venn`\n",
    "- Functions from `huracanpy.assess` because it is for multiple datasets"
   ]
  }
 ],
 "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
}