Set up the R CMD check workflow for the data package
Description
setup_ci() writes the GitHub Actions workflow that runs R CMD check on
every push and pull request to main and dev, on macOS, Windows and
three versions of R on Linux. The openwashdata review standard requires
this workflow with the dev trigger, so a package scaffolded with washr
passes that part of the review floor by construction.
The workflow lands in .github/workflows/R-CMD-check.yaml and .github
is added to .Rbuildignore. When README.Rmd exists with badge markers,
the matching R CMD check badge is added between them (the README template
from setup_readme() carries it already). An existing workflow file is
kept as it is, so the function is safe to run again.
Usage
setup_ci()setup_ci()
Value
The path of the workflow file, invisibly.
See Also
Next: setup_rawdata(). The badge appears in the README written by setup_readme().
Other setup functions:
setup_dictionary(),
setup_rawdata(),
setup_roxygen()
Examples
## Not run: setup_ci() ## End(Not run)## Not run: setup_ci() ## End(Not run)
Create a dictionary file for tidy data sets
Description
setup_dictionary() generates a dictionary CSV file in the
data/ directory. The dictionary file
contains information on the tidy data sets such as directory, file names, variable names,
variable types, and descriptions. If tidy data exists, the dictionary is populated with
relevant information; otherwise, it creates an empty dictionary CSV file.
Usage
setup_dictionary()setup_dictionary()
Value
NULL. Error if raw data is not found or not in a package directory.
See Also
Before: setup_rawdata(). Next: setup_roxygen() once the descriptions in data-raw/dictionary.csv are written.
Other setup functions:
setup_ci(),
setup_rawdata(),
setup_roxygen()
Examples
## Not run: setup_rawdata() # Go to data_processing.R, clean the raw data and export tidy data setup_dictionary() ## End(Not run)## Not run: setup_rawdata() # Go to data_processing.R, clean the raw data and export tidy data setup_dictionary() ## End(Not run)
Create the data-raw directory with a data-processing.R template
Description
setup_rawdata() creates a directory for raw data and an example script
named data_processing.R for importing, processing and exporting the tidy data.
The template assumes that the dataset name is the same as the data package name.
Usage
setup_rawdata()setup_rawdata()
Value
NULL. This function will create a directory "data-raw" under the package directory.
See Also
Before: setup_ci(). Next: setup_dictionary() once the processing script has exported the tidy data with usethis::use_data().
Other setup functions:
setup_ci(),
setup_dictionary(),
setup_roxygen()
Examples
## Not run: setup_rawdata() ## End(Not run)## Not run: setup_rawdata() ## End(Not run)
Generate the README RMarkdown file
Description
setup_readme() uses the openwashdata README template to generate README files based on datasets
retrieved from the data/ directory. It helps in creating consistent and informative README documentation
for your data packages.
The template documents the first data object in data/ (alphabetically);
add a section per further object by hand. It stops when data/ holds no
data object, because every data section needs one.
Usage
setup_readme(force = FALSE, has_example = FALSE)setup_readme(force = FALSE, has_example = FALSE)
Arguments
force |
Logical. If FALSE (the default), the function stops when a README.Rmd already exists. Set to TRUE to overwrite the existing file. |
has_example |
Logical. Should the README include an Example section
with a commented ggplot2 scaffold for a first plot of the data? Defaults
to FALSE. Pairs with the |
Value
NULL. This function creates a README.Rmd under the package directory.
See Also
Before: update_description(). Next: setup_website(), which builds the site from README.md.
Other publishing functions:
setup_website(),
use_brand()
Examples
## Not run: # Generate the README file after setting up the dictionary setup_dictionary() # Complete and save the dictionary CSV file with variable descriptions setup_readme() # With an Example section to fill with a first plot setup_readme(has_example = TRUE) ## End(Not run)## Not run: # Generate the README file after setting up the dictionary setup_dictionary() # Complete and save the dictionary CSV file with variable descriptions setup_readme() # With an Example section to fill with a first plot setup_readme(has_example = TRUE) ## End(Not run)
Set up roxygen documentation for all tidy data sets using the dictionary
Description
Creates or updates Roxygen documentation for all tidy data sets found in the dictionary file.
When first run, this function creates the Roxygen documentation with placeholders for the title and description field. The dictionary should include columns for directory, file name, variable name, variable type, and description. This function generates Roxygen comments with this information, facilitating consistent and thorough documentation for your data sets.
When re-run this function, this function updates only the variable description entries in the Roxygen documentation files within R/ directory. The title and description fields remain unchanged.
Usage
setup_roxygen()setup_roxygen()
Value
NULL. This function creates documentation files inside "R/". Error if tidy data cannot be found.
See Also
Before: setup_dictionary(). Next: update_description().
Other setup functions:
setup_ci(),
setup_dictionary(),
setup_rawdata()
Examples
## Not run: setup_dictionary() # Once the dictionary is created, go to data-raw/dictionary.csv and complete the column description. setup_roxygen() ## End(Not run)## Not run: setup_dictionary() # Once the dictionary is created, go to data-raw/dictionary.csv and complete the column description. setup_roxygen() ## End(Not run)
Set up a pkgdown website for the data package
Description
setup_website() writes the openwashdata pkgdown configuration and builds
the site from the package documentation and README.md. The configuration
comes from the washr template: the Pages URL as the site URL, the
openwashdata analytics header, the funding sidebar, the authors footer,
and a reference index with one entry per data object in data/.
The function is safe to re-run. An existing _pkgdown.yml is kept as it
is and only the site is rebuilt, so hand edits and the brand wiring from
use_brand() survive. The example article is created once.
By default the built docs/ folder is tracked in git, which is how
openwashdata packages publish their site from main. When the package
deploys through the pkgdown GitHub Actions workflow instead
(.github/workflows/pkgdown.yaml exists), docs/ stays ignored.
Usage
setup_website(has_example = FALSE, track_docs = NULL)setup_website(has_example = FALSE, track_docs = NULL)
Arguments
has_example |
Logical. Should the pkgdown website include a vignette page for writing an example? Defaults to FALSE. |
track_docs |
Logical. Remove |
Value
NULL. Error if no README file is found.
See Also
Before: setup_readme(). Next: use_brand() for the brand, and update_citation() once the release has a DOI.
Other publishing functions:
setup_readme(),
use_brand()
Examples
## Not run: # Set up the pkgdown website including a vignette page setup_website(has_example = TRUE) ## End(Not run)## Not run: # Set up the pkgdown website including a vignette page setup_website(has_example = TRUE) ## End(Not run)
Update the citation file for the dataset.
Description
Create a citation *.cff file for the dataset from a given DOI (Digital Object Identifier). When a DOI is supplied, it adds the DOI badge to the README RMarkdown file and re-builds the README.md and pkgdown website if they exist. Before a release exists, call it without arguments to generate the citation files without a DOI or badge.
Usage
update_citation(doi = NULL, build = TRUE, type = c("dataset", "software"))update_citation(doi = NULL, build = TRUE, type = c("dataset", "software"))
Arguments
doi |
DOI (Digital Object Identifier), e.g., 10.5281/zenodo.11185699. |
build |
Logical. Rebuild README.md and the pkgdown site after the
citation files change? Defaults to |
type |
The CFF |
Value
NULL. A citation .cff file is written under the root directory.
See Also
Before: setup_website(). Run again with the DOI after the Zenodo release; update_metadata() then picks the DOI up.
Other metadata functions:
update_description(),
update_metadata()
Examples
## Not run: update_citation(doi = "10.5281/zenodo.11185699") # Regenerate the citation files without rebuilding README.md and the site update_citation(build = FALSE) ## End(Not run)## Not run: update_citation(doi = "10.5281/zenodo.11185699") # Regenerate the citation files without rebuilding README.md and the site update_citation(build = FALSE) ## End(Not run)
Update the DESCRIPTION file to conform with openwashdata standards
Description
This function updates the DESCRIPTION file of an R package to comply with openwashdata standards.
It ensures that fields such as License, Language, Date, URL, and others are correctly specified.
Existing URL and Config/Needs/website entries are preserved and merged
with the openwashdata defaults. A CC BY 4.0 license is only set when the
package does not have a license yet; an existing license is left untouched.
Usage
update_description( file = ".", github_user = "https://github.com/openwashdata/" )update_description( file = ".", github_user = "https://github.com/openwashdata/" )
Arguments
file |
Character. The file path to the DESCRIPTION file of the R package. Defaults to the current working directory. |
github_user |
Character. The URL path to the GitHub user or organization that hosts the current package. Defaults to "https://github.com/openwashdata". |
Value
NULL. Update fields directly in DESCRIPTION file.
See Also
Before: setup_roxygen(). Next: update_metadata() for the schema.org metadata, then setup_readme().
Other metadata functions:
update_citation(),
update_metadata()
Examples
## Not run: # Update DESCRIPTION file in the current package update_description() # Update DESCRIPTION file in a specific package update_description(file = "path/to/your/package/DESCRIPTION") # Update DESCRIPTION file with a specific GitHub user update_description(github_user = "https://github.com/yourusername") ## End(Not run)## Not run: # Update DESCRIPTION file in the current package update_description() # Update DESCRIPTION file in a specific package update_description(file = "path/to/your/package/DESCRIPTION") # Update DESCRIPTION file with a specific GitHub user update_description(github_user = "https://github.com/yourusername") ## End(Not run)
Generate and embed the schema.org metadata of the data package
Description
![[Experimental]](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB3aWR0aD0iMTM4IiBoZWlnaHQ9IjIwIiByb2xlPSJpbWciIGFyaWEtbGFiZWw9ImxpZmVjeWNsZTogZXhwZXJpbWVudGFsIj4KICAgIDx0aXRsZT5saWZlY3ljbGU6IGV4cGVyaW1lbnRhbDwvdGl0bGU+CiAgICA8bGluZWFyR3JhZGllbnQgaWQ9InMiIHgyPSIwIiB5Mj0iMTAwJSI+CiAgICAgICAgPHN0b3Agb2Zmc2V0PSIwIiBzdG9wLWNvbG9yPSIjYmJiIiBzdG9wLW9wYWNpdHk9Ii4xIiAvPgogICAgICAgIDxzdG9wIG9mZnNldD0iMSIgc3RvcC1vcGFjaXR5PSIuMSIgLz4KICAgIDwvbGluZWFyR3JhZGllbnQ+CiAgICA8Y2xpcFBhdGggaWQ9InIiPgogICAgICAgIDxyZWN0IHdpZHRoPSIxMzgiIGhlaWdodD0iMjAiIHJ4PSIzIiBmaWxsPSIjZmZmIiAvPgogICAgPC9jbGlwUGF0aD4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNyKSI+CiAgICAgICAgPHJlY3Qgd2lkdGg9IjU1IiBoZWlnaHQ9IjIwIiBmaWxsPSIjNTU1IiAvPgogICAgICAgIDxyZWN0IHg9IjU1IiB3aWR0aD0iODMiIGhlaWdodD0iMjAiIGZpbGw9IiNmZTdkMzciIC8+CiAgICAgICAgPHJlY3Qgd2lkdGg9IjEzOCIgaGVpZ2h0PSIyMCIgZmlsbD0idXJsKCNzKSIgLz4KICAgIDwvZz4KICAgIDxnIGZpbGw9IiNmZmYiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZvbnQtZmFtaWx5PSJWZXJkYW5hLEdlbmV2YSxEZWphVnUgU2FucyxzYW5zLXNlcmlmIiB0ZXh0LXJlbmRlcmluZz0iZ2VvbWV0cmljUHJlY2lzaW9uIiBmb250LXNpemU9IjExMCI+CiAgICAgICAgPHRleHQgYXJpYS1oaWRkZW49InRydWUiIHg9IjI4NSIgeT0iMTUwIiBmaWxsPSIjMDEwMTAxIiBmaWxsLW9wYWNpdHk9Ii4zIiB0cmFuc2Zvcm09InNjYWxlKC4xKSIgdGV4dExlbmd0aD0iNDUwIj5saWZlY3ljbGU8L3RleHQ+CiAgICAgICAgPHRleHQgeD0iMjg1IiB5PSIxNDAiIHRyYW5zZm9ybT0ic2NhbGUoLjEpIiBmaWxsPSIjZmZmIiB0ZXh0TGVuZ3RoPSI0NTAiPmxpZmVjeWNsZTwvdGV4dD4KICAgICAgICA8dGV4dCBhcmlhLWhpZGRlbj0idHJ1ZSIgeD0iOTU1IiB5PSIxNTAiIGZpbGw9IiMwMTAxMDEiIGZpbGwtb3BhY2l0eT0iLjMiIHRyYW5zZm9ybT0ic2NhbGUoLjEpIiB0ZXh0TGVuZ3RoPSI3MzAiPmV4cGVyaW1lbnRhbDwvdGV4dD4KICAgICAgICA8dGV4dCB4PSI5NTUiIHk9IjE0MCIgdHJhbnNmb3JtPSJzY2FsZSguMSkiIGZpbGw9IiNmZmYiIHRleHRMZW5ndGg9IjczMCI+ZXhwZXJpbWVudGFsPC90ZXh0PgogICAgPC9nPgo8L3N2Zz4K)
update_metadata() derives a schema.org Dataset description from the
canonical sources of the package and writes it as a JSON-LD block into the
head of every pkgdown page, where dataset search engines read it. Nothing
is hand edited: to change a value, change its source and run the function
again. Running it twice produces no change. It ends by listing the fields
it could not fill and where to fill them.
The sources are:
| Field | Source |
| name, description, version, datePublished, license | Title, Description, Version, Date, License in DESCRIPTION |
| url | the pkgdown site (a github.io entry in URL), else the repository |
| keywords | X-schema.org-keywords in DESCRIPTION, comma separated |
| spatialCoverage, temporalCoverage | X-schema.org-spatialCoverage and X-schema.org-temporalCoverage in DESCRIPTION |
| creator, maintainer, funder, publisher | Authors@R roles aut/cre, cre, fnd, cph; ORCID from the comment field |
| identifier, sameAs | the DOI in CITATION.cff, written by update_citation() |
| variableMeasured | data-raw/dictionary.csv |
| distribution | every file in inst/extdata that belongs to a dataset, one entry per file
|
The JSON-LD lands in pkgdown/templates/in-header.html, which pkgdown
picks up on the next site build. The file also keeps the in_header
includes from _pkgdown.yml working. It is not shipped in the package
tarball.
Usage
update_metadata(quiet = FALSE)update_metadata(quiet = FALSE)
Arguments
quiet |
Logical. Suppress the messages and the report of blank
fields. Defaults to |
Value
The Dataset description as a list, invisibly. The "blank"
attribute names the fields that could not be filled and says where to
fill them.
See Also
Before: update_description(), which writes the DESCRIPTION fields this reads. Next: setup_readme(). The DOI comes from update_citation().
Other metadata functions:
update_citation(),
update_description()
Examples
## Not run: update_metadata() ## End(Not run)## Not run: update_metadata() ## End(Not run)
Install or refresh the openwashdata brand in the active package
Description
use_brand() copies the openwashdata brand definition (_brand.yml)
and the logo files it references from the central
openwashdata/brand repository
into the package root. Re-running the function refreshes an existing
copy and reports which files changed, so consuming packages stay in
sync with the central definition.
Brand values are never edited locally: change them in
openwashdata/brand first, then refresh consumers with use_brand().
Usage
use_brand(ref = "main", pkgdown = TRUE, source = NULL)use_brand(ref = "main", pkgdown = TRUE, source = NULL)
Arguments
ref |
Character. Git reference (branch or tag) of
openwashdata/brand to copy from. Defaults to |
pkgdown |
Logical. Should |
source |
Character. Advanced: an alternative source for the
brand files, either a local directory or a URL prefix. When |
Details
With pkgdown = TRUE (the default), an existing _pkgdown.yml is
pointed at the brand through bslib (template.bslib.brand), so the
next pkgdown::build_site() renders the site with the brand fonts
and colors. The wiring rewrites _pkgdown.yml through the yaml
package, which does not preserve comments in that file. When no
_pkgdown.yml exists, the wiring is skipped with a hint to run
setup_website() first. Building the wired site requires the
brand.yml package (bslib asks for it at build time); it is listed in
Suggests and installed on demand.
Value
Invisibly, a character vector of the files written or updated (empty when everything was already current).
See Also
Before: setup_website(), which writes the _pkgdown.yml this wires.
For branded PDF and Word reports that read the installed _brand.yml,
the openwashdata Quarto extension
quarto-owd.
Other publishing functions:
setup_readme(),
setup_website()
Examples
## Not run: # Install the brand and wire the pkgdown site use_brand() # Refresh later, without touching _pkgdown.yml use_brand(pkgdown = FALSE) ## End(Not run)## Not run: # Install the brand and wire the pkgdown site use_brand() # Refresh later, without touching _pkgdown.yml use_brand(pkgdown = FALSE) ## End(Not run)