This is a repository for materials to complete the NEON Ecological Forecasting Challenge tutorial. This tutorial repository is a dynamic repository and may change in future iterations.
The tutorial is designed as a 90-minute, standalone session that includes an introductory presentation, a guided demonstration of forecast code, and open time for discussion. If a longer time period is available, this repository has additional activities and content that includes more advanced topics. These materials can also be completed as a self-paced tutorial.
R version 4.2 is required to run the code in this workshop. You should also check that your Rtools is up to date and compatible with R 4.2, see (https://cran.r-project.org/bin/windows/Rtools/rtools42/rtools.html).
The following packages need to be installed using the following code.
install.packages('remotes')
install.packages('tidyverse') # collection of R packages for data manipulation, analysis, and visualisation
install.packages('lubridate') # working with dates and times
remotes::install_github('eco4cast/neon4cast') # package from NEON4cast challenge organisers to assist with forecast building and submission
There are 3 options for getting the code locally so that you can run it, depending on your experience with Github/Git you can do one of the following:
- Fork (recommended) the repository to your Github and then clone the repository from your Github repository to a local RStudio project. This will allow you to modify the scripts and push it back to your Github.
- Find the fork button in the top right of the webpage --> Create Fork. This will generate a copy of this repository in your Github.
- Then use the <> Code button to copy the HTTPS link (from you Github!).
- In RStudio, go to New Project --> Version Control --> Git.
- Paste the HTTPS link in the Repository URL space, and choose a suitable location for your local repository --> Create Project.
- Open the .Rmd file
- Clone the workshop repository to a local RStudio project. Your local workspace will be set up and you can commit changes locally but they won't be pushed back to the Github repository.
- Use the <> Code button to copy the HTTPS link.
- In RStudio go to New Project --> Version Control --> Git.
- Paste the HTTPS link in the Repository URL space, and choose a suitable location for your local repository --> Create Project.
- Open the .Rmd file
- Download the zip file of the repository code. You can save changes (without version control) locally.
- Find the <> Code button --> Download ZIP.
- Unzip this to a location on your PC and open the
NEON-forecast-challenge-workshop.Rprojfile in RStudio.
More information on forking and cloning in R can be found at happygitwithr, a great resource to get you started using version control with RStudio.
For the workshop you can follow along via the rmarkdown document (Submit_forecast/NEON_forecast_challenge_workshop_aquatics.Rmd) or the md (Submit_forecast/NEON_forecast_challenge_workshop_aquatics.md), both of which can be downloaded here or you can fork the whole repository.
An introductory presentation that covers key forecasting concepts and a broad introduction the the Challenge and NEON data is available as both a PowerPoint or PDF. This presentation can be tailored to the audience based on expected familiarity with forecasting concepts and the data being forecasted.
The hands-on materials are split into three sections:
Submit_forecast- want to get started with making and submitting forecasts to the Challenge - start here!Automate_forecasts- you've made a model and submitted a forecast successfully? Automate your workflow to submit a new forecast every dayAnalyse_scores- interested in knowing how different forecasts are performing within the Challenge? This is a brief introduction in how to access the scored forecasts and do some simple analyses.
For a 90-minute workshop, the hands-on R markdown walk through uses the materials in the Submit_forecast directory (30-40 minutes). The Rmarkdown includes descriptive text to reinforce some of the ideas introduced in the presentation and guides participants through the stages of forecast development from importing 'target' data (observations), plotting and investigating data, developing a model, generating a forecast, adjusting the format to Challenge standards, and submitting their forecast to the Challenge.
Materials in the other directories are recommended for later completion and cover more advanced topics (see Tutorial extension).
For a standard 90-minute workshop, time at the end of the session can be used to debug user-specific code issues (package installation etc.), allow participants to modify the forecast model code available in the template (forecast_code_template.R), explore alternative forecast methods, or form forecasting teams to submit additional forecasts to the Challenge beyond the workshop session. Some potential topics and additional activities are detailed at the end of the Rmarkdown, including code for alternative forecasting methods or possible modifications to the example forecast.
To extend the tutorial beyond 90 minutes, we have provided materials that walk participants through how forecast submission could be automated (Automate_Forecast). Automation is a crucial step for iterative, near-term ecological forecasting, and is highly encouraged when participating in the Challenge after completing the tutorial. Finally, materials are available that introduce participants to how a forecast is evaluated and how the scores (evaluated forecast performance) can be analysed (Analyse_Scores). These materials could also be used in a self-paced manner after a workshop.
Analternative to running the materials locally, is to use a Docker container that has all the packages pre-installed.
Go to https://docs.docker.com/get-docker/ to install the relevant install for your platform (available for PC, Mac and Linux). Also see https://docs.docker.com/desktop/.
NOTE: * If you're running Windows, you will need WSL (Windows Subsystem for Linux) * If you're running a Linux distribution, you may have to enable Viritualization on your computer (see here)
- Launch Docker Desktop (either from the Command Line or by starting the GUI)
- At the command line run the following command which tells docker to
runthe container with the nameeco4cast/rocker-neon4castthat has all the packages and libraries installed already. ThePASSWORD=yourpasswordsets a simple password that you will use to open the container. The-tioption starts both a terminal and an interactive session.
docker run --rm -ti -e PASSWORD=yourpassword -p 8787:8787 eco4cast/rocker-neon4cast
This can take a few minutes to download and install. It will be quicker the next time you launch it.
- Open up a web browser and navigate to
http://localhost:8787/ - Enter the username:
rstudioand password:yourpassword - You should see a R Studio interface with all the packages etc. pre-installed and ready to go.
You can close this localhost window (and then come back to it) but if you close the container from Docker (turn off your computer etc.) any changes will be lost unless you push them to Github or exported to your local environment.
Then follow the instructions for Getting the Code above (2. Get the Code).