sbooscripts

Multimedia mass balance model simulating environmental fate of substances in air, soil, water and sediment compartments

https://github.com/rivm-syso/sbooscripts

Repository

Multimedia mass balance model simulating environmental fate of substances in air, soil, water and sediment compartments

README.Rmd

---
title: "SimpleBox data and scripts"
author: "RIVM"
date: "`r Sys.Date()`"
output: github_document
editor_options: 
  chunk_output_type: console
---

# 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](https://www.rivm.nl/SimpleBox "More info on SimpleBox") and in the [model quality and transparency document.](vignettes/Development/QualityDocumentation.md)

# 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](https://github.com/rivm-syso/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](https://github.com/rivm-syso/SBoo) repository and save it in your parent folder

3.  Download the [SBooScripts](https://github.com/rivm-syso/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](vignettes/Getting-started.md) 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](vignettes/Getting-started.Rmd) : 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](vignettes/10.0-Solver-use.md) : 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](vignettes/Getting-started.md) and [Solver use](vignettes/10.0-Solver-use.md) vignettes.
Consequently it is recommended to follow the [Basics for developers](vignettes/Development/BasicsOfDevelopment.md) 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](/vignettes/Development/start.md) 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](/vignettes/Development/CSVdata.Rmd), [creating variables](vignettes/Development/FirstVars.Rmd), [creating and checking flows](/vignettes/Development/AirFlow.Rmd), [creating processes](vignettes/Development/processFlow.Rmd) and [testing new variables](/vignettes/Development/testRainDropRadius.Rmd).
- The vignette folder outlines the theoretical implementation of the SimpleBox model, following the structure of Chapter 3 in [Schoorl et al. (2015)](https://www.rivm.nl/bibliotheek/rapporten/2015-0161.html)

# 4. Contact information

Issues can be submitted through GitHub.

RIVM leads the development of SimpleBox.

Contact: simplebox\@rivm.nl

# 5. License

EUROPEAN UNION PUBLIC LICENCE v. 1.2

Owner

Citation (CITATION.cff)

cff-version: 1.2.0
title: 'SimpleBox object oriented - Scripts, Data and Documentation repository'
message: >-
  If you use this software, please cite it using the
  metadata from this file.
type: software
authors:
  - name: RIVM
    address: P.O. Box 1
    city: Bilthoven
    country: NL
    post-code: 3720 BA
    website: 'https://www.rivm.nl/SimpleBox/'
contact:
  - email: simplebox@rivm.nl
    name: "National Institute for Public Health and the Environment"
repository-code: 'https://github.com/rivm-syso/SBooScripts'
url: 'https://www.rivm.nl/en/soil-and-water/simplebox'
repository-artifact: 'https://github.com/rivm-syso/SimpleBox'
abstract: SimpleBox is a multimedia mass balance model of the so-called ‘Mackay type’. It simulates environmental fate of chemicals as fluxes (mass flows) between a series of well-mixed boxes of air, water, sediment and soil on regional, continental and global spatial scales. 
keywords:
  - RIVM
  - environmental fate
  - fate model
  - soil
  - air
  - water 
  - sediment 
  - concentration
license: EUPL-1.2
version: 2024.11.0

GitHub Events

Issues and Pull Requests

Last synced: 8 months ago