Read climate data from local files

.Rbuildignore

@@ -13,3 +13,8 @@
 ^docs$
 ^pkgdown$
 ^tools$
+^air.toml$
+^scratch-data$
+^format-R.sh$
+^scratch.R$
+^\.covrignore$

.covrignore

@@ -0,0 +1 @@
+R/import-*.R

.gitattributes

@@ -0,0 +1 @@
+R/import-*.R linguist-generated=true

.github/workflows/R-CMD-check.yaml

@@ -47,11 +47,11 @@ jobs:
 
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: any::rcmdcheck
+          extra-packages: any::rcmdcheck, any::tzdb
           needs: check
 
       - uses: r-lib/actions/check-r-package@v2
         with:
           upload-snapshots: true
           build_args: 'c("--no-manual","--compact-vignettes=gs+qpdf")'
-          error-on: '"note"'
+          error-on: '"warning"'

.gitignore

@@ -49,3 +49,6 @@ po/*~
 rsconnect/
 inst/doc
 docs
+scratch-data
+format-R.sh
+scratch.R

.lintr

@@ -1,12 +1,14 @@
 linters: all_linters(
     indentation_linter = NULL, # unstable as of lintr 3.1.0
-    extraction_operator_linter = NULL, # lints auto-generated vignette setup chunks
     implicit_integer_linter = NULL, # turn off due to multiple integerish values used
     duplicate_argument_linter = NULL, # due to cli_bullets
     object_name_linter = NULL, # due to S3 methods
     object_length_linter = NULL # due to length of method names
     )
 exclusions: list(
+    "R/get_vimc_climate.R" = list(
+      object_overwrite_linter = Inf
+    ),
     "tests/testthat.R" = list(
       unused_import_linter = Inf,
       undesirable_function_linter = Inf
@@ -23,5 +25,7 @@ exclusions: list(
     ),
     # do no attempt to lint auto-generated files
     "R/RcppExports.R",
-    "R/cpp11.R"
+    "R/cpp11.R",
+    "R/import-standalone-utils-assert.R",
+    "R/import-standalone-utils-assert-path.R"
   )

DESCRIPTION

@@ -1,24 +1,27 @@
-Package: ji.rpkg.template
-Title: Your Package Title in Title Case
+Package: vimclimate
+Title: Access Climate Data Time-series from the Vaccine Impact Modelling
+    Consortium
 Version: 0.0.0.9000
-Authors@R: c(
+Authors@R: 
     person("Pratik", "Gupte", , "pratik.gupte@lshtm.ac.uk", role = c("aut", "cre"),
-           comment = c(ORCID = "0000-0001-5294-7819")),
-    person("Abdul Latif Jameel Institute for Disease and Emergency Analytics", role = "fnd"),
-    person("Imperial College of Science, Technology and Medicine", role = c("cph", "fnd"))
-  )
-Description: Your package description. It must end with a period (".") and
-    include relevant bibliographical references if applicable, using the
-    following format: Author et al. (2023) <doi:10.5281/zenodo.6619350>.
+           comment = c(ORCID = "0000-0001-5294-7819"))
+Description: Access pre-made climate data time-series.
 License: MIT + file LICENSE
+URL: https://github.com/vimc/vimclimate, https://vimc.github.io/vimclimate
+Imports: 
+    arrow,
+    checkmate,
+    cli,
+    countrycode,
+    fs,
+    lubridate
 Suggests: 
     knitr,
     rmarkdown,
     spelling,
     testthat (>= 3.0.0)
 VignetteBuilder: 
     knitr
-Config/Needs/website: jameel-institute/jameelinst.rpkg.theme
 Config/testthat/edition: 3
 Encoding: UTF-8
 Language: en-GB

LICENSE

@@ -1,2 +1,2 @@
-YEAR: 2024
-COPYRIGHT HOLDER: ji.rpkg.template authors
+YEAR: 2025
+COPYRIGHT HOLDER: Imperial College of Science, Technology and Medicine

LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2024 ji.rpkg.template authors
+Copyright (c) 2025 Imperial College of Science, Technology and Medicine
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

NAMESPACE

@@ -1,3 +1,3 @@
 # Generated by roxygen2: do not edit by hand
 
-export(get_manual_mean)
+export(load_local_vimc_climate)

NEWS.md

@@ -1,5 +1,5 @@
-# ji.rpkg.template 0.0.1
+# vimclimate (development version)
 
-* This project now includes a
-   [`NEWS.md`](https://r-pkgs.org/other-markdown.html#sec-news) file to inform
-   users about changes and new features.
+- Initial package infrastructure from template.
+
+- Initial package function and data information constants.

R/constants.R

@@ -0,0 +1,15 @@
+#' Climate data source names
+#' @keywords internal constants
+data_source_names <- c(
+  CHIRPS = "chirps",
+  ERA5_mean = "era5mean",
+  ERA5_min = "era5min",
+  ERA5_max = "era5max",
+  ERA5_RH = "era5rh",
+  ERA5_SH = "era5sh",
+  PERSIANN = "persiann"
+)
+
+#' Allowed GADM admin levels
+#' @keywords internal constants
+allowed_admin_levels <- as.character(seq(0, 3))

R/get_vimc_climate.R

@@ -0,0 +1,60 @@
+#' Get climate data prepared for VIMC and stored locally
+#'
+#' @description
+#' Load climate data prepared for VIMC from a local directory.
+#'
+#'
+#' @param country A string for the country name, or for the country ISO 2- or 3-
+#' character code. E.g. one of "Canada", "CA", or "CAN". Input is checked
+#' against names and codes in \pkg{countrycode}.
+#'
+#' @param date_range A two element vector of `<Date>`s, giving the interval for
+#' which to get data.
+#'
+#' @param data_location A location relative to the current working directory
+#' to search for the data. Data for `country` are expected to live in
+#' `data_location/XYZ` as Parquet files, where `XYZ` is the ISO 3-character code
+#' for `country`. Defaults to the working directory.
+#'
+#' @param data_source A string giving the climate data to search for. Names must
+#' match exactly.
+#'
+#' @param admin_level A numeric giving the GADM admin level for which to get
+#' data. Only one unit may be passed at a time.
+#'
+#' @return A `<data.frame>` of climate data.
+#'
+#' @keywords data_access
+#'
+#' @export
+load_local_vimc_climate <- function(
+  country,
+  date_range,
+  data_location,
+  data_source = NULL,
+  admin_level = c(0, 1, 2, 3)
+) {
+  country <- validate_country(country)
+  date_range <- validate_date_range(date_range)
+  data_location <- validate_data_location(data_location)
+  data_source <- match_value(data_source, names(data_source_names))
+  admin_level <- validate_admin_level(admin_level)
+
+  target_file <- locate_parquet_file(
+    data_location,
+    country,
+    admin_level,
+    data_source
+  )
+
+  # read files and return data.frame as being of familiar format
+  data <- arrow::read_parquet(target_file)
+  data <- as.data.frame(data)
+
+  # filter on date, assume timezone is UTC
+  data$Date <- lubridate::as_date(data$Date)
+
+  data[
+    data$Date >= min(date_range) & data$Date <= max(date_range),
+  ]
+}