diff --git a/R/accessEnvDat.R b/R/accessEnvDat.R index 8330aed..0a8e200 100644 --- a/R/accessEnvDat.R +++ b/R/accessEnvDat.R @@ -215,6 +215,12 @@ read_day <- function(item, vars) { #' Names carry through to the result, so a request for `"SST"` returns a column #' called `SST` rather than `thetao`. #' +#' @section Citing the data: +#' The products carry their own DOIs and Copernicus asks that they be cited with +#' an access date. `variable_dataset()` says which product a variable came from, +#' and `product_url()` links to its page. The README's References section lists +#' every DOI. +#' #' Because the catalog knows which product and dataset holds each variable, #' **`product_id` and `dataset_id` can be omitted** when every requested variable #' is in it: diff --git a/R/bathymetry.R b/R/bathymetry.R index 8330f56..6bebf86 100644 --- a/R/bathymetry.R +++ b/R/bathymetry.R @@ -53,6 +53,18 @@ bathymetry_variables <- function() { #' Downloads NOAA ETOPO bathymetry via `marmap::getNOAA.bathy()` and derives #' slope and aspect from it. #' +#' @section Citation: +#' The grid is NOAA NCEI ETOPO 2022, requested at 60 arc-second bedrock +#' resolution through `marmap`. Both want citing when the result is published: +#' +#' \itemize{ +#' \item NOAA National Centers for Environmental Information (2022). ETOPO 2022 +#' 15 Arc-Second Global Relief Model. \doi{10.25921/fd45-gt74} +#' \item Pante E, Simon-Bouhet B, Irisson J (2025). marmap: Import, Plot and +#' Analyze Bathymetric and Topographic Data. +#' \doi{10.32614/CRAN.package.marmap} +#' } +#' #' The bounding box takes the same shape as `accessEnvDat()`'s, so a single #' definition of the study area serves both. #' diff --git a/R/climate_indices.R b/R/climate_indices.R index bb44a9f..4461258 100644 --- a/R/climate_indices.R +++ b/R/climate_indices.R @@ -94,10 +94,16 @@ climate_indices <- function() { format = "rapid_netcdf", # RAPID extends the series in versioned releases roughly yearly. updates = "annual", - reference = paste("Moat BI et al. Atlantic meridional overturning", + # BODC mints a new DOI per release, and retires the old one: the + # 2004-2020 DOI this entry first carried now 404s. Checked before + # changing, and worth re-checking whenever RAPID publishes a new version. + reference = paste("Moat BI, Smeed DA, Rayner D, Johns WE, Smith R,", + "Volkov D, Elipot S, Petit T, Kajtar J, Baringer MO,", + "Collins J (2026). Atlantic meridional overturning", "circulation observed by the RAPID-MOCHA-WBTS array at", - "26N. British Oceanographic Data Centre, NERC, UK.", - "doi:10.5285/223b34a3-2dc5-c945-e063-6c86abc0f5b3"), + "26N from 2004 to 2024 (v2024.1a). British", + "Oceanographic Data Centre, NERC, UK.", + "doi:10.5285/48d0bf43-0598-ceb2-e063-7086abc062f1"), description = paste("Strength of the overturning circulation, in", "Sverdrups, measured directly by a mooring array at", "26.5N. This is the real thing rather than a proxy,", @@ -116,6 +122,11 @@ climate_indices <- function() { #' Printable dictionary of climate indices #' +#' The `reference` column carries a citation for the indices that have one. +#' `LCR` and `AMOC` are published output and should be cited when used; the NOAA +#' indices are operational products with no single paper, and credit the provider +#' instead. Both are printed by the print method. +#' #' @return a data frame of class `datamatch_index_dictionary` #' @examples #' index_dictionary() @@ -181,11 +192,17 @@ print.datamatch_index_dictionary <- function(x, ...) { #' \item Jutras M, Dufour CO, Mucci A, Talbot LC (2023) Large-scale control of #' the retroflection of the Labrador Current. *Nature Communications* #' **14**:2623. \doi{10.1038/s41467-023-38321-y} -#' \item Moat BI et al. Atlantic meridional overturning circulation observed by -#' the RAPID-MOCHA-WBTS array at 26N. British Oceanographic Data Centre, -#' NERC, UK. \doi{10.5285/223b34a3-2dc5-c945-e063-6c86abc0f5b3} +#' \item Moat BI, Smeed DA, Rayner D, Johns WE, Smith R, Volkov D, Elipot S, +#' Petit T, Kajtar J, Baringer MO, Collins J (2026). Atlantic meridional +#' overturning circulation observed by the RAPID-MOCHA-WBTS array at 26N +#' from 2004 to 2024 (v2024.1a). British Oceanographic Data Centre, NERC, +#' UK. \doi{10.5285/48d0bf43-0598-ceb2-e063-7086abc062f1} #' } #' +#' BODC mints a new DOI for each RAPID release and retires the old one, so the +#' `AMOC` reference changes when a new version is published. +#' `as.data.frame(index_dictionary())$reference` is the current one. +#' #' The series is the source data published with that paper's Figure 3, fetched #' from the journal rather than recomputed, so the values are the authors' own. #' `as.data.frame(index_dictionary())$reference` carries this at runtime. diff --git a/README.Rmd b/README.Rmd index b284fdf..a02d2d5 100644 --- a/README.Rmd +++ b/README.Rmd @@ -66,8 +66,10 @@ indices. - [Putting it together](#putting-it-together) — a full worked example, four sources onto one table - [Matching](#matching) — a general spatiotemporal join, not just observations +- [Looking things up](#looking-things-up) — dictionaries, catalogs, and small helpers - [Troubleshooting](#troubleshooting) — what the error messages mean - [Related packages](#related-packages) +- [References](#references) — cite the data, not this package @@ -764,9 +766,11 @@ Two practical notes. RAPID publishes this only as NetCDF, so it needs the the published series is twelve-hourly, averaged to monthly here; the file is over a megabyte, so it is cached like the Copernicus downloads. -> Moat BI et al. Atlantic meridional overturning circulation observed by the -> RAPID-MOCHA-WBTS array at 26°N. British Oceanographic Data Centre, NERC, UK. -> +> Moat BI, Smeed DA, Rayner D, Johns WE, Smith R, Volkov D, Elipot S, Petit T, +> Kajtar J, Baringer MO, Collins J (2026). Atlantic meridional overturning +> circulation observed by the RAPID-MOCHA-WBTS array at 26°N from 2004 to 2024 +> (v2024.1a). British Oceanographic Data Centre, NERC, UK. +> #### Staying current @@ -956,6 +960,30 @@ is suffixed `.matched`, so nothing of yours is overwritten. > The arguments used to be `speciesDat` and `envDat`. Those still work and warn; > they will be removed in a later version. +## Looking things up + +Small helpers for asking the package what it knows, rather than reading the +source or guessing: + +```{r reference, eval = FALSE} +variable_dictionary() # printable table of Copernicus variables +copernicus_variables() # the same catalog as a list, for programmatic use +forecast_variables() # which variables have a forecast equivalent +variable_dataset("SST") # which dataset a variable comes from +product_url("GLOBAL_MULTIYEAR_PHY_001_030") # link to the product page + +index_dictionary() # printable table of climate indices +climate_indices() # the same catalog as a list +bathymetry_variables() # DEPTH, SLOPE, ASPECT, TPI + +covariate_columns(env) # which columns of an object are covariates +grid_resolution(env) # the grid spacing, for deciding which way to resample +``` + +The `_dictionary()` pair print as tables and are what to read; the plain catalog +functions return lists and are what to write code against. `as_markdown()` +renders either dictionary for pasting into documentation. + ## Troubleshooting Errors you might hit, and what they mean. @@ -1015,3 +1043,90 @@ Update and re-fetch. `NEWS.md` describes what was affected and how to check. - [derivoce](https://github.com/chross22/derivoce) — derived covariates (gradients, FTLE/FSLE, front and isobath distances, lags, integrals) computed from what `accessEnvDat()` returns + +## References + +datamatch is plumbing: everything it returns comes from someone else's data, and +the obligation to cite travels with the data rather than with this package. +`index_dictionary()` carries the references for the indices at runtime, and +`variable_dictionary()` links to each Copernicus product page. + +**Cite whichever of these you actually used.** + +### Copernicus Marine Service + +[Copernicus asks for a specific +form](https://help.marine.copernicus.eu/en/articles/4444611-how-to-cite-copernicus-marine-products-and-services), +including the access date: + +> *Product Title*. E.U. Copernicus Marine Service Information (CMEMS). Marine +> Data Store (MDS). DOI: 10.48670/moi-xxxxx (Accessed on DD MMM YYYY) + +Reanalysis products, used by default: + +| Product | Supplies | DOI | +|---|---|---| +| Global Ocean Physics Reanalysis (GLORYS12V1) | `SST`, `SSS`, `BOTT`, `UO`, `VO`, `SSH`, `MLD`, `SIC` | [10.48670/moi-00021](https://doi.org/10.48670/moi-00021) | +| Global Ocean Biogeochemistry Hindcast | `CHL_MODEL`, `NPP_MODEL`, `NO3`, `PO4`, `O2`, `PH` | [10.48670/moi-00019](https://doi.org/10.48670/moi-00019) | +| Global Ocean Colour (Copernicus-GlobColour) | satellite `CHL`, `PP`, `DIATO`, `DINO` | [10.48670/moi-00281](https://doi.org/10.48670/moi-00281) | + +Analysis-and-forecast products, used with `mode = "forecast"`: + +| Product | DOI | +|---|---| +| Global Ocean Physics Analysis and Forecast | [10.48670/moi-00016](https://doi.org/10.48670/moi-00016) | +| Global Ocean Biogeochemistry Analysis and Forecast | [10.48670/moi-00015](https://doi.org/10.48670/moi-00015) | + +`variable_dataset()` says which product a variable came from, so only the ones +you used need citing. Downloads go through the [Copernicus Marine +Toolbox](https://toolbox-docs.marine.copernicus.eu/), which publishes no DOI of +its own — cite the products. + +### Seafloor terrain + +- NOAA National Centers for Environmental Information (2022). *ETOPO 2022 + 15 Arc-Second Global Relief Model*. +- Pante E, Simon-Bouhet B, Irisson J (2025). *marmap: Import, Plot and Analyze + Bathymetric and Topographic Data*. + + +`fetch_bathymetry()` requests the 60 arc-second bedrock grid +(`ETOPO_2022_v1_60s_bed`) through `marmap`. + +### Climate indices + +Two are the published output of specific work and **should be cited when used**: + +- **`LCR`** — Jutras M, Dufour CO, Mucci A, Talbot LC (2023). Large-scale control + of the retroflection of the Labrador Current. *Nature Communications* + **14**:2623. +- **`AMOC`** — Moat BI, Smeed DA, Rayner D, Johns WE, Smith R, Volkov D, Elipot + S, Petit T, Kajtar J, Baringer MO, Collins J (2026). *Atlantic meridional + overturning circulation observed by the RAPID-MOCHA-WBTS array at 26°N from + 2004 to 2024 (v2024.1a)*. British Oceanographic Data Centre, NERC, UK. + + + BODC mints a new DOI for each release and retires the old one, so this changes + when RAPID publishes a new version. `index_dictionary()` carries the current + reference. + +The other four are operational products with no single paper behind them. Credit +the provider: + +- **`NAO`**, **`AO`** — NOAA Climate Prediction Center. + +- **`AMO`**, **`PDO`** — NOAA Physical Sciences Laboratory. + + +### Software this is built on + +- Pebesma E, Bivand R (2023). *Spatial Data Science: With Applications in R*. + Chapman and Hall/CRC. — the `sf` + reference +- Hijmans R, Brown A, Barbosa M (2026). *terra: Spatial Data Analysis*. + +- Pierce D (2025). *ncdf4: Interface to Unidata netCDF Format Data Files*. + — needed for `AMOC` + +`citation("datamatch")` gives this package's own entry, and `citation()` works on +any of the above. diff --git a/README.md b/README.md index 27d5778..22b0226 100644 --- a/README.md +++ b/README.md @@ -59,8 +59,10 @@ indices. - [Putting it together](#putting-it-together) — a full worked example, four sources onto one table - [Matching](#matching) — a general spatiotemporal join, not just observations +- [Looking things up](#looking-things-up) — dictionaries, catalogs, and small helpers - [Troubleshooting](#troubleshooting) — what the error messages mean - [Related packages](#related-packages) +- [References](#references) — cite the data, not this package @@ -844,9 +846,11 @@ Two practical notes. RAPID publishes this only as NetCDF, so it needs the the published series is twelve-hourly, averaged to monthly here; the file is over a megabyte, so it is cached like the Copernicus downloads. -> Moat BI et al. Atlantic meridional overturning circulation observed by the -> RAPID-MOCHA-WBTS array at 26°N. British Oceanographic Data Centre, NERC, UK. -> +> Moat BI, Smeed DA, Rayner D, Johns WE, Smith R, Volkov D, Elipot S, Petit T, +> Kajtar J, Baringer MO, Collins J (2026). Atlantic meridional overturning +> circulation observed by the RAPID-MOCHA-WBTS array at 26°N from 2004 to 2024 +> (v2024.1a). British Oceanographic Data Centre, NERC, UK. +> #### Staying current @@ -1042,6 +1046,31 @@ is suffixed `.matched`, so nothing of yours is overwritten. > The arguments used to be `speciesDat` and `envDat`. Those still work and warn; > they will be removed in a later version. +## Looking things up + +Small helpers for asking the package what it knows, rather than reading the +source or guessing: + + +``` r +variable_dictionary() # printable table of Copernicus variables +copernicus_variables() # the same catalog as a list, for programmatic use +forecast_variables() # which variables have a forecast equivalent +variable_dataset("SST") # which dataset a variable comes from +product_url("GLOBAL_MULTIYEAR_PHY_001_030") # link to the product page + +index_dictionary() # printable table of climate indices +climate_indices() # the same catalog as a list +bathymetry_variables() # DEPTH, SLOPE, ASPECT, TPI + +covariate_columns(env) # which columns of an object are covariates +grid_resolution(env) # the grid spacing, for deciding which way to resample +``` + +The `_dictionary()` pair print as tables and are what to read; the plain catalog +functions return lists and are what to write code against. `as_markdown()` +renders either dictionary for pasting into documentation. + ## Troubleshooting Errors you might hit, and what they mean. @@ -1102,3 +1131,90 @@ Update and re-fetch. `NEWS.md` describes what was affected and how to check. - [derivoce](https://github.com/chross22/derivoce) — derived covariates (gradients, FTLE/FSLE, front and isobath distances, lags, integrals) computed from what `accessEnvDat()` returns + +## References + +datamatch is plumbing: everything it returns comes from someone else's data, and +the obligation to cite travels with the data rather than with this package. +`index_dictionary()` carries the references for the indices at runtime, and +`variable_dictionary()` links to each Copernicus product page. + +**Cite whichever of these you actually used.** + +### Copernicus Marine Service + +[Copernicus asks for a specific +form](https://help.marine.copernicus.eu/en/articles/4444611-how-to-cite-copernicus-marine-products-and-services), +including the access date: + +> *Product Title*. E.U. Copernicus Marine Service Information (CMEMS). Marine +> Data Store (MDS). DOI: 10.48670/moi-xxxxx (Accessed on DD MMM YYYY) + +Reanalysis products, used by default: + +| Product | Supplies | DOI | +|---|---|---| +| Global Ocean Physics Reanalysis (GLORYS12V1) | `SST`, `SSS`, `BOTT`, `UO`, `VO`, `SSH`, `MLD`, `SIC` | [10.48670/moi-00021](https://doi.org/10.48670/moi-00021) | +| Global Ocean Biogeochemistry Hindcast | `CHL_MODEL`, `NPP_MODEL`, `NO3`, `PO4`, `O2`, `PH` | [10.48670/moi-00019](https://doi.org/10.48670/moi-00019) | +| Global Ocean Colour (Copernicus-GlobColour) | satellite `CHL`, `PP`, `DIATO`, `DINO` | [10.48670/moi-00281](https://doi.org/10.48670/moi-00281) | + +Analysis-and-forecast products, used with `mode = "forecast"`: + +| Product | DOI | +|---|---| +| Global Ocean Physics Analysis and Forecast | [10.48670/moi-00016](https://doi.org/10.48670/moi-00016) | +| Global Ocean Biogeochemistry Analysis and Forecast | [10.48670/moi-00015](https://doi.org/10.48670/moi-00015) | + +`variable_dataset()` says which product a variable came from, so only the ones +you used need citing. Downloads go through the [Copernicus Marine +Toolbox](https://toolbox-docs.marine.copernicus.eu/), which publishes no DOI of +its own — cite the products. + +### Seafloor terrain + +- NOAA National Centers for Environmental Information (2022). *ETOPO 2022 + 15 Arc-Second Global Relief Model*. +- Pante E, Simon-Bouhet B, Irisson J (2025). *marmap: Import, Plot and Analyze + Bathymetric and Topographic Data*. + + +`fetch_bathymetry()` requests the 60 arc-second bedrock grid +(`ETOPO_2022_v1_60s_bed`) through `marmap`. + +### Climate indices + +Two are the published output of specific work and **should be cited when used**: + +- **`LCR`** — Jutras M, Dufour CO, Mucci A, Talbot LC (2023). Large-scale control + of the retroflection of the Labrador Current. *Nature Communications* + **14**:2623. +- **`AMOC`** — Moat BI, Smeed DA, Rayner D, Johns WE, Smith R, Volkov D, Elipot + S, Petit T, Kajtar J, Baringer MO, Collins J (2026). *Atlantic meridional + overturning circulation observed by the RAPID-MOCHA-WBTS array at 26°N from + 2004 to 2024 (v2024.1a)*. British Oceanographic Data Centre, NERC, UK. + + + BODC mints a new DOI for each release and retires the old one, so this changes + when RAPID publishes a new version. `index_dictionary()` carries the current + reference. + +The other four are operational products with no single paper behind them. Credit +the provider: + +- **`NAO`**, **`AO`** — NOAA Climate Prediction Center. + +- **`AMO`**, **`PDO`** — NOAA Physical Sciences Laboratory. + + +### Software this is built on + +- Pebesma E, Bivand R (2023). *Spatial Data Science: With Applications in R*. + Chapman and Hall/CRC. — the `sf` + reference +- Hijmans R, Brown A, Barbosa M (2026). *terra: Spatial Data Analysis*. + +- Pierce D (2025). *ncdf4: Interface to Unidata netCDF Format Data Files*. + — needed for `AMOC` + +`citation("datamatch")` gives this package's own entry, and `citation()` works on +any of the above. diff --git a/man/accessEnvDat.Rd b/man/accessEnvDat.Rd index 939e5ba..9a82baa 100644 --- a/man/accessEnvDat.Rd +++ b/man/accessEnvDat.Rd @@ -77,6 +77,14 @@ download rather than an obvious mistake. Names carry through to the result, so a request for \code{"SST"} returns a column called \code{SST} rather than \code{thetao}. +} + +\section{Citing the data}{ + +The products carry their own DOIs and Copernicus asks that they be cited with +an access date. \code{variable_dataset()} says which product a variable came from, +and \code{product_url()} links to its page. The README's References section lists +every DOI. Because the catalog knows which product and dataset holds each variable, \strong{\code{product_id} and \code{dataset_id} can be omitted} when every requested variable diff --git a/man/fetch_bathymetry.Rd b/man/fetch_bathymetry.Rd index 188bbc6..e8dac60 100644 --- a/man/fetch_bathymetry.Rd +++ b/man/fetch_bathymetry.Rd @@ -32,10 +32,23 @@ a \code{terra::SpatRaster} with one layer per variable in Downloads NOAA ETOPO bathymetry via \code{marmap::getNOAA.bathy()} and derives slope and aspect from it. } -\details{ +\section{Citation}{ + +The grid is NOAA NCEI ETOPO 2022, requested at 60 arc-second bedrock +resolution through \code{marmap}. Both want citing when the result is published: + +\itemize{ +\item NOAA National Centers for Environmental Information (2022). ETOPO 2022 +15 Arc-Second Global Relief Model. \doi{10.25921/fd45-gt74} +\item Pante E, Simon-Bouhet B, Irisson J (2025). marmap: Import, Plot and +Analyze Bathymetric and Topographic Data. +\doi{10.32614/CRAN.package.marmap} +} + The bounding box takes the same shape as \code{accessEnvDat()}'s, so a single definition of the study area serves both. } + \section{Caching}{ \code{marmap} caches downloads into the working directory by default, which diff --git a/man/fetch_climate_index.Rd b/man/fetch_climate_index.Rd index d6e099c..8708193 100644 --- a/man/fetch_climate_index.Rd +++ b/man/fetch_climate_index.Rd @@ -44,11 +44,17 @@ operational products, and should be cited when used: \item Jutras M, Dufour CO, Mucci A, Talbot LC (2023) Large-scale control of the retroflection of the Labrador Current. \emph{Nature Communications} \strong{14}:2623. \doi{10.1038/s41467-023-38321-y} -\item Moat BI et al. Atlantic meridional overturning circulation observed by -the RAPID-MOCHA-WBTS array at 26N. British Oceanographic Data Centre, -NERC, UK. \doi{10.5285/223b34a3-2dc5-c945-e063-6c86abc0f5b3} +\item Moat BI, Smeed DA, Rayner D, Johns WE, Smith R, Volkov D, Elipot S, +Petit T, Kajtar J, Baringer MO, Collins J (2026). Atlantic meridional +overturning circulation observed by the RAPID-MOCHA-WBTS array at 26N +from 2004 to 2024 (v2024.1a). British Oceanographic Data Centre, NERC, +UK. \doi{10.5285/48d0bf43-0598-ceb2-e063-7086abc062f1} } +BODC mints a new DOI for each RAPID release and retires the old one, so the +\code{AMOC} reference changes when a new version is published. +\code{as.data.frame(index_dictionary())$reference} is the current one. + The series is the source data published with that paper's Figure 3, fetched from the journal rather than recomputed, so the values are the authors' own. \code{as.data.frame(index_dictionary())$reference} carries this at runtime. diff --git a/man/index_dictionary.Rd b/man/index_dictionary.Rd index e25b8aa..e84b7da 100644 --- a/man/index_dictionary.Rd +++ b/man/index_dictionary.Rd @@ -18,7 +18,10 @@ index_dictionary() a data frame of class \code{datamatch_index_dictionary} } \description{ -Printable dictionary of climate indices +The \code{reference} column carries a citation for the indices that have one. +\code{LCR} and \code{AMOC} are published output and should be cited when used; the NOAA +indices are operational products with no single paper, and credit the provider +instead. Both are printed by the print method. } \examples{ index_dictionary() diff --git a/tests/testthat.R b/tests/testthat.R index 9fffd0e..755bd7c 100644 --- a/tests/testthat.R +++ b/tests/testthat.R @@ -9,4 +9,4 @@ library(testthat) library(datamatch) -#test_check("datamatch") +test_check("datamatch") diff --git a/tests/testthat/test-documentation.R b/tests/testthat/test-documentation.R new file mode 100644 index 0000000..4374b0e --- /dev/null +++ b/tests/testthat/test-documentation.R @@ -0,0 +1,142 @@ +# Guards against the failure these tests exist because of: code lands, the +# documentation describing it does not, and nothing notices. Seven exported +# functions - fetch_bathymetry(), attach_climate_index() and their companions - +# were once implemented, tested, and absent from the README entirely. +# +# The source tree is preferred over the installed copy, so a run from the working +# directory checks what is about to be committed rather than what was installed +# last. R CMD check has no source tree, and falls through to the installed files, +# which came from the tarball being checked and are therefore current too. + +package_file <- function(name) { + local <- file.path(c("../..", "../../..", "."), name) + hit <- local[file.exists(local)] + if (length(hit) > 0) return(hit[1]) + + installed <- system.file(name, package = "datamatch") + if (nzchar(installed)) installed else NULL +} + +readme_text <- function() { + path <- package_file("README.md") + if (is.null(path)) return(NULL) + paste(readLines(path, warn = FALSE), collapse = "\n") +} + +test_that("every exported function is mentioned in the README", { + readme <- readme_text() + skip_if(is.null(readme), "README.md not reachable from the test directory") + + exported <- getNamespaceExports("datamatch") + # S3 methods are an implementation detail of printing, not something a reader + # calls by name. + exported <- grep("^print\\.", exported, value = TRUE, invert = TRUE) + + undocumented <- exported[!vapply(exported, function(fn) { + grepl(fn, readme, fixed = TRUE) + }, logical(1))] + + expect_equal(undocumented, character(0), + info = paste("Exported but absent from the README:", + paste(undocumented, collapse = ", "))) +}) + +test_that("every climate index is named in the README", { + readme <- readme_text() + skip_if(is.null(readme), "README.md not reachable from the test directory") + + missing <- setdiff(names(climate_indices()), + regmatches(readme, gregexpr("\\b[A-Z]{2,4}\\b", readme))[[1]]) + + expect_equal(missing, character(0), + info = paste("Index in the catalog but not the README:", + paste(missing, collapse = ", "))) +}) + +test_that("every catalog variable and bathymetry layer is named in the README", { + readme <- readme_text() + skip_if(is.null(readme), "README.md not reachable from the test directory") + + named <- regmatches(readme, gregexpr("\\b[A-Z][A-Z0-9_]{1,11}\\b", readme))[[1]] + wanted <- c(names(copernicus_variables()), names(bathymetry_variables())) + + expect_equal(setdiff(wanted, named), character(0), + info = "A variable in the catalog is not mentioned in the README") +}) + +test_that("DESCRIPTION describes the package as it is now", { + # The specific way this went stale: matchData() stopped being about species + # observations, and the Title still said it was. A claim that is wrong is + # worse than one that is merely incomplete, because a reader acts on it. + path <- package_file("DESCRIPTION") + skip_if(is.null(path), "DESCRIPTION not reachable") + description <- read.dcf(path) + + expect_false(grepl("Species Observations", description[1, "Title"], fixed = TRUE)) + # The things the package grew that the Description once omitted. + for (topic in c("resampling", "climate", "daily")) { + expect_match(description[1, "Description"], topic, ignore.case = TRUE) + } +}) + +test_that("NEWS.md is in the shape R can parse", { + news <- package_file("NEWS.md") + skip_if(is.null(news), "NEWS.md not reachable") + + # "# datamatch (development version)", the usethis convention, yields a + # "No news entries found" NOTE from R CMD check. The version heading has to be + # something R can parse as a version. + # + # Checked by pattern rather than by parsing, because R's own NEWS.md reader + # needs commonmark, which is not on the CI runners. Depending on it here would + # make this test fail for a reason that has nothing to do with NEWS.md. + headings <- grep("^#+ ", readLines(news, warn = FALSE), value = TRUE) + expect_gt(length(headings), 0) + + version_heading <- headings[1] + expect_match(version_heading, "^# datamatch [0-9]+\\.[0-9]+") + expect_false(grepl("development version", version_heading, fixed = TRUE)) + + # Where commonmark is available, confirm R really does read entries from it. + skip_if_not_installed("commonmark") + db <- tools:::.build_news_db_from_package_NEWS_md(news) + expect_gt(nrow(db), 0) + expect_false(anyNA(db$Version)) +}) + +test_that("cited DOIs are the ones that resolve", { + # A dead DOI is worse than a missing one: it looks like a citation and sends + # the reader nowhere. BODC retires the old DOI on each RAPID release, and the + # one this package first shipped (223b34a3-...) now 404s. Pinned here so a + # revert to it is caught without the tests needing a network. + amoc <- climate_indices()$AMOC$reference + + expect_match(amoc, "10.5285/48d0bf43-0598-ceb2-e063-7086abc062f1", fixed = TRUE) + expect_false(grepl("223b34a3-2dc5-c945-e063-6c86abc0f5b3", amoc, fixed = TRUE)) + + readme <- readme_text() + skip_if(is.null(readme), "README.md not reachable") + expect_false(grepl("223b34a3-2dc5-c945-e063-6c86abc0f5b3", readme, fixed = TRUE)) +}) + +test_that("every data source the package uses is cited in the README", { + readme <- readme_text() + skip_if(is.null(readme), "README.md not reachable") + + # Everything datamatch returns comes from someone else's data, so each source + # needs a DOI or a named provider in the reference list. + for (doi in c("10.48670/moi-00021", # physics reanalysis + "10.48670/moi-00019", # biogeochemistry hindcast + "10.48670/moi-00281", # ocean colour + "10.48670/moi-00016", # physics forecast + "10.48670/moi-00015", # biogeochemistry forecast + "10.25921/fd45-gt74", # ETOPO 2022 + "10.1038/s41467-023-38321-y")) { # LCR + expect_true(grepl(doi, readme, fixed = TRUE), + info = paste("DOI missing from the README:", doi)) + } + + # The operational indices have no paper, so the provider is the credit. + expect_match(readme, "Climate Prediction Center") + expect_match(readme, "Physical Sciences Laboratory") +})