Merge pull request #130 from ropensci/dev

Dev

Author: HadleyBN

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: fingertipsR
 Type: Package
-Version: 1.0.13
+Version: 1.1.0
 Title: Fingertips Data for Public Health
 Description: Fingertips (<http://fingertips.phe.org.uk/>) contains data for many indicators of public health in England. The underlying data is now more easily accessible by making use of the API.
 Maintainer: Sam Dunn <[email protected]>
@@ -17,6 +17,7 @@ Authors@R: c(
     person("David", "Whiting", , "[email protected]", c("ctb")),
     person("Luke", "Bradley", , "[email protected]", c("ctb")),
     person("Samuel", "Cutler", , "[email protected]", c("ctb")),
+    person("Thilaksan", "Vikneswaran", , "[email protected]", c("ctb")),
     person("Crown Copyright 2020", , , , c("cph")))
 URL: https://fingertips.phe.org.uk, 
     https://github.com/ropensci/fingertipsR, 

NEWS.md

@@ -1,3 +1,12 @@
+# fingertipsR 1.1.0 (2025-10-10)
+
+* Updated the description of the nearest_neighbours function, and removed the measure variable that was previously deprecated. 
+* Added checks to handle cases where no data is available for the specified combination of parameters in `fingertips_data()`.
+* When no data is available and `rank = TRUE`, the function now returns an empty data frame with `Polarity`, `Rank`, and `AreaValuesCount` columns set to `NA`.
+* Improved error message to inform users that no data is available and an empty data frame is returned.
+* Updated examples. 
+* Updated area_types() function to use the short name in the API rather than the long name 
+
 # fingertipsR 1.0.13 (2025-05-29)
 
 * no change for users. Package tests updated.

R/area_types.R

@@ -19,15 +19,15 @@
 #' area_types()
 #'
 #' # Returns a data frame of county and unitary authority mappings
-#'  area_types("counties")
+#' area_types("counties")
 #'
 #' # Returns a data frame of both counties, district
 #' # and unitary authorities and their respective mappings
-#' areas <- c("counties","district")
+#' areas <- c("counties", "district")
 #' area_types(areas)
 #'
 #' # Uses AreaTypeID to filter area types
-#' area_types(AreaTypeID = 152)}
+#' area_types(AreaTypeID = 7)}
 #' @import dplyr
 #' @importFrom stats complete.cases
 #' @importFrom rlang .data
@@ -55,7 +55,7 @@ area_types  <- function(AreaTypeName = NULL, AreaTypeID = NULL, ProfileID = NULL
           proxy_settings = proxy_settings)
         parentAreas <- paste0(path,"area_types/parent_area_types") %>%
                 get_fingertips_api(proxy_settings = proxy_settings)
-        area_types <- parentAreas[,c("Id", "Name")]
+        area_types <- parentAreas[,c("Id", "Short")]
         names(area_types) <- c("AreaTypeID","AreaTypeName")
         parentAreasNoNames <- parentAreas$ParentAreaTypes
         names(parentAreasNoNames) <- parentAreas$Id
@@ -65,7 +65,7 @@ area_types  <- function(AreaTypeName = NULL, AreaTypeID = NULL, ProfileID = NULL
                 select(
                   AreaTypeID = "t",
                   ParentAreaTypeID = "Id",
-                  ParentAreaTypeName = "Name") %>%
+                  ParentAreaTypeName = "Short") %>%
                 mutate(AreaTypeID = as.numeric(.data$AreaTypeID),
                        ParentAreaTypeID = as.numeric(.data$ParentAreaTypeID))
         area_types <- left_join(area_types, parentAreas, by = c("AreaTypeID" = "AreaTypeID")) %>%
@@ -153,7 +153,7 @@ category_types <- function(proxy_settings = fingertips_proxy_settings(),
 #' @import dplyr
 #' @examples
 #' \dontrun{
-#' indicator_areatypes(IndicatorID = 10101)}
+#' indicator_areatypes(IndicatorID = 90362)}
 #' @export
 #' @family lookup functions
 #' @seealso \code{\link{indicators}} for indicator lookups,
@@ -196,35 +196,38 @@ indicator_areatypes <- function(IndicatorID, AreaTypeID,
 
 #' Nearest neighbours
 #'
-#' Outputs a character vector of similar areas for given area. Currently returns
-#' similar areas for Clinical Commissioning Groups (old and new) based on
-#' \href{https://www.england.nhs.uk/publication/similar-10-ccg-explorer-tool/}{NHS
-#' England's similar CCG explorer tool} or lower and upper tier local
-#' authorities based on
+#' Outputs a character vector of similar areas for a given area.\cr\cr**Details**\cr
+#' - For new upper tier local authorities (post 4/23) the
+#' \href{https://github.com/NHSDigital/ASC_LA_Peer_Groups}{NHSE Nearest Neighbours
+#' Model} is used.
+#' - All other local authorities types (lower tier and older upper tier) use the
 #' \href{https://www.cipfastats.net/resources/nearestneighbours/}{CIPFA's
-#' Nearest Neighbours Model} or upper tier local authorities based on
+#' Nearest Neighbours Model}. Older local authority geography types will use
+#' older versions of the model.
+#' - Similar areas for Clinical Commissioning Groups are based on
+#' \href{https://www.england.nhs.uk/publication/similar-10-ccg-explorer-tool/}{NHS
+#' England's similar CCG explorer tool}.
+#' - Currently the function does not have the ability to use the method from the
 #' \href{https://www.gov.uk/government/publications/local-authority-interactive-tool-lait}{Children's
-#' services statistical neighbour benchmarking tool}
+#' services statistical neighbour benchmarking tool}.
+#' @md
 #'
 #' @return A character vector of area codes
 #' @param AreaTypeID AreaTypeID of the nearest neighbours (see
 #'   \code{\link{nearest_neighbour_areatypeids}}) for available IDs
-#' @param measure deprecated. Previously a string; when AreaTypeID = 102 measure
-#'   must be either "CIPFA" for CIPFA local authority nearest neighbours or
-#'   "CSSN" for Children's services statistical neighbours
 #' @inheritParams fingertips_data
 #' @inheritParams area_types
 #' @import dplyr
 #' @importFrom utils head
 #' @importFrom rlang .data
 #' @examples
 #' \dontrun{
-#' nearest_neighbours(AreaCode = "E38000002", AreaTypeID = 154)}
+#' nearest_neighbours(AreaCode = "E09000004", AreaTypeID = 502)}
 #' @export
 #' @family lookup functions
 #' @seealso \code{\link{nearest_neighbour_areatypeids}} for the AreaTypeIDs
 #'   available for this function
-nearest_neighbours <- function(AreaCode, AreaTypeID, measure,
+nearest_neighbours <- function(AreaCode, AreaTypeID,
                                proxy_settings = fingertips_proxy_settings(), path) {
 
         if (missing(path)) path <- fingertips_endpoint()
@@ -264,10 +267,6 @@ nearest_neighbours <- function(AreaCode, AreaTypeID, measure,
                 stop("AreaTypeID not found. Use function `nearest_neighbour_areatypeids()` to see available AreaTypeIDs.")
         }
 
-        if (!(missing(measure))) {
-                warning("Measure argument is now deprecated.")
-        }
-
         ParentAreaTypeID <- area_types(AreaTypeID = AreaTypeID) %>%
                 pull("ParentAreaTypeID") %>%
                 head(1)

R/deprivation_decile.R

@@ -16,8 +16,8 @@
 #' @inheritParams area_types
 #' @examples
 #' \dontrun{
-#' # Return 2019 deprivation scores for Sustainability and Transformation Footprints
-#' deprivation_decile(120, 2019)}
+#' # Return 2019 deprivation scores for Upper tier local authorities (post 4/23)
+#' deprivation_decile(502, 2019)}
 #' @return A lookup table providing deprivation decile and area code
 #' @import dplyr
 #' @importFrom rlang .data

R/enhancements.R

@@ -13,7 +13,7 @@
 #' @examples
 #' \dontrun{
 #' # Returns data for the two selected domains at county and unitary authority geography
-#' reddata <- fingertips_redred(ProfileID = 26, AreaTypeID = 102)}
+#' reddata <- fingertips_redred(ProfileID = 26, AreaTypeID = 502)}
 #' @family data extract functions
 #' @export
 

R/fingertipsR.R

@@ -10,6 +10,6 @@
 #' @section Data extract functions: Using ID codes as inputs, the data extract
 #'   functions allow the user to extract data from the Fingertips API.
 #'
-#' @docType package
+#' @docType _PACKAGE
 #' @name fingertipsR
 NULL

R/fingertips_data.R

@@ -8,6 +8,9 @@
 #' @details Note, polarity of an indicator is not automatically returned (eg,
 #'   whether a low value is good, bad or neither). Use the rank field for this
 #'   to be returned (though it adds a lot of time to the query)
+#'
+#'   Some indicators may have different comparisons due to indicator polarity differences between profiles on the website.
+#'   It is recommended to check the website to ensure consistency between your data extract here and the polarity required
 #' @inheritParams indicators
 #' @param IndicatorID Numeric vector, id of the indicator of interest
 #' @param ProfileID Numeric vector, id of profiles of interest. Indicator
@@ -38,24 +41,14 @@
 #' \dontrun{
 #' # Returns data for the two selected domains at county and unitary authority geography
 #' doms <- c(1000049,1938132983)
-#' fingdata <- fingertips_data(DomainID = doms, AreaTypeID = 202)
+#' fingdata <- fingertips_data(DomainID = doms, AreaTypeID = 502)
 #'
-#' # Returns data at local authority district geography (AreaTypeID = 101)
+#' # Returns data at local authority district geography (AreaTypeID = 501)
 #' # for the indicator with the id 22401
-#' fingdata <- fingertips_data(22401, AreaTypeID = 101)
-#'
-#' # Returns same indicator with different comparisons due to indicator polarity
-#' # differences between profiles on the website
-#' # It is recommended to check the website to ensure consistency between your
-#' # data extract here and the polarity required
-#' fingdata <- fingertips_data(rep(90282,2),
-#'                             ProfileID = c(19,93),
-#'                             AreaTypeID = 202,
-#'                             AreaCode = "E06000008")
-#' fingdata <- fingdata[order(fingdata$TimeperiodSortable, fingdata$Sex),]
+#' fingdata <- fingertips_data(22401, AreaTypeID = 501)
 #'
 #' # Returns data for all available area types for an indicator
-#' fingdata <- fingertips_data(10101, AreaTypeID = "All")}
+#' fingdata <- fingertips_data(90362, AreaTypeID = "All")}
 #' @family data extract functions
 #' @export
 
@@ -112,7 +105,6 @@ fingertips_data <- function(IndicatorID = NULL,
   if (!(categorytype %in% c(TRUE, FALSE))){
     stop("categorytype input must be TRUE or FALSE")
   }
-
   # check on area details before calling data
   if (is.null(AreaTypeID)) {
     stop("AreaTypeID must have a value. Use function area_types() to see what values can be used.")
@@ -340,8 +332,22 @@ fingertips_data <- function(IndicatorID = NULL,
     }
 
   }
+
+
   names(fingertips_data) <- gsub("\\s","",names(fingertips_data))
 
+  if (nrow(fingertips_data) == 0) {
+    warning("No data available for the specified combination of parameters. Returning an empty data frame.")
+    if (rank == TRUE) {
+      required_columns <- c(names(fingertips_data), "Polarity", "Rank", "AreaValuesCount")
+      fingertips_data <- data.frame(matrix(ncol = length(required_columns), nrow = 0))
+      colnames(fingertips_data) <- required_columns
+      fingertips_data <- fingertips_data %>%
+        mutate(Polarity = character(), Rank = integer(), AreaValuesCount = integer())
+      return(fingertips_data)
+    }
+  }
+
   if (rank == TRUE) {
     inds <- unique(fingertips_data$IndicatorID)
     if (!is.null(ProfileID)) {
@@ -351,14 +357,12 @@ fingertips_data <- function(IndicatorID = NULL,
         proxy_settings = proxy_settings,
         path = path) %>%
         select(.data$IndicatorID, .data$Polarity)
-
     } else {
       polarities <- indicator_metadata(
         inds,
         proxy_settings = proxy_settings,
         path = path) %>%
         select("IndicatorID", "Polarity")
-
     }
     fingertips_data <- left_join(fingertips_data, polarities, by = c("IndicatorID" = "IndicatorID")) %>%
       group_by(.data$IndicatorID,
@@ -371,8 +375,10 @@ fingertips_data <- function(IndicatorID = NULL,
       mutate(Rank = rank(.data$Value, na.last = "keep"),
              AreaValuesCount = sum(!is.na(.data$Value))) %>%
       ungroup()
-
   }
+
+
+
   if (!is.null(AreaCode)) {
     fingertips_data <- fingertips_data[fingertips_data$AreaCode %in% AreaCode,] %>%
       droplevels()

R/indicator_metadata.R

@@ -8,15 +8,15 @@
 #' @inheritParams area_types
 #' @examples
 #' \dontrun{
-#' # Returns metadata for indicator ID 90362 and 1107
-#' indicatorIDs <- c(90362, 1107)
+#' # Returns metadata for indicator ID 90362 and 92901
+#' indicatorIDs <- c(90362, 92901)
 #' indicator_metadata(indicatorIDs)
 #'
-#' # Returns metadata for the indicators within the domain 1000101
-#' indicator_metadata(DomainID = 1000101)
+#' # Returns metadata for the indicators within the domain 1000049
+#' indicator_metadata(DomainID = 1000049)
 #'
-#' # Returns metadata for the indicators within the profile with the ID 129
-#' indicator_metadata(ProfileID = 129)}
+#' # Returns metadata for the indicators within the profile with the ID 19
+#' indicator_metadata(ProfileID = 19)}
 #' @return The metadata associated with each indicator/domain/profile identified
 #' @importFrom utils read.csv
 #' @importFrom readr read_csv cols
@@ -157,8 +157,8 @@ indicator_metadata <- function(IndicatorID = NULL,
 #' @inheritParams area_types
 #' @examples
 #' \dontrun{
-#' # Returns metadata for indicator ID 90362 and 1107
-#' indicatorIDs <- c(90362, 1107)
+#' # Returns metadata for indicator ID 90362 and 92901
+#' indicatorIDs <- c(90362, 92901)
 #' indicator_update_information(indicatorIDs)}
 #' @return The date of latest data update for selected indicators
 #' @importFrom rlang .data

R/indicators.R

@@ -139,7 +139,7 @@ indicators_unique <- function(ProfileID = NULL,
 #' @importFrom rlang .data
 #' @examples
 #' \dontrun{
-#' indicator_order(DomainID = 1938133161, AreaTypeID = 102, ParentAreaTypeID = 6)}
+#' indicator_order(DomainID = 1000049, AreaTypeID = 502, ParentAreaTypeID = 6)}
 #' @family lookup functions
 #' @seealso \code{\link{indicators}} for indicators and their parent domains and profiles,
 #'   \code{\link{area_types}} for area type and their parent mappings,