Merge pull request #242 from jkittner/docs-update-subplots

fix the docs build and add an easy example for subplots using seaborn

README.md

@@ -35,12 +35,13 @@ Some academics use it to track lightning strikes during high intensity storms. T
 - numpy http://www.numpy.org/
 - and naturally python https://www.python.org/ :-P
 
-Option libraries:
+Optional libraries:
 
 - Pandas http://pandas.pydata.org/ (to feed plot functions easily)
 - Scipy http://www.scipy.org/ (to fit data with Weibull distribution)
 - ffmpeg https://www.ffmpeg.org/ (to output video)
 - click http://click.pocoo.org/ (for command line interface tools)
+- seaborn https://seaborn.pydata.org/ (for easy subplots)
 
 ### Install latest release version via pip
 

docs/conf.py

@@ -36,6 +36,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "nbsphinx",
+    "sphinx_copybutton",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/install.rst

@@ -14,6 +14,7 @@ Option libraries:
 -  SciPy https://scipy.org/ (to fit data with Weibull distribution)
 -  ffmpeg https://www.ffmpeg.org/ (to output video)
 -  click https://click.palletsprojects.com/ (for command line interface tools)
+-  seaborn https://seaborn.pydata.org/ (for easy subplots)
 
 Install latest release version via pip
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

notebooks/usage.ipynb

@@ -42,7 +42,7 @@
     "\n",
     "ax = WindroseAxes.from_ax()\n",
     "ax.bar(wd, ws, normed=True, opening=0.8, edgecolor=\"white\")\n",
-    "ax.set_legend();"
+    "ax.set_legend()"
    ]
   },
   {
@@ -60,7 +60,7 @@
    "source": [
     "ax = WindroseAxes.from_ax()\n",
     "ax.box(wd, ws, bins=np.arange(0, 8, 1))\n",
-    "ax.set_legend();"
+    "ax.set_legend()"
    ]
   },
   {
@@ -80,7 +80,7 @@
     "\n",
     "ax = WindroseAxes.from_ax()\n",
     "ax.contourf(wd, ws, bins=np.arange(0, 8, 1), cmap=cm.hot)\n",
-    "ax.set_legend();"
+    "ax.set_legend()"
    ]
   },
   {
@@ -99,7 +99,7 @@
     "ax = WindroseAxes.from_ax()\n",
     "ax.contourf(wd, ws, bins=np.arange(0, 8, 1), cmap=cm.hot)\n",
     "ax.contour(wd, ws, bins=np.arange(0, 8, 1), colors=\"black\")\n",
-    "ax.set_legend();"
+    "ax.set_legend()"
    ]
   },
   {
@@ -117,7 +117,7 @@
    "source": [
     "ax = WindroseAxes.from_ax()\n",
     "ax.contour(wd, ws, bins=np.arange(0, 8, 1), cmap=cm.hot, lw=3)\n",
-    "ax.set_legend();"
+    "ax.set_legend()"
    ]
   },
   {
@@ -356,6 +356,75 @@
     "    ax.tick_params(labelleft=False, labelbottom=False)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Subplots\n",
+    "\n",
+    "[seaborn](https://seaborn.pydata.org/index.html) offers an easy way to create subplots per parameter. For example per month or day. You can adapt this to have years as columns and rows as months or vice versa."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from windrose import WindroseAxes, plot_windrose\n",
+    "import seaborn as sns\n",
+    "from matplotlib import pyplot as plt\n",
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "\n",
+    "wind_data = pd.DataFrame({\n",
+    "    'ws': np.random.random(1200) * 6,\n",
+    "    'wd': np.random.random(1200) * 360,\n",
+    "    'month': np.repeat(range(1, 13), 100),\n",
+    "})\n",
+    "\n",
+    "\n",
+    "def plot_windrose_subplots(data, *, direction, var, color=None, **kwargs):\n",
+    "    \"\"\"wrapper function to create subplots per axis\"\"\"\n",
+    "    ax = plt.gca()\n",
+    "    ax = WindroseAxes.from_ax(ax=ax)\n",
+    "    plot_windrose(direction_or_df=data[direction], var=data[var], ax=ax, **kwargs)\n",
+    "\n",
+    "# this creates the raw subplot structure with a subplot per value in month.\n",
+    "g = sns.FacetGrid(\n",
+    "    data=wind_data,\n",
+    "    # the column name for each level a subplot should be created\n",
+    "    col='month',\n",
+    "    # place a maximum of 3 plots per row\n",
+    "    col_wrap=3,\n",
+    "    subplot_kws={'projection': 'windrose'},\n",
+    "    sharex=False,\n",
+    "    sharey=False,\n",
+    "    despine=False,\n",
+    "    height=3.5\n",
+    ")\n",
+    "\n",
+    "g.map_dataframe(\n",
+    "    plot_windrose_subplots,\n",
+    "    direction='wd',\n",
+    "    var='ws',\n",
+    "    normed=True,\n",
+    "    # manually set bins, so they match for each subplot\n",
+    "    bins=(0.1, 1, 2, 3, 4, 5),\n",
+    "    calm_limit=0.1,\n",
+    "    kind='bar'\n",
+    ")\n",
+    "\n",
+    "# make the subplots easier to compare, by having the same y-axis range\n",
+    "y_ticks = range(0, 17, 4)\n",
+    "for ax in g.axes:\n",
+    "    ax.set_legend(title='$m \\cdot s^{-1}$', bbox_to_anchor=(1.15, -.1), loc='lower right')\n",
+    "    ax.set_rgrids(y_ticks, y_ticks)\n",
+    "\n",
+    "# adjust the spacing between the subplots to have sufficient space between plots\n",
+    "plt.subplots_adjust(wspace=-.2)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -402,7 +471,7 @@
     "ws = np.random.random(N) * 6\n",
     "wd = np.random.random(N) * 360\n",
     "df = pd.DataFrame({\"speed\": ws, \"direction\": wd})\n",
-    "plot_windrose(df, kind=\"contour\", bins=np.arange(0.01, 8, 1), cmap=cm.hot, lw=3);"
+    "plot_windrose(df, kind=\"contour\", bins=np.arange(0.01, 8, 1), cmap=cm.hot, lw=3)"
    ]
   },
   {
@@ -470,7 +539,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.4"
+   "version": "3.11.3"
   }
  },
  "nbformat": 4,

requirements-dev.txt

@@ -19,8 +19,10 @@ pytest-cov
 pytest-flake8
 pytest-mpl
 pytest-sugar
+seaborn
 setuptools_scm
 sphinx
+sphinx-copybutton
 sphinx_rtd_theme
 twine
 wheel