HW3_template.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "2646a34e-a634-47ac-9fe7-73bf40ece8ae",
   "metadata": {},
   "source": [
    "# HW3 Template: Dataset Overview and Use Case Examples\n",
    "## EDS 220, Fall 2021\n",
    "\n",
    "The following is a template you can use for constructing your draft Jupyter notebooks demonstrating the features and use case examples for your chosen environmental datasets. I've included sections addressing the major themes that should be included, but there is also room for customization as well. \n",
    "\n",
    "Many of the resources provided are adapted from this template guide to notebook creation built for the \"EarthCube\" project:\n",
    "https://github.com/earthcube/NotebookTemplates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56a405bf-2d38-4175-a931-f52905e11211",
   "metadata": {},
   "source": [
    "## Template Notebook for EDS 220 HW/Group Project\n",
    "\n",
    "Replace the above with your chosen title. This should include some indication of the dataset you chose, but can also include a 'team title' or short summary of the themes of your analysis. Possible examples taken from the Week 7 sea surface temperature analysis notebook:\n",
    "- ERSSTv5 Sea Surface Temperature \n",
    "- El Nino/Southern Oscillation Overview with ERSSTv5"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc47afd0-adb0-4d5b-8903-992b7904322e",
   "metadata": {},
   "source": [
    "## Authors\n",
    "\n",
    "Include the names of everyone in your group! In professional contexts, best practice is to also include up-to-date contact information and any affiliation information: here we're all at UCSB of course, but listing contact info can be helpful nonetheless if you plan to use this notebook later on for any job hunting purposes. \n",
    "\n",
    "An example for this notebook:\n",
    "\n",
    "#### Authors\n",
    "- Samantha Stevenson, UC Santa Barbara (sstevenson@ucsb.edu) <br>\n",
    "  https://www.samanthalstevenson.com/"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e8c2013-fef1-44ac-bb00-3215807cacac",
   "metadata": {},
   "source": [
    "## Table of Contents\n",
    "\n",
    "Include a summary of the various sections included in your notebook, so that users can easily skip to a section of interest. It's also good to include hyperlinks to the different sections, so that clicking on the heading sends one to that section directly. Examples are below; see also this handy guide to adding hyperlinks to Jupyter notebooks:\n",
    "https://medium.illumidesk.com/jupyter-notebook-little-known-tricks-b0866a558017\n",
    "\n",
    "The major sections you'll need for HW3 - and your group project - are shown below:\n",
    "\n",
    "[1. Purpose](#purpose)\n",
    "\n",
    "[2. Dataset Description](#overview)\n",
    "\n",
    "[3. Data I/O](#io)\n",
    "\n",
    "[4. Metadata Display and Basic Visualization](#display)\n",
    "\n",
    "[5. Use Case Examples](#usecases)\n",
    "\n",
    "[6. Create Binder Environment](#binder)\n",
    "\n",
    "[7. References](#references)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba52c6e3-3584-48be-b500-21578b61bd72",
   "metadata": {},
   "source": [
    "<a id='purpose'></a> \n",
    "### Notebook Purpose\n",
    "\n",
    "State the overall purpose of the notebook. Again, this may seem obvious for this particular case, but can come in handy if you're using the notebook later on!\n",
    "\n",
    "An example for the Week 7 in-class intensive: <br>\n",
    "This notebook was created to provide an introduction to using sea surface temperature data from the NOAA Extended Reconstructed SST dataset version 5 (ERSSTv5) for analysis of El Nino/Southern Oscillation (ENSO) behavior."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d429260a-2c30-44da-a5af-e100a440056a",
   "metadata": {},
   "source": [
    "<a id='overview'></a> \n",
    "### Dataset Description\n",
    "\n",
    "This portion of the notebook should contain a summary description of your chosen environmental dataset. In a few paragraphs, discuss:\n",
    "- The creators of the dataset: NASA/NOAA/other government agency? Nonprofit? etc.\n",
    "- Major characteristics of the dataset: global coverage? Spatial resolution? Temporal resolution? Creation date? \n",
    "- The file format(s) used to store the data: netCDF? CSV? Other?\n",
    "- The source/archive you will be using to retrieve the data: Google Earth Engine? Agency data portal? Other API?\n",
    "- Any known issues with data quality that might be expected to impact the results\n",
    "\n",
    "Include links to any external resources needed to access the data here, including either the location of files stored on an external server you've set up or the access URL for a pre-existing repository. You can also include any example images you find useful for motivating the choice of dataset (optional).\n",
    "\n",
    "**Here and throughout the notebook:** use a mix of markdown cells and code blocks to demonstrate your code. Markdown cells should be used to describe the purpose of the code blocks which follow them, but _do not replace_ comments within the code block! Make sure to include comments in the code as well illustrating the specific function of the various lines of code. Your later self - and other users - will thank you!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "02d5cb75-cb54-4708-8b88-459cae2ca17d",
   "metadata": {},
   "source": [
    "<a id='io'></a> \n",
    "### Dataset Input/Output \n",
    "\n",
    "Next, provide code to read in the data necessary for your analysis. This should be in the following order:\n",
    "\n",
    "1) Import all necessary packages (matplotlib, numpy, etc)\n",
    "\n",
    "2) Set any parameters that will be needed during subsequent portions of the notebook. Typical examples of parameters include:\n",
    "- names of any directories where data are stored\n",
    "- ranges of years over which data are valid\n",
    "- any thresholds or latitude/longitude ranges to be used later (e.g. dimensions of NINO3.4 region, threshold SSTA values for El Nino, etc.)\n",
    "\n",
    "3) Read in the data! If the data files are very large, you may want to consider subsetting the portion of files to be read in (see examples of this during notebooks provided in Weeks 7 and 8).\n",
    "\n",
    "_Since we will be running these notebooks in class during Weeks 9 and 10_, here is a good rule of thumb: It's good to aim for a relatively short amount of time needed to read in the data, since otherwise we'll be sitting around waiting for things to load for a long time. A  minute or two for data I/O is probably the max you'll want to target!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30253e61-0707-4540-9c86-9afc6df27958",
   "metadata": {},
   "source": [
    "<a id='display'></a> \n",
    "### Metadata Display and Basic Visualization\n",
    "\n",
    "Next, provide some example commands to take a quick look at what is in your dataset. We've done some things along these lines in class by now, but you should include at least one of:\n",
    "\n",
    "- Metadata display: commands to indicate a) which variables are included in the dataset and their names; b) coordinate information associated with the data variables; c) other important metadata parameters (site names, etc); and d) any important information on missing data\n",
    "- Basic visualization: a \"quick and dirty\" plot showing generally what the data look like. Depending on your dataset, this could be either a time series or a map (no fancy coordinate reference system/projection needed yet)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "62354cdf-609f-487d-be51-9ea306997a69",
   "metadata": {},
   "source": [
    "<a id='usecases'></a> \n",
    "### Use Case Examples"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e5b04a9-b2bb-40ed-bb8c-9c75d3494c38",
   "metadata": {},
   "source": [
    "This is the \"meat\" of the notebook, and what will take the majority of the time to present in class. This section should provide:\n",
    "1) A plain-text summary (1-2 paragraphs) of the use case example you have chosen: include the target users and audience, and potential applicability. For example, the Week 7 SST exercise might discuss how the state of the ENSO system can be important for seasonal weather forecasts/coral bleaching outlooks, then mention the typical diagnostics associated with ENSO (i.e. identification of El Nino/La Nina events).\n",
    "\n",
    "2) Markdown and code blocks demonstrating how one walks through the desired use case example. This should be similar to the labs we've done in class: you might want to demonstrate how to isolate a particularly interesting time period, then create an image showing a feature you're interested in, for example.\n",
    "\n",
    "3) A discussion of the results and how they might be extended on further analysis. For example, we are doing El Nino/La Nina composites in class; a natural extension might be to look at individual events to see what their particular impacts were. Or if there are data quality issues which impact the results, you could discuss how these might be mitigated with additional information/analysis.\n",
    "\n",
    "Just keep in mind, you'll have roughly 20 minutes for your full presentation, and that goes surprisingly quickly! Probably 2-3 diagnostics is the most you'll be able to get through (you could try practicing with your group members to get a sense of timing).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d07de0d-1e81-442a-a895-7b7fd7906385",
   "metadata": {},
   "source": [
    "<a id='binder'></a> \n",
    "### Create Binder Environment\n",
    "\n",
    "The last step is to create a Binder environment for your project, so that we don't have to spend time configuring everyone's environment each time we switch between group presentations. Instructions are below:\n",
    "\n",
    " - Assemble all of the data needed in your Github repo: Jupyter notebooks, a README file, and any datasets needed (these should be small, if included within the repo). Larger datasets should be stored on a separate server, and access codes included within the Jupyter notebook as discussed above. \n",
    " \n",
    " - Create an _environment_ file: this is a text file which contains information on the packages needed in order to execute your code. The filename should be \"environment.yml\": an example that you can use for the proper syntax is included in this template repo. To determine which packages to include, you'll probably want to start by displaying the packages loaded in your environment: you can use the command `conda list -n [environment_name]` to get a list.\n",
    " \n",
    " More information on environment files can be found here:\n",
    " https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#\n",
    "\n",
    " - Create Binder. Use http://mybinder.org to create a  URL for your notebook Binder (you will need to enter your GitHub repo URL). You can also add a Launch Binder button directly to your GitHub repo, by including the following in your README.md:\n",
    "\n",
    "```\n",
    "launch with myBinder\n",
    "[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/<path to your repo>)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c62c774b-8a7c-4f47-9c07-7f9823c48473",
   "metadata": {},
   "source": [
    "<a id='references'></a> \n",
    "### References\n",
    "\n",
    "List relevant references. Here are some additional resources on creating professional, shareable notebooks you may find useful:\n",
    "\n",
    "1. Notebook sharing guidelines from reproducible-science-curriculum: https://reproducible-science-curriculum.github.io/publication-RR-Jupyter/\n",
    "2. Guide for developing shareable notebooks by Kevin Coakley, SDSC: https://github.com/kevincoakley/sharing-jupyter-notebooks/raw/master/Jupyter-Notebooks-Sharing-Recommendations.pdf\n",
    "3. Guide for sharing notebooks by Andrea Zonca, SDSC: https://zonca.dev/2020/09/how-to-share-jupyter-notebooks.html\n",
    "4. Jupyter Notebook Best Practices: https://towardsdatascience.com/jupyter-notebook-best-practices-f430a6ba8c69\n",
    "5. Introduction to Jupyter templates nbextension: https://towardsdatascience.com/stop-copy-pasting-notebooks-embrace-jupyter-templates-6bd7b6c00b94  \n",
    "    5.1. Table of Contents (Toc2) readthedocs: https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/toc2/README.html  \n",
    "    5.2. Steps to install toc2: https://stackoverflow.com/questions/23435723/installing-ipython-notebook-table-of-contents\n",
    "6. Rule A, Birmingham A, Zuniga C, Altintas I, Huang SC, et al. (2019) Ten simple rules for writing and sharing computational analyses in Jupyter Notebooks. PLOS Computational Biology 15(7): e1007007. https://doi.org/10.1371/journal.pcbi.1007007. Supplementary materials: example notebooks (https://github.com/jupyter-guide/ten-rules-jupyter) and tutorial (https://github.com/ISMB-ECCB-2019-Tutorial-AM4/reproducible-computational-workflows)\n",
    "7. Languages supported by Jupyter kernels: https://github.com/jupyter/jupyter/wiki/Jupyter-kernels\n",
    "8. EarthCube notebooks presented at EC Annual Meeting 2020: https://www.earthcube.org/notebooks\n",
    "9. Manage your Python Virtual Environment with Conda: https://towardsdatascience.com/manage-your-python-virtual-environment-with-conda-a0d2934d5195\n",
    "10. Venv - Creation of Virtual Environments: https://docs.python.org/3/library/venv.html"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e9f10df5-100c-4f4a-a1c3-bd417b524a61",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}