From 45df80f2f7709f73aeba8842b39fc4750d11b2fc Mon Sep 17 00:00:00 2001 From: chross22 <52218551+chross22@users.noreply.github.com> Date: Fri, 7 Aug 2026 16:03:39 -0400 Subject: [PATCH 1/2] Run the tests in R CMD check, and test that the docs keep up Two things, both about the documentation staying true rather than the code being correct. tests/testthat.R had test_check("datamatch") commented out. It was commented on 23 July in a commit titled "update readme", so almost certainly a debugging leftover that was never restored. Since then R CMD check has reported "checking tests ... OK" while running nothing, and CI has done the same. The suite has been passing throughout - every report of that came from testthat::test_local(), which does run it - but nothing was enforcing it. Uncommented: 759 tests now run under check. The new tests guard the failure mode that keeps recurring here: code lands, the documentation describing it does not, and nothing notices. Seven exported functions were once implemented, tested, and absent from the README entirely. So: - every exported function is named in the README - every climate index, catalog variable, and bathymetry layer is too - DESCRIPTION does not still describe matchData() as species-specific, and does mention what the package grew - NEWS.md has a version heading R can parse, which is what stops the "No news entries found" NOTE coming back The first of those failed on its first run and found six: copernicus_ variables, covariate_columns, product_url, forecast_variables, climate_indices, and grid_resolution. They now have a "Looking things up" section rather than a weakened test. Paths prefer the source tree over the installed copy, so a local run checks what is about to be committed. R CMD check has no source tree and falls through to the installed files, which came from the tarball being checked and are current too - which is why these run rather than skip under check. Co-Authored-By: Claude Opus 5 --- README.Rmd | 25 ++++++++ README.md | 26 ++++++++ tests/testthat.R | 2 +- tests/testthat/test-documentation.R | 93 +++++++++++++++++++++++++++++ 4 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 tests/testthat/test-documentation.R diff --git a/README.Rmd b/README.Rmd index b284fdf..ebd20c5 100644 --- a/README.Rmd +++ b/README.Rmd @@ -66,6 +66,7 @@ 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) @@ -956,6 +957,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. diff --git a/README.md b/README.md index 27d5778..d31510d 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ 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) @@ -1042,6 +1043,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. 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..f2af394 --- /dev/null +++ b/tests/testthat/test-documentation.R @@ -0,0 +1,93 @@ +# 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. + db <- tools:::.build_news_db_from_package_NEWS_md(news) + + expect_gt(nrow(db), 0) + expect_false(anyNA(db$Version)) +}) From 98e531e7bc2f7a4742615cbf36c3ff3d529dba70 Mon Sep 17 00:00:00 2001 From: chross22 <52218551+chross22@users.noreply.github.com> Date: Fri, 7 Aug 2026 16:14:13 -0400 Subject: [PATCH 2/2] Cite the data, and fix a citation that pointed nowhere Everything this package returns comes from someone else's data, and the obligation to cite travels with the data rather than with the package. The README had citations for the two indices published with papers and nothing for the Copernicus products, ETOPO, or the software - so someone publishing from a run had no list to work from. A References section at the bottom now covers all of it, grouped so only what a run actually used needs citing. Every DOI came from an authoritative source rather than from memory: the Copernicus ones from `copernicusmarine describe`, the package ones from citation(), and ETOPO from NCEI. All twelve were then checked to resolve. Two came back wrong. The Copernicus Marine Toolbox DOI I first wrote was a 404 - recalled, not looked up. There is no DOI for the client, so the section now points at its documentation and says to cite the products. More seriously, the AMOC reference in the catalog cited 10.5285/223b34a3-..., which also 404s. BODC mints a DOI per RAPID release and retires the old one; that was the 2004-2020 version. Now 10.5285/48d0bf43-... for v2024.1a, with the full author list, verified to resolve. A test pins it, since a dead DOI looks like a citation and sends the reader nowhere - worse than having none. Also adopts Copernicus's own required citation form, which asks for an access date, and adds a test that every data source has a DOI or a named provider in the reference list. Co-Authored-By: Claude Opus 5 --- R/accessEnvDat.R | 6 ++ R/bathymetry.R | 12 ++++ R/climate_indices.R | 29 +++++++-- README.Rmd | 96 ++++++++++++++++++++++++++++- README.md | 96 ++++++++++++++++++++++++++++- man/accessEnvDat.Rd | 8 +++ man/fetch_bathymetry.Rd | 15 ++++- man/fetch_climate_index.Rd | 12 +++- man/index_dictionary.Rd | 5 +- tests/testthat/test-documentation.R | 51 ++++++++++++++- 10 files changed, 312 insertions(+), 18 deletions(-) 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 ebd20c5..a02d2d5 100644 --- a/README.Rmd +++ b/README.Rmd @@ -69,6 +69,7 @@ indices. - [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 @@ -765,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 @@ -1040,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 d31510d..22b0226 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,7 @@ indices. - [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 @@ -845,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 @@ -1128,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/test-documentation.R b/tests/testthat/test-documentation.R index f2af394..4374b0e 100644 --- a/tests/testthat/test-documentation.R +++ b/tests/testthat/test-documentation.R @@ -86,8 +86,57 @@ test_that("NEWS.md is in the shape R can parse", { # "# 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") +})