SimpleBox data and scripts

RIVM 2025-03-31

1. About SimpleBox

SimpleBox is a multimedia mass balance model of the so-called ‘Mackay type’ (also called “box models”). It simulates environmental fate of chemicals, nanomaterials and plastics as fluxes (mass flows) between a series of well-mixed boxes of air, water, sediment and soil on regional, continental and global spatial scales. SimpleBox was first developed in 1986 and since then has seen multiple versions. The current version (SimpleBox v5.0) is the first implementation in R. The primary use of SimpleBox is to calculate the expected environmental fate of specific chemicals or particles, given a certain emission into the environment. Donald Mackay classified environmental fate models into four levels. SimpleBox is a level 3 and 4 model, meaning that SimpleBox can calculate concentrations for multiple environmental compartments (e.g. air, soil, water) and multiple scales (regional, continental, global) both at steady-state and dynamically, over time. More information can be found here and in the model quality and transparency document.

2. Repository structure

The SBooScripts repository contains serveral folders:

• baseScripts: this folder contains the base scripts for using SBoo, i.e. scripts that can be used to easily create the central object for SimpleBox and a package that installs all needed requirements

• data: folder that contains the data needed for initializing SBoo

• testScripts: folder that contains scripts used to test specific functions

• vignettes: this folder contains explanatory RMarkdown files on several subjects; how to get started with SBoo, information on how to use the solvers, how to use SBoo for development, information on all process functions, and several case studies.

3. Installation and user guidelines

Installation

SB is split over two repositories. In order to use SBOO you need two projects with the parent folder in common. You can do this as follows:

1. Create a parent folder (you can name it whatever you like)

2. Download the SBoo repository and save it in your parent folder

3. Download the SBooScripts repository and save it in your parent folder

4. When you start using SimpleBox, set your working directory to your SBooScripts folder.

Dependencies

These packages are installed when running the Getting started vignette for the first time.

Guidance for users

If you intend to use the model without changing its functions, read/run the following markdown files to get started:

• Getting Started : this Rmarkdown file includes all basics for users (not necessarily developers) to use SimpleBox. It includes:

  • Installing and loading the needed packages

  • Setup of the model for a substance

  • How to alter a variable

  • How to calculate deterministic steady state output

  • How to plot the outcome.

• Solver use : explains the use of the four different methods for solving with SimpleBox

  • Steady state deterministic solver: calculate steady state masses and concentrations once

  • Steady state probabilistic solver: calculate steady state masses and concentrations n times, while varying emissions and/or variable values per run

  • Dynamic deterministic solver: calculate masses and concentrations over time once

  • Dynamic probabilistic solver: calculate masses and concentrations over time n times, while varying emissions and/or variable values per run

Guidance for developers

If you intend to use the model as well as change its functions, it is still useful to run the Getting started and Solver use vignettes. Consequently it is recommended to follow the Basics for developers vignette, which explains the underlying structure of the repository, including the input data.

The Development folder details the technical construction of the project and is most suitable for developers. The vignette start explains the basics of object-oriented modelling and how this is implemented in this model. Multiple other vignettes are useful if aiming to develop, such as CSV-reordering, creating variables, creating and checking flows, creating processes and testing new variables. - The vignette folder outlines the theoretical implementation of the SimpleBox model, following the structure of Chapter 3 in Schoorl et al. (2015)

4. Contact information

Issues can be submitted through GitHub.

RIVM leads the development of SimpleBox.

Contact: [email protected]

5. License

EUROPEAN UNION PUBLIC LICENCE v. 1.2