Merge pull request #46 from davidcarslaw/feat/refine-markers

Feat/refine markers

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: openairmaps
 Title: Create Maps of Air Pollution Data
-Version: 0.8.0.9001
+Version: 0.8.0.9002
 Authors@R: c(
     person("Jack", "Davison", , "jack.davison@ricardo.com", role = c("cre", "aut")),
     person("David", "Carslaw", , "david.carslaw@york.ac.uk", role = "aut")

NEWS.md

@@ -2,21 +2,27 @@
 
 These are items associated with the development version of `{openairmaps}`.
 
+## Breaking changes
+
+* BREAKING: The arguments of `addPolarMarkers()` have been rejigged to move "data" after "pollutant", owing to the new use of `leaflet::getMapData()` (#45).
+
 ## New features
 
-* `networkMap()` popups now contain links to the associated network websites. For example, the popup for London Marylebone Road in `networkMap("aurn")` now contains a link to <https://uk-air.defra.gov.uk/networks/site-info?site_id=MY1>. All networks are supported with the exception of "europe".
+* The "data" argument of `addPolarMarkers()` and `addTrajPaths()` and both the "before" and "after" arguments of `addPolarDiffMarkers()` now default to `leaflet::getMapData(map)`. This makes their use less verbose when creating multiple polar plots with the same underlying data, which will likely be a common use-case (#45).
+
+* `networkMap()` popups now contain links to the associated network websites. For example, the popup for London Marylebone Road in `networkMap("aurn")` now contains a link to <https://uk-air.defra.gov.uk/networks/site-info?site_id=MY1>. All networks are supported with the exception of "europe" (#39).
 
-* `addPolarMarkers()` and `addPolarDiffMarkers()` now have all of the "options" arguments of `leaflet::addMarkers()`. This means that, for example, polar markers can be clustered (<https://leafletjs.com/reference.html#marker>).
+* `addPolarMarkers()` and `addPolarDiffMarkers()` now have all of the "options" arguments of `leaflet::addMarkers()`. This means that, for example, polar markers can be clustered (<https://leafletjs.com/reference.html#marker>) (#38).
 
-* The `polarMap()` family and `networkMap()` `provider` argument can now take a named vector. The names will be used in the layer control menu, if `length(provider) > 1`.
+* The `polarMap()` family and `networkMap()` `provider` argument can now take a named vector. The names will be used in the layer control menu, if `length(provider) > 1` (#42).
 
 # openairmaps 0.8.0
 
 This is a minor release adding a range of quality of life features, adding two new experimental functions, and fixing a few bugs.
 
 ## New features
 
-* `trajMapStatic()` and `trajLevelMapStatic()` have been added as two new *experimental* functions to provide `{ggplot2}` equivalents of `openair::trajPlot()` and `openair::trajLevel()`. 
+* `trajMapStatic()` and `trajLevelMapStatic()` have been added as two new *experimental* functions to provide `{ggplot2}` equivalents of `openair::trajPlot()` and `openair::trajLevel()` (#28). 
 
   * These are experimental as the long term place for these functions is uncertain; there will definitely be need for a `{ggplot2}` incarnation of the trajectory plotting functions, but whether they will sit in `{openair}`, `{ggopenair}` or `{openairmaps}` and what they will be named is not clear.
 
@@ -26,15 +32,15 @@ This is a minor release adding a range of quality of life features, adding two n
 
 * `trajLevelMap()` now has the `control` argument, which maps directly onto the `type` argument of `openair::trajLevel()`. Like other `control` arguments elsewhere in `{openairmaps}`, this creates a "layer control" menu.
 
-* `networkMap()` now uses different coloured markers for different networks. If more than one network is specified, and `draw.legend` is set to `TRUE`, a legend will also be drawn for quick identification of different data sources.
+* `networkMap()` now uses different coloured markers for different networks. If more than one network is specified, and `draw.legend` is set to `TRUE`, a legend will also be drawn for quick identification of different data sources (#30).
 
 * Deprecations are now managed by the `{lifecycle}` package. This currently only applies to the `type` argument.
 
 ## Bug fixes
 
 * Fixed issues where multiple `addPolarMarkers()` chained together would all show the same plot.
 
-* Fixed issue where `...` and `pollutant` weren't being passed to `addPolarMarkers()`.
+* Fixed issue where `...` and `pollutant` weren't being passed to `addPolarMarkers()` (#27).
 
 * Fixed issue in `trajMap()` caused by recent updates to `{dplyr}` and `{forcats}`.
 
@@ -58,21 +64,21 @@ This is a minor release containing several important new features that expand th
 
 * BREAKING: The arguments in `addPolarMarkers()` have been put in a more sensible order, leading with `data`, `pollutant` and `fun`.
 
-* BREAKING: The `date` argument from `networkMap()` has been replaced by `year`.
+* BREAKING: The `date` argument from `networkMap()` has been replaced by `year` (#26).
 
 ## New features
 
-* Added "static" equivalents of all of the polar marker maps written in `{ggplot2}`. While interactive HTML maps are preferred, the static equivalents may be more appropriate for, e.g., academic publications.
+* Added "static" equivalents of all of the polar marker maps written in `{ggplot2}`. While interactive HTML maps are preferred, the static equivalents may be more appropriate for, e.g., academic publications (#19).
 
   * The `{ggplot2}` functions can be identified by "Static" being appended to the function name. For example, `polarMap()` is the `{leaflet}` polar plot map, whereas `polarMapStatic()` is the `{ggplot2}` equivalent.
 
   * Currently, "static" versions of the trajectory maps are served by `openair::trajPlot()` and `openair::trajLevel()`, but there may be space in future to have `ggmap` equivalents of these in `openairmaps`.
 
-* Added `diffMap()` and `diffMapStatic()` which are to `openair::polarDiff()` what `polarMap()` and `polarMapStatic()` are to `openair::polarPlot()`. Also added `addPolarDiffMarkers()`, which is the equivalent of `addPolarMarkers()`.
+* Added `diffMap()` and `diffMapStatic()` which are to `openair::polarDiff()` what `polarMap()` and `polarMapStatic()` are to `openair::polarPlot()` (#17). Also added `addPolarDiffMarkers()`, which is the equivalent of `addPolarMarkers()` (#25).
 
-* Added `alpha` as an argument to all of the directional analysis polar mapping functions, not just `polarMap()`.
+* Added `alpha` as an argument to all of the directional analysis polar mapping functions, not just `polarMap()` (#14).
 
-* Fixed `alpha` to work on both Windows and MacOS by forcing the use of the "cairo" device to save plots.
+* Fixed `alpha` to work on both Windows and MacOS by forcing the use of the "cairo" device to save plots (#14).
 
 * Polar marker maps and `addPolarMarkers()` now show a progress bar when creating the markers takes more than a few seconds (most commonly in `polarMap()` and `annulusMap()`, particularly with multiple pollutants/control groups).
 
@@ -90,7 +96,7 @@ This is a patch release primarily to fix a few bugs in `{openairmaps}`, and impl
 
 ## Bug fixes
 
-* Fixed issue with polar marker maps (e.g., `polarMap()`) and the generic `addPolarMarkers()` function where lat/lon info in the Southern Hemisphere would misalign markers. Hat tip to Deanna Tuxford and James/"@jenright-git" for noticing this issue.
+* Fixed issue with polar marker maps (e.g., `polarMap()`) and the generic `addPolarMarkers()` function where lat/lon info in the Southern Hemisphere would misalign markers. Hat tip to Deanna Tuxford and James (#18) for noticing this issue.
 
 * Fixed an issue with `networkMap()` where `control = "variable"` would fail to show all pollutants.
 
@@ -102,15 +108,15 @@ This is a minor release, mainly focusing on enhancing the ability for polar mark
 
 ## New features
 
-* All directional analysis maps can now have their limits provided (can be "limits", "breaks", "percentiles", etc., depending on function). This was always possible through `...`, but it is now explicitly listed as an option.
+* All directional analysis maps can now have their limits provided (can be "limits", "breaks", "percentiles", etc., depending on function). This was always possible through `...`, but it is now explicitly listed as an option (#12).
 
-* If limits are defined in a directional analysis function, a shared legend will now be drawn at the top-right of the map. This functionality can be disabled by setting `draw.legend` to FALSE.
+* If limits are defined in a directional analysis function, a shared legend will now be drawn at the top-right of the map. This functionality can be disabled by setting `draw.legend` to FALSE (#12).
 
 * Added the `buildPopup()` function, which allows users to easily construct HTML popups for use with the "popup" argument of directional analysis maps (or `leaflet` maps more widely).
 
 * The default options for fig.width and fig.height are now `3.5` rather than `4`. This appears to remove some visual artefacts and makes the axis labels more legible.
 
-* `networkMap()` now supports multiple sources. For example, using `source = c("aurn", "saqn")` will show both the AURN and SAQN on one map. This may be useful if users are interested in air quality in a specific region of the UK (e.g., users may wish to locate AURN, AQE *and* locally managed sites near to a given urban centre).
+* `networkMap()` now supports multiple sources. For example, using `source = c("aurn", "saqn")` will show both the AURN and SAQN on one map. This may be useful if users are interested in air quality in a specific region of the UK (e.g., users may wish to locate AURN, AQE *and* locally managed sites near to a given urban centre) (#16).
 
 * `networkMap()` now supports `source = "local"`.
 
@@ -142,17 +148,17 @@ This is a minor release centred around the addition of the `control` argument, w
 
 ## Breaking changes
 
-* All functions now use latitude and longitude to distinguish between site types. Therefore, "type" is now deprecated. Maps using the old system will still render, but popups will not be displayed. For most users, to restore previous site labels simply rewrite `type = "site"` as `popup = "site"`.
+* All functions now use latitude and longitude to distinguish between site types. Therefore, "type" is now deprecated. Maps using the old system will still render, but popups will not be displayed. For most users, to restore previous site labels simply rewrite `type = "site"` as `popup = "site"` (#10).
 
 * The default values for "pollutant" have all been removed. Any users relying on this default should update their code to explicitly state `pollutant = "nox"`.
 
 ## New features
 
-* All functions now possess the "control" argument, which allows users to create a "layer control" menu with any arbitrary column. Appropriate columns may be those produced using `openair::cutData()`, `openair::splitByDate()`, or a user-defined `dplyr::case_when()`/`dplyr::if_else()` column transformation.
+* All functions now possess the "control" argument, which allows users to create a "layer control" menu with any arbitrary column. Appropriate columns may be those produced using `openair::cutData()`, `openair::splitByDate()`, or a user-defined `dplyr::case_when()`/`dplyr::if_else()` column transformation (#9).
 
-* All functions now possess the "popup" and "label" arguments, which control pop-up and hover-over labels, respectively. This allows users to define *any* popup or label column, even non-unique ones. For example, multiple sites can be labelled with identical site types.
+* All functions now possess the "popup" and "label" arguments, which control pop-up and hover-over labels, respectively. This allows users to define *any* popup or label column, even non-unique ones. For example, multiple sites can be labelled with identical site types (#10).
 
-* All functions now try to guess the latitude/longitude column if not provided, similar to `{leaflet}`.
+* All functions now try to guess the latitude/longitude column if not provided, similar to `{leaflet}` (#10).
 
 * Updated many error messages and warnings to use `{cli}` and be broadly more descriptive.
 

R/addPolarMarkers.R

@@ -12,7 +12,8 @@
 #'   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.
+#'   latitude and longitude. By default, it is the data object provided to
+#'   [leaflet::leaflet()] initially, but can be overridden.
 #' @param pollutant The name of the pollutant to be plot. Note that, if `fun =
 #'   openair::windRose`, you must set `pollutant = "ws"`.
 #' @param fun An `openair` directional analysis plotting function. Supported
@@ -47,36 +48,30 @@
 #' library(openair)
 #'
 #' # different types of polar plot on one map
-#' leaflet() %>%
+#' leaflet(data = polar_data) %>%
 #'   addTiles() %>%
-#'   addPolarMarkers(
-#'     data = polar_data,
-#'     pollutant = "ws",
-#'     fun = windRose,
+#'   addPolarMarkers("ws",
+#'     fun = openair::windRose,
 #'     group = "Wind Rose"
 #'   ) %>%
-#'   addPolarMarkers(
-#'     data = polar_data,
-#'     pollutant = "nox",
-#'     fun = polarPlot,
+#'   addPolarMarkers("nox",
+#'     fun = openair::polarPlot,
 #'     group = "Polar Plot"
 #'   ) %>%
 #'   addLayersControl(
 #'     baseGroups = c("Wind Rose", "Polar Plot")
 #'   )
 #'
-#' # use of polar diff
-#' leaflet() %>%
+#' # use of polar diff (NB: both 'before' and 'after' inherit from `leaflet()`,
+#' # so at least one should be overridden - in this case 'after')
+#' leaflet(data = polar_data) %>%
 #'   addTiles() %>%
-#'   addPolarDiffMarkers(
-#'     before = polar_data,
-#'     after = dplyr::mutate(polar_data, nox = jitter(nox, 5)),
-#'     pollutant = "nox"
+#'   addPolarDiffMarkers("nox",
+#'     after = dplyr::mutate(polar_data, nox = jitter(nox, 5))
 #'   )
 #' }
 addPolarMarkers <-
   function(map,
-           data,
            pollutant,
            fun = openair::polarPlot,
            lng = NULL,
@@ -93,6 +88,7 @@ addPolarMarkers <-
            key = FALSE,
            d.icon = 200,
            d.fig = 3.5,
+           data = leaflet::getMapData(map),
            ...) {
     # guess lat/lon
     latlon <- assume_latlon(
@@ -181,14 +177,18 @@ addPolarMarkers <-
   }
 
 #' @inheritParams diffMap
+#' @param before,after 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.
 #' @describeIn addPolarMarkers Add the two-table [openair::polarDiff()] marker.
 #' @order 2
 #' @export
 addPolarDiffMarkers <-
   function(map,
-           before,
-           after,
            pollutant,
+           before = leaflet::getMapData(map),
+           after = leaflet::getMapData(map),
            lng = NULL,
            lat = NULL,
            layerId = NULL,

R/addTrajPaths.R

@@ -31,7 +31,8 @@
 #'   identifier-style names. Any number of layers and even different types of
 #'   layers (e.g. markers and polygons) can share the same group name.
 #' @param data Data frame, the result of importing a trajectory file using
-#'   [openair::importTraj()].
+#'   [openair::importTraj()]. By default, it is the data object provided to
+#'   [leaflet::leaflet()] initially, but can be overridden.
 #' @param npoints 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
@@ -74,7 +75,7 @@ addTrajPaths <-
            lat = "lat",
            layerId = NULL,
            group = NULL,
-           data,
+           data = leaflet::getMapData(map),
            npoints = 12,
            ...) {
     # check opts