Update docs: download script and README

Update the download script & README
* mostly to expose image usage rules of road
* also to be explicit that script here is a derived work
  of original script from NASA
  * Upstream script does not have a clear licence
    * https://sdo.gsfc.nasa.gov/data/bestpractice.php
  * Assume not an issue, given intention (for data!) seems to be for reuse
    for precisely NASA Space Apps sort of usage:
    * https://sdo.gsfc.nasa.gov/data/rules.php

Also update README to:
* crosslink to the resources just added
* expose teams which chose spacewx-y challenges
* clarify the creche activities: 2024 might be able to do more here
* clarify the bootcamp stuff is to crosslink to last year's resources
  * this to keep institutional knowledge that these exists
  * again 2024 might be able to just reuse as pointers, even if don't
    rerun the bootcamp either

GH-3

README.md

@@ -1,51 +1,106 @@
 # Nasa Space Apps 2023 - Met Office, Exeter
-![NASA SpaceApps Logo](nasa_spaceapps_logo.png)
-## Resources:
-- [2023 challenges](https://www.spaceappschallenge.org/2023/challenges/)
-- [Met Office blog](https://blog.metoffice.gov.uk/2023/09/07/nasa-space-apps-challenge-is-coming-to-exeter/)
-
-
-## Space weather-y challenges
-
-1. Oracle of DSCOVR
-2. Magnetic reconnection
-3. Immersed in the sounds of space
-4. ??? Helio Big Year
 
-## Creche-compatible challenges
+![NASA SpaceApps Logo](nasa_spaceapps_logo.png)
 
-1. Eclipses: Perspective
-2. Work of SARt
-3. Video on Artemis?
-4. Open science storytelling
+* [Introduction](#introduction)
+* [Resources](#resources)
+  * [Challenges related to space weather, and resources](#challenges-related-to-space-weather-and-resources)
+  * [Creche-compatible challenges](#creche-compatible-challenges)
+  * [Introduction to Python for Environmental Science](#introduction-to-python-for-environmental-science)
 
 ## Introduction
 
-This series of tutorials on technical and data resources for NASA Space Apps Challenge 2023, hosted in Exeter by the Joint Centre of Excellence in Environmental Intelligence and TechExeter.
+This repository provides a series of tutorials on technical and data resources
+for NASA Space Apps Challenge 2023, hosted in Exeter by the Joint Centre of Excellence
+in Environmental Intelligence and TechExeter.
+
+## Resources
+
+* [2023 challenges](https://www.spaceappschallenge.org/2023/challenges/)
+* [Met Office blog](https://blog.metoffice.gov.uk/2023/09/07/nasa-space-apps-challenge-is-coming-to-exeter/)
+* [Exeter event (schedule, teams)](https://www.spaceappschallenge.org/2023/locations/exeter/)
+
+### Challenges related to space weather, and resources
+
+1. [Develop the Oracle of DSCOVR](https://www.spaceappschallenge.org/2023/challenges/develop-the-oracle-of-dscovr/)
+   1. 2 teams chose
+      1. [BANSSAB](https://www.spaceappschallenge.org/2023/find-a-team/banssab/)
+      2. [Solar Storm](https://www.spaceappschallenge.org/2023/find-a-team/solar-storm/)
+2. [Immersed in the Sounds of Space](https://www.spaceappschallenge.org/2023/challenges/immersed-in-the-sounds-of-space/)
+   1. 1 team chose
+      1. [Solar Sounds](https://www.spaceappschallenge.org/2023/find-a-team/solar-sounds/)
+         1. Local event winners!
+         2. *Contained members of pre-event team [Solar Audible Experience](https://www.spaceappschallenge.org/2023/find-a-team/solar-sounds/)*
+   2. Data: Solar Dynamics Observatory imagery in [`data/immersed_sounds_space/SDO/`](data/immersed_sounds_space/SDO/)
+      1. Attribute as follows: ["Courtesy of NASA/SDO and the AIA, EVE, and HMI science teams."](https://sdo.gsfc.nasa.gov/data/rules.php)
+      2. Data retrieval script: [`bin/download_sdo_data`](bin/download_sdo_data)
+3. [Magnetic Reconnection](https://www.spaceappschallenge.org/2023/challenges/magnetic-reconnection/)
+   1. *No teams participated locally*
+   2. *No resources created*
+4. Potentially: [Winning the Helio Big Year with Joy, Curiosity, and Science!](https://www.spaceappschallenge.org/2023/challenges/winning-the-helio-big-year-with-joy-curiosity-and-science/)
+   1. *No teams participated locally*
+   2. *No resources created*
+
+### Creche-compatible challenges
+
+The creche could possibly come up with some activities linked with these challenges:
+
+1. [Eclipses: Perspective is Everything](https://www.spaceappschallenge.org/2023/challenges/eclipses-perspective-is-everything/)
+   1. Get kids to make a game for kids to explain why not whole Earth can see given eclipse
+2. [Create a Work of SARt (Synthetic Aperture Radar Art)](https://www.spaceappschallenge.org/2023/challenges/create-a-work-of-sart-synthetic-aperture-radar-art/)
+   1. Craft activities - interpret SAR imagery with crayons, glitter, glue, ...
+3. [Artemis II and You!](https://www.spaceappschallenge.org/2023/challenges/artemis-ii-and-you/)
+   1. Get kids to create a video?
+4. [Open Science Storytelling](https://www.spaceappschallenge.org/2023/challenges/open-science-storytelling/)
+   1. Find a case; get children to come up with a story about it
 
 ### Introduction to Python for Environmental Science
 
-Learn about useful Python packages for working with environmental datasets and work through some basic examples for loading and exploring different types of data.
+*The following guidance is taken from the [bootcamp run before NASA Space Apps 2022](https://github.com/informatics-lab/spaceapps-2022-mo-bootcamp).*
+*No bootcamp was run in 2023.*
+*Nevertheless, cross-linking the previous guidance to flag resources available*
+*at the link above to help with Python and environment management*
+
+Learn about useful Python packages for working with environmental datasets and work
+through some basic examples for loading and exploring different types of data.
 
-### Machine Learning with Weather Data
+#### Machine Learning with Weather Data
 
-A brief introduction to machine learning and have the opportunity to work through a simple (cloud computing) example, specifically using some readily available weather data.
+A brief introduction to machine learning and have the opportunity to work through
+a simple (cloud computing) example, specifically using some readily available weather
+data.
 
-### Introduction to Weather and Climate Datasets
+#### Introduction to Weather and Climate Datasets
 
-A brief overview of the types of data we have available within the Met Office. These datasets are open source, you'll have the oppertunity download and explore this data through the example notebooks provided. This will give you the tools to explore weather and climate data yourself.
+A brief overview of the types of data we have available within the Met Office.
+These datasets are open source, you'll have the oppertunity download and explore
+this data through the example notebooks provided.
+This will give you the tools to explore weather and climate data yourself.
 
 ______________________________________________________________________
 
-We will assume you have some experience with programming langauges and ideally have a little bit of knowledge of python. There are a lot of excellent resources on the internet for learning python. This short series of tutorials condenses the most important parts for working specifically with enviromental datasets and provides an overview of tools to make this easier. For a more in depth understanding of python, exploring these exellent tutorials is recommended:
+We will assume you have some experience with programming langauges and ideally have a
+little bit of knowledge of python.
+There are a lot of excellent resources on the internet for learning python.
+This short series of tutorials condenses the most important parts for working
+specifically with enviromental datasets and provides an overview of tools to make
+this easier.
+For a more in depth understanding of python, exploring these exellent tutorials is
+recommended:
+
+- Software Carpentry: <https://swcarpentry.github.io/python-novice-inflammation/index.html>
+- DataCamp: <https://www.datacamp.com/courses/intro-to-python-for-data-science>
 
-- Software Carpentry: https://swcarpentry.github.io/python-novice-inflammation/index.html
-- DataCamp: https://www.datacamp.com/courses/intro-to-python-for-data-science
+#### Python environment set up
 
-### Python environment set up
-Some of these tutorials require some python package management, we have done this through [Conda](https://docs.conda.io/projects/conda/en/latest/). If you don't have Conda, [install miniconda here](https://docs.conda.io/en/latest/miniconda.html). If you prefer other package management methods please feel free to use them. More information about package management for each session will be contained in the README of that folder.
+Some of these tutorials require some python package management, we have done this
+through [Conda](https://docs.conda.io/projects/conda/en/latest/).
+If you don't have Conda, [install miniconda here](https://docs.conda.io/en/latest/miniconda.html).
+If you prefer other package management methods please feel free to use them.
+More information about package management for each session will be contained in the
+README of that folder.
 
-### Acknowledgements
+#### Acknowledgements
 
 Development of these tutorials was funded by the [Joint Centre for Excellence in Environmental Intelligence](https://jceei.org/).
 

bin/download_sdo_data

@@ -18,13 +18,20 @@ Usage: $0 START_DATE END_DATE CHANNEL RESOLUTION DOWNLOAD_PATH
 Download Solar Dynamics Observatory images to a local directory, for later sonification
 
 NOTE:
-* based on script from https://sdo.gsfc.nasa.gov/data/bestpractice.php
-  * converted from Mac/BSD date options to GNU date
-* naive, intended just for simple images
+* this script is based on script from https://sdo.gsfc.nasa.gov/data/bestpractice.php
+  * source script had no explicit licence
+  * changes made:
+    * converted from Mac/BSD date options to GNU date
+    * extended to allow retrievals based on synoptic solar rotation rate
+    * generally tightened up a little
+* this script is naive, intended just for retrieving simple images
   * use sunpy for:
     * more complex retrievals
     * to get .fits data better-suited for sophisticated sonification
   * see https://docs.sunpy.org/en/stable/tutorial/acquiring_data/jsoc.html
+* rules for use of imagery retrieved: https://sdo.gsfc.nasa.gov/data/rules.php
+  * TLDR: very permissive, but attribute as follows
+  * "Courtesy of NASA/SDO and the AIA, EVE, and HMI science teams."
 
 Positional parameters:
 * START_DATE: date to start downloading from, format YYYY/MM/DD
@@ -53,25 +60,32 @@ START_DATE=$1
 END_DATE=$2
 CHANNEL=$3
 RESOLUTION=$4
+# shellcheck disable=SC2086  # $5 unquoted to allow expansion of paths with ~/ or ~user/
+# * but as unquoted will break with paths with whitespace etc!
+# * more complex alternative to fix: https://stackoverflow.com/a/15859646
 DOWNLOAD_PATH=$(realpath $5)
 
-# Download cadence
+# Set cadence mode: controls time interval between downloaded images
+# * Currently available modes: ["solar" "daily"]
+# * TODO: expose as positional parameter / getopts option
 CADENCE_MODE="solar"
+
+# Calculate download cadence
 SECONDS_IN_DAY=$(( 24 * 60 * 60 ))
 if [ "$CADENCE_MODE" == "solar" ]; then
   # Use synodic (viewed from Earth) solar rotation rate at heliolatitude ~26N (/~26S!)
   # * https://www.star.bris.ac.uk/bjm/solar/solarrot.html
   # * https://en.wikipedia.org/wiki/Solar_rotation
   solar_rot_rate=27.25
-  # Perform multiplication with bc, truncating floating point component
+  # Multiply with bc; use scale to truncate decimal component -> get int result
   # * See https://linux.die.net/man/1/bc
   CADENCE_SECONDS=$(echo "scale=0;($solar_rot_rate * $SECONDS_IN_DAY) / 1" | bc)
   # Filter: only want 1 image from each solar rotation
   # Via .25 fraction, we'll cycle through 6 hour blocks: T00, T06, T12, T18
-  # Given channel+resolution images are usually available at ~15 min repeats
+  # Given channel+resolution images are *usually* available at ~15 min repeats
   # So unfiltered, would retrieve get ~4 images / H -> 24 images / block
   # Only want to retrieve 1 image per block
-  # So filter to minute 0N (minute 00 to 09) or 1N (minute 10 to 19) to get 1-2
+  # So filter to minute 0N (minute 00 to 09) or 1N (minute 10 to 19) to get ~0-3
   # images for the given block
   MMSS_FILTER="[0-1]???"
 elif [ "$CADENCE_MODE" == "daily" ]; then
@@ -143,7 +157,7 @@ do
     # Move the 1st downloaded image to $LOCAL_DIR, & any remaining to $ALTERNATIVES_DIR
     # * don't clobber pre-existing files (e.g. from earlier runs of script)
     # * so empty $STAGING_DIR after, in case --no-clobber means we've got leftovers here
-    # shellcheck disable=SC2224
+    # shellcheck disable=SC2224  # avoid false positive about mv missing a target
     mv --no-clobber --target-directory="$LOCAL_DIR" "$first_image"
     n_alternative_images="${#alternative_images[@]}"
     if (( n_alternative_images > 0 )); then