capeml: tools to aid the generation of EML metadata
overview
This package contains tools to aid the generation of EML metadata with
intent to publish a dataset (data + metadata) in the Environmental Data
Initiative (EDI) data repository. Functions and a template work flow are
included that allow for the creation of metadata at the dataset level,
and individual data entities (e.g., other entities, data tables).
Helper functions for the creation of dataset metadata for dataTable and
otherEntity objects using the EML
package are supported. The package can be extended with companion
packages for spatial data:
capemlVector for
spatialVector (KML, GeoJSON, shapefile) metadata, and
capemlGIS for spatialRaster
metadata.
A template work flow is available as part of this package. The template
is automatically generated if a new project is created with
write_directory, which also generates a config.yaml file and new
directory, or with the write_template function.
installation
Install from GitHub with pak:
pak::pak("CAPLTER/capeml")
options
EML version
This package defaults to the current version of EML. Users can switch to
the previous version with emld::eml_version("eml-2.1.1").
project naming
Most EML-generating functions in the capeml ecosystem will create both
physical objects and EML references to those objects. By default, the
package will name output files with the format
identifier_object-name.file-extension (e.g., 664_site_map.png).
The target object (e.g., my_map.png) is renamed with the additional
metadata and this object name is referenced in the EML metadata. Project
naming can be disabled by setting the projectNaming flag to FALSE.
When set to FALSE, the object name is not changed, and the name of the
data object as read into the R environment is written to file and
referenced in the EML. Note that the package identifier (number) is not
passed as an argument, and must exist in config.yaml (as
identifier).
getting started
new projects
For new projects, write_directory will create a project directory at
the current (default) or specified path. The package scope and number
(e.g., “edi”, 521) are passed as arguments, with the package name (i.e.,
scope + identifier) becoming the directory name. Within the newly
created directory, a template work flow as a Quarto (qmd) file with the
package scope and number as the file name is generated. Additional files
include a config.yaml for providing project-level metadata, a
people.yaml for providing project personnel details (see below), and a
keywords.csv file for providing project keywords. In config.yaml,
the provided scope and package identifier are generated as parameters.
Note that each of these template files can be generated outside of
write_directory with package functions (see below).
Creating a new project from the command line (sensu below) then
opening it with R is a convenient approach.
create project from command line
R --vanilla -e 'capeml::write_directory(scope = "knb-lter-cap", identifier = 716)'
existing projects
For existing projects, we can generate any of the needed configuration
files with package functions:
write_config generates config.yaml with the package scope and
identifier (e.g., “edi”, 521) passed as an argument to the function. A
version number can optionally be passed as a separate argument to
hard-code the package version (see below).write_template generates a template work flow as a Quarto (qmd) file
named with the package scope and identifier.write_people_template generates a template yaml file for providing
metadata regarding project personnel.write_keywords generates a template csv file for providing metadata
regarding project keywords.
construct a dataset
project details: dataset package number and package identifier
Package details, including scope and identifier are read from
config.yaml. The appropriate version is determined by identifying the
highest version currently in the production environment of the EDI
repository (1 for new packages).
hard-coding the package version
Determining the version requires calls to the EDI API (and an
EDI_API_KEY), which can be slow or unavailable in remote environments
such as ASU SOL. To skip the API entirely, add a version key to
config.yaml:
scope: knb-lter-cap
identifier: 716
version: 3
When version is present, create_dataset, create_eml, and
write_cap_eml use that value, print a message noting that the EDI
repository was not queried, and make no API calls. The value must be a
positive whole number. It is not updated automatically: increment it for
each new revision of the package, or remove the key to return to
determining the version from EDI. write_config(..., version = 3)
writes the key when creating a new config.yaml.
title
The dataset title is read from the title parameter of config.yaml.
The title can be quoted or unquoted but must be quoted if the title
contains a colon.
maintenance
The maintenance status of a project is read from the maintenance
parameter of config.yaml. Standardized language is provided for either
none (updates not anticipated) or regular (approximately annual
updates are anticipated) maintenance regimes. NULL or text other than
none or regular will omit the maintenance element from the
resulting EML.
abstract
The create_dataset function will look for a abstract.md file in the
working directory or at the path provided if specified. abstract.md
must be a markdown file.
keywords
write_keywords creates a template as a csv file for supplying dataset
keywords. The create_dataset function will look for a keywords.csv
file in the working directory or at the path provided if specified.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
