Merge pull request #6 from kanderso-nrel/jb-setup

Add jupyter-book config

Author: mikofski

.github/workflows/build-gh-pages.yaml

@@ -0,0 +1,37 @@
+name: deploy-book
+
+# Only run this when the main branch changes
+on:
+  push:
+    branches:
+    - main
+
+# This job installs dependencies, build the book, and pushes it to `gh-pages`
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+
+    # Install dependencies
+    - name: Set up Python 3.7
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.7
+
+    - name: Install dependencies
+      run: |
+        pip install -r requirements.txt
+        pip install jupyter-book
+
+    # Build the book
+    - name: Build the book
+      run: |
+        jupyter-book build .
+
+    # Push the book's HTML to github-pages
+    - name: GitHub Pages action
+      uses: peaceiris/[email protected]
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./_build/html

.gitignore

@@ -1,3 +1,5 @@
 .ipynb_checkpoints
 *.py
 *.html
+
+_build

Tutorial 0 - Overview.ipynb

@@ -30,7 +30,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# More on your teachers:\n",
+    "## More on your teachers:\n",
     "\n",
     "The three of us have ample experience in data, coding, and PV field performance modeling, so we look forward to all of your questions.\n",
     "\n",
@@ -49,7 +49,7 @@
     }
    },
    "source": [
-    "### Learning Objectives\n",
+    "## Learning Objectives\n",
     "\n",
     "1.\tAccess weather data (TMY3), understand irradiance data, and visualize it monthly.\n",
     "2.\tCalculate sun position, plane of array irradiance, and aggregate irradiance data into average daily insolation by month and year.\n",
@@ -91,7 +91,7 @@
     }
    },
    "source": [
-    "# How to use this tutorial?\n",
+    "## How to use this tutorial?\n",
     "\n",
     "This tutorial is a [Jupyter](https://jupyter.org) notebook. Jupyter is a browser based interactive tool that combines text, images, equations, and code that can be shared with others. Please see the setup section in the [README](./README.md) to learn more about how to get started."
    ]
@@ -151,7 +151,7 @@
     }
    },
    "source": [
-    "# Exercise: Print Hello, world!\n",
+    "## Exercise: Print Hello, world!\n",
     "\n",
     "Each notebook will have exercises for you to solve. You'll be given a blank or\n",
     "partially completed cell, followed by a hidden cell with a solution. For\n",
@@ -186,7 +186,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Exercise 1: Modify to print something else:"
+    "## Exercise 1: Modify to print something else:"
    ]
   },
   {
@@ -203,12 +203,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Let's go over some Python Concepts\n",
+    "## Let's go over some Python Concepts\n",
     "\n",
     "(A lot of this examples were shamely taken from https://jckantor.github.io/CBE30338/01.01-Getting-Started-with-Python-and-Jupyter-Notebooks.html :$)\n",
     "\n",
     "\n",
-    "###  Basic Arithmetic Operations\n",
+    "## Basic Arithmetic Operations\n",
     "\n",
     "Basic arithmetic operations are built into the Python langauge. Here are some examples. In particular, note that exponentiation is done with the ** operator."
    ]
@@ -244,7 +244,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Python Libraries\n",
+    "## Python Libraries\n",
     "\n",
     "The Python language has only very basic operations. Most math functions are in various math libraries. The numpy library is convenient library. This next cell shows how to import numpy with the prefix np, then use it to call a common mathematical functions."
    ]
@@ -312,7 +312,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Concatenation\n",
+    "## Concatenation\n",
     "\n",
     "Concatentation is the operation of joining one list to another."
    ]
@@ -364,7 +364,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Loops"
+    "## Loops"
    ]
   },
   {
@@ -392,7 +392,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Working with Dictionaries\n",
+    "## Working with Dictionaries\n",
     "\n",
     "Dictionaries are useful for storing and retrieving data as key-value pairs. For example, here is a short dictionary of molar masses. The keys are molecular formulas, and the values are the corresponding molar masses.\n"
    ]
@@ -438,7 +438,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Plotting\n",
+    "## Plotting\n",
     "\n",
     "Importing the matplotlib.pyplot library gives IPython notebooks plotting functionality very similar to Matlab's. Here are some examples using functions from the"
    ]
@@ -487,7 +487,7 @@
     }
    },
    "source": [
-    "# Going Deeper\n",
+    "## Going Deeper\n",
     "\n",
     "We've designed the notebooks above to cover the basics of pvlib from beginning\n",
     "to end. To help you go deeper, we've also create a list of notebooks that\n",

Tutorial 1 - TMY Weather Data.ipynb

@@ -35,19 +35,19 @@
     }
    },
    "source": [
-    "### Steps:\n",
+    "## Steps:\n",
     "- [Weather data in PV performance models](#Weather-Data-&-PV)\n",
     "- Looking at a sample weather data file\n",
     "- Where to get weather data from? \n",
     "- Weather data to API\n",
     "\n",
-    "### PV Concepts:\n",
+    "## PV Concepts:\n",
     "- TMY\n",
     "- GHI, DNI, DHI\n",
     "- DryBulb, Wspd\n",
     "- Irradiance vs. Insolation\n",
     "\n",
-    "### Python Concepts:\n",
+    "## Python Concepts:\n",
     "- Exploring a Pandas dataframe (`df`): `len()`, `df.head()`, `df.keys()`\n",
     "- [pvlib input-output tools](https://pvlib-python.readthedocs.io/en/stable/api.html#io-tools)\n",
     "- Ploting a Pandas dataframe (`df`): `df.plot()`\n",
@@ -63,7 +63,7 @@
     }
    },
    "source": [
-    "# Weather Data & PV \n",
+    "## Weather Data & PV \n",
     "\n",
     "Weather and irradiance data are used as input to PV performance models.  \n",
     "\n",
@@ -120,7 +120,7 @@
     }
    },
    "source": [
-    "#### First Step: Import Libraries\n",
+    "## First Step: Import Libraries\n",
     "\n",
     "In Python, some functions are builtin like `print()` but others must be imported before they can be used. For this notebook we're going to import three packages:\n",
     "* [pvlib](https://pvlib-python.readthedocs.io/en/stable/) - library for simulating performance of photovoltaic energy systems. \n",
@@ -725,7 +725,7 @@
     }
    },
    "source": [
-    "# Irradiance \n",
+    "## Irradiance \n",
     "\n",
     "Irradiance is an instantaneous measurement of solar power over some area.  For practical purposes of measurement and interpretation, irradiance is expressed and separated into different components.\n",
     "\n",
@@ -742,7 +742,7 @@
     }
    },
    "source": [
-    "### Wind\n",
+    "## Wind\n",
     "\n",
     "Wind speed is measured with an anemometer.  The most common type is a the cup-type anemometer, shown on the right side of the picture below.  The number of rotations per time interval is used to calculate the wind speed.  The vane on the left is used to measure the direction of the wind.  Wind direction is reported as the direction from which the wind is blowing.\n",
     "\n",
@@ -757,7 +757,7 @@
     }
    },
    "source": [
-    "### Air temperature \n",
+    "## Air temperature \n",
     "\n",
     "Also known as dry-bulb temperature, is the temperature of the ambient air when the measurement device is shielded from radiation and moisture. The most common method of air temperature measurement uses a resistive temperature device (RTD) or thermocouple within a radiation shield. The shield blocks sunlight from reaching the sensor (avoiding radiative heating), yet allows natural air flow around the sensor. More accurate temperature measurement devices utilize a shield which forces air across the sensor.\n",
     "\n",
@@ -776,7 +776,7 @@
     }
    },
    "source": [
-    "#### Downselect columns \n",
+    "## Downselect columns \n",
     "\n",
     "There are a lot more weather data in that file that you can access. To investigate all the column headers, we used `.keys()` above. Always read the [Instruction Manual](https://www.nrel.gov/docs/fy08osti/43156.pdf) for the weather files to get more details on how the data is aggregated, units, etc.\n",
     "\n",
@@ -1138,7 +1138,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Temperature\n",
+    "### Temperature\n",
     "\n",
     "Next up is temperature:"
    ]
@@ -1299,7 +1299,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Exercise\n",
+    "### Exercise\n",
     "\n",
     "Plot the Average DNI per Day"
    ]
@@ -1333,7 +1333,7 @@
     }
    },
    "source": [
-    "# Where to get Solar Irradiance Data?\n",
+    "## Where to get Solar Irradiance Data?\n",
     "\n",
     "There are many different sources of solar irradiance data. For your projects, these are some of the most common:\n",
     "\n",
@@ -1368,7 +1368,7 @@
     }
    },
    "source": [
-    "### Fetching TMYs from the NSRDB\n",
+    "## Fetching TMYs from the NSRDB\n",
     "\n",
     "The example TMY dataset used here is from an airport in North Carolina, but what if we wanted to model a PV system somewhere else? The NSRDB, one of many sources of weather data intended for PV modeling, is free and easy to access using pvlib. As an example, we'll fetch a TMY dataset for Albuquerque, New Mexico at coordinates [(35.0844, -106.6504)](https://www.google.com/maps/@35.0844,-106.6504,9z). We use [`pvlib.iotools.get_psm3()`](https://pvlib-python.readthedocs.io/en/stable/generated/pvlib.iotools.get_psm3.html) which returns a Python dictionary of metadata and a Pandas dataframe of the timeseries weather data."
    ]

Tutorial 2 - POA Irradiance.ipynb

@@ -4,6 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "![tutorialpromo](images/tutorial_banner.PNG)\n",
+    "\n",
+    "\n",
     "# Tutorial 2 - POA Irradiance\n",
     "\n",
     "This notebook shows how to use pvlib to transform the three irradiance components (GHI, DHI, and DNI) into POA irradiance, the main driver of a PV system.\n",
@@ -15,13 +18,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### PV Concepts\n",
+    "## PV Concepts\n",
     "- Plane of Array Irradiance\n",
     "- Angle of Incidence\n",
     "- Time delta for solar position\n",
     "- GHI vs POA for fixed tilt system and tracked systems\n",
     "\n",
-    "### Python Concepts\n",
+    "## Python Concepts\n",
     "- pandas Timedelta\n",
     "- making a new dataframe from existing columns\n",
     "- resampling\n",
@@ -36,7 +39,7 @@
     "\n",
     "The amount of sunlight collected by a PV panel depends on how well the panel orientation matches incoming sunlight.  For example, a rooftop array facing West will produce hardly any energy in the morning when the sun is in the East because the panel can only \"see\" the dim part of the sky away from the sun.  \n",
     "\n",
-    "[Overview](images/t2_solarpanel_directions.PNG)\n",
+    "![Overview](images/t2_solarpanel_directions.PNG)\n",
     "\n",
     "\n",
     "As the sun comes into view and moves towards the center of the panel's field of view, the panel will collect more and more irradiance.  This concept is what defines plane-of-array irradiance -- the amount of sunlight available to be collected at a given panel orientation.  Like the three \"basic\" irradiance components, POA irradiance is measured in watts per square meter."
@@ -255,7 +258,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Fixed Tilt POA:"
+    "## Fixed Tilt POA"
    ]
   },
   {
@@ -308,7 +311,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### What's angle should you tilt your modules at?"
+    "### What angle should you tilt your modules at?"
    ]
   },
   {
@@ -547,7 +550,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.10"
+   "version": "3.7.3"
   }
  },
  "nbformat": 4,

Tutorial 3 - Module Temperature.ipynb

@@ -4,6 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "![tutorialpromo](images/tutorial_banner.PNG)\n",
+    "\n",
+    "\n",
     "# Tutorial 3 - Module Temperature\n",
     "\n",
     "This notebook shows how to use pvlib to estimate PV cell temperature, a secondary driver that affects the PV conversion efficiency.\n",
@@ -16,13 +19,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### PV Concepts in this lesson:\n",
+    "## PV Concepts in this lesson:\n",
     "\n",
     "* cell and module temperature\n",
     "* NSRDB data\n",
     "* TMY files\n",
     "\n",
-    "### Python concepts in this lesson:\n",
+    "## Python concepts in this lesson:\n",
     "\n",
     "* file system paths in Python with [`pathlib`](https://docs.python.org/3/library/pathlib.html)\n",
     "* parsing NSRDB data with [`pvlib.iotools.read_tmy3`](https://pvlib-python.readthedocs.io/en/stable/generated/pvlib.iotools.read_tmy3.html)\n",
@@ -253,7 +256,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Pop Quix\n",
+    "## Pop Quiz\n",
     "Now it's your turn. There's another, older TMY3 file in the pvlib data folder: \"703165TY.csv\".\n",
     "1. Create a path to the TMY3 file: \"703165TY.csv\" using `DATA_DIR` and the `/` operator\n",
     "2. read the timeseries and metadata from the file\n",
@@ -307,7 +310,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.10"
+   "version": "3.7.3"
   }
  },
  "nbformat": 4,