Update documentation ipynb's to match new layout

Author: leosaffin

docs/conf.py

@@ -31,7 +31,6 @@
 autodoc_member_order = "bysource"
 
 nbsphinx_prompt_width = "88"
-nbsphinx_allow_errors = True
 
 # Options for intersphinx.
 intersphinx_mapping = {

docs/examples/IBTrACS.ipynb

@@ -28,8 +28,8 @@
     "\n",
     "\n",
     "### Online\n",
-    "With the arguments `tracker = \"ibtracs\", ibtracs_online=True`, `load` will retrieve IBTrACS from the NCEI-NOAA (https://www.ncei.noaa.gov/data/international-best-track-archive-for-climate-stewardship-ibtracs/v04r00/access/csv/). \n",
-    "Use the `ibtracs_subset` argument to specify the subset you want to download. See the webpage mentionned above for the list of existing subset."
+    "With the arguments `source=\"ibtracs\"`, `ibtracs_online=True`, `load` will retrieve IBTrACS from the NCEI-NOAA (https://www.ncei.noaa.gov/data/international-best-track-archive-for-climate-stewardship-ibtracs/v04r00/access/csv/). \n",
+    "Use the `ibtracs_subset` argument to specify the subset you want to download. See the webpage mentionned above for the list of existing subset. The following cells are not being run as it requires downloading the IBTrACS data"
    ]
   },
   {
@@ -46,8 +46,8 @@
    "outputs": [],
    "source": [
     "# Example of 'last3years' subset\n",
-    "ib = huracanpy.load(source=\"ibtracs\", ibtracs_online=True, ibtracs_subset=\"last3years\")\n",
-    "huracanpy.plot.tracks(ib.lon, ib.lat, intensity_var=ib.wmo_wind)"
+    "#ib = huracanpy.load(source=\"ibtracs\", ibtracs_online=True, ibtracs_subset=\"last3years\")\n",
+    "#huracanpy.plot.tracks(ib.lon, ib.lat, intensity_var=ib.wmo_wind)"
    ]
   },
   {
@@ -64,8 +64,8 @@
    "outputs": [],
    "source": [
     "# Example of 'SI' subset\n",
-    "ib = huracanpy.load(source=\"ibtracs\", ibtracs_online=True, ibtracs_subset=\"SI\")\n",
-    "huracanpy.plot.tracks(ib.lon, ib.lat, intensity_var=ib.wmo_wind)"
+    "#ib = huracanpy.load(source=\"ibtracs\", ibtracs_online=True, ibtracs_subset=\"SI\")\n",
+    "#huracanpy.plot.tracks(ib.lon, ib.lat, intensity_var=ib.wmo_wind)"
    ]
   },
   {
@@ -144,7 +144,7 @@
    "outputs": [],
    "source": [
     "# Add basin data to ib_wmo\n",
-    "ib_wmo[\"basin\"] = huracanpy.utils.get_basin(ib_wmo.lon, ib_wmo.lat)\n",
+    "ib_wmo[\"basin\"] = huracanpy.info.get_basin(ib_wmo.lon, ib_wmo.lat)\n",
     "# Match tracks between ib_wmo and ib_usa, then retrieve LMI\n",
     "m = huracanpy.assess.match([ib_wmo, ib_usa], names=[\"wmo\", \"usa\"])\n",
     "max_winds = m.join(\n",

docs/examples/basins.ipynb

@@ -29,7 +29,7 @@
    "outputs": [],
    "source": [
     "# Basins defined in huracanpy\n",
-    "huracanpy.basins[\"WMO\"]"
+    "huracanpy.basins[\"WMO-TC\"]"
    ]
   },
   {
@@ -41,7 +41,7 @@
    "source": [
     "# Plot basins\n",
     "# Default defined from 0-360.\n",
-    "for n, (basin, geometry) in enumerate(huracanpy.basins[\"WMO\"].iterrows()):\n",
+    "for n, (basin, geometry) in enumerate(huracanpy.basins[\"WMO-TC\"].iterrows()):\n",
     "    # South Atlantic (SA) crosses dateline so is defined as two regions\n",
     "    if isinstance(geometry.geometry, MultiPolygon):\n",
     "        for geom in geometry.geometry.geoms:\n",
@@ -81,7 +81,7 @@
     "    plt.figure()\n",
     "    ax = plt.axes(projection=EqualEarth(central_longitude=central_longitude))\n",
     "\n",
-    "    for n, (basin, geometry) in enumerate(huracanpy.basins[\"WMO\"].iterrows()):\n",
+    "    for n, (basin, geometry) in enumerate(huracanpy.basins[\"WMO-TC\"].iterrows()):\n",
     "        if isinstance(geometry.geometry, MultiPolygon):\n",
     "            for geom in geometry.geometry.geoms:\n",
     "                plt.plot(*geom.exterior.xy, color=f\"C{n}\", transform=transform)\n",

docs/examples/track_density.ipynb

@@ -55,7 +55,7 @@
    "outputs": [],
    "source": [
     "# Compute track density\n",
-    "D = huracanpy.diags.density(tracks.lon, tracks.lat)\n",
+    "D = huracanpy.calc.density(tracks.lon, tracks.lat)\n",
     "D  # D, the track density, is a map stored in xarray"
    ]
   },
@@ -115,7 +115,7 @@
    "outputs": [],
    "source": [
     "# Setting a smaller bin_size\n",
-    "D = huracanpy.diags.density(tracks.lon, tracks.lat, bin_size=1)\n",
+    "D = huracanpy.calc.density(tracks.lon, tracks.lat, bin_size=1)\n",
     "D.plot()\n",
     "D"
    ]
@@ -128,7 +128,7 @@
    "outputs": [],
    "source": [
     "# Setting a larger bin_size\n",
-    "D = huracanpy.diags.density(tracks.lon, tracks.lat, bin_size=10)\n",
+    "D = huracanpy.calc.density(tracks.lon, tracks.lat, bin_size=10)\n",
     "D.plot()\n",
     "D"
    ]
@@ -147,7 +147,7 @@
     "N = len(np.unique(tracks.season.values))\n",
     "print(N)\n",
     "## Track density with normalization.\n",
-    "D = huracanpy.diags.density(tracks.lon, tracks.lat, N_seasons=N)\n",
+    "D = huracanpy.calc.density(tracks.lon, tracks.lat, n_seasons=N)\n",
     "# In this case, now the number in D in number of TC points in each 5x5 box.\n",
     "D.plot()"
    ]

docs/examples/utils.ipynb

@@ -5,8 +5,8 @@
    "id": "02a608e9-0fb1-4532-980e-ce860b421d58",
    "metadata": {},
    "source": [
-    "# Additional information with the `utils` module\n",
-    "In the `utils` module, an `add_all_info` function add to your dataset all the information that HuracanPy may compute. Submodules allow for the computation of individual attributes."
+    "# Additional information with the `info` module\n",
+    "In the `info` module, an `add_all_info` function add to your dataset all the information that HuracanPy may compute. Submodules allow for the computation of individual attributes."
    ]
   },
   {
@@ -35,7 +35,7 @@
    "outputs": [],
    "source": [
     "# Add info\n",
-    "data = huracanpy.utils.add_all_info(data, slp_units=\"Pa\")\n",
+    "data = huracanpy.info.add_all_info(data)\n",
     "\n",
     "list(data.keys())  # Available attributes"
    ]
@@ -55,7 +55,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# hemisphere, can also be obtained with huracanpy.utils.geography.get_hemisphere\n",
+    "# hemisphere, can also be obtained with huracanpy.info.get_hemisphere\n",
     "huracanpy.plot.tracks(\n",
     "    data.lon, data.lat, intensity_var=data.hemisphere, scatter_kws=dict(s=10)\n",
     ")"
@@ -68,7 +68,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# basin, can also be obtained with huracanpy.utils.geography.get_basin (NB: Several convention available)\n",
+    "# basin, can also be obtained with huracanpy.info.get_basin (NB: Several convention available)\n",
     "huracanpy.plot.tracks(\n",
     "    data.lon, data.lat, intensity_var=data.basin, scatter_kws=dict(s=10)\n",
     ")"
@@ -81,7 +81,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# is_ocean, can also be obtained with huracanpy.utils.geography.get_is_ocean\n",
+    "# is_ocean, can also be obtained with huracanpy.info.get_is_ocean\n",
     "huracanpy.plot.tracks(\n",
     "    data.lon, data.lat, intensity_var=data.is_ocean, scatter_kws=dict(s=10)\n",
     ")"
@@ -100,7 +100,7 @@
    },
    "outputs": [],
    "source": [
-    "# country, can also be obtained with huracanpy.utils.geography.get_country\n",
+    "# country, can also be obtained with huracanpy.info.get_country\n",
     "data_ = data.isel(record=slice(0, 60))\n",
     "huracanpy.plot.tracks(\n",
     "    data_.lon, data_.lat, intensity_var=data_.country, scatter_kws=dict(s=10)\n",
@@ -114,7 +114,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# continent, can also be obtained with huracanpy.utils.geography.get_country\n",
+    "# continent, can also be obtained with huracanpy.info.get_country\n",
     "huracanpy.plot.tracks(\n",
     "    data.lon, data.lat, intensity_var=data.continent, scatter_kws=dict(s=10)\n",
     ")"
@@ -135,7 +135,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Season. Can also be obtained with huracanpy.utils.time.get_season\n",
+    "# Season. Can also be obtained with huracanpy.info.get_season\n",
     "sns.scatterplot(data=data, x=\"time\", y=\"hemisphere\", hue=\"season\")"
    ]
   },
@@ -144,7 +144,10 @@
    "id": "e2753aa6-1e8a-478f-bef5-08701ec29ad0",
    "metadata": {},
    "source": [
-    "# Categories"
+    "# Categories\n",
+    "\n",
+    "Categories are specific to tropical cyclones and can be found in the `huracanpy.tc` module\n",
+    "A more generic function is available in `huracanpy.info.get_category`"
    ]
   },
   {
@@ -154,11 +157,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# sshs, can also be obtained with huracanpy.utils.category.get_sshs_cat\n",
+    "# sshs, can also be obtained with huracanpy.tc.get_sshs_cat\n",
+    "sshs = huracanpy.tc.get_sshs_cat(data.wind10)\n",
     "huracanpy.plot.tracks(\n",
     "    data.lon,\n",
     "    data.lat,\n",
-    "    intensity_var=data.sshs,\n",
+    "    intensity_var=sshs,\n",
     "    scatter_kws=dict(s=5, palette=\"Spectral\"),\n",
     ")"
    ]
@@ -170,11 +174,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# pressure category, can also be obtained with huracanpy.utils.category.get_pres_cat\n",
+    "# pressure category, can also be obtained with huracanpy.tc.get_pres_cat\n",
+    "pres_cat = huracanpy.tc.get_pressure_cat(data.slp)\n",
     "huracanpy.plot.tracks(\n",
     "    data.lon,\n",
     "    data.lat,\n",
-    "    intensity_var=data.pres_cat,\n",
+    "    intensity_var=pres_cat,\n",
     "    scatter_kws=dict(s=5, palette=\"Spectral\"),\n",
     ")"
    ]

docs/user_guide/extract.ipynb

@@ -235,15 +235,15 @@
     "# category 2\n",
     "tracks = huracanpy.load(huracanpy.example_csv_file)\n",
     "\n",
-    "tracks[\"category\"] = huracanpy.utils.get_pressure_cat(tracks.slp, slp_units=\"Pa\")\n",
+    "tracks[\"category\"] = huracanpy.tc.get_pressure_cat(tracks.slp, slp_units=\"Pa\")\n",
     "\n",
     "# Show the categories for each storm\n",
     "# Storms 0 and 2 reach category 2, and storm 1 only reaches category 1\n",
     "for track_id, track in tracks.groupby(\"track_id\"):\n",
     "    print(\"track\", track_id, \"category\", int(track.category.max()))\n",
     "\n",
     "# Subset the tracks by category threshold which will remove track 1\n",
-    "track_subset = huracanpy.trackswhere(tracks, lambda track: track.category.max() >= 2)\n",
+    "track_subset = huracanpy.trackswhere(tracks, tracks.track_id, lambda track: track.category.max() >= 2)\n",
     "\n",
     "# Confirm that track 1 has been filtered out\n",
     "print(\"\\n\", \"tracks remaining -\", set(track_subset.track_id.data))"