[ref #9] Improve Usage notebook; update documentation

Author: camirmas

Usage.ipynb

@@ -1,5 +1,17 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "intermediate-triangle",
+   "metadata": {},
+   "source": [
+    "# Albatross Usage Information\n",
+    "\n",
+    "_Before using this notebook, make sure to follow the [installation](https://github.com/camirmas/albatross#installation) instructions._\n",
+    "\n",
+    "**Full installation and module documentation can be found at https://albatross-wind.readthedocs.io/en/latest/index.html**"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -12,6 +24,26 @@
     "from albatross import WindTurbine, RequestParams"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "involved-hopkins",
+   "metadata": {},
+   "source": [
+    "## The `requests` module\n",
+    "\n",
+    "This module is responsible for retrieving WIND Toolkit data.\n",
+    "\n",
+    "Full documentation can be found at https://albatross-wind.readthedocs.io/en/latest/requests.html"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "foreign-ethiopia",
+   "metadata": {},
+   "source": [
+    "`get_regions` returns the full set of available regions with their configuration options. Its optional argument determines whether to pretty print the results alongside returning them."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 2,
@@ -297,6 +329,14 @@
     "get_regions(True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "broke-salon",
+   "metadata": {},
+   "source": [
+    "`identify_regions` returns the region associated with a given lat/lon point. By default, it does not make any network requests. However, the kwarg `coordinates=True` will make a network request to include all lat/lon data points associated with the region that includes the specified lat/lon point. Note that multiple regions might be returned: that is because some of the WIND Toolkit's bounding boxes overlap in some places."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 3,
@@ -369,6 +409,14 @@
     "identify_regions(lat_lon, coordinates=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "anonymous-arrangement",
+   "metadata": {},
+   "source": [
+    "In order to make a request, let's first define our parameters using a `RequestParams` instance. We can see the valid fields using the class method `get_fields`. Note that the first four fields (`wind_speed`, `wind_direction`, `pressure`, and `temperature`) must be registered with a `height` parameter. "
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 6,
@@ -399,6 +447,14 @@
     "RequestParams.get_fields()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "variable-camcorder",
+   "metadata": {},
+   "source": [
+    "Here's an example point data request. Note that the region 'nw_pacific' is explicitly specified here. This is only necessary the given lat/lon point falls in multiple regions. Normally, the function will infer the region, so if you aren't sure, leave the `region` kwarg out and the function will raise an error with instructions if it encounters multiple regions."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 7,
@@ -415,6 +471,14 @@
     "(data, meta) = request_wtk_point_data(lat_lon, year, rp.params, region='nw_pacific', resolution=\"5min\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "streaming-style",
+   "metadata": {},
+   "source": [
+    "The result of this request is a `pandas.DataFrame` with all specified arguments included."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 8,
@@ -552,6 +616,26 @@
     "data"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "subject-tournament",
+   "metadata": {},
+   "source": [
+    "## The `analysis` module \n",
+    "\n",
+    "This module is responsible for generating insights from wind data. **This module does not require WIND Toolkit data specifically;** however, if you intend to use your own data, you'll need to specify which fields you want, or meet the field inference requirements as specified in the documentation for each function. In general, unless explicitly overridden, wind speed and direction fields will be **inferred** by looking for data columns that contain the strings `'windspeed'` and `'winddirection'`, respectively.\n",
+    "\n",
+    "Full module documentation can be found at https://albatross-wind.readthedocs.io/en/latest/analysis.html"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "attempted-recall",
+   "metadata": {},
+   "source": [
+    "`boxplot` generates boxplots of wind speeds. It returns normal `matplotlib` objects for further modification."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 9,
@@ -577,6 +661,14 @@
     "fig.set_figwidth(8)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "cordless-iceland",
+   "metadata": {},
+   "source": [
+    "`plot_windrose` generates a windrose plot from the given data. It uses the [windrose](https://github.com/python-windrose/windrose) Python package."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 10,
@@ -598,6 +690,14 @@
     "ax = plot_windrose(data)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "interracial-gospel",
+   "metadata": {},
+   "source": [
+    "`pdf` generates a Weibull probability density plot from the given data. It returns `matplotlib` objects as well as parameters representing shape (2), location, and scale for the Weibull distribution."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 11,
@@ -642,6 +742,14 @@
     "params"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "charged-given",
+   "metadata": {},
+   "source": [
+    "`get_diurnal_stats` returns basic relevant diurnal wind speed statistics for the given data."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 13,
@@ -972,6 +1080,14 @@
     "get_diurnal_stats(data)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "aggregate-security",
+   "metadata": {},
+   "source": [
+    "`plot_diurnal_stats` plots basic relevant diurnal wind speed statistics for the given data."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 14,
@@ -995,6 +1111,14 @@
     "(fig, ax, df) = plot_diurnal_stats(data)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "spoken-clinic",
+   "metadata": {},
+   "source": [
+    "`turbulence_std` Calculates the turbulence standard deviation. It requires a `WindTurbine` instance, which provides information about the turbulence intensity based on standard wind turbine specifications according to IEC-61400, Section 6.2."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 15,

albatross/analysis.py

@@ -112,7 +112,7 @@ def plot_windrose(data, speed=None, direction=None, **wr_kwargs):
 
 def pdf(data, speed=None, hist_kwargs=None, plot_kwargs=None):
     """
-    Generates a windrose plot from the given data.
+    Generates a Weibull probability density plot from the given data.
 
     Args:
       data (DataFrame): Wind data

albatross/requests.py

@@ -229,7 +229,7 @@ def request_wtk_point_data(lat_lon, year, params, region=None, resolution=None,
 
 def get_regions(pprint=False):
     """
-    Returns the full set of regions with their configuration options.
+    Returns the full set of available regions with their configuration options.
 
     Note that the `year_range` represents an inclusive (beginning, end), where
     any specified value within that range is a valid year for that region.

docs/index.rst

@@ -1,14 +1,44 @@
-Welcome to albatross's documentation!
-=====================================
+albatross
+=========
+
+``albatross`` is a Python package designed for wind energy analysis and visualization. It utilizes NREL's [Wind Integration National Dataset (WIND) Toolkit](https://www.nrel.gov/grid/wind-toolkit.html) and [REsource eXtraction (rex)](https://github.com/NREL/rex) package, and is inspired in part by a similar package aimed instead at Marine Renewable Energy, [MHKiT](https://github.com/MHKiT-Software/MHKiT-Python).
+
+Features
+--------
+
+``albatross`` consists of two primary modules:
+
+* ``requests``:
+
+  * Request WIND Toolkit data by lat/lon point via HSDS
+  * Read WIND Toolkit data from a local HDF5 file
+  * Identify WIND Toolkit region and associated lat/lon coordinates, given a lat/lon point
+
+* ``analysis``:
+
+  * Draw boxplots for inferred windspeed fields (or other specified fields)
+  * Plot windrose chart for wind speed and direction data
+  * Fit a Weibull distribution for wind speed data and plot a histogram/line chart showing probability density
+  * Generate and/or plot diurnal statistics for wind speed data
+  * Determine turbulence standard deviation using the Normal Turbulence model for wind data and a set of archetype wind turbine configurations
+
+Future enhancements:
+
+* multi-year requests
+* allow use of CSV for ``analysis`` module functions
+* further incorporate turbulence model statistics
+
+Contents
+--------
 
 .. toctree::
-   :caption: Contents:
 
    modules
 
 .. toctree::
    :maxdepth: 1
 
+   installation
    proposal
 
 Indices and tables

docs/installation.md

@@ -0,0 +1,7 @@
+### Installation
+
+`albatross` has not yet been hosted on PyPI, so for now, install from Github:
+
+`pip install git+https://github.com/camirmas/albatross`
+
+If you'll be using the `requests` module, you'll also need to [configure HSDS](https://github.com/NREL/hsds-examples#how-to-use).