NEON Forecast Challenge Workshop Pre-Workshop Instructions

This is a repository for materials for submitting forecasts to the NEON Ecological Forecasting Challenge at EFI 2024.

This EFI 2024 workshop is based on materials developed by Freya Olsson (see original and complete materials here).

The materials are split into two sections:

workshop - materials for participating in the EFI2024 NEON Forecasting Challenge workshop. Within this are three subdirectories that cover the Challenge from different perspectives:

submitter: want to get started with making and submitting forecasts to the Challenge?

organizer: interested in learning about the cyberinfrastructure underpinning the Challenge?

synthesizer: aspire to improve understanding of ecological predictability across variables and temporal and spatial scales?

your_forecast_code - you've worked through the workshop materials and are ready to start making your own forecast model and learn about automating your forecast to submit a new forecast every day.

Below are some pre-workshop instructions to make sure you are ready to go!

Any questions, email freyao@vt.edu before the workshop!

1. Setting up your R environment

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 visualization 

install.packages('arrow') #see note below

remotes::install_github('eco4cast/neon4cast') # package from neon4cast challenge organizers to assist with forecast building and submission

Note: If you have issues installing the “arrow” package on Mac M1/2/3 chips use the following instructions: eco4cast/neon4cast#16 (comment)

2. Get the code

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.

Find the fork button in the top left of the webpage --> Create Fork.
Then 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-Challenge-EFI2024.Rproj file 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 documents within each directory contained in the workshop directory.

Optional: Use Docker

Another option to running the materials locally is to use a Docker container that has all the packages pre-installed.

Installing Docker

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)

Running a docker container

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 run the container with the name eco4cast/rocker-neon4cast that has all the packages and libraries installed already. The PASSWORD=yourpassword sets a simple password that you will use to open the container. The -ti option 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: rstudio and 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.