Combine dynamic and static polar plotting functions

.gitignore

@@ -6,3 +6,4 @@ ggmapTemp.png
 .DS_Store
 CRAN-SUBMISSION
 docs
+rosm.cache/

DESCRIPTION

@@ -31,13 +31,15 @@ Imports:
     openair (>= 2.13),
     purrr (>= 1.0.0),
     rlang,
+    rosm,
     sf,
     stringr,
     tibble,
     tidyr
 Suggests:
     httr,
     jsonlite,
+    shiny,
     worldmet
 Encoding: UTF-8
 Language: en-GB

NAMESPACE

@@ -29,5 +29,6 @@ export(windroseMap)
 export(windroseMapStatic)
 importFrom(lifecycle,deprecated)
 importFrom(magrittr,"%>%")
+importFrom(rlang,"%||%")
 importFrom(rlang,.data)
 importFrom(tibble,tibble)

NEWS.md

@@ -2,13 +2,27 @@
 
 ## Breaking changes
 
-* BREAKING: The `polarMapStatic()` family is now powered by `{ggspatial}` rather than `{ggmap}` as it does not require an API key. This means the `ggmap` argument has been removed and the `provider` argument has been added.
+* BREAKING: The `polarMapStatic()` family is now powered by `{ggspatial}` rather than `{ggmap}` as it does not require an API key. This means the `ggmap` argument has been removed and the `provider` argument has been added. Other benefits of this switch include a greater number of available base maps (see: `rosm::osm.types()`) and the ability to simply change the extent of the map axes using `ggplot2::coord_sf()`.
+
+* BREAKING: The `control` and `facet` arguments have been deprecated in favour of `type` in all functions. These arguments will eventually be removed, but as of this version of `{openairmaps}` users will be warned away from their use. This brings `{openairmaps}` in-line with the `{openair}` package.
+
+* BREAKING: The `names` and `cols` arguments of `buildPopup()` have been coalesced into a single `columns` argument for less verbose function usage.
 
 ## New features
 
+* The `polarMapStatic()` family of functions have been combined with the `polarMap()` family, with static maps available to be accessed using the `static` argument. The `polarMapStatic()` family are therefore deprecated, and will later be removed from `{openairmaps}`. The justification for this is as follows:
+
+    * The combined functions allows for a more simple, consistent API for users (e.g., avoiding needing to switch between `facet` and `control`).
+
+    * The use of the `static` argument allows for simple switching between dynamic and static maps. For example, a researcher may wish to use the dynamic maps for data exploration, but then switch to a static map for placement into a PDF report.
+
+    * Recent developments have meant that the arguments and capability of these functions have started to align regardless (e.g., `provider`, `crs`).
+
+    * Combining these functions has reduced repetition in the source code of `{openairmaps}`, reducing the likelihood of oversights and bugs, and allowing for more rapid development.
+
 * The `crs` argument has been added to the `polarMap()` and `polarMapStatic()` families and to `searchNetwork()`. This argument allows for users to specify that their data is using an alternative coordinate system to the standard longitude/latitude (e.g., the British National Grid CRS). Alternate CRS will be re-projected to longitude/latitude for plotting as this is expected by `{leaflet}` / `{ggspatial}`.
 
-* Popups for the `polarMap()` family will now be near the top of the plot rather than the centre. This will obscure less of the plot itself while the marker is visible.
+* Popups for the dynamic `polarMap()` family will now be near the top of the plot rather than the centre. This will obscure less of the plot itself while the marker is visible.
 
 * Two examples of the use of `{openairmaps}` with `{shiny}` have been added to the package. Run `shiny::runExample(package = "openairmaps")` to view these.
 
@@ -20,7 +34,7 @@
 
     * `layerId` is now the base on which the actual layerId is built, with each real layerId in the form BASE-LN-PN where LN is the line number and PN is the point number. For example, if `layerId = "traj"`, the first point of the first line has the ID `"traj-1-1"`, the second point of the first line has ID `"traj-1-2"`, the first point of the second line has ID `"traj-2-1"`, and so on.
 
-* "illegal" filepath characters can now be used in the columns provided to the `type` argument of the `polarMap()` family. Most relevant to most users is that this will allow them to provide their own custom HTML tags - e.g., for formatting superscripts, subscripts, and so on.
+* "illegal" file path characters can now be used in the columns provided to the `type` argument of the `polarMap()` family. Most relevant to most users is that this will allow them to provide their own custom HTML tags - e.g., for formatting superscripts, subscripts, and so on.
 
 # openairmaps 0.8.1
 

R/addPolarMarkers.R

@@ -37,7 +37,7 @@
 #'   non-circular marker is desired.
 #' @param ... Other arguments for the plotting function (e.g. `period` for
 #'   [openair::polarAnnulus()]).
-#' @return A leaflet object.
+#' @returns A leaflet object.
 #' @seealso `shiny::runExample(package = "openairmaps")` to see examples of this
 #'   function used in a [shiny::shinyApp()]
 #' @describeIn addPolarMarkers Add any one-table polar marker (e.g.,

R/addTrajPaths.R

@@ -47,7 +47,7 @@
 #'   [leaflet::addPolylines()] (i.e., use `color = ~ pal(nox)[1]`). Note that
 #'   `opacity` controls the opacity of the lines and `fillOpacity` the opacity
 #'   of the markers.
-#' @return A leaflet object.
+#' @returns A leaflet object.
 #' @seealso `shiny::runExample(package = "openairmaps")` to see examples of this
 #'   function used in a [shiny::shinyApp()]
 #' @export
@@ -109,7 +109,7 @@ addTrajPaths <-
     )
 
     for (i in seq(length(unique(data$datef)))) {
-      layerid = paste(layerId, i, sep = "-")
+      layerid <- paste(layerId, i, sep = "-")
 
       # get line/points data
       ldata <- dplyr::filter(data, .data$datef == unique(data$datef)[[i]])

R/network_networkMap.R

@@ -21,30 +21,81 @@
 #' "aurn")` and the "AURN" layer control group when `source = c("aurn",
 #' "saqn")`.
 #'
-#' @inheritParams openair::importMeta
 #'
-#' @param control Option to add a "layer control" menu to allow readers to
-#'   select between different site types. Can choose between effectively any
-#'   column in the [openair::importMeta()] output, such as `"variable"`,
-#'   `"site_type"`, or `"agglomeration"`, as well as `"network"` when more than
-#'   one `source` was specified.
-#' @param year By default, [networkMap()] visualises sites which are currently
+#' @param source *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.
+#'    - `"kcl"`, 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").
+#'
+#' @param control *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:
+#'   - `"variable"` to toggle between different pollutants
+#'   - `"site_type"` for different site classifications
+#'   - `"agglomeration"`, `"zone"` or `"local_authority"` for different regions of the UK
+#'   - `"network"` for different monitoring networks, if more than one `source` is provided.
+#'
+#' @param year *A year, or range of years, with which to filter data.*
+#'
+#'  *default*: `NULL`
+#'
+#'   By default, [networkMap()] visualises sites which are currently
 #'   operational. `year` allows users to show sites open in a specific year, or
 #'   over a range of years. See [openair::importMeta()] for more information.
-#' @param cluster When `cluster = TRUE`, markers are clustered together. This
-#'   may be useful for sources like "kcl" where there are many markers very
-#'   close together. Defaults to `TRUE`, and is forced to be `TRUE` when `source
-#'   = "europe"` due to the large number of sites.
-#' @param provider The base map(s) to be used. See
+#'
+#' @param cluster *Cluster markers together when zoomed out?*
+#'
+#'  *default:* `FALSE`
+#'
+#'   When `cluster = TRUE`, markers are clustered together. This may be useful
+#'   for sources like "kcl" where there are many markers very close together.
+#'   Defaults to `TRUE`, and is forced to be `TRUE` when `source = "europe"` due
+#'   to the large number of sites.
+#'
+#' @param provider *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.
-#' @param draw.legend When multiple `source`s are specified, should a legend be
-#'   created at the side of the map? Default is `TRUE`.
-#' @param collapse.control Should the "layer control" interface be collapsed?
-#'   Defaults to `FALSE`.
+#'   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")`)
+#'
+#' @param draw.legend *Draw a shared legend?*
+#'
+#'  *default:* `TRUE` | *scope:* dynamic & static
+#'
+#'   When multiple `source`s are defined, should a shared legend be created at
+#'   the side of the map?
+#'
+#' @param collapse.control *Show the layer control as a collapsed?*
+#'
+#'  *default:* `FALSE` | *scope:* dynamic
+#'
+#'   Should the "layer control" interface be collapsed? If `TRUE`, users will
+#'   have to hover over an icon to view the options.
 #'
-#' @return A leaflet object.
+#' @returns A leaflet object.
 #' @export
 #' @family uk air quality network mapping functions
 #'

R/network_searchNetwork.R

@@ -10,34 +10,60 @@
 #' first `source` and `year`, then `site_type` and `variable`, then `max_dist`,
 #' and finally `n`.
 #'
-#' @inheritParams openair::importMeta
-#'
-#' @param lat,lng The decimal latitude/longitude (or other Y/X coordinate if
-#'   using a different `crs`) for the location of interest. If not provided,
-#'   will be automatically inferred from data by looking for a column named
-#'   "lat"/"latitude" or "lon"/"lng"/"long"/"longitude" (case-insensitively).
-#' @param crs The coordinate reference system (CRS) of `lat`/`lng`, passed to
-#'   [sf::st_crs()]. By default this is [EPSG:4326](https://epsg.io/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](https://epsg.io/27700)). Note that
-#'   non-lat/lng coordinate systems will be re-projected to EPSG:4326 for
-#'   plotting on the map.
-#' @param site_type Optional. One or more site types with which to subset the
-#'   site metadata. For example, `site_type = "urban background"` will only
-#'   search urban background sites.
-#' @param variable Optional. One or more variables of interest with which to
-#'   subset the site metadata. For example, `variable = c("pm10", "co")` will
-#'   search sites that measure PM10 and/or CO.
-#' @param max_dist Optional. A maximum distance from the location of interest in
-#'   kilometres.
-#' @param n Optional. The maximum number of sites to return.
-#' @param map If `TRUE`, the default, [searchNetwork()] will return a `leaflet`
-#'   map. If `FALSE`, it will instead return a [tibble][tibble::tibble-package].
+#' @inheritParams networkMap
+#' @inheritParams polarMap
+#'
+#' @param lat,lng *The decimal latitude(Y)/longitude(X).*
+#'
+#'  **required**
+#'
+#'   Values representing the decimal latitude and longitude (or other Y/X
+#'   coordinate if using a different `crs`) of the site of interest.
+#'
+#' @param site_type *One or more site types with which to subset the site
+#'   metadata.*
+#'
+#'  *default:* `NULL`
+#'
+#'   If `site_type` is specified, only sites of that type will be searched for.
+#'   For example, `site_type = "urban background"` will only search urban
+#'   background sites.
+#'
+#' @param variable *One or more variables of interest with which to subset the
+#'   site metadata.*
+#'
+#'   *default:* `NULL`
+#'
+#'   If `variable` is specified, only sites measuring at least one of these
+#'   pollutants will be searched for. For example, `variable = c("pm10", "co")`
+#'   will search sites that measure PM10 and/or CO.
+#'
+#' @param max_dist *A maximum distance from the location of interest in
+#'   kilometres.*
+#'
+#'   *default:* `NULL`
+#'
+#'   If `max_dist` is specified, only sites within `max_dist` kilometres from
+#'   the `lat` / `lng` coordinate will be searched for.
+#'
+#' @param n *The maximum number of sites to return.*
+#'
+#'    *default:* `NULL`
+#'
+#'   If `n` is specified, only `n` sites will be returned. Note that this
+#'   filtering step is applied last, after `site_type`, `variable`, and
+#'   `max_dist`.
+#'
+#' @param map *Return a map?*
+#'
+#'    *default:* `TRUE`
+#'
+#'   If `TRUE`, the default, [searchNetwork()] will return a `leaflet` map. If
+#'   `FALSE`, it will instead return a [tibble][tibble::tibble-package].
 #'
 #' @order 2
 #'
-#' @return Either a [tibble][tibble::tibble-package] or `leaflet` map.
+#' @returns Either a [tibble][tibble::tibble-package] or `leaflet` map.
 #' @export
 #' @family uk air quality network mapping functions
 #'

R/openairmaps-package.R

@@ -40,6 +40,7 @@
 
 ## usethis namespace: start
 #' @importFrom lifecycle deprecated
+#' @importFrom rlang %||%
 #' @importFrom rlang .data
 #' @importFrom tibble tibble
 ## usethis namespace: end