diff --git a/doc/reference/pandas/paths.ipynb b/doc/reference/pandas/paths.ipynb new file mode 100644 index 000000000..395f21be4 --- /dev/null +++ b/doc/reference/pandas/paths.ipynb @@ -0,0 +1,80 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Paths" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import pandas as pd\n", + "import hvplot.pandas # noqa\n", + "import cartopy.crs as ccrs" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Paths are useful if you are plotting lines on a geographic map." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "df = pd.DataFrame({\"city\": [\"NY\", \"Delhi\"], \"lon\": [-75, 77.23], \"lat\": [43, 28.61]})" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Notice how the line in blue between New York and Delhi is not straight on a flat PlateCarree map, this is because the Geodetic coordinate system is a truly spherical coordinate system, where a line between two points is defined as the shortest path between those points on the globe rather than 2d Cartesian space." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "common_kwargs = dict(\n", + " x=\"lon\",\n", + " y=\"lat\",\n", + " geo=True,\n", + " project=True,\n", + " projection=ccrs.GOOGLE_MERCATOR,\n", + " global_extent=True\n", + ")\n", + "shortest_path = df.hvplot.paths(color=\"blue\", crs=ccrs.Geodetic(), tiles=True, **common_kwargs)\n", + "straight_path = df.hvplot.paths(color=\"grey\", line_dash=\"dashed\", **common_kwargs)\n", + "labels = df.hvplot.labels(text_color=\"black\", text=\"city\", **common_kwargs)\n", + "shortest_path * straight_path * labels" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Example adapted from https://scitools.org.uk/cartopy/docs/latest/matplotlib/intro.html." + ] + } + ], + "metadata": { + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +}