An Introduction to {mqor}

library(mqor)

Overview

The mqor package implements the methodology contained in “Ambient Air — Definition and use of modelling quality objectives for air quality assessment”. This ‘getting started’ guide provides a basic overview of using mqor for model evaluation.

The below flowchart shows how data moves through mqor.

Users can provide data from one of three sources:

1. Input files expected by the DELTA tool. For the monitoring and measurement data, this can either be a CDF or a directory of delimited files. The startup.ini is also additionally required, formatted as expected by the DELTA tool. No other DELTA config files are required.

2. An alternative “simplified” data format, originally developed alongside mqor during its inception project.

3. Any kind of R object which the user can coerce into a data.frame (or tibble). It is up to the user to ensure that this data is in an appropriate.

mqor provides two ‘dummy’ datasets - demo_longterm and demo_shorterm - which can be used as templates for user-provided data.

# long term data (one obs/mod per site)
head(demo_longterm)
#> # A tibble: 6 × 6
#>   site  type  param  date   obs   mod
#>   <chr> <chr> <chr> <dbl> <dbl> <dbl>
#> 1 S1    fixed PM10   2025  34.4  42.6
#> 2 S2    fixed PM10   2025  44.4  48.6
#> 3 S3    fixed PM10   2025  53.6  59.6
#> 4 S4    fixed PM10   2025  44.8  44.8
#> 5 S5    fixed PM10   2025  16.2  13.2
#> 6 S6    fixed PM10   2025  40.2  36.2

# short term data (multiple obs/mod per site)
head(demo_shortterm, n = 10)
#> # A tibble: 10 × 6
#>    site  type  param date         obs   mod
#>    <chr> <chr> <chr> <date>     <dbl> <dbl>
#>  1 S1    fixed PM10  2025-01-01    24    48
#>  2 S1    fixed PM10  2025-01-02    35    47
#>  3 S1    fixed PM10  2025-01-03    44    39
#>  4 S1    fixed PM10  2025-01-04    38    37
#>  5 S1    fixed PM10  2025-01-05    31    42
#>  6 S2    fixed PM10  2025-01-01    37    36
#>  7 S2    fixed PM10  2025-01-02    45    49
#>  8 S2    fixed PM10  2025-01-03    53    61
#>  9 S2    fixed PM10  2025-01-04    49    53
#> 10 S2    fixed PM10  2025-01-05    38    44

The values contained within these tables are tabulated below in a more web-accessible format:

Long term demo data.

stat	S1	S2	S3	S4	S5	S6	S7	S8	S9	S10	S11	S12	S13	S14	S15
obs	34.4	44.4	53.6	44.8	16.2	40.2	37.8	40.6	27.4	21.6	15.0	47.8	42.2	36.4	31
mod	42.6	48.6	59.6	44.8	13.2	36.2	43.4	38.8	28.8	19.8	24.6	37.4	50.8	45.6	35

Short term demo data.

stat	time	S1	S2	S3	S4	S5	S6	S7	S8	S9	S10	S11	S12	S13	S14	S15
mod	1	48	36	50	23	21	30	34	30	0	13	12	37	48	50	37
mod	2	47	49	61	42	21	36	56	47	80	36	27	24	59	40	37
mod	3	39	61	70	50	12	43	47	52	21	22	34	47	49	48	37
mod	4	37	53	66	59	4	39	42	36	24	17	32	44	36	55	17
mod	5	42	44	51	50	8	33	38	29	19	11	18	35	62	35	47
obs	1	24	37	37	50	12	33	31	18	22	12	15	46	46	38	33
obs	2	35	45	51	51	16	50	44	80	40	24	5	54	38	38	28
obs	3	44	53	57	44	21	43	48	35	29	29	22	46	44	38	33
obs	4	38	49	65	38	18	39	36	37	25	27	20	36	49	22	40
obs	5	31	38	58	41	14	36	30	33	21	16	13	57	34	46	21

These data are useful to use to demonstrate package functionality, as they eliminate the need to import any external datasets into R.

Regardless of how data is imported into R, a user will likely then calculate a statistics set using summarise_mqo_stats(). This will return all relevant model quality objective statistics for the input data. From that point, users can examine this data further directly, or use a handful of plotting functions to helpfully visualise the results.

demo_shortterm |>
  summarise_mqo_stats(pollutant = "PM10") |>
  plot_mqi_bars()
#> ! term assumed to be 'short'.
#> ℹ If this is incorrect, please specify the data's term using the term argument.

Other articles in this package describe much of the package functionality in more detail.