Skip to contents

freqMapStatic() creates a ggplot2 map using polar frequency plots as markers. As this function returns a ggplot2 object, further customisation can be achieved using functions like ggplot2::theme() and ggplot2::guides().


  pollutant = NULL,
  statistic = "mean",
  breaks = "free",
  latitude = NULL,
  longitude = NULL,
  crs = 4326,
  provider = "osm",
  facet = NULL,
  cols = "turbo",
  alpha = 1,
  key = FALSE,
  facet.nrow = NULL,
  d.icon = 150,
  d.fig = 3,



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.


The column name(s) of the pollutant(s) to plot. If multiple pollutants are specified, they will each form part of a separate panel.


The statistic that should be applied to each wind speed/direction bin. 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.


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.

latitude, longitude

The decimal latitude/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) 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.


The base map to be used. See rosm::osm.types() for a list of all base maps that can be used.


Used for splitting the input data into different panels, passed to the type argument of openair::cutData(). facet cannot be used if multiple pollutant columns have been provided.


The colours used for plotting. See openair::openColours() for more information.


The alpha transparency to use for the plotting surface (a value between 0 and 1 with zero being fully transparent and 1 fully opaque).


Should a key for each marker be drawn? Default is FALSE.


Passed to the nrow argument of ggplot2::facet_wrap().


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.


Arguments passed on to openair::polarFreq

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


Number of intervals of wind direction.


Radial spacing of grid lines.


Should a transformation be applied? Sometimes when producing plots of this kind they can be dominated by a few high points. The default therefore is TRUE and a square-root transform is applied. This results in a non-linear scale and (usually) a better representation of the distribution. If set to FALSE a linear scale is used.


type determines how the data are split i.e. conditioned, and then plotted. The default is will produce a single plot using the entire data. Type can be one of the built-in types as detailed in cutData e.g. “season”, “year”, “weekday” and so on. For example, type = "season" will produce four plots --- one for each season.

It is also possible to choose type as another variable in the data frame. If that variable is numeric, then the data will be split into four quantiles (if possible) and labelled accordingly. If type is an existing character or factor variable, then those categories/levels will be used directly. This offers great flexibility for understanding the variation of different variables and how they depend on one another.

Type can be up length two e.g. type = c("season", "weekday") will produce a 2x2 plot split by season and day of the week. Note, when two types are provided the first forms the columns and the second the rows.


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.


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 = 10.


offset controls the size of the ‘hole’ in the middle and is expressed as a percentage of the maximum wind speed. Setting a higher offset e.g. 50 is useful for statistic = "weighted.mean" when is greater than the maximum wind speed. See example below.


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


Adds additional text/labels to the scale key. For example, passing the options key.header = "header", key.footer = "footer1" adds addition text above and below the scale key. These arguments are passed to drawOpenKey via quickText, applying the auto.text argument, to handle formatting.


see key.footer.


Location where the scale key is to plotted. Allowed arguments currently include "top", "right", "bottom" and "left".


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.


a ggplot2 plot with a ggspatial basemap

Further customisation using ggplot2

As the outputs of the static directional analysis functions are ggplot2 figures, further customisation is possible using functions such as ggplot2::theme(), ggplot2::guides() and ggplot2::labs().

If multiple pollutants are specified, subscripting (e.g., the "x" in "NOx") is achieved using the ggtext package. Therefore if you choose to override the plot theme, it is recommended to use [ggplot2::theme()] and [ggtext::element_markdown()] to define the strip.text parameter.

When arguments like limits, percentile or breaks are defined, a legend is automatically added to the figure. Legends can be removed using ggplot2::theme(legend.position = "none"), or further customised using ggplot2::guides() and either color = ggplot2::guide_colourbar() for continuous legends or fill = ggplot2::guide_legend() for discrete legends.

See also

the original openair::polarFreq()

freqMap() for the interactive leaflet equivalent of freqMapStatic()

Other static directional analysis maps: annulusMapStatic(), diffMapStatic(), percentileMapStatic(), polarMapStatic(), pollroseMapStatic(), windroseMapStatic()