Overview

simulariatools is an open-source R package developed by Simularia, an environmental consulting firm specialized in atmospheric dispersion modelling.

It provides a collection of functions to pre- and post-process meteorological and air quality data in the context of air quality and odour dispersion modelling.

It is used daily in real-world applications, improving reproducibility, saving time and reducing errors.

Key functions

• contourPlot2() plots a production-ready contour map of a pollutant concentration field.
• plotAvgRad() plots the hourly average of solar radiation.
• plotAvgTemp() plots the average atmospheric temperature.
• plotStabilityClass() plots histograms of atmospheric stability class.
• vectorField() plots a simple vector field given two components.
• importRaster() imports a generic raster file.
• importADSOBIN() imports an ADSO/BIN raster file.
• importSurferGrd() imports a grid file (CALPUFF).
• stabilityClass() computes atmospheric stability class.
• turnerStabilityClass() computes atmospheric PGT stability class with Turner method.
• downloadBasemap() downloads GeoTIFF basemaps from the Italian PCN.
• removeOutliers() removes time series outliers based on interquartile range.
• rollingMax() computes rolling max of a time series.

Installation

To install the latest release of simulariatools from CRAN:

install.packages("simulariatools")

NOTE: To import ADSO/BIN data files via importADSOBIN(), a working installation of Python3 is required. For more information about R and Python interoperability, please refer to the documentation of reticulate.

Development version

To get bug fixes or to use a feature from the development version, install the development version from GitHub:

# install.packages("pak")
pak::pkg_install("Simularia/simulariatools")

Examples

Contour Plot from NetCDF

First, import air quality data from NetCDF file with the appropriate convenience function:

library(simulariatools)
nox_concentration <- importRaster(
    file = "./development/conc_avg.nc",
    k = 1000,
    destaggering = TRUE,
    variable = "nox",
    verbose = TRUE
)
#> Raster statistics -----------------------------------------------
#>        X (min, max, dx)  :   496000.000   519250.000      250.000
#>        Y (min, max, dy)  :  4943000.000  4955250.000      250.000
#>      nox (min, max, mean):     0.00e+00     2.71e+00     1.52e-01
#> -----------------------------------------------------------------

Concentration data are imported as a data.frame with x and y columns corresponding to the coordinates of the cell centre and a z column for grid values.

str(nox_concentration)
#> 'data.frame':    4557 obs. of  3 variables:
#>  $ x: num  496125 496375 496625 496875 497125 ...
#>  $ y: num  4955125 4955125 4955125 4955125 4955125 ...
#>  $ z: num  0 0 0 0 0 0 0 0 0 0 ...

A quick contour plot, with default configuration, can be easily obtained by running contourPlot2() without any optional argument:

contourPlot2(nox_concentration)

The plot is customisable by using contourPlot2() arguments and by piping ggplot2 instructions together with the + operator.

In the following example, the original domain is cropped, colour levels are explicitly assigned and a legend name is provided through function arguments. Furthermore, labs() and theme_minimal() functions from ggplot2 are used to remove axis labels and to change the overall theme:

library(ggplot2)
contourPlot2(
    nox_concentration,
    xlim = c(502000, 519000),
    ylim = c(4943125, 4955125),
    nticks = 5,
    levels = c(-Inf, 0.5, 1, 1.5, 2, Inf),
    legend = "NOx [ug/m3]"
) +
    labs(x = NULL, y = NULL) +
    theme_minimal()

In order to save the last plot to file, you can directly use the ggplot2 function ggsave():

ggsave(filename = "~/path/to/myplot.png", width = 7, height = 6, dpi = 300)

Optional arguments can be used to create special versions of the plot. For example, use tile = TRUE to produce a plot without spatial interpolation:

contourPlot2(
    nox_concentration,
    tile = TRUE,
    legend = "NOx [ug/m3]"
)

Citation

If you use simulariatools in your work, please consider citing it:

Giuseppe Carlino. (2026). Simularia/simulariatools: simulariatools 3.1.0 (v3.1.0). Zenodo. https://doi.org/10.5281/zenodo.18184316.

Contact

Maintained by Giuseppe Carlino (Simularia srl).

Contributors

Matteo Paolo Costa