| Title: | Convert 'R Markdown' and 'Quarto' Documents to Ecological Metadata Language |
|---|---|
| Description: | Ecological Metadata Language or 'EML' is a long-established format for describing ecological datasets to facilitate sharing and re-use. Because 'EML' is effectively a modified 'xml' schema, however, it is challenging to write and manipulate for non-expert users. 'delma' supports users to write metadata statements in 'R Markdown' or 'Quarto markdown' format, and parse them to 'EML' and (optionally) back again. |
| Authors: | Martin Westgate [aut, cre], Shandiya Balasubramaniam [aut], Dax Kellie [aut] |
| Maintainer: | Martin Westgate <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1.2 |
| Built: | 2026-05-20 07:15:22 UTC |
| Source: | https://github.com/AtlasOfLivingAustralia/delma |
list
Takes an object of class xml_document or tibble, and
converts it to a list. When converting from an xml_document, this is
simply a wrapper for xml2::as_list()
as_eml_list(x, ...) ## S3 method for class 'tbl_lp' as_eml_list(x, ...) ## S3 method for class 'tbl_df' as_eml_list(x, ...) ## S3 method for class 'list' as_eml_list(x, ...) ## S3 method for class 'xml_document' as_eml_list(x, ...)as_eml_list(x, ...) ## S3 method for class 'tbl_lp' as_eml_list(x, ...) ## S3 method for class 'tbl_df' as_eml_list(x, ...) ## S3 method for class 'list' as_eml_list(x, ...) ## S3 method for class 'xml_document' as_eml_list(x, ...)
x |
Object to be converted |
... |
Other arguments, currently ignored |
A list, where both the nested structure of the XML/md and the attributes of XML nodes, are preserved.
source_file <- system.file("extdata", "bionet_metadata.Rmd", package = "delma") df <- read_md(source_file) as_eml_list(df) |> str()source_file <- system.file("extdata", "bionet_metadata.Rmd", package = "delma") df <- read_md(source_file) as_eml_list(df) |> str()
tibble
Takes objects of class list or xml_document and converts
them to a tibble with a particular structure, designed for storing nested
data. Tibbles are required because attributes are stored as list-columns,
which are not supported by class data.frame.
as_eml_tibble(x, ...) ## S3 method for class 'tbl_df' as_eml_tibble(x, ...) ## S3 method for class 'tbl_lp' as_eml_tibble(x, ...) ## S3 method for class 'list' as_eml_tibble(x, ...) ## S3 method for class 'xml_document' as_eml_tibble(x, ...)as_eml_tibble(x, ...) ## S3 method for class 'tbl_df' as_eml_tibble(x, ...) ## S3 method for class 'tbl_lp' as_eml_tibble(x, ...) ## S3 method for class 'list' as_eml_tibble(x, ...) ## S3 method for class 'xml_document' as_eml_tibble(x, ...)
x |
Object to be converted |
... |
Other arguments, currently ignored |
An object of class tbl_df, tbl and data.frame, containing
the following fields:
level (int) gives the nestedness level of the node/heading in question
label (chr) the xml tag
text (chr) Any text stored within that tag
attributes (list) Any attributes for that tag
source_file <- system.file("extdata", "bionet_metadata.xml", package = "delma") xml_data <- xml2::read_xml(source_file) as_eml_tibble(xml_data)source_file <- system.file("extdata", "bionet_metadata.xml", package = "delma") xml_data <- xml2::read_xml(source_file) as_eml_tibble(xml_data)
xml_document
Takes a character vector, tibble, or list and converts it to an
xml_document, as defined by the xml2 package. When converting from
a list, this is simply a wrapper for xml2::as_xml_document().
as_eml_xml(x, ...) ## S3 method for class 'tbl_lp' as_eml_xml(x, ...) ## S3 method for class 'tbl_df' as_eml_xml(x, ...) ## S3 method for class 'list' as_eml_xml(x, ...) ## S3 method for class 'xml_document' as_eml_xml(x, ...)as_eml_xml(x, ...) ## S3 method for class 'tbl_lp' as_eml_xml(x, ...) ## S3 method for class 'tbl_df' as_eml_xml(x, ...) ## S3 method for class 'list' as_eml_xml(x, ...) ## S3 method for class 'xml_document' as_eml_xml(x, ...)
x |
Object to be converted. |
... |
Other arguments, currently ignored. |
An xml_document with the specified nodes and attributes.
source_file <- system.file("extdata", "bionet_metadata.Rmd", package = "delma") df <- read_md(source_file) as_eml_list(df) |> str()source_file <- system.file("extdata", "bionet_metadata.Rmd", package = "delma") df <- read_md(source_file) as_eml_list(df) |> str()
tibble
Takes objects of class tbl_df, list or xml_document and converts
them to a tibble with a structure required by lightparser. Note that
delma represents these as an object of class tbl_lp for convenience.
as_lp_tibble(x, ...) ## S3 method for class 'tbl_lp' as_lp_tibble(x, ...) ## S3 method for class 'tbl_df' as_lp_tibble(x, ...) ## S3 method for class 'list' as_lp_tibble(x, ...) ## S3 method for class 'xml_document' as_lp_tibble(x, ...)as_lp_tibble(x, ...) ## S3 method for class 'tbl_lp' as_lp_tibble(x, ...) ## S3 method for class 'tbl_df' as_lp_tibble(x, ...) ## S3 method for class 'list' as_lp_tibble(x, ...) ## S3 method for class 'xml_document' as_lp_tibble(x, ...)
x |
Object to be converted. |
... |
Other arguments, currently ignored. |
An object of class tbl_lp, tbl_df, tbl and data.frame, containing
the following fields:
type (chr) Whether that section is e.g. YAML, inline text, heading, or code block
label (chr) The tag associated with a given code block (otherwise NA)
params (list) Attributes of a code block
text (list) Any text in that section
code (list) Any code in that section
heading (chr) For type = heading, the value of that heading
heading_level (dbl) The heading level of that heading (i.e. number of #)
section (chr) The heading this section sits within
source_file <- system.file("extdata", "bionet_metadata.xml", package = "delma") xml_data <- xml2::read_xml(source_file) as_lp_tibble(xml_data)source_file <- system.file("extdata", "bionet_metadata.xml", package = "delma") xml_data <- xml2::read_xml(source_file) as_lp_tibble(xml_data)
In the Darwin Core standard, metadata statements are mandatory and must be
provided in Ecological Metadata Language (EML) in a file called eml.xml. This
function applies a series of checks designed by GBIF to check the structure
of the specified xml document for consistency with the standard. Note,
however, that this function doesn't check the content of those files,
meaning a file could be structurally sound and still be lacking critical
information.
check_metadata(file = NULL, schema = NULL, quiet = FALSE)check_metadata(file = NULL, schema = NULL, quiet = FALSE)
file |
An EML file to check Can be either local or a URL. |
schema |
Either |
quiet |
(logical) Should messages be hidden? Defaults to |
This function uses local versions of dc.xsd, eml-gbif-profile.xsd and
eml.xsd downloaded
from http://rs.gbif.org/schema/eml-gbif-profile/1.3/ on
2024-09-25.
Invisibly returns a tibble showing parsed errors; or an empty tibble if no errors are identified.
source_file <- system.file("extdata", "bionet_metadata.xml", package = "delma") check_metadata(source_file)source_file <- system.file("extdata", "bionet_metadata.xml", package = "delma") check_metadata(source_file)
read_eml() imports metadata from an EML file into the workspace as a
tibble.
read_eml(file)read_eml(file)
file |
Filename or URL to read from. |
read_eml() returns an object of class tbl_df, tbl and
data.frame (i.e. a tibble).
source_file <- system.file("extdata", "bionet_metadata.xml", package = "delma") df <- read_eml(source_file)source_file <- system.file("extdata", "bionet_metadata.xml", package = "delma") df <- read_eml(source_file)
read_md() imports metadata from a markdown file into the workspace as a
tibble.
read_md(file)read_md(file)
file |
Filename to read from. Must be either |
read_md() is unusual in that it calls rmarkdown::render() or
quarto::quarto_render() internally to ensure code blocks and snippets
are parsed correctly. This ensures dynamic content is rendered correctly in
the resulting EML document, but makes this function considerably slower
than a standard import function. Conceptually, therefore, it is closer to a
renderer with output type tibble than a traditional read_ function.
This approach has one unusual consequence; it prevents 'round-tripping' of
embedded code. That is, dynamic content in code snippets within the
metadata statement is rendered to plain text in EML. If that EML document
is later re-imported to Rmd using read_eml() and write_md(), formerly
dynamic content will be shown as plain text.
Internally, read_md() calls lightparser::split_to_tbl().
read_md() returns an object of class tbl_df, tbl and
data.frame (i.e. a tibble).
source_file <- system.file("extdata", "bionet_metadata.Rmd", package = "delma") read_md(source_file)source_file <- system.file("extdata", "bionet_metadata.Rmd", package = "delma") read_md(source_file)
This function places a metadata template at the address specified by "file",
defaulting to "metadata.Rmd" in the working directory. The template is
built in such a way that standard rendering with rmarkdown or Quarto to
HTML or PDF will function; but also that it renders to valid EML when
processed using read_md() and write_eml().
use_metadata_template(file = NULL, overwrite = FALSE, quiet = FALSE)use_metadata_template(file = NULL, overwrite = FALSE, quiet = FALSE)
file |
(string) A name for the resulting file, with either |
overwrite |
(logical) Should any existing file be overwritten? Defaults
to |
quiet |
(logical) Should messages be suppressed? Defaults to |
Doesn't return anything to the workspace; called for the side-effect of placing a metadata statement in the working directory.
use_metadata_template("example.Rmd")use_metadata_template("example.Rmd")
write_eml() writes a tibble, list or xml_document to an EML file.
Note that EML files always have the file extension .xml.
write_eml(x, file)write_eml(x, file)
x |
Object of any class handled by |
file |
Filename to write to |
Doesn't return anything; called for the side-effect of writing the specified EML file to disk.
source_file <- system.file("extdata", "bionet_metadata.Rmd", package = "delma") df <- read_md(source_file) write_eml(df, "example.xml")source_file <- system.file("extdata", "bionet_metadata.Rmd", package = "delma") df <- read_md(source_file) write_eml(df, "example.xml")
write_md() creates an Rmd or Qmd file from an EML file.
write_md(x, file)write_md(x, file)
x |
Object of any class handled by |
file |
Filename to write to. Must be either |
Similar to read_md(), write_md() is considerably less generic than most
write_ functions. If x is an xml_document this should convert seamlessly;
but lists or tibbles that have been manually formatted require care.
Internally, write_md() calls lightparser::combine_tbl_to_file.
Doesn't return anything; called for the side-effect of writing the specified markdown file to disk.
source_file <- system.file("extdata", "bionet_metadata.xml", package = "delma") df <- read_eml(source_file) write_md(df, "example.Rmd")source_file <- system.file("extdata", "bionet_metadata.xml", package = "delma") df <- read_eml(source_file) write_md(df, "example.Rmd")