CAP LTER package for generating EML

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.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗