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.
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.
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 ofreticulate.
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")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]"
)
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.
Maintained by Giuseppe Carlino (Simularia srl).