A reproducible analysis of environmental data - from hardware to plot!
The analysis can be explored in three ways, all of which offer full transparency and provide an interactive environment to study and adopt code and data.
The following commands build a Docker image from the
Dockerfile and the runs it on your local machine.
Therefore you need Docker.
The steps are roughly what happens when launching this repository in Binder.
docker build --tag sensebinder .
Continue with Local execution.
This workflow relies on several online resources and tools that might disappear or stop working (GitHub, openseSenseMap-API, Docker, ...), but Zenodo is much less likely to vanish.
Download all files from https://doi.org/10.5281/zenodo.1135140 and put them in one directory.
Import the runtime from the compressed tarball (cf. Export runtime).
docker image load --input sensebox-binder.tar.gz
Continue with Local execution.
You have now either build or loaded a Docker image. Now start a Docker container using the image with the following command.
docker run -p 8888:8888 -v $(pwd):/home/rstudio sensebinder
The current directory (
$(pwd) for Ubuntu/Debian; on Windows or Mac please manually put in the local path) is mounted to the container's default working directory (
/home/rstudio) and the Jupyter port (
8888) is exposed to the host computer.
You may leave out the mount, but changes are not persisted to the host machine then.
The output includes a login link to the Jupyter Notebook start page, similar to
http://0.0.0.0:8888/?token=bd3fc8b1176293170965e7ce613f5fbfd7a64733f312c34a but with a different token.
Open this link in your browser and continue with Open analysis.
If you encounter file permission errors, such as
PermissionError: [Errno 13] Permission denied: '/home/rstudio/.local' when starting the container, try to explicitly set the container user ID to the required default user
docker run -it -p 8888:8888 --user=1000 sensebinder
To open the R Markdown document, click on "new" in the top right, and at "RStudio Session" in the pop-up menu.
This will start a new browser tab with an RStudio session.
In the RStudio window, open the file
sensebox-analysis.Rmd from the "Files" tab in the bottom right of the interface.
Now click on the "Knit" button to render the document.
For a quick preview, the HTML output of the R Markdown document is also rendered by Travis CI (see configuration in
.travis.yml) and available at https://nuest.github.io/sensebox-binder/sensebox-analysis.html.
To open the Jupyter Notebook, click on the notebook file
sensebox-analysis.ipynb on the Jupyter start page.
The Jupyter Notebook is automatically updated when rendering the R Markdown document.
Because the host directory is mounted into the container, all changes to the workflows saved in Jupyter or RStudio are persisted to your local disc.
It is strongly recommended to use only the containerised browser version of RStudio, although the R Markdown document could easily be edited with the desktop version, because working in the container ensures a controlled environment.
To install additional packages, use
install.R and re-build the container (see Local execution).
The following steps were used to create the archivable version of the workflow stored on Zenodo (cf. Import runtime).
docker image save sensebinder:latest | gzip -c > sensebox-binder.tar.gz
The created image contains the runtime environment of the workflow (R, Jupyter Notebook, libraries & packages) as well as files from this directory, including the git repository.
- Create a Local build and start a Local execution without mounting the local files
- Make sure the R Markdown document renders correctly with
online <- FALSEin the code chunk
load_box_data, then set
online <- TRUEagain and re-render
- Commit all changes to the git repository
- Add a tag
v1to the current git commit and push the tag to GitHub
- Start a Local execution with mounting the local files to render the R Markdown document to HTML;make sure the hash in the HTML file is the one with the version tag
- Create a Local build (to have the latest commit and tag in the local git repository)
- Export runtime
- Create ZIP file with
zip -1 -r sensebox-binder.zip .git data .dockerignore .gitignore .travis.yml 320px-Fireworks_2.jpg Dockerfile install.R LICENSE README.md sensebox-analysis.* sensebox-binder.Rproj sensebox-binder.tar.gz(fast compression, the tarball is already compressed and the other file sizes are negligible)
- Upload to Zenodo (as a new version), setting the same version tag
This project is licensed under Apache License, Version 2.0, see file LICENSE.