Package 'openairmaps'

a map widget object created from leaflet()

The name of the pollutant to be plot. Note that, if fun = openair::windRose, you must set pollutant = "ws".

An openair directional analysis plotting function. Supported functions include openair::polarPlot() (the default), openair::polarAnnulus(), openair::polarFreq(), openair::percentileRose(), openair::pollutionRose() and openair::windRose(). For openair::polarDiff(), use addPolarDiffMarkers().

The decimal longitude.

The decimal latitude.

the layer id

the name of the group the newly created layers should belong to (for clearGroup() and addLayersControl() purposes). Human-friendly group names are permitted–they need not be short, identifier-style names. Any number of layers and even different types of layers (e.g., markers and polygons) can share the same group name.

A column of data to be used as a popup.

A Vector of popupOptions() to provide popups

A column of data to be used as a label.

A Vector of labelOptions() to provide label options for each label. Default NULL

a list of extra options for tile layers, popups, paths (circles, rectangles, polygons, ...), or other map elements

if not NULL, markers will be clustered using Leaflet.markercluster; you can use markerClusterOptions() to specify marker cluster options

the id for the marker cluster layer

Passed to key.position for the relevant fun.

The diameter of the plot on the map in pixels. This will affect the size of the individual polar markers. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

The diameter of the plots to be produced using openair in inches. This will affect the resolution of the markers on the map. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

The desired opacity of the polar markers. Can also be set via options but is provided here for convenience.

Show a progress bar while the markers are created?

A data frame. The data frame must contain the data to plot your choice of openair directional analysis plot, which includes wind speed (ws), wind direction (wd), and the column representing the concentration of a pollutant. In addition, data must include a decimal latitude and longitude. By default, it is the data object provided to leaflet::leaflet() initially, but can be overridden.

Other arguments for the plotting function (e.g. period for openair::polarAnnulus()).

A data frame that represents the before/after case. See openair::polarPlot() for details of different input requirements. By default, both before and after are the data object provided to leaflet::leaflet() initially, but at least one should be overridden.

a map widget object created from leaflet::leaflet().

Data frame, the result of importing a trajectory file using openair::importTraj(). By default, it is the data object provided to leaflet::leaflet() initially, but can be overridden.

The decimal longitude.

The decimal latitude.

The pollutant of interest. Not required when statistic = "frequency".

One of:

• "frequency" (the default) shows trajectory frequencies.

• "hexbin", which is similar to "frequency" but shows a hexagonal grid of counts.

• "difference" - in this case trajectories where the associated concentration is greater than percentile are compared with the the full set of trajectories to understand the differences in frequencies of the origin of air masses. The comparison is made by comparing the percentage change in gridded frequencies. For example, such a plot could show that the top 10\ to the east.

• "pscf" for a Potential Source Contribution Function map. This statistic method interacts with percentile.

• "cwt" for concentration weighted trajectories.

• "sqtba" to undertake Simplified Quantitative Transport Bias Analysis. This statistic method interacts with .combine and sigma.

The percentile concentration of pollutant against which the all trajectories are compared.

The longitude and latitude intervals to be used for binning data. If statistic = "hexbin", the minimum value out of of lon.inc and lat.inc is passed to the binwidth argument of ggplot2::geom_hex().

breaks bins a continuous axis into discrete bins. It can either take a single number (e.g., breaks = 5) to split the scale into quantiles, a vector of numbers (e.g., ⁠breaks = c(0, 50, 100, 200, 500⁠) to define specific break-points, or a named list. See breakOpts() for more details. Note that, in trajLevel(), each statistic provides a different default break strategy; to override those that bin the limits by default (e.g., "frequency"), pass breaks = NULL explicitly.

The minimum number of unique points in a grid cell. Counts below min.bin are set as missing.

When statistic is "SQTBA" it is possible to combine lots of receptor locations to derive a single map. .combine identifies the column that differentiates different sites (commonly a column named "site"). Note that individual site maps are normalised first by dividing by their mean value.

For the SQTBA approach sigma determines the amount of back trajectory spread based on the Gaussian plume equation. Values in the literature suggest 5.4 km after one hour. However, testing suggests lower values reveal source regions more effectively while not introducing too much noise.

Should the trajectory surface be smoothed? Defaults to FALSE. Note that, when smooth = TRUE, no popup information will be available.

Optionally, a method to condition the data, passed to openair::cutData(). Each level of type is added to the map as its own group (sharing a single colour scale), so can be toggled between using leaflet::addLayersControl(). If type is provided, group is ignored.

The colours used for plotting, passed to openair::openColours(). The default, "turbo", is a rainbow palette with relatively perceptually uniform colours.

Opacity of the tiles. Must be between 0 and 1.

Colour to use for the border of binned tiles. Defaults to NA, which draws no border.

The base string for the layer id. The actual layer IDs will be in the format "layerId-tilenum". For example, the first tile will be "layerId-1".

the name of the group the newly created layers should belong to (for leaflet::clearGroup() and leaflet::addLayersControl() purposes). Human-friendly group names are permitted–they need not be short, identifier-style names. Any number of layers and even different types of layers (e.g. markers and polygons) can share the same group name.

Should a legend be added to the map? Defaults to TRUE. When type is not used, the legend is given the same group as the tiles, so it is shown and hidden alongside them.

Where should the legend be placed? One of "topright", "topleft", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLegend().

Title of the legend. By default, when legend.title = NULL, the function will attempt to provide a sensible legend title based on statistic. legend.title allows users to overwrite this - for example, to include units or other contextual information. Users may wish to use HTML tags to format the title.

When legend.title.autotext = TRUE, legend.title will be first run through quickTextHTML().

Other arguments to pass to leaflet::addRectangles(). These will override any defaults set by addTrajLevel() (e.g., weight).

a map widget object created from leaflet::leaflet().

The decimal longitude.

The decimal latitude.

The base string for the layer id. The actual layer IDs will be in the format "layerId-linenum" for lines and "layerId_linenum-pointnum" for points. For example, the first point of the first trajectory path will be "layerId-1-1".

the name of the group the newly created layers should belong to (for leaflet::clearGroup() and leaflet::addLayersControl() purposes). Human-friendly group names are permitted–they need not be short, identifier-style names. Any number of layers and even different types of layers (e.g. markers and polygons) can share the same group name.

Data frame, the result of importing a trajectory file using openair::importTraj(). By default, it is the data object provided to leaflet::leaflet() initially, but can be overridden.

A dot is placed every npoints along each full trajectory. For hourly back trajectories points are plotted every npoints hours. This helps to understand where the air masses were at particular times and get a feel for the speed of the air (points closer together correspond to slower moving air masses). Defaults to 12.

An optional colour (or vector of colours, one per row of data) to use for the point markers, overriding whatever color is passed via .... Unlike color/fillColor, this is permitted to vary per point - useful for colouring the markers along a single trajectory by a continuous variable (e.g. a pollutant) while keeping the trajectory line itself a single colour, as required by leaflet::addPolylines().

Other arguments o pass to both leaflet::addCircleMarkers() and leaflet::addPolylines(). If you use the color argument, it is important to ensure the vector you supply is of length one to avoid issues with leaflet::addPolylines() (i.e., use color = ~ pal(nox)[1]), unless you use markerColor to separately control the colour of the point markers. Note that opacity controls the opacity of the lines and fillOpacity the opacity of the markers.

Input data table with pollutant, wind, and geo-spatial information.

required | scope: dynamic & static

A data frame. The data frame must contain the data to plot the directional analysis marker, which includes wind speed (ws), wind direction (wd), and the column representing the concentration of a pollutant. In addition, data must include a decimal latitude and longitude (or X/Y coordinate used in conjunction with crs).

Pollutant name(s).

required | scope: dynamic & static

The column name(s) of the pollutant(s) to plot. If multiple pollutants are specified and a non-pairwise statistic is supplied, the type argument will no longer be able to be used and:

• Dynamic: The pollutants can be toggled between using a "layer control" menu.

• Static: The pollutants will each appear in a different panel.

Multiple pollutants prohibit the use of the type argument for non-pairwise statistics.

Temporal period for radial axis.

default: "hour" | scope: dynamic & static

Options are "hour" (the default, to plot diurnal variations), "season" to plot variation throughout the year, "weekday" to plot day of the week variation and "trend" to plot the trend by wind direction.

Specifier for the plot colour scale bounds.

default: "free" | scope: dynamic & static

One of:

• "fixed" which ensures all of the markers use the same colour scale.

• "free" (the default) which allows all of the markers to use different colour scales.

• A numeric vector in the form c(lower, upper) used to define the colour scale. For example, limits = c(0, 100) would force the plot limits to span 0-100.

limits is ignored if breaks is also provided.

Specifier for a binned colour scale.

default: NULL | scope: dynamic & static

By default, markers use a continuous colour scale (see limits). If breaks is provided, the colour scale is instead binned into discrete intervals. One of:

• A numeric vector of breakpoints. For example, breaks = c(0, 50, 100, 1000) would bin the colour scale into three intervals.

• A single number, which is the number of intervals to bin the colour scale into.

• A list created using openair::breakOpts(), which provides finer control over the binning method and allows custom labels to be defined.

In all cases, a single set of breakpoints is calculated across all of the markers, so that they share the same intervals and a shared legend can be drawn. If any of the markers' data fall outside of the given breakpoints, the lowest and/or highest breakpoints are extended to cover them. If breaks is provided, limits is ignored.

The decimal latitude(Y)/longitude(X).

default: NULL | scope: dynamic & static

Column names representing the decimal latitude and longitude (or other Y/X coordinate if using a different crs). If not provided, will be automatically inferred from data by looking for a column named "lat"/"latitude" or "lon"/"lng"/"long"/"longitude" (case-insensitively).

The coordinate reference system (CRS).

default: 4326 | scope: dynamic & static

The coordinate reference system (CRS) of the data, passed to sf::st_crs(). By default this is EPSG:4326, the CRS associated with the commonly used latitude and longitude coordinates. Different coordinate systems can be specified using crs (e.g., crs = 27700 for the British National Grid). Note that non-lat/lng coordinate systems will be re-projected to EPSG:4326 for plotting on the map.

A method to condition the data for separate plotting.

default: NULL | scope: dynamic & static

Used for splitting the input data into different groups, passed to the type argument of openair::cutData(). When type is specified:

• Dynamic: The different data splits can be toggled between using a "layer control" menu.

• Static: The data splits will each appear in a different panel.

type cannot be used if multiple pollutant columns have been provided.

Content for marker popups on dynamic maps.

default: NULL | scope: dynamic

Columns to be used as the HTML content for marker popups on dynamic maps. Popups may be useful to show information about the individual sites (e.g., site names, codes, types, etc.). If a vector of column names are provided they are passed to buildPopup() using its default values.

Numeric columns (e.g., pollutant concentrations) have many values at each marker, so are averaged and labelled as such (e.g., "NO₂ (mean)"). Names given to popup (e.g., c("Mean NOx" = "nox")) are used instead of these labels.

Content for marker hover-over on dynamic maps.

default: NULL | scope: dynamic

Column to be used as the HTML content for hover-over labels. Labels are useful for the same reasons as popups, though are typically shorter. As with popup, numeric columns are averaged at each marker.

The basemap(s) to be used.

default: "OpenStreetMap" | scope: dynamic & static

The base map(s) to be used for the map. If not provided, will default to "OpenStreetMap"/"osm" for both dynamic and static maps.

• Dynamic: Any number of leaflet::providers. See http://leaflet-extras.github.io/leaflet-providers/preview/ for a list of all base maps that can be used. If multiple base maps are provided, they can be toggled between using a "layer control" interface. By default, the interface will use the provider names as labels, but users can define their own using a named vector (e.g., c("Default" = "OpenStreetMap", "Satellite" = "Esri.WorldImagery"))

• Static: One of the options listed in rosm::osm.types() (for example, "osm", "cartodark", "cartolight", etc.).

There is some overlap in static and dynamic providers. For example, {ggspatial} uses "osm" to specify "OpenStreetMap". When static providers are provided to dynamic maps or vice versa, {openairmaps} will attempt to substitute the correct provider string.

Colours to use for plotting.

default: "turbo" | scope: dynamic & static

The colours used for plotting, passed to openair::openColours(). The default, "turbo", is a rainbow palette with relatively perceptually uniform colours.

Transparency value for polar markers.

default: 1 | scope: dynamic & static

A value between 0 (fully transparent) and 1 (fully opaque).

Custom ggplot2 theme for the polar markers.

default: "default" | scope: dynamic & static

A custom ggplot2 theme to add to the polar markers. This should ideally be a partial theme (i.e., ggplot2::theme()) over a complete theme (e.g., ggplot2::theme_bw()) as other arguments like key interact with the plot theme before custom themes are set, so would be overridden by a complete theme.

Legend position for individual marker legends.

default: "none" | scope: dynamic & static

When key.position is not "none", a key will be drawn for each individual marker. Potentially useful when limits = "free", but of limited use otherwise.

Draw a shared legend?

default: TRUE | scope: dynamic & static

When all markers share the same colour scale, should a shared legend be created at the side of the map? This is the case for:

• Continuous colour scales, when all markers share the same limits (e.g., when limits != "free" in polarMap()), which are shown as a colour bar. This legend is not drawn if the colour scale has been transformed using trans (e.g., trans = "log10"), as it would be misleading.

• Discrete colour scales, when all markers are binned into the same intervals (e.g., when breaks are passed to polarMap(), or in windroseMap()), which are shown as a set of labelled colours.

Position of the shared legend.

default: NULL | scope: dynamic & static

When legend = TRUE, where should the legend be placed?

• Dynamic: One of "topright", "topleft", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLegend().

• Static: One of "top", "right", "bottom" or "left". Passed to the legend.position argument of ggplot2::theme().

Title of the legend.

default: NULL | scope: dynamic & static

By default, when legend.title = NULL, the function will attempt to provide a sensible legend title. legend.title allows users to overwrite this - for example, to include units or other contextual information. For dynamic maps, users may wish to use HTML tags to format the title.

Automatically format the title of the legend?

default: TRUE | scope: dynamic & static

When legend.title.autotext = TRUE, legend.title will be first run through quickTextHTML() (dynamic) or openair::quickText() (static).

Show the layer control as a collapsed?

default: FALSE | scope: dynamic

For dynamic maps, should the "layer control" interface be collapsed? If TRUE, users will have to hover over an icon to view the options.

Position of the layer control menu

default: "topright" | scope: dynamic

When type != NULL, or multiple pollutants are specified, where should the "layer control" interface be placed? One of "topleft", "topright", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLayersControl().

Automatically format the content of the layer control menu?

default: TRUE | scope: dynamic

When control.autotext = TRUE, the content of the "layer control" interface will be first run through quickTextHTML().

The diameter of the plot on the map in pixels.

default: 200 | scope: dynamic & static

This will affect the size of the individual polar markers. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

The diameter of the plots to be produced using {openair} in inches.

default: 3.5 | scope: dynamic & static

This will affect the resolution of the markers on the map. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

Produce a static map?

default: FALSE

This controls whether a dynamic or static map is produced. The former is the default and is broadly more useful, but the latter may be preferable for DOCX or PDF outputs (e.g., academic papers).

Number of rows in a static map.

default: NULL | scope: static

Controls the number of rows of panels on a static map when multiple pollutants or type are specified; passed to the nrow argument of ggplot2::facet_wrap(). The default, NULL, results in a roughly square grid of panels.

API key for certain 'static' base map providers.

default: NULL | scope: static

Passed to the api_key argument of ggspatial::annotation_map_tile(). Needed for certain providers (e.g., "cartolight").

Show a progress bar?

default: TRUE | scope: dynamic & static

By default, a progress bar is shown to visualise the function's progress creating individual polar markers. This option allows this to be turned off, if desired.

Arguments passed on to openair::polarAnnulus

mydata

A data frame minimally containing date, a wind direction and a pollutant.

wd

The name of the column in mydata representing the decimal wind direction, 0 to 360 where 0/360 are North and 180 is South. Defaults to "wd".

resolution

Two plot resolutions can be set: “normal” and “fine” (the default).

local.tz

Should the results be calculated in local time that includes a treatment of daylight savings time (DST)? The default is not to consider DST issues, provided the data were imported without a DST offset. Emissions activity tends to occur at local time e.g. rush hour is at 8 am every day. When the clocks go forward in spring, the emissions are effectively released into the atmosphere typically 1 hour earlier during the summertime i.e. when DST applies. When plotting diurnal profiles, this has the effect of “smearing-out” the concentrations. Sometimes, a useful approach is to express time as local time. This correction tends to produce better-defined diurnal profiles of concentration (or other variables) and allows a better comparison to be made with emissions/activity data. If set to FALSE then GMT is used. Examples of usage include local.tz = "Europe/London", local.tz = "America/New_York". See cutData and import for more details.

statistic

The statistic that should be applied to each wind speed/direction bin. Can be “mean” (default), “median”, “max” (maximum), “frequency”. “stdev” (standard deviation), “weighted.mean” or “cpf” (Conditional Probability Function). Because of the smoothing involved, the colour scale for some of these statistics is only to provide an indication of overall pattern and should not be interpreted in concentration units e.g. for statistic = "weighted.mean" where the bin mean is multiplied by the bin frequency and divided by the total frequency. In many cases using polarFreq will be better. Setting statistic = "weighted.mean" can be useful because it provides an indication of the concentration * frequency of occurrence and will highlight the wind speed/direction conditions that dominate the overall mean.

percentile

If statistic = "percentile" or statistic = "cpf" then percentile is used, expressed from 0 to 100. Note that the percentile value is calculated in the wind speed, wind direction ‘bins’. For this reason it can also be useful to set min.bin to ensure there are a sufficient number of points available to estimate a percentile. See quantile for more details of how percentiles are calculated.

trans

Should a transformation be applied to the colour scale? If the distribution of data is skewed, the default scale may be dominated by a few high values, so a log or square-root transform may mean the whole colour scale is better presented on the plot. Can be:

• FALSE, which performs no transform.

• TRUE, which uses an appropriate transform for the plot type (usually "log10").

• A scales 'transform' object (e.g., scales::transform_log10()).

• A character string corresponding to a scales transform function. Useful options include "sqrt", "log10", "log2", "log1p", "pseudo_log" and "reverse".

col.na

Colour to be used to show missing data.

offset

offset controls the size of the 'hole' in the middle and is expressed on a scale of 0 to 100, where 0 is no hole and 100 is a hole that takes up the entire plotting area.

angle.scale

In radial plots (e.g., polarPlot()), the radial scale is drawn directly on the plot itself. While suitable defaults have been chosen, sometimes the placement of the scale may interfere with an interesting feature. angle.scale can take any value between 0 and 360 to place the scale at a different angle, or FALSE to move it to the side of the plots.

min.bin

The minimum number of points allowed in a wind speed/wind direction bin. The default is 1. A value of two requires at least 2 valid records in each bin an so on; bins with less than 2 valid records are set to NA. Care should be taken when using a value > 1 because of the risk of removing real data points. It is recommended to consider your data with care. Also, the polarFreq function can be of use in such circumstances.

exclude.missing

Setting this option to TRUE (the default) removes points from the plot that are too far from the original data. The smoothing routines will produce predictions at points where no data exist i.e. they predict. By removing the points too far from the original data produces a plot where it is clear where the original data lie. If set to FALSE missing data will be interpolated.

date.pad

For type = "trend" (default), date.pad = TRUE will pad-out missing data to the beginning of the first year and the end of the last year. The purpose is to ensure that the trend plot begins and ends at the beginning or end of year.

force.positive

The default is TRUE. Sometimes if smoothing data with steep gradients it is possible for predicted values to be negative. force.positive = TRUE ensures that predictions remain positive. This is useful for several reasons. First, with lots of missing data more interpolation is needed and this can result in artefacts because the predictions are too far from the original data. Second, if it is known beforehand that the data are all positive, then this option carries that assumption through to the prediction. The only likely time where setting force.positive = FALSE would be if background concentrations were first subtracted resulting in data that is legitimately negative. For the vast majority of situations it is expected that the user will not need to alter the default option.

k

The smoothing value supplied to gam for the temporal and wind direction components, respectively. In some cases e.g. a trend plot with less than 1-year of data the smoothing with the default values may become too noisy and affected more by outliers. Choosing a lower value of k (say 10) may help produce a better plot.

normalise

If TRUE concentrations are normalised by dividing by their mean value. This is done after fitting the smooth surface. This option is particularly useful if one is interested in the patterns of concentrations for several pollutants on different scales e.g. NOx and CO. Often useful if more than one pollutant is chosen.

key.title

Used to set the title of the legend. The legend title is passed to quickText() if auto.text = TRUE.

auto.text

Either TRUE (default) or FALSE. If TRUE titles and axis labels will automatically try and format pollutant names and units properly, e.g., by subscripting the "2" in "NO2". Passed to quickText().

plot

When openair plots are created they are automatically printed to the active graphics device. plot = FALSE deactivates this behaviour. This may be useful when the plot data is of more interest, or the plot is required to appear later (e.g., later in a Quarto document, or to be saved to a file).

key

Deprecated; please use key.position. If FALSE, sets key.position to "none".

Removed. Please use type.

Input data table with geo-spatial information.

required

A data frame containing latitude and longitude information that will go on to be used in a function such as polarMap().

A character vector of column names to include in the popup.

required

Summaries of the selected columns will appear in the popup. If a named vector is provided, the names of the vector will be used in place of the raw column names. See the Examples for more information.

The decimal latitude(Y)/longitude(X).

default: NULL | scope: dynamic & static

Column names representing the decimal latitude and longitude (or other Y/X coordinate if using a different crs). If not provided, will be automatically inferred from data by looking for a column named "lat"/"latitude" or "lon"/"lng"/"long"/"longitude" (case-insensitively).

A column to be passed to the type argument of another function.

default: NULL

Column which will be used for the type argument of other mapping functions. This only needs to be used if type is going to be used in polarMap() or another similar function, and you'd expect different values for the different map layers (for example, if you are calculating a mean pollutant concentration).

A function to summarise character, factor and logical columns.

default: function(x) paste(unique(x), collapse = ", ")

The default collapses unique values into a comma-separated list.

A function to summarise numeric columns.

default: function(x) signif(mean(x, na.rm = TRUE), 3)

The default takes the mean to three significant figures. Other numeric summaries may be of interest, such as the maximum, minimum, standard deviation, and so on.

A function to summarise date and date-time columns.

default: function(x) paste(lubridate::floor_date(range(x, na.rm = TRUE), "day"), collapse = " to ")

The default presents the date as a range. Other statistics of interest could be the start or end of the dates.

The name for the new column.

default: "popup"

A character string for the name for the new column to be appended to data.

Not currently used.

A valid UK postcode.

required

A string containing a single valid UK postcode, e.g., "SW1A 1AA".

Data frames representing the "before" and "after" cases. See polarPlot() for details of different input requirements.

Mandatory. A pollutant name corresponding to a variable in a data frame should be supplied e.g. pollutant = "nox". There can also be more than one pollutant specified e.g. pollutant = c("nox", "no2"). The main use of using two or more pollutants is for model evaluation where two species would be expected to have similar concentrations. This saves the user stacking the data and it is possible to work with columns of data directly. A typical use would be pollutant = c("obs", "mod") to compare two columns “obs” (the observations) and “mod” (modelled values). When pair-wise statistics such as Pearson correlation and regression techniques are to be plotted, pollutant takes two elements too. For example, pollutant = c("bc", "pm25") where "bc" is a function of "pm25".

Name of variable to plot against wind direction in polar coordinates, the default is wind speed, “ws”.

Limits for the plot colour scale.

default: "free" | scope: dynamic & static

One of:

• "free" (the default) which allows all of the markers to use different colour scales.

• A numeric vector in the form c(lower, upper) used to define the colour scale. For example, limits = c(-10, 10) would force the plot limits to span -10 to 10. It is recommended to use a symmetrical limit scale (along with a "diverging" colour palette) for effective visualisation.

Note that the "fixed" option is not supported in diffMap().

The decimal latitude(Y)/longitude(X).

default: NULL | scope: dynamic & static

Column names representing the decimal latitude and longitude (or other Y/X coordinate if using a different crs). If not provided, will be automatically inferred from data by looking for a column named "lat"/"latitude" or "lon"/"lng"/"long"/"longitude" (case-insensitively).

The coordinate reference system (CRS).

default: 4326 | scope: dynamic & static

The coordinate reference system (CRS) of the data, passed to sf::st_crs(). By default this is EPSG:4326, the CRS associated with the commonly used latitude and longitude coordinates. Different coordinate systems can be specified using crs (e.g., crs = 27700 for the British National Grid). Note that non-lat/lng coordinate systems will be re-projected to EPSG:4326 for plotting on the map.

Character string(s) defining how data should be split/conditioned before plotting. "default" produces a single panel using the entire dataset. Any other options will split the plot into different panels - a roughly square grid of panels if one type is given, or a 2D matrix of panels if two types are given. type is always passed to cutData(), and can therefore be any of:

• A built-in type defined in cutData() (e.g., "season", "year", "weekday", etc.). For example, type = "season" will split the plot into four panels, one for each season.

• The name of a numeric column in mydata, which will be split into n.levels quantiles (defaulting to 4).

• The name of a character or factor column in mydata, which will be used as-is. Commonly this could be a variable like "site" to ensure data from different monitoring sites are handled and presented separately. It could equally be any arbitrary column created by the user (e.g., whether a nearby possible pollutant source is active or not).

Most openair plotting functions can take two type arguments. If two are given, the first is used for the columns and the second for the rows.

Content for marker popups on dynamic maps.

default: NULL | scope: dynamic

Columns to be used as the HTML content for marker popups on dynamic maps. Popups may be useful to show information about the individual sites (e.g., site names, codes, types, etc.). If a vector of column names are provided they are passed to buildPopup() using its default values.

Numeric columns (e.g., pollutant concentrations) have many values at each marker, so are averaged and labelled as such (e.g., "NO₂ (mean)"). Names given to popup (e.g., c("Mean NOx" = "nox")) are used instead of these labels.

Content for marker hover-over on dynamic maps.

default: NULL | scope: dynamic

Column to be used as the HTML content for hover-over labels. Labels are useful for the same reasons as popups, though are typically shorter. As with popup, numeric columns are averaged at each marker.

The basemap(s) to be used.

default: "OpenStreetMap" | scope: dynamic & static

The base map(s) to be used for the map. If not provided, will default to "OpenStreetMap"/"osm" for both dynamic and static maps.

• Dynamic: Any number of leaflet::providers. See http://leaflet-extras.github.io/leaflet-providers/preview/ for a list of all base maps that can be used. If multiple base maps are provided, they can be toggled between using a "layer control" interface. By default, the interface will use the provider names as labels, but users can define their own using a named vector (e.g., c("Default" = "OpenStreetMap", "Satellite" = "Esri.WorldImagery"))

• Static: One of the options listed in rosm::osm.types() (for example, "osm", "cartodark", "cartolight", etc.).

There is some overlap in static and dynamic providers. For example, {ggspatial} uses "osm" to specify "OpenStreetMap". When static providers are provided to dynamic maps or vice versa, {openairmaps} will attempt to substitute the correct provider string.

Colours to use for plotting.

default: rev(openair::openColours("RdBu", 10)) | scope: dynamic & static

The colours used for plotting, passed to openair::openColours(). It is recommended to use a "diverging" colour palette (along with a symmetrical limit scale) for effective visualisation.

Transparency value for polar markers.

default: 1 | scope: dynamic & static

A value between 0 (fully transparent) and 1 (fully opaque).

Custom ggplot2 theme for the polar markers.

default: "default" | scope: dynamic & static

A custom ggplot2 theme to add to the polar markers. This should ideally be a partial theme (i.e., ggplot2::theme()) over a complete theme (e.g., ggplot2::theme_bw()) as other arguments like key interact with the plot theme before custom themes are set, so would be overridden by a complete theme.

Legend position for individual marker legends.

default: "none" | scope: dynamic & static

When key.position is not "none", a key will be drawn for each individual marker. Potentially useful when limits = "free", but of limited use otherwise.

Draw a shared legend?

default: TRUE | scope: dynamic & static

When all markers share the same colour scale, should a shared legend be created at the side of the map? This is the case for:

• Continuous colour scales, when all markers share the same limits (e.g., when limits != "free" in polarMap()), which are shown as a colour bar. This legend is not drawn if the colour scale has been transformed using trans (e.g., trans = "log10"), as it would be misleading.

• Discrete colour scales, when all markers are binned into the same intervals (e.g., when breaks are passed to polarMap(), or in windroseMap()), which are shown as a set of labelled colours.

Position of the shared legend.

default: NULL | scope: dynamic & static

When legend = TRUE, where should the legend be placed?

• Dynamic: One of "topright", "topleft", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLegend().

• Static: One of "top", "right", "bottom" or "left". Passed to the legend.position argument of ggplot2::theme().

Title of the legend.

default: NULL | scope: dynamic & static

By default, when legend.title = NULL, the function will attempt to provide a sensible legend title. legend.title allows users to overwrite this - for example, to include units or other contextual information. For dynamic maps, users may wish to use HTML tags to format the title.

Automatically format the title of the legend?

default: TRUE | scope: dynamic & static

When legend.title.autotext = TRUE, legend.title will be first run through quickTextHTML() (dynamic) or openair::quickText() (static).

Show the layer control as a collapsed?

default: FALSE | scope: dynamic

For dynamic maps, should the "layer control" interface be collapsed? If TRUE, users will have to hover over an icon to view the options.

Position of the layer control menu

default: "topright" | scope: dynamic

When type != NULL, or multiple pollutants are specified, where should the "layer control" interface be placed? One of "topleft", "topright", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLayersControl().

Automatically format the content of the layer control menu?

default: TRUE | scope: dynamic

When control.autotext = TRUE, the content of the "layer control" interface will be first run through quickTextHTML().

The diameter of the plot on the map in pixels.

default: 200 | scope: dynamic & static

This will affect the size of the individual polar markers. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

The diameter of the plots to be produced using {openair} in inches.

default: 3.5 | scope: dynamic & static

This will affect the resolution of the markers on the map. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

Produce a static map?

default: FALSE

This controls whether a dynamic or static map is produced. The former is the default and is broadly more useful, but the latter may be preferable for DOCX or PDF outputs (e.g., academic papers).

Number of rows in a static map.

default: NULL | scope: static

Controls the number of rows of panels on a static map when multiple pollutants or type are specified; passed to the nrow argument of ggplot2::facet_wrap(). The default, NULL, results in a roughly square grid of panels.

API key for certain 'static' base map providers.

default: NULL | scope: static

Passed to the api_key argument of ggspatial::annotation_map_tile(). Needed for certain providers (e.g., "cartolight").

Show a progress bar?

default: TRUE | scope: dynamic & static

By default, a progress bar is shown to visualise the function's progress creating individual polar markers. This option allows this to be turned off, if desired.

Arguments passed on to openair::polarPlot

mydata

A data frame minimally containing a decimal wind direction, another variable to plot in polar coordinates (the default is a column "ws" — wind speed) and a pollutant. Should also contain date if plots by time period are required.

wd

The name of the column in mydata representing the decimal wind direction, 0 to 360 where 0/360 are North and 180 is South. Defaults to "wd".

statistic

The statistic that should be applied to each wind speed/direction bin. Because of the smoothing involved, the colour scale for some of these statistics is only to provide an indication of overall pattern and should not be interpreted in concentration units e.g. for statistic = "weighted.mean" where the bin mean is multiplied by the bin frequency and divided by the total frequency. In many cases using polarFreq will be better. Setting statistic = "weighted.mean" can be useful because it provides an indication of the concentration * frequency of occurrence and will highlight the wind speed/direction conditions that dominate the overall mean.Can be:

• “mean” (default), “median”, “max” (maximum), “frequency”. “stdev” (standard deviation), “weighted.mean”.

• statistic = "nwr" Implements the Non-parametric Wind Regression approach of Henry et al. (2009) that uses kernel smoothers. The openair implementation is not identical because Gaussian kernels are used for both wind direction and speed. The smoothing is controlled by ws_spread and wd_spread.

• statistic = "cpf" the conditional probability function (CPF) is plotted and a single (usually high) percentile level is supplied. The CPF is defined as CPF = my/ny, where my is the number of samples in the y bin (by default a wind direction, wind speed interval) with mixing ratios greater than the overall percentile concentration, and ny is the total number of samples in the same wind sector (see Ashbaugh et al., 1985). Note that percentile intervals can also be considered; see percentile for details.

• When statistic = "r" or statistic = "Pearson", the Pearson correlation coefficient is calculated for two pollutants. The calculation involves a weighted Pearson correlation coefficient, which is weighted by Gaussian kernels for wind direction an the radial variable (by default wind speed). More weight is assigned to values close to a wind speed-direction interval. Kernel weighting is used to ensure that all data are used rather than relying on the potentially small number of values in a wind speed-direction interval.

• When statistic = "Spearman", the Spearman correlation coefficient is calculated for two pollutants. The calculation involves a weighted Spearman correlation coefficient, which is weighted by Gaussian kernels for wind direction an the radial variable (by default wind speed). More weight is assigned to values close to a wind speed-direction interval. Kernel weighting is used to ensure that all data are used rather than relying on the potentially small number of values in a wind speed-direction interval.

• "robust_slope" is another option for pair-wise statistics and "quantile.slope", which uses quantile regression to estimate the slope for a particular quantile level (see also tau for setting the quantile level).

• "york_slope" is another option for pair-wise statistics which uses the York regression method to estimate the slope. In this method the uncertainties in x and y are used in the determination of the slope. The uncertainties are provided by x_error and y_error — see below.

breaks

breaks bins a continuous axis into discrete bins. It can either take a single number (e.g., breaks = 5) to split the scale into quantiles, a vector of numbers (e.g., ⁠breaks = c(0, 50, 100, 200, 500⁠) to define specific break-points, or a named list. See breakOpts() for more details.

trans

Should a transformation be applied to the colour scale? If the distribution of data is skewed, the default scale may be dominated by a few high values, so a log or square-root transform may mean the whole colour scale is better presented on the plot. Can be:

• FALSE, which performs no transform.

• TRUE, which uses an appropriate transform for the plot type (usually "log10").

• A scales 'transform' object (e.g., scales::transform_log10()).

• A character string corresponding to a scales transform function. Useful options include "sqrt", "log10", "log2", "log1p", "pseudo_log" and "reverse".

exclude.missing

Setting this option to TRUE (the default) removes points from the plot that are too far from the original data. The smoothing routines will produce predictions at points where no data exist i.e. they predict. By removing the points too far from the original data produces a plot where it is clear where the original data lie. If set to FALSE missing data will be interpolated.

uncertainty

Should the uncertainty in the calculated surface be shown? If TRUE three plots are produced on the same scale showing the predicted surface together with the estimated lower and upper uncertainties at the 95% confidence interval. Calculating the uncertainties is useful to understand whether features are real or not. For example, at high wind speeds where there are few data there is greater uncertainty over the predicted values. The uncertainties are calculated using the GAM and weighting is done by the frequency of measurements in each wind speed-direction bin. Note that if uncertainties are calculated then the type is set to "default".

percentile

If statistic = "percentile" then percentile is used, expressed from 0 to 100. Note that the percentile value is calculated in the wind speed, wind direction ‘bins’. For this reason it can also be useful to set min.bin to ensure there are a sufficient number of points available to estimate a percentile. See quantile for more details of how percentiles are calculated.

percentile is also used for the Conditional Probability Function (CPF) plots. percentile can be of length two, in which case the percentile interval is considered for use with CPF. For example, percentile = c(90, 100) will plot the CPF for concentrations between the 90 and 100th percentiles. Percentile intervals can be useful for identifying specific sources. In addition, percentile can also be of length 3. The third value is the ‘trim’ value to be applied. When calculating percentile intervals many can cover very low values where there is no useful information. The trim value ensures that values greater than or equal to the trim * mean value are considered before the percentile intervals are calculated. The effect is to extract more detail from many source signatures. See the manual for examples. Finally, if the trim value is less than zero the percentile range is interpreted as absolute concentration values and subsetting is carried out directly.

weights

At the edges of the plot there may only be a few data points in each wind speed-direction interval, which could in some situations distort the plot if the concentrations are high. weights applies a weighting to reduce their influence. For example and by default if only a single data point exists then the weighting factor is 0.25 and for two points 0.5. To not apply any weighting and use the data as is, use weights = c(1, 1, 1).

An alternative to down-weighting these points they can be removed altogether using min.bin.

min.bin

The minimum number of points allowed in a wind speed/wind direction bin. The default is 1. A value of two requires at least 2 valid records in each bin an so on; bins with less than 2 valid records are set to NA. Care should be taken when using a value > 1 because of the risk of removing real data points. It is recommended to consider your data with care. Also, the polarFreq function can be of use in such circumstances.

col.na

When min.bin is > 1 it can be useful to show where data are removed on the plots. This is done by shading the missing data in col.na. To not highlight missing data when min.bin > 1 choose col.na = "transparent".

upper

This sets the upper limit wind speed to be used. Often there are only a relatively few data points at very high wind speeds and plotting all of them can reduce the useful information in the plot.

angle.scale

In radial plots (e.g., polarPlot()), the radial scale is drawn directly on the plot itself. While suitable defaults have been chosen, sometimes the placement of the scale may interfere with an interesting feature. angle.scale can take any value between 0 and 360 to place the scale at a different angle, or FALSE to move it to the side of the plots.

units

The units shown on the polar axis scale.

force.positive

The default is TRUE. Sometimes if smoothing data with steep gradients it is possible for predicted values to be negative. force.positive = TRUE ensures that predictions remain positive. This is useful for several reasons. First, with lots of missing data more interpolation is needed and this can result in artefacts because the predictions are too far from the original data. Second, if it is known beforehand that the data are all positive, then this option carries that assumption through to the prediction. The only likely time where setting force.positive = FALSE would be if background concentrations were first subtracted resulting in data that is legitimately negative. For the vast majority of situations it is expected that the user will not need to alter the default option.

k

This is the smoothing parameter used by the gam function in package mgcv. Typically, value of around 100 (the default) seems to be suitable and will resolve important features in the plot. The most appropriate choice of k is problem-dependent; but extensive testing of polar plots for many different problems suggests a value of k of about 100 is suitable. Setting k to higher values will not tend to affect the surface predictions by much but will add to the computation time. Lower values of k will increase smoothing. Sometimes with few data to plot polarPlot will fail. Under these circumstances it can be worth lowering the value of k.

normalise

If TRUE concentrations are normalised by dividing by their mean value. This is done after fitting the smooth surface. This option is particularly useful if one is interested in the patterns of concentrations for several pollutants on different scales e.g. NOx and CO. Often useful if more than one pollutant is chosen.

key.title

Used to set the title of the legend. The legend title is passed to quickText() if auto.text = TRUE.

auto.text

Either TRUE (default) or FALSE. If TRUE titles and axis labels will automatically try and format pollutant names and units properly, e.g., by subscripting the "2" in "NO2". Passed to quickText().

ws_spread

The value of sigma used for Gaussian kernel weighting of wind speed when statistic = "nwr" or when correlation and regression statistics are used such as r. Default is 0.5.

wd_spread

The value of sigma used for Gaussian kernel weighting of wind direction when statistic = "nwr" or when correlation and regression statistics are used such as r. Default is 4.

x_error

The x error / uncertainty used when statistic = "york_slope".

y_error

The y error / uncertainty used when statistic = "york_slope".

kernel

Type of kernel used for the weighting procedure for when correlation or regression techniques are used. Only "gaussian" is supported but this may be enhanced in the future.

formula.label

When pair-wise statistics such as regression slopes are calculated and plotted, should a formula label be displayed? formula.label will also determine whether concentration information is printed when statistic = "cpf".

tau

The quantile to be estimated when statistic is set to "quantile.slope". Default is 0.5 which is equal to the median and will be ignored if "quantile.slope" is not used.

plot

When openair plots are created they are automatically printed to the active graphics device. plot = FALSE deactivates this behaviour. This may be useful when the plot data is of more interest, or the plot is required to appear later (e.g., later in a Quarto document, or to be saved to a file).

key

Deprecated; please use key.position. If FALSE, sets key.position to "none".

Removed. Please use type.

Input data table with pollutant, wind, and geo-spatial information.

required | scope: dynamic & static

A data frame. The data frame must contain the data to plot the directional analysis marker, which includes wind speed (ws), wind direction (wd), and the column representing the concentration of a pollutant. In addition, data must include a decimal latitude and longitude (or X/Y coordinate used in conjunction with crs).

Pollutant name(s).

required | scope: dynamic & static

The column name(s) of the pollutant(s) to plot. If multiple pollutants are specified and a non-pairwise statistic is supplied, the type argument will no longer be able to be used and:

• Dynamic: The pollutants can be toggled between using a "layer control" menu.

• Static: The pollutants will each appear in a different panel.

Multiple pollutants prohibit the use of the type argument for non-pairwise statistics.

The statistic that should be applied to each wind speed/direction bin.

default: "mean" | scope: dynamic & static

Can be "frequency", "mean", "median", "max" (maximum), "stdev" (standard deviation) or "weighted.mean". The option "frequency" is the simplest and plots the frequency of wind speed/direction in different bins. The scale therefore shows the counts in each bin. The option "mean" (the default) will plot the mean concentration of a pollutant (see next point) in wind speed/direction bins, and so on. Finally, "weighted.mean" will plot the concentration of a pollutant weighted by wind speed/direction. Each segment therefore provides the percentage overall contribution to the total concentration. Note that for options other than "frequency", it is necessary to also provide the name of a pollutant. See function openair::cutData() for further details.

Specifier for the breaks of the plot colour scale.

default: "free" | scope: dynamic & static

One of:

• "fixed" which ensures all of the markers use the same colour scale.

• "free" (the default) which allows all of the markers to use different colour scales.

• A numeric vector defining a sequence of numbers to use as the breaks. The sequence could represent one with equal spacing, e.g., breaks = seq(0, 100, 10) - a scale from 0-10 in intervals of 10, or a more flexible sequence, e.g., breaks = c(0, 1, 5, 7, 10), which may be useful for some situations.

The decimal latitude(Y)/longitude(X).

default: NULL | scope: dynamic & static

Column names representing the decimal latitude and longitude (or other Y/X coordinate if using a different crs). If not provided, will be automatically inferred from data by looking for a column named "lat"/"latitude" or "lon"/"lng"/"long"/"longitude" (case-insensitively).

The coordinate reference system (CRS).

default: 4326 | scope: dynamic & static

The coordinate reference system (CRS) of the data, passed to sf::st_crs(). By default this is EPSG:4326, the CRS associated with the commonly used latitude and longitude coordinates. Different coordinate systems can be specified using crs (e.g., crs = 27700 for the British National Grid). Note that non-lat/lng coordinate systems will be re-projected to EPSG:4326 for plotting on the map.

A method to condition the data for separate plotting.

default: NULL | scope: dynamic & static

Used for splitting the input data into different groups, passed to the type argument of openair::cutData(). When type is specified:

• Dynamic: The different data splits can be toggled between using a "layer control" menu.

• Static: The data splits will each appear in a different panel.

type cannot be used if multiple pollutant columns have been provided.

Content for marker popups on dynamic maps.

default: NULL | scope: dynamic

Columns to be used as the HTML content for marker popups on dynamic maps. Popups may be useful to show information about the individual sites (e.g., site names, codes, types, etc.). If a vector of column names are provided they are passed to buildPopup() using its default values.

Numeric columns (e.g., pollutant concentrations) have many values at each marker, so are averaged and labelled as such (e.g., "NO₂ (mean)"). Names given to popup (e.g., c("Mean NOx" = "nox")) are used instead of these labels.

Content for marker hover-over on dynamic maps.

default: NULL | scope: dynamic

Column to be used as the HTML content for hover-over labels. Labels are useful for the same reasons as popups, though are typically shorter. As with popup, numeric columns are averaged at each marker.

The basemap(s) to be used.

default: "OpenStreetMap" | scope: dynamic & static

The base map(s) to be used for the map. If not provided, will default to "OpenStreetMap"/"osm" for both dynamic and static maps.

• Dynamic: Any number of leaflet::providers. See http://leaflet-extras.github.io/leaflet-providers/preview/ for a list of all base maps that can be used. If multiple base maps are provided, they can be toggled between using a "layer control" interface. By default, the interface will use the provider names as labels, but users can define their own using a named vector (e.g., c("Default" = "OpenStreetMap", "Satellite" = "Esri.WorldImagery"))

• Static: One of the options listed in rosm::osm.types() (for example, "osm", "cartodark", "cartolight", etc.).

There is some overlap in static and dynamic providers. For example, {ggspatial} uses "osm" to specify "OpenStreetMap". When static providers are provided to dynamic maps or vice versa, {openairmaps} will attempt to substitute the correct provider string.

Colours to use for plotting.

default: "turbo" | scope: dynamic & static

The colours used for plotting, passed to openair::openColours(). The default, "turbo", is a rainbow palette with relatively perceptually uniform colours.

Transparency value for polar markers.

default: 1 | scope: dynamic & static

A value between 0 (fully transparent) and 1 (fully opaque).

Custom ggplot2 theme for the polar markers.

default: "default" | scope: dynamic & static

A custom ggplot2 theme to add to the polar markers. This should ideally be a partial theme (i.e., ggplot2::theme()) over a complete theme (e.g., ggplot2::theme_bw()) as other arguments like key interact with the plot theme before custom themes are set, so would be overridden by a complete theme.

Legend position for individual marker legends.

default: "none" | scope: dynamic & static

When key.position is not "none", a key will be drawn for each individual marker. Potentially useful when limits = "free", but of limited use otherwise.

Draw a shared legend?

default: TRUE | scope: dynamic & static

When all markers share the same colour scale, should a shared legend be created at the side of the map? This is the case for:

• Continuous colour scales, when all markers share the same limits (e.g., when limits != "free" in polarMap()), which are shown as a colour bar. This legend is not drawn if the colour scale has been transformed using trans (e.g., trans = "log10"), as it would be misleading.

• Discrete colour scales, when all markers are binned into the same intervals (e.g., when breaks are passed to polarMap(), or in windroseMap()), which are shown as a set of labelled colours.

Position of the shared legend.

default: NULL | scope: dynamic & static

When legend = TRUE, where should the legend be placed?

• Dynamic: One of "topright", "topleft", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLegend().

• Static: One of "top", "right", "bottom" or "left". Passed to the legend.position argument of ggplot2::theme().

Title of the legend.

default: NULL | scope: dynamic & static

By default, when legend.title = NULL, the function will attempt to provide a sensible legend title. legend.title allows users to overwrite this - for example, to include units or other contextual information. For dynamic maps, users may wish to use HTML tags to format the title.

Automatically format the title of the legend?

default: TRUE | scope: dynamic & static

When legend.title.autotext = TRUE, legend.title will be first run through quickTextHTML() (dynamic) or openair::quickText() (static).

Show the layer control as a collapsed?

default: FALSE | scope: dynamic

For dynamic maps, should the "layer control" interface be collapsed? If TRUE, users will have to hover over an icon to view the options.

Position of the layer control menu

default: "topright" | scope: dynamic

When type != NULL, or multiple pollutants are specified, where should the "layer control" interface be placed? One of "topleft", "topright", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLayersControl().

Automatically format the content of the layer control menu?

default: TRUE | scope: dynamic

When control.autotext = TRUE, the content of the "layer control" interface will be first run through quickTextHTML().

The diameter of the plot on the map in pixels.

default: 200 | scope: dynamic & static

This will affect the size of the individual polar markers. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

The diameter of the plots to be produced using {openair} in inches.

default: 3.5 | scope: dynamic & static

This will affect the resolution of the markers on the map. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

Produce a static map?

default: FALSE

This controls whether a dynamic or static map is produced. The former is the default and is broadly more useful, but the latter may be preferable for DOCX or PDF outputs (e.g., academic papers).

Number of rows in a static map.

default: NULL | scope: static

Controls the number of rows of panels on a static map when multiple pollutants or type are specified; passed to the nrow argument of ggplot2::facet_wrap(). The default, NULL, results in a roughly square grid of panels.

API key for certain 'static' base map providers.

default: NULL | scope: static

Passed to the api_key argument of ggspatial::annotation_map_tile(). Needed for certain providers (e.g., "cartolight").

Show a progress bar?

default: TRUE | scope: dynamic & static

By default, a progress bar is shown to visualise the function's progress creating individual polar markers. This option allows this to be turned off, if desired.

Arguments passed on to openair::polarFreq

mydata

A data frame minimally containing a wind speed, a decimal wind direction, and date.

ws

The name of the column in mydata representing the wind speed. Defaults to "ws".

wd

The name of the column in mydata representing the decimal wind direction, 0 to 360 where 0/360 are North and 180 is South. Defaults to "wd".

ws.int

Wind speed interval assumed. In some cases e.g. a low met mast, an interval of 0.5 may be more appropriate.

wd.nint

Number of intervals of wind direction.

grid.line

Radial spacing of grid lines.

limits

The limits of the colour scale, in the form c(lower, upper). For example, limits = c(0, 100) will set the colour scale to be between 0 and 100. Values greater than 100 will be coloured as if they were 100, and those lower than 0 will be coloured as if they were 0. limits can be wider than the range of the data, which can be useful for ensuring multiple plots share the same colour scale.

trans

Should a transformation be applied to the colour scale? If the distribution of data is skewed, the default scale may be dominated by a few high values, so a log or square-root transform may mean the whole colour scale is better presented on the plot. Can be:

• FALSE, which performs no transform.

• TRUE, which uses an appropriate transform for the plot type (usually "log10").

• A scales 'transform' object (e.g., scales::transform_log10()).

• A character string corresponding to a scales transform function. Useful options include "sqrt", "log10", "log2", "log1p", "pseudo_log" and "reverse".

min.bin

The minimum number of points allowed in a wind speed/wind direction bin. The default is 1. A value of two requires at least 2 valid records in each bin an so on; bins with less than 2 valid records are set to NA. Care should be taken when using a value > 1 because of the risk of removing real data points. It is recommended to consider your data with care. Also, the polarFreq function can be of use in such circumstances.

ws.upper

A user-defined upper wind speed to use. This is useful for ensuring a consistent scale between different plots. For example, to always ensure that wind speeds are displayed between 1-10, set ws.int = 10.

angle.scale

In radial plots (e.g., polarPlot()), the radial scale is drawn directly on the plot itself. While suitable defaults have been chosen, sometimes the placement of the scale may interfere with an interesting feature. angle.scale can take any value between 0 and 360 to place the scale at a different angle, or FALSE to move it to the side of the plots.

offset

offset controls the size of the 'hole' in the middle and is expressed on a scale of 0 to 100, where 0 is no hole and 100 is a hole that takes up the entire plotting area.

border.col

The colour of the boundary of each wind speed/direction bin. The default is transparent. Another useful choice sometimes is "white".

key.title

Used to set the title of the legend. The legend title is passed to quickText() if auto.text = TRUE.

auto.text

Either TRUE (default) or FALSE. If TRUE titles and axis labels will automatically try and format pollutant names and units properly, e.g., by subscripting the "2" in "NO2". Passed to quickText().

plot

When openair plots are created they are automatically printed to the active graphics device. plot = FALSE deactivates this behaviour. This may be useful when the plot data is of more interest, or the plot is required to appear later (e.g., later in a Quarto document, or to be saved to a file).

key

Deprecated; please use key.position. If FALSE, sets key.position to "none".

Removed. Please use type.

Input data table with pollutant and geo-spatial information.

required | scope: dynamic & static

A data frame. The data frame must contain at least one numeric column to interpolate, plus a decimal latitude and longitude (or X/Y coordinate used in conjunction with crs).

Pollutant name.

required | scope: dynamic & static

The column name of the pollutant to plot. Multiple pollutants are prohibited by this function.

Statistic for aggregating pollutant data.

default: "mean" | scope: dynamic & static

Pollutant data will be aggregated by latitude & longitude; statistic controls how this is achieved. Possible statistics include:

• "mean": the arithmetic mean (using base::mean())

• "median": the median (middle) value (using stats::median())

• "max": the maximum value (using max())

• "min": the maximum value (using min())

• "sd": the standard deviation (using stats::sd())

• "percentile": a percentile value, defined using the percentile argument (using stats::quantile())

To show this value in marker popups or labels, include pollutant in popup or label (e.g., popup = c("site", "nox")).

The percentile when 'statistic = "percentile"

default: 95 | scope: dynamic & static

The percentile level used when statistic = "percentile". The default is 95, representing 95%. Should be between 0 and 100.

A spatial dataset of prediction locations.

default: NULL | scope: dynamic & static

By default, a bounding box of all latitudes and longitudes are used for prediction, but this is often not useful or aesthetically pleasing. newdata should be a spatial data frame (constructed with sf::st_as_sf()). This may be a country or authority boundary relevant to the data input.

Spatial interpolation method.

default: "idw" | scope: dynamic & static

The spatial interpolation method to use for krigingMap(). "idw" uses inverse distance weighting (IDW) which is simpler and faster. "kriging" uses full point kriging which is typically more accurate, but is also more complex and computationally intensive.

Discretise the map color scale.

default: NULL | scope: dynamic & static

By default, a continuous colour scale is used. If breaks are provided, the colour scale will be discretised using cut(). labels can also be provided to customise how each factor level is labelled.

If the data extend beyond breaks, the outermost breaks are expanded to cover them so that no sites are left uncoloured. For example, breaks = c(50, 100, 150) would become c(25, 100, 200) for data ranging from 25 to 200.

Specifier for the plot colour scale bounds.

default: NULL | scope: dynamic & static

A numeric vector in the form c(lower, upper) used to define the colour scale. For example, limits = c(0, 100) would force the plot limits to span 0-100. If NULL, appropriate limits will be selected based on the range in data[[pollutant]]. Values outside of limits are given the colour of the nearest limit.

The decimal latitude(Y)/longitude(X).

default: NULL | scope: dynamic & static

Column names representing the decimal latitude and longitude (or other Y/X coordinate if using a different crs). If not provided, will be automatically inferred from data by looking for a column named "lat"/"latitude" or "lon"/"lng"/"long"/"longitude" (case-insensitively).

The coordinate reference system (CRS).

default: 4326 | scope: dynamic & static

The coordinate reference system (CRS) of the data, passed to sf::st_crs(). By default this is EPSG:4326, the CRS associated with the commonly used latitude and longitude coordinates. Different coordinate systems can be specified using crs (e.g., crs = 27700 for the British National Grid). Note that non-lat/lng coordinate systems will be re-projected to EPSG:4326 for plotting on the map.

A method to condition the data for separate plotting.

default: NULL | scope: dynamic & static

Used for splitting the input data into different groups, passed to the type argument of openair::cutData(). When type is specified:

• Dynamic: The different data splits can be toggled between using a "layer control" menu.

• Static: The data splits will each appear in a different panel.

type cannot be used if multiple pollutant columns have been provided.

Content for marker popups on dynamic maps.

default: NULL | scope: dynamic

Columns to be used as the HTML content for site marker popups on dynamic maps. Popups may be useful to show information about the individual sites (e.g., site names, codes, types, etc.). If a vector of column names are provided they are passed to buildPopup() using its default values.

The pollutant column shows the site statistic (i.e., what the markers are coloured by), labelled as such (e.g., "NO₂ (max)"). Any other numeric columns have many values at each site, so are averaged and labelled "(mean)". Names given to popup (e.g., c("Site NOx" = "nox")) are used instead of these labels.

Content for marker hover-over on dynamic maps.

default: NULL | scope: dynamic

Column to be used as the HTML content for hover-over labels. Labels are useful for the same reasons as popups, though are typically shorter. The pollutant column shows the site statistic, and other numeric columns are averaged at each site.

The basemap(s) to be used.

default: "OpenStreetMap" | scope: dynamic & static

The base map(s) to be used for the map. If not provided, will default to "OpenStreetMap"/"osm" for both dynamic and static maps.

• Dynamic: Any number of leaflet::providers. See http://leaflet-extras.github.io/leaflet-providers/preview/ for a list of all base maps that can be used. If multiple base maps are provided, they can be toggled between using a "layer control" interface. By default, the interface will use the provider names as labels, but users can define their own using a named vector (e.g., c("Default" = "OpenStreetMap", "Satellite" = "Esri.WorldImagery"))

• Static: One of the options listed in rosm::osm.types() (for example, "osm", "cartodark", "cartolight", etc.).

There is some overlap in static and dynamic providers. For example, {ggspatial} uses "osm" to specify "OpenStreetMap". When static providers are provided to dynamic maps or vice versa, {openairmaps} will attempt to substitute the correct provider string.

Colours to use for plotting.

default: "turbo" | scope: dynamic & static

The colours used for plotting, passed to openair::openColours(). The default, "turbo", is a rainbow palette with relatively perceptually uniform colours.

Transparency value for interpolated surface.

default: 0.8 | scope: dynamic & static

A value between 0 (fully transparent) and 1 (fully opaque).

Show original monitoring site markers?

default: TRUE | scope: dynamic & static

When TRUE, the coordinates in the input data will be shown as coloured markers. Any popup or label is attached to these markers, so neither is shown when show.markers = FALSE.

Border colour to use for markers and voronoi tiles.

default: "white" | scope: dynamic & static

Any valid HTML colour (e.g., a hex code). Use NA for no border.

Draw a legend?

default: TRUE | scope: dynamic & static

When TRUE, a legend will appear on the map identifying the colour scale.

Position of the shared legend.

default: NULL | scope: dynamic & static

When legend = TRUE, where should the legend be placed?

• Dynamic: One of "topright", "topleft", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLegend().

• Static: One of "top", "right", "bottom" or "left". Passed to the legend.position argument of ggplot2::theme().

Title of the legend.

default: NULL | scope: dynamic & static

By default, when legend.title = NULL, the function will attempt to provide a sensible legend title. legend.title allows users to overwrite this - for example, to include units or other contextual information. For dynamic maps, users may wish to use HTML tags to format the title.

Automatically format the title of the legend?

default: TRUE | scope: dynamic & static

When legend.title.autotext = TRUE, legend.title will be first run through quickTextHTML() (dynamic) or openair::quickText() (static).

Show the layer control as a collapsed?

default: FALSE | scope: dynamic

For dynamic maps, should the "layer control" interface be collapsed? If TRUE, users will have to hover over an icon to view the options.

Position of the layer control menu

default: "topright" | scope: dynamic

When type != NULL, or multiple pollutants are specified, where should the "layer control" interface be placed? One of "topleft", "topright", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLayersControl().

Automatically format the content of the layer control menu?

default: TRUE | scope: dynamic

When control.autotext = TRUE, the content of the "layer control" interface will be first run through quickTextHTML().

Produce a static map?

default: FALSE

This controls whether a dynamic or static map is produced. The former is the default and is broadly more useful, but the latter may be preferable for DOCX or PDF outputs (e.g., academic papers).

Number of rows in a static map.

default: NULL | scope: static

Controls the number of rows of panels on a static map when multiple pollutants or type are specified; passed to the nrow argument of ggplot2::facet_wrap(). The default, NULL, results in a roughly square grid of panels.

API key for certain 'static' base map providers.

default: NULL | scope: static

Passed to the api_key argument of ggspatial::annotation_map_tile(). Needed for certain providers (e.g., "cartolight").

A variogram model

default: gstat::vgm(psill = 1, model = "Exp", range = 50, nugget = 1) | scope: dynamic & static

The variogram model to use when method = "kriging". Must be the output of gstat::vgm(). As the data are in latitude and longitude, {gstat} measures distances (e.g., the range) in kilometres.

Extra arguments to pass to spatial interpolation functions for krigingMap().

scope: dynamic & static

Extra arguments passed to gstat::idw(), gstat::variogram(), gstat::fit.variogram(), and gstat::krige(). gstat::idw() and gstat::krige() are silenced by default (debug.level = 0), but this can be overridden (e.g., args.idw = list(debug.level = 1)).

Arguments passed on to openair::cutData

names

By default, the columns created by cutData() are named after their type option. Specifying names defines other names for the columns, which map onto the type options in the same order they are given. The length of names should therefore be equal to the length of type.

suffix

If name is not specified, suffix will be appended to any added columns that would otherwise overwrite existing columns. For example, cutData(mydata, "nox", suffix = "_cuts") would append a nox_cuts column rather than overwriting nox.

hemisphere

Can be "northern" or "southern", used to split data into seasons.

n.levels

Number of quantiles to split numeric data into.

wd.res

The number of wind direction bins; one of 4 (N/E/S/W), 8 (N/NE/E/SE/etc., the default) or 16 (N/NNE/NE/ENE/etc.).

start.day

What day of the week should the type = "weekday" start on? The user can change the start day by supplying an integer between 0 and 6. Sunday = 0, Monday = 1, ... For example to start the weekday plots on a Saturday, choose start.day = 6.

start.season

What order should the season be. By default, the order is spring, summer, autumn, winter. start.season = "winter" would plot winter first.

is.axis

A logical (TRUE/FALSE), used to request shortened cut labels for axes.

local.tz

Used for identifying whether a date has daylight savings time (DST) applied or not. Examples include local.tz = "Europe/London", local.tz = "America/New_York", i.e., time zones that assume DST. https://en.wikipedia.org/wiki/List_of_zoneinfo_time_zones shows time zones that should be valid for most systems. It is important that the original data are in GMT (UTC) or a fixed offset from GMT.

latitude,longitude

The decimal latitude and longitudes used when type = "daylight". Note that locations west of Greenwich have negative longitudes.

drop

How to handle empty factor levels. One of:

• "default": Sensible defaults selected on a case-by-case basis for different type options.

• "empty": Drop all empty factor levels.

• "none": Retain all empty factor levels, where possible. For example, for type = "hour", all factor levels from 0 and 23 will be represented.

• "outside": Retain empty factor levels within the range of the data. For example, for type = "hour" when the data only contains data for 1 AM and 5 AM, the factor levels, 1, 2, 3, 4 and 5 will be retained.

Some of these options only apply to certain type options. For example, for type = "year", "outside" is equivalent to "none" as there is no fixed range of years to use in the "none" case.

Extra arguments to pass to spatial interpolation functions for voronoiMap().

scope: dynamic & static

Extra arguments passed to terra::voronoi(), with the exception of x which is dealt with by voronoiMap().

One or more UK or European monitoring networks.

default: "aurn"

One or more air quality networks for which data is available through openair. Available networks include:

• "aurn", The UK Automatic Urban and Rural Network.

• "aqe", The Air Quality England Network.

• "saqn", The Scottish Air Quality Network.

• "waqn", The Welsh Air Quality Network.

• "ni", The Northern Ireland Air Quality Network.

• "local", Locally managed air quality networks in England.

• "imperial", Imperial College London (formerly King's College London) networks.

• "europe", European AirBase/e-reporting data.

There are two additional options provided for convenience:

• "ukaq" will return metadata for all networks for which data is imported by importUKAQ() (i.e., AURN, AQE, SAQN, WAQN, NI, and the local networks).

• "all" will import all available metadata (i.e., "ukaq" plus "kcl" and "europe").

Arguments passed on to openair::importMeta

year

If a single year is selected, only sites that were open at some point in that year are returned. If all = TRUE only sites that measured a particular pollutant in that year are returned. Year can also be a sequence e.g. year = 2010:2020 or of length 2 e.g. year = c(2010, 2020), which will return only sites that were open over the duration.

pollutant

Character vectors used to search the metadata for the specified sources. pollutant is case-insensitive. For example, pollutant = c("nox", "o3") will return sites which measure either NOx or O3. Can also take the shorthand "hc", will returns all hydrocarbons. Similar to code, values are matched exactly (e.g., pollutant = "no" will only return NO and not NO2 or NOx). Note that pollutant only applies to networks available through importUKAQ().

site,code,site_type

Character vectors used to search the metadata for the specified sources. All of code, site and site_type are case-insensitive. code and site_type are matched exactly, but site is 'pattern matched' - e.g., site = "Sunderland" and source = "aurn" will return data for "Sunderland", "Sunderland Silksworth" and "Sunderland Wessington Way" (plus any future sites with the string "Sunderland" in their name).

lat,lng

Decimal latitude (lat) and longitude (lng) (or other Y/X coordinate if using a different crs). If provided, the data will be returned with a distance_km column displaying the distance of each station from the target coordinate. The data will also be automatically sorted by this column.

crs

The coordinate reference system (CRS) of the data, passed to sf::st_crs(). By default this is EPSG:4326, the CRS associated with the commonly used latitude and longitude coordinates. Different coordinate systems can be specified using crs (e.g., crs = 27700 for the British National Grid). Note that non-lat/lng coordinate systems will be re-projected to EPSG:4326 for comparison with the site metadata.

max_dist,max_n

If lat and lng are provided, max_dist and max_n further filter the metadata. max_dist defines a maximum distance from the target coordinate in kilometers, and max_n a maximum number of sites to be returned. max_n is applied after max_dist.

Option to create a 'layer control' menu.

default: NULL

A string to specify categories in a "layer control" menu, to allow readers to select between different site categories. Choices include:

• "source" to toggle between different networks

• "variable" to toggle between different pollutants

• "site_type" for different site classifications

• "agglomeration", "zone" or "local_authority" for different regions of the UK

Cluster markers together when zoomed out?

default: NULL

When cluster = TRUE, markers are clustered together. This may be useful for sources like "imperial" where there are many markers very close together. Defaults to NULL, which is TRUE if there are more than 25 sites mapped and FALSE if there are fewer.

The basemap(s) to be used.

default: c("Default" = "OpenStreetMap", "Satellite" = "Esri.WorldImagery")

Any number of leaflet::providers. See http://leaflet-extras.github.io/leaflet-providers/preview/ for a list of all base maps that can be used. If multiple base maps are provided, they can be toggled between using a "layer control" interface. By default, the interface will use the provider names as labels, but users can define their own using a named vector (e.g., c("Default" = "OpenStreetMap", "Satellite" = "Esri.WorldImagery"))

Draw a shared legend?

default: TRUE

When multiple sources are defined, should a shared legend be created at the side of the map?

Position of the legend

default: "topright"

Where should the shared legend be placed? One of "topleft", "topright", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLayersControl().

Show the layer control as a collapsed?

default: FALSE

Should the "layer control" interface be collapsed? If TRUE, users will have to hover over an icon to view the options.

Position of the layer control menu

default: "topright"

Where should the "layer control" interface be placed? One of "topleft", "topright", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLayersControl().

Input data table with pollutant, wind, and geo-spatial information.

required | scope: dynamic & static

A data frame. The data frame must contain the data to plot the directional analysis marker, which includes wind speed (ws), wind direction (wd), and the column representing the concentration of a pollutant. In addition, data must include a decimal latitude and longitude (or X/Y coordinate used in conjunction with crs).

Pollutant name(s).

required | scope: dynamic & static

The column name(s) of the pollutant(s) to plot. If multiple pollutants are specified and a non-pairwise statistic is supplied, the type argument will no longer be able to be used and:

• Dynamic: The pollutants can be toggled between using a "layer control" menu.

• Static: The pollutants will each appear in a different panel.

Multiple pollutants prohibit the use of the type argument for non-pairwise statistics.

The percentile values for the colour scale bin.

default: c(25, 50, 75, 90, 95) | scope: dynamic & static

The percentile value(s) to plot using openair::percentileRose(). Must be a vector of values between 0 and 100. If percentile = NA then only a mean line will be shown.

Specifier for the percentile rose radial axis intervals.

default: "fixed" | scope: dynamic & static

One of:

• "fixed" (the default) which ensures all of the markers use the same radial axis scale.

• "free" which allows all of the markers to use different radial axis scales.

• A numeric vector defining a sequence of numbers to use as the intervals, e.g., intervals = c(0, 10, 30, 50).

The decimal latitude(Y)/longitude(X).

default: NULL | scope: dynamic & static

Column names representing the decimal latitude and longitude (or other Y/X coordinate if using a different crs). If not provided, will be automatically inferred from data by looking for a column named "lat"/"latitude" or "lon"/"lng"/"long"/"longitude" (case-insensitively).

The coordinate reference system (CRS).

default: 4326 | scope: dynamic & static

The coordinate reference system (CRS) of the data, passed to sf::st_crs(). By default this is EPSG:4326, the CRS associated with the commonly used latitude and longitude coordinates. Different coordinate systems can be specified using crs (e.g., crs = 27700 for the British National Grid). Note that non-lat/lng coordinate systems will be re-projected to EPSG:4326 for plotting on the map.

A method to condition the data for separate plotting.

default: NULL | scope: dynamic & static

Used for splitting the input data into different groups, passed to the type argument of openair::cutData(). When type is specified:

• Dynamic: The different data splits can be toggled between using a "layer control" menu.

• Static: The data splits will each appear in a different panel.

type cannot be used if multiple pollutant columns have been provided.

Content for marker popups on dynamic maps.

default: NULL | scope: dynamic

Columns to be used as the HTML content for marker popups on dynamic maps. Popups may be useful to show information about the individual sites (e.g., site names, codes, types, etc.). If a vector of column names are provided they are passed to buildPopup() using its default values.

Numeric columns (e.g., pollutant concentrations) have many values at each marker, so are averaged and labelled as such (e.g., "NO₂ (mean)"). Names given to popup (e.g., c("Mean NOx" = "nox")) are used instead of these labels.

Content for marker hover-over on dynamic maps.

default: NULL | scope: dynamic

Column to be used as the HTML content for hover-over labels. Labels are useful for the same reasons as popups, though are typically shorter. As with popup, numeric columns are averaged at each marker.

The basemap(s) to be used.

default: "OpenStreetMap" | scope: dynamic & static

The base map(s) to be used for the map. If not provided, will default to "OpenStreetMap"/"osm" for both dynamic and static maps.

• Dynamic: Any number of leaflet::providers. See http://leaflet-extras.github.io/leaflet-providers/preview/ for a list of all base maps that can be used. If multiple base maps are provided, they can be toggled between using a "layer control" interface. By default, the interface will use the provider names as labels, but users can define their own using a named vector (e.g., c("Default" = "OpenStreetMap", "Satellite" = "Esri.WorldImagery"))

• Static: One of the options listed in rosm::osm.types() (for example, "osm", "cartodark", "cartolight", etc.).

There is some overlap in static and dynamic providers. For example, {ggspatial} uses "osm" to specify "OpenStreetMap". When static providers are provided to dynamic maps or vice versa, {openairmaps} will attempt to substitute the correct provider string.

Colours to use for plotting.

default: "turbo" | scope: dynamic & static

The colours used for plotting, passed to openair::openColours(). The default, "turbo", is a rainbow palette with relatively perceptually uniform colours.

Transparency value for polar markers.

default: 1 | scope: dynamic & static

A value between 0 (fully transparent) and 1 (fully opaque).

Custom ggplot2 theme for the polar markers.

default: "default" | scope: dynamic & static

A custom ggplot2 theme to add to the polar markers. This should ideally be a partial theme (i.e., ggplot2::theme()) over a complete theme (e.g., ggplot2::theme_bw()) as other arguments like key interact with the plot theme before custom themes are set, so would be overridden by a complete theme.

Legend position for individual marker legends.

default: "none" | scope: dynamic & static

When key.position is not "none", a key will be drawn for each individual marker. Potentially useful when limits = "free", but of limited use otherwise.

Draw a shared legend?

default: TRUE | scope: dynamic & static

When all markers share the same colour scale, should a shared legend be created at the side of the map? This is the case for:

• Continuous colour scales, when all markers share the same limits (e.g., when limits != "free" in polarMap()), which are shown as a colour bar. This legend is not drawn if the colour scale has been transformed using trans (e.g., trans = "log10"), as it would be misleading.

• Discrete colour scales, when all markers are binned into the same intervals (e.g., when breaks are passed to polarMap(), or in windroseMap()), which are shown as a set of labelled colours.

Position of the shared legend.

default: NULL | scope: dynamic & static

When legend = TRUE, where should the legend be placed?

• Dynamic: One of "topright", "topleft", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLegend().

• Static: One of "top", "right", "bottom" or "left". Passed to the legend.position argument of ggplot2::theme().

Title of the legend.

default: NULL | scope: dynamic & static

By default, when legend.title = NULL, the function will attempt to provide a sensible legend title. legend.title allows users to overwrite this - for example, to include units or other contextual information. For dynamic maps, users may wish to use HTML tags to format the title.

Automatically format the title of the legend?

default: TRUE | scope: dynamic & static

When legend.title.autotext = TRUE, legend.title will be first run through quickTextHTML() (dynamic) or openair::quickText() (static).

Show the layer control as a collapsed?

default: FALSE | scope: dynamic

For dynamic maps, should the "layer control" interface be collapsed? If TRUE, users will have to hover over an icon to view the options.

Position of the layer control menu

default: "topright" | scope: dynamic

When type != NULL, or multiple pollutants are specified, where should the "layer control" interface be placed? One of "topleft", "topright", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLayersControl().

Automatically format the content of the layer control menu?

default: TRUE | scope: dynamic

When control.autotext = TRUE, the content of the "layer control" interface will be first run through quickTextHTML().

The diameter of the plot on the map in pixels.

default: 200 | scope: dynamic & static

This will affect the size of the individual polar markers. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

The diameter of the plots to be produced using {openair} in inches.

default: 3.5 | scope: dynamic & static

This will affect the resolution of the markers on the map. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

Produce a static map?

default: FALSE

This controls whether a dynamic or static map is produced. The former is the default and is broadly more useful, but the latter may be preferable for DOCX or PDF outputs (e.g., academic papers).

Number of rows in a static map.

default: NULL | scope: static

Controls the number of rows of panels on a static map when multiple pollutants or type are specified; passed to the nrow argument of ggplot2::facet_wrap(). The default, NULL, results in a roughly square grid of panels.

API key for certain 'static' base map providers.

default: NULL | scope: static

Passed to the api_key argument of ggspatial::annotation_map_tile(). Needed for certain providers (e.g., "cartolight").

Show a progress bar?

default: TRUE | scope: dynamic & static

By default, a progress bar is shown to visualise the function's progress creating individual polar markers. This option allows this to be turned off, if desired.

Arguments passed on to openair::percentileRose

mydata

A data frame minimally containing a decimal wind direction and a numeric field to plot.

ws

The name of the column in mydata representing the wind speed. Defaults to "ws".

wd

The name of the column in mydata representing the decimal wind direction, 0 to 360 where 0/360 are North and 180 is South. Defaults to "wd".

smooth

Should the wind direction data be smoothed using a cyclic spline?

method

When method = "default" the supplied percentiles by wind direction are calculated. When method = "cpf" the conditional probability function (CPF) is plotted and a single (usually high) percentile level is supplied. The CPF is defined as CPF = my/ny, where my is the number of samples in the wind sector y with mixing ratios greater than the overall percentile concentration, and ny is the total number of samples in the same wind sector (see Ashbaugh et al., 1985).

angle

Default angle of “spokes” is when smooth = FALSE.

mean

Show the mean by wind direction as a line?

mean.lty

Line type for mean line.

mean.lwd

Line width for mean line.

mean.col

Line colour for mean line.

fill

Should the percentile intervals be filled (default) or should lines be drawn (fill = FALSE).

angle.scale

In radial plots (e.g., polarPlot()), the radial scale is drawn directly on the plot itself. While suitable defaults have been chosen, sometimes the placement of the scale may interfere with an interesting feature. angle.scale can take any value between 0 and 360 to place the scale at a different angle, or FALSE to move it to the side of the plots.

offset

offset controls the size of the 'hole' in the middle and is expressed on a scale of 0 to 100, where 0 is no hole and 100 is a hole that takes up the entire plotting area.

auto.text

Either TRUE (default) or FALSE. If TRUE titles and axis labels will automatically try and format pollutant names and units properly, e.g., by subscripting the "2" in "NO2". Passed to quickText().

key.title

Used to set the title of the legend. The legend title is passed to quickText() if auto.text = TRUE.

plot

When openair plots are created they are automatically printed to the active graphics device. plot = FALSE deactivates this behaviour. This may be useful when the plot data is of more interest, or the plot is required to appear later (e.g., later in a Quarto document, or to be saved to a file).

key

Deprecated; please use key.position. If FALSE, sets key.position to "none".

Removed. Please use type.

Input data table with pollutant and geo-spatial information.

required | scope: dynamic & static

A data frame. The data frame must contain at least one numeric column to interpolate, plus a decimal latitude and longitude (or X/Y coordinate used in conjunction with crs).

Pollutant name.

required | scope: dynamic & static

The column name of the pollutant to plot. Multiple pollutants are prohibited by this function.

Statistic for aggregating pollutant data.

default: "mean" | scope: dynamic & static

Pollutant data will be aggregated by latitude & longitude; statistic controls how this is achieved. Possible statistics include:

• "mean": the arithmetic mean (using base::mean())

• "median": the median (middle) value (using stats::median())

• "max": the maximum value (using max())

• "min": the maximum value (using min())

• "sd": the standard deviation (using stats::sd())

• "percentile": a percentile value, defined using the percentile argument (using stats::quantile())

To show this value in marker popups or labels, include pollutant in popup or label (e.g., popup = c("site", "nox")).

The percentile when 'statistic = "percentile"

default: 95 | scope: dynamic & static

The percentile level used when statistic = "percentile". The default is 95, representing 95%. Should be between 0 and 100.

Discretise the map color scale.

default: NULL | scope: dynamic & static

By default, a continuous colour scale is used. If breaks are provided, the colour scale will be discretised using cut(). labels can also be provided to customise how each factor level is labelled.

If the data extend beyond breaks, the outermost breaks are expanded to cover them so that no sites are left uncoloured. For example, breaks = c(50, 100, 150) would become c(25, 100, 200) for data ranging from 25 to 200.

Specifier for the plot colour scale bounds.

default: NULL | scope: dynamic & static

A numeric vector in the form c(lower, upper) used to define the colour scale. For example, limits = c(0, 100) would force the plot limits to span 0-100. If NULL, appropriate limits will be selected based on the range in data[[pollutant]]. Values outside of limits are given the colour of the nearest limit.

The decimal latitude(Y)/longitude(X).

default: NULL | scope: dynamic & static

Column names representing the decimal latitude and longitude (or other Y/X coordinate if using a different crs). If not provided, will be automatically inferred from data by looking for a column named "lat"/"latitude" or "lon"/"lng"/"long"/"longitude" (case-insensitively).

The coordinate reference system (CRS).

default: 4326 | scope: dynamic & static

The coordinate reference system (CRS) of the data, passed to sf::st_crs(). By default this is EPSG:4326, the CRS associated with the commonly used latitude and longitude coordinates. Different coordinate systems can be specified using crs (e.g., crs = 27700 for the British National Grid). Note that non-lat/lng coordinate systems will be re-projected to EPSG:4326 for plotting on the map.

A method to condition the data for separate plotting.

default: NULL | scope: dynamic & static

Used for splitting the input data into different groups, passed to the type argument of openair::cutData(). When type is specified:

• Dynamic: The different data splits can be toggled between using a "layer control" menu.

• Static: The data splits will each appear in a different panel.

type cannot be used if multiple pollutant columns have been provided.

Content for marker popups on dynamic maps.

default: NULL | scope: dynamic

Columns to be used as the HTML content for site marker popups on dynamic maps. Popups may be useful to show information about the individual sites (e.g., site names, codes, types, etc.). If a vector of column names are provided they are passed to buildPopup() using its default values.

The pollutant column shows the site statistic (i.e., what the markers are coloured by), labelled as such (e.g., "NO₂ (max)"). Any other numeric columns have many values at each site, so are averaged and labelled "(mean)". Names given to popup (e.g., c("Site NOx" = "nox")) are used instead of these labels.

Content for marker hover-over on dynamic maps.

default: NULL | scope: dynamic

Column to be used as the HTML content for hover-over labels. Labels are useful for the same reasons as popups, though are typically shorter. The pollutant column shows the site statistic, and other numeric columns are averaged at each site.

The basemap(s) to be used.

default: "OpenStreetMap" | scope: dynamic & static

The base map(s) to be used for the map. If not provided, will default to "OpenStreetMap"/"osm" for both dynamic and static maps.

• Dynamic: Any number of leaflet::providers. See http://leaflet-extras.github.io/leaflet-providers/preview/ for a list of all base maps that can be used. If multiple base maps are provided, they can be toggled between using a "layer control" interface. By default, the interface will use the provider names as labels, but users can define their own using a named vector (e.g., c("Default" = "OpenStreetMap", "Satellite" = "Esri.WorldImagery"))

• Static: One of the options listed in rosm::osm.types() (for example, "osm", "cartodark", "cartolight", etc.).

There is some overlap in static and dynamic providers. For example, {ggspatial} uses "osm" to specify "OpenStreetMap". When static providers are provided to dynamic maps or vice versa, {openairmaps} will attempt to substitute the correct provider string.

Colours to use for plotting.

default: "turbo" | scope: dynamic & static

The colours used for plotting, passed to openair::openColours(). The default, "turbo", is a rainbow palette with relatively perceptually uniform colours.

Transparency value for the site markers.

default: 1 | scope: dynamic & static

A value between 0 (fully transparent) and 1 (fully opaque).

Border colour to use for the site markers.

default: "white" | scope: dynamic & static

Any valid HTML colour (e.g., a hex code). Use NA for no border.

Draw a legend?

default: TRUE | scope: dynamic & static

When TRUE, a legend will appear on the map identifying the colour scale.

Position of the shared legend.

default: NULL | scope: dynamic & static

When legend = TRUE, where should the legend be placed?

• Dynamic: One of "topright", "topleft", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLegend().

• Static: One of "top", "right", "bottom" or "left". Passed to the legend.position argument of ggplot2::theme().

Title of the legend.

default: NULL | scope: dynamic & static

By default, when legend.title = NULL, the function will attempt to provide a sensible legend title. legend.title allows users to overwrite this - for example, to include units or other contextual information. For dynamic maps, users may wish to use HTML tags to format the title.

Automatically format the title of the legend?

default: TRUE | scope: dynamic & static

When legend.title.autotext = TRUE, legend.title will be first run through quickTextHTML() (dynamic) or openair::quickText() (static).

Show the layer control as a collapsed?

default: FALSE | scope: dynamic

For dynamic maps, should the "layer control" interface be collapsed? If TRUE, users will have to hover over an icon to view the options.

Position of the layer control menu

default: "topright" | scope: dynamic

When type != NULL, or multiple pollutants are specified, where should the "layer control" interface be placed? One of "topleft", "topright", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLayersControl().

Automatically format the content of the layer control menu?

default: TRUE | scope: dynamic

When control.autotext = TRUE, the content of the "layer control" interface will be first run through quickTextHTML().

Produce a static map?

default: FALSE

This controls whether a dynamic or static map is produced. The former is the default and is broadly more useful, but the latter may be preferable for DOCX or PDF outputs (e.g., academic papers).

Number of rows in a static map.

default: NULL | scope: static

Controls the number of rows of panels on a static map when multiple pollutants or type are specified; passed to the nrow argument of ggplot2::facet_wrap(). The default, NULL, results in a roughly square grid of panels.

API key for certain 'static' base map providers.

default: NULL | scope: static

Passed to the api_key argument of ggspatial::annotation_map_tile(). Needed for certain providers (e.g., "cartolight").

Arguments passed on to openair::cutData

names

By default, the columns created by cutData() are named after their type option. Specifying names defines other names for the columns, which map onto the type options in the same order they are given. The length of names should therefore be equal to the length of type.

suffix

If name is not specified, suffix will be appended to any added columns that would otherwise overwrite existing columns. For example, cutData(mydata, "nox", suffix = "_cuts") would append a nox_cuts column rather than overwriting nox.

hemisphere

Can be "northern" or "southern", used to split data into seasons.

n.levels

Number of quantiles to split numeric data into.

wd.res

The number of wind direction bins; one of 4 (N/E/S/W), 8 (N/NE/E/SE/etc., the default) or 16 (N/NNE/NE/ENE/etc.).

start.day

What day of the week should the type = "weekday" start on? The user can change the start day by supplying an integer between 0 and 6. Sunday = 0, Monday = 1, ... For example to start the weekday plots on a Saturday, choose start.day = 6.

start.season

What order should the season be. By default, the order is spring, summer, autumn, winter. start.season = "winter" would plot winter first.

is.axis

A logical (TRUE/FALSE), used to request shortened cut labels for axes.

local.tz

Used for identifying whether a date has daylight savings time (DST) applied or not. Examples include local.tz = "Europe/London", local.tz = "America/New_York", i.e., time zones that assume DST. https://en.wikipedia.org/wiki/List_of_zoneinfo_time_zones shows time zones that should be valid for most systems. It is important that the original data are in GMT (UTC) or a fixed offset from GMT.

latitude,longitude

The decimal latitude and longitudes used when type = "daylight". Note that locations west of Greenwich have negative longitudes.

drop

How to handle empty factor levels. One of:

• "default": Sensible defaults selected on a case-by-case basis for different type options.

• "empty": Drop all empty factor levels.

• "none": Retain all empty factor levels, where possible. For example, for type = "hour", all factor levels from 0 and 23 will be represented.

• "outside": Retain empty factor levels within the range of the data. For example, for type = "hour" when the data only contains data for 1 AM and 5 AM, the factor levels, 1, 2, 3, 4 and 5 will be retained.

Some of these options only apply to certain type options. For example, for type = "year", "outside" is equivalent to "none" as there is no fixed range of years to use in the "none" case.

Input data table with pollutant, wind, and geo-spatial information.

required | scope: dynamic & static

A data frame. The data frame must contain the data to plot the directional analysis marker, which includes wind speed (ws), wind direction (wd), and the column representing the concentration of a pollutant. In addition, data must include a decimal latitude and longitude (or X/Y coordinate used in conjunction with crs).

Pollutant name(s).

required | scope: dynamic & static

The column name(s) of the pollutant(s) to plot. If multiple pollutants are specified and a non-pairwise statistic is supplied, the type argument will no longer be able to be used and:

• Dynamic: The pollutants can be toggled between using a "layer control" menu.

• Static: The pollutants will each appear in a different panel.

Multiple pollutants prohibit the use of the type argument for non-pairwise statistics.

The radial axis variable.

default: "ws" | scope: dynamic & static

The column name for the radial axis variable to use in openair::polarPlot(). Defaults to using wind speed, "ws", but other meteorological variables such as ambient temperature or atmospheric stability may be useful.

Specifier for the plot colour scale bounds.

default: "free" | scope: dynamic & static

One of:

• "fixed" which ensures all of the markers use the same colour scale.

• "free" (the default) which allows all of the markers to use different colour scales.

• A numeric vector in the form c(lower, upper) used to define the colour scale. For example, limits = c(0, 100) would force the plot limits to span 0-100.

limits is ignored if breaks is also provided.

Specifier for a binned colour scale.

default: NULL | scope: dynamic & static

By default, markers use a continuous colour scale (see limits). If breaks is provided, the colour scale is instead binned into discrete intervals. One of:

• A numeric vector of breakpoints. For example, breaks = c(0, 50, 100, 1000) would bin the colour scale into three intervals.

• A single number, which is the number of intervals to bin the colour scale into.

• A list created using openair::breakOpts(), which provides finer control over the binning method and allows custom labels to be defined.

In all cases, a single set of breakpoints is calculated across all of the markers, so that they share the same intervals and a shared legend can be drawn. If any of the markers' data fall outside of the given breakpoints, the lowest and/or highest breakpoints are extended to cover them. If breaks is provided, limits is ignored.

Specifier for the polar plot radial axis upper boundary.

default: "fixed" | scope: dynamic & static

One of:

• "fixed" (the default) which ensures all of the markers use the same radial axis scale.

• "free" which allows all of the markers to use different radial axis scales.

• A numeric value, used as the upper limit for the radial axis scale.

The decimal latitude(Y)/longitude(X).

default: NULL | scope: dynamic & static

Column names representing the decimal latitude and longitude (or other Y/X coordinate if using a different crs). If not provided, will be automatically inferred from data by looking for a column named "lat"/"latitude" or "lon"/"lng"/"long"/"longitude" (case-insensitively).

The coordinate reference system (CRS).

default: 4326 | scope: dynamic & static

The coordinate reference system (CRS) of the data, passed to sf::st_crs(). By default this is EPSG:4326, the CRS associated with the commonly used latitude and longitude coordinates. Different coordinate systems can be specified using crs (e.g., crs = 27700 for the British National Grid). Note that non-lat/lng coordinate systems will be re-projected to EPSG:4326 for plotting on the map.

A method to condition the data for separate plotting.

default: NULL | scope: dynamic & static

Used for splitting the input data into different groups, passed to the type argument of openair::cutData(). When type is specified:

• Dynamic: The different data splits can be toggled between using a "layer control" menu.

• Static: The data splits will each appear in a different panel.

type cannot be used if multiple pollutant columns have been provided.

Content for marker popups on dynamic maps.

default: NULL | scope: dynamic

Columns to be used as the HTML content for marker popups on dynamic maps. Popups may be useful to show information about the individual sites (e.g., site names, codes, types, etc.). If a vector of column names are provided they are passed to buildPopup() using its default values.

Numeric columns (e.g., pollutant concentrations) have many values at each marker, so are averaged and labelled as such (e.g., "NO₂ (mean)"). Names given to popup (e.g., c("Mean NOx" = "nox")) are used instead of these labels.

Content for marker hover-over on dynamic maps.

default: NULL | scope: dynamic

Column to be used as the HTML content for hover-over labels. Labels are useful for the same reasons as popups, though are typically shorter. As with popup, numeric columns are averaged at each marker.

The basemap(s) to be used.

default: "OpenStreetMap" | scope: dynamic & static

The base map(s) to be used for the map. If not provided, will default to "OpenStreetMap"/"osm" for both dynamic and static maps.

• Dynamic: Any number of leaflet::providers. See http://leaflet-extras.github.io/leaflet-providers/preview/ for a list of all base maps that can be used. If multiple base maps are provided, they can be toggled between using a "layer control" interface. By default, the interface will use the provider names as labels, but users can define their own using a named vector (e.g., c("Default" = "OpenStreetMap", "Satellite" = "Esri.WorldImagery"))

• Static: One of the options listed in rosm::osm.types() (for example, "osm", "cartodark", "cartolight", etc.).

There is some overlap in static and dynamic providers. For example, {ggspatial} uses "osm" to specify "OpenStreetMap". When static providers are provided to dynamic maps or vice versa, {openairmaps} will attempt to substitute the correct provider string.

Colours to use for plotting.

default: "turbo" | scope: dynamic & static

The colours used for plotting, passed to openair::openColours(). The default, "turbo", is a rainbow palette with relatively perceptually uniform colours.

Transparency value for polar markers.

default: 1 | scope: dynamic & static

A value between 0 (fully transparent) and 1 (fully opaque).

Custom ggplot2 theme for the polar markers.

default: "default" | scope: dynamic & static

A custom ggplot2 theme to add to the polar markers. This should ideally be a partial theme (i.e., ggplot2::theme()) over a complete theme (e.g., ggplot2::theme_bw()) as other arguments like key interact with the plot theme before custom themes are set, so would be overridden by a complete theme.

Legend position for individual marker legends.

default: "none" | scope: dynamic & static

When key.position is not "none", a key will be drawn for each individual marker. Potentially useful when limits = "free", but of limited use otherwise.

Draw a shared legend?

default: TRUE | scope: dynamic & static

When all markers share the same colour scale, should a shared legend be created at the side of the map? This is the case for:

• Continuous colour scales, when all markers share the same limits (e.g., when limits != "free" in polarMap()), which are shown as a colour bar. This legend is not drawn if the colour scale has been transformed using trans (e.g., trans = "log10"), as it would be misleading.

• Discrete colour scales, when all markers are binned into the same intervals (e.g., when breaks are passed to polarMap(), or in windroseMap()), which are shown as a set of labelled colours.

Position of the shared legend.

default: NULL | scope: dynamic & static

When legend = TRUE, where should the legend be placed?

• Dynamic: One of "topright", "topleft", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLegend().

• Static: One of "top", "right", "bottom" or "left". Passed to the legend.position argument of ggplot2::theme().

Title of the legend.

default: NULL | scope: dynamic & static

By default, when legend.title = NULL, the function will attempt to provide a sensible legend title. legend.title allows users to overwrite this - for example, to include units or other contextual information. For dynamic maps, users may wish to use HTML tags to format the title.

Automatically format the title of the legend?

default: TRUE | scope: dynamic & static

When legend.title.autotext = TRUE, legend.title will be first run through quickTextHTML() (dynamic) or openair::quickText() (static).

Show the layer control as a collapsed?

default: FALSE | scope: dynamic

For dynamic maps, should the "layer control" interface be collapsed? If TRUE, users will have to hover over an icon to view the options.

Position of the layer control menu

default: "topright" | scope: dynamic

When type != NULL, or multiple pollutants are specified, where should the "layer control" interface be placed? One of "topleft", "topright", "bottomleft" or "bottomright". Passed to the position argument of leaflet::addLayersControl().

Automatically format the content of the layer control menu?

default: TRUE | scope: dynamic

When control.autotext = TRUE, the content of the "layer control" interface will be first run through quickTextHTML().

The diameter of the plot on the map in pixels.

default: 200 | scope: dynamic & static

This will affect the size of the individual polar markers. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

The diameter of the plots to be produced using {openair} in inches.

default: 3.5 | scope: dynamic & static

This will affect the resolution of the markers on the map. Alternatively, a vector in the form c(width, height) can be provided if a non-circular marker is desired.

Produce a static map?

default: FALSE

This controls whether a dynamic or static map is produced. The former is the default and is broadly more useful, but the latter may be preferable for DOCX or PDF outputs (e.g., academic papers).

Number of rows in a static map.

default: NULL | scope: static

Controls the number of rows of panels on a static map when multiple pollutants or type are specified; passed to the nrow argument of ggplot2::facet_wrap(). The default, NULL, results in a roughly square grid of panels.

API key for certain 'static' base map providers.

default: NULL | scope: static

Passed to the api_key argument of ggspatial::annotation_map_tile(). Needed for certain providers (e.g., "cartolight").

Show a progress bar?

default: TRUE | scope: dynamic & static

By default, a progress bar is shown to visualise the function's progress creating individual polar markers. This option allows this to be turned off, if desired.

Arguments passed on to openair::polarPlot

mydata

A data frame minimally containing a decimal wind direction, another variable to plot in polar coordinates (the default is a column "ws" — wind speed) and a pollutant. Should also contain date if plots by time period are required.

wd

The name of the column in mydata representing the decimal wind direction, 0 to 360 where 0/360 are North and 180 is South. Defaults to "wd".

statistic

The statistic that should be applied to each wind speed/direction bin. Because of the smoothing involved, the colour scale for some of these statistics is only to provide an indication of overall pattern and should not be interpreted in concentration units e.g. for statistic = "weighted.mean" where the bin mean is multiplied by the bin frequency and divided by the total frequency. In many cases using polarFreq will be better. Setting statistic = "weighted.mean" can be useful because it provides an indication of the concentration * frequency of occurrence and will highlight the wind speed/direction conditions that dominate the overall mean.Can be:

• “mean” (default), “median”, “max” (maximum), “frequency”. “stdev” (standard deviation), “weighted.mean”.

• statistic = "nwr" Implements the Non-parametric Wind Regression approach of Henry et al. (2009) that uses kernel smoothers. The openair implementation is not identical because Gaussian kernels are used for both wind direction and speed. The smoothing is controlled by ws_spread and wd_spread.

• statistic = "cpf" the conditional probability function (CPF) is plotted and a single (usually high) percentile level is supplied. The CPF is defined as CPF = my/ny, where my is the number of samples in the y bin (by default a wind direction, wind speed interval) with mixing ratios greater than the overall percentile concentration, and ny is the total number of samples in the same wind sector (see Ashbaugh et al., 1985). Note that percentile intervals can also be considered; see percentile for details.

• When statistic = "r" or statistic = "Pearson", the Pearson correlation coefficient is calculated for two pollutants. The calculation involves a weighted Pearson correlation coefficient, which is weighted by Gaussian kernels for wind direction an the radial variable (by default wind speed). More weight is assigned to values close to a wind speed-direction interval. Kernel weighting is used to ensure that all data are used rather than relying on the potentially small number of values in a wind speed-direction interval.

• When statistic = "Spearman", the Spearman correlation coefficient is calculated for two pollutants. The calculation involves a weighted Spearman correlation coefficient, which is weighted by Gaussian kernels for wind direction an the radial variable (by default wind speed). More weight is assigned to values close to a wind speed-direction interval. Kernel weighting is used to ensure that all data are used rather than relying on the potentially small number of values in a wind speed-direction interval.

• "robust_slope" is another option for pair-wise statistics and "quantile.slope", which uses quantile regression to estimate the slope for a particular quantile level (see also tau for setting the quantile level).

• "york_slope" is another option for pair-wise statistics which uses the York regression method to estimate the slope. In this method the uncertainties in x and y are used in the determination of the slope. The uncertainties are provided by x_error and y_error — see below.

trans

Should a transformation be applied to the colour scale? If the distribution of data is skewed, the default scale may be dominated by a few high values, so a log or square-root transform may mean the whole colour scale is better presented on the plot. Can be:

• FALSE, which performs no transform.

• TRUE, which uses an appropriate transform for the plot type (usually "log10").

• A scales 'transform' object (e.g., scales::transform_log10()).

• A character string corresponding to a scales transform function. Useful options include "sqrt", "log10", "log2", "log1p", "pseudo_log" and "reverse".

exclude.missing

Setting this option to TRUE (the default) removes points from the plot that are too far from the original data. The smoothing routines will produce predictions at points where no data exist i.e. they predict. By removing the points too far from the original data produces a plot where it is clear where the original data lie. If set to FALSE missing data will be interpolated.

uncertainty

Should the uncertainty in the calculated surface be shown? If TRUE three plots are produced on the same scale showing the predicted surface together with the estimated lower and upper uncertainties at the 95% confidence interval. Calculating the uncertainties is useful to understand whether features are real or not. For example, at high wind speeds where there are few data there is greater uncertainty over the predicted values. The uncertainties are calculated using the GAM and weighting is done by the frequency of measurements in each wind speed-direction bin. Note that if uncertainties are calculated then the type is set to "default".

percentile

If statistic = "percentile" then percentile is used, expressed from 0 to 100. Note that the percentile value is calculated in the wind speed, wind direction ‘bins’. For this reason it can also be useful to set min.bin to ensure there are a sufficient number of points available to estimate a percentile. See quantile for more details of how percentiles are calculated.

percentile is also used for the Conditional Probability Function (CPF) plots. percentile can be of length two, in which case the percentile interval is considered for use with CPF. For example, percentile = c(90, 100) will plot the CPF for concentrations between the 90 and 100th percentiles. Percentile intervals can be useful for identifying specific sources. In addition, percentile can also be of length 3. The third value is the ‘trim’ value to be applied. When calculating percentile intervals many can cover very low values where there is no useful information. The trim value ensures that values greater than or equal to the trim * mean value are considered before the percentile intervals are calculated. The effect is to extract more detail from many source signatures. See the manual for examples. Finally, if the trim value is less than zero the percentile range is interpreted as absolute concentration values and subsetting is carried out directly.

weights

At the edges of the plot there may only be a few data points in each wind speed-direction interval, which could in some situations distort the plot if the concentrations are high. weights applies a weighting to reduce their influence. For example and by default if only a single data point exists then the weighting factor is 0.25 and for two points 0.5. To not apply any weighting and use the data as is, use weights = c(1, 1, 1).

An alternative to down-weighting these points they can be removed altogether using min.bin.

min.bin

The minimum number of points allowed in a wind speed/wind direction bin. The default is 1. A value of two requires at least 2 valid records in each bin an so on; bins with less than 2 valid records are set to NA. Care should be taken when using a value > 1 because of the risk of removing real data points. It is recommended to consider your data with care. Also, the polarFreq function can be of use in such circumstances.

col.na

When min.bin is > 1 it can be useful to show where data are removed on the plots. This is done by shading the missing data in col.na. To not highlight missing data when min.bin > 1 choose col.na = "transparent".

angle.scale

In radial plots (e.g., polarPlot()), the radial scale is drawn directly on the plot itself. While suitable defaults have been chosen, sometimes the placement of the scale may interfere with an interesting feature. angle.scale can take any value between 0 and 360 to place the scale at a different angle, or FALSE to move it to the side of the plots.

units

The units shown on the polar axis scale.

force.positive

The default is TRUE. Sometimes if smoothing data with steep gradients it is possible for predicted values to be negative. force.positive = TRUE ensures that predictions remain positive. This is useful for several reasons. First, with lots of missing data more interpolation is needed and this can result in artefacts because the predictions are too far from the original data. Second, if it is known beforehand that the data are all positive, then this option carries that assumption through to the prediction. The only likely time where setting force.positive = FALSE would be if background concentrations were first subtracted resulting in data that is legitimately negative. For the vast majority of situations it is expected that the user will not need to alter the default option.

k

This is the smoothing parameter used by the gam function in package mgcv. Typically, value of around 100 (the default) seems to be suitable and will resolve important features in the plot. The most appropriate choice of k is problem-dependent; but extensive testing of polar plots for many different problems suggests a value of k of about 100 is suitable. Setting k to higher values will not tend to affect the surface predictions by much but will add to the computation time. Lower values of k will increase smoothing. Sometimes with few data to plot polarPlot will fail. Under these circumstances it can be worth lowering the value of k.

normalise

If TRUE concentrations are normalised by dividing by their mean value. This is done after fitting the smooth surface. This option is particularly useful if one is interested in the patterns of concentrations for several pollutants on different scales e.g. NOx and CO. Often useful if more than one pollutant is chosen.

key.title

Used to set the title of the legend. The legend title is passed to quickText() if auto.text = TRUE.

auto.text

Either TRUE (default) or FALSE. If TRUE titles and axis labels will automatically try and format pollutant names and units properly, e.g., by subscripting the "2" in "NO2". Passed to quickText().

ws_spread

The value of sigma used for Gaussian kernel weighting of wind speed when statistic = "nwr" or when correlation and regression statistics are used such as r. Default is 0.5.

wd_spread

The value of sigma used for Gaussian kernel weighting of wind direction when statistic = "nwr" or when correlation and regression statistics are used such as r. Default is 4.

x_error

The x error / uncertainty used when statistic = "york_slope".

y_error

The y error / uncertainty used when statistic = "york_slope".

kernel

Type of kernel used for the weighting procedure for when correlation or regression techniques are used. Only "gaussian" is supported but this may be enhanced in the future.

formula.label

When pair-wise statistics such as regression slopes are calculated and plotted, should a formula label be displayed? formula.label will also determine whether concentration information is printed when statistic = "cpf".

tau

The quantile to be estimated when statistic is set to "quantile.slope". Default is 0.5 which is equal to the median and will be ignored if "quantile.slope" is not used.

plot

When openair plots are created they are automatically printed to the active graphics device. plot = FALSE deactivates this behaviour. This may be useful when the plot data is of more interest, or the plot is required to appear later (e.g., later in a Quarto document, or to be saved to a file).

key

Deprecated; please use key.position. If FALSE, sets key.position to "none".

Removed. Please use type.

Input data table with pollutant, wind, and geo-spatial information.

required | scope: dynamic & static

A data frame. The data frame must contain the data to plot the directional analysis marker, which includes wind speed (ws), wind direction (wd), and the column representing the concentration of a pollutant. In addition, data must include a decimal latitude and longitude (or X/Y coordinate used in conjunction with crs).

Pollutant name(s).

required | scope: dynamic & static

The column name(s) of the pollutant(s) to plot. If multiple pollutants are specified and a non-pairwise statistic is supplied, the type argument will no longer be able to be used and:

• Dynamic: The pollutants can be toggled between using a "layer control" menu.

• Static: The pollutants will each appear in a different panel.

Multiple pollutants prohibit the use of the type argument for non-pairwise statistics.

The statistic to be applied to each data bin in the plot

default: "prop.mean" | scope: dynamic & static

Options currently include "prop.count", "prop.mean" and "abs.count". "prop.count" sizes bins according to the proportion of the frequency of measurements. Similarly, "prop.mean" sizes bins according to their relative contribution to the mean. "abs.count" provides the absolute count of measurements in each bin.

Specifier for the number of breaks of the colour axis.

default: NULL | scope: dynamic & static

Most commonly, the number of break points. If not specified, each marker will independently break its supplied data at approximately 6 sensible break points. When breaks are specified, all markers will use the same break points. Breaks can also be used to set specific break points. For example, the argument breaks = c(0, 1, 10, 100) breaks the data into segments <1, 1-10, 10-100, >100.

The decimal latitude(Y)/longitude(X).

default: NULL | scope: dynamic & static

Column names representing the decimal latitude and longitude (or other Y/X coordinate if using a different crs). If not provided, will be automatically inferred from data by looking for a column named "lat"/"latitude" or "lon"/"lng"/"long"/"longitude" (case-insensitively).

The coordinate reference system (CRS).

default: 4326 | scope: dynamic & static

The coordinate reference system (CRS) of the data, passed to sf::st_crs(). By default this is EPSG:4326, the CRS associated with the commonly used latitude and longitude coordinates. Different coordinate systems can be specified using crs (e.g., crs = 27700 for the British National Grid). Note that non-lat/lng coordinate systems will be re-projected to EPSG:4326 for plotting on the map.

A method to condition the data for separate plotting.

default: NULL | scope: dynamic & static