Read and Write Ecological Metadata Language Files

Parse and serialize Ecological Metadata Language ('EML', see < https://en.wikipedia.org/wiki/Ecological_Metadata_Language> for more information) files into S4 objects.


Travis-CI Build Status codecov.io AppVeyor Build Status CRAN_Status_Badge CRAN RStudio mirror downloads Github Stars DOI

EML is a widely used metadata standard in the ecological and environmental sciences. We strongly recommend that interested users visit the EML Homepage for an introduction and thorough documentation of the standard. Additionally, the scientific article The New Bioinformatics: Integrating Ecological Data from the Gene to the Biosphere (Jones et al 2006) provides an excellent introduction into the role EML plays in building metadata-driven data repositories to address the needs of highly hetergenous data that cannot be easily reduced to a traditional vertically integrated database. At this time, the EML R package provides support for the serializing and parsing of all low-level EML concepts, but still assumes some familiarity with the EML standard, particularly for users seeking to create their own EML files. We hope to add more higher-level functions which will make such familiarity less essential in future development.

Note: The EML R package is work in progress. Please see the Issues tracker in this repository for details about current issues and development milestonds.

Installation

You can install the current development version from rOpenSci using:

install.packages("EML", repos = c("http://packages.ropensci.org", "https://cran.rstudio.com"))

or install directly from GitHub (after installing the devtools package from CRAN):

devtools::install_github("ropensci/EML")

Quickstart

Load the package and read in an EML file:

library("EML")
f <- system.file("xsd/test/eml.xml", package = "EML")
eml <- read_eml(f)

This creates a native R object called eml. Although this is an "S4 object" type, it uses a "show" method which displays in an XML-like layout for convenience:

eml
#>   <dataset>
#>     <title>Sample dataset Description</title>
#>     <creator id="23445" scope="document">
#>       <individualName>
#>         <surName>Smith</surName>
#>       </individualName>
#>     </creator>
#>     <creator id="23446" scope="document">
#>       <individualName>
#>         <surName>Smith</surName>
#>       </individualName>
#>     </creator>
#>     <additionalInfo>
#>       <para>My comments go here.</para>
#>     </additionalInfo>
#>     <intellectualRights>
#>       <section>
#>         <para>Anyone can use it.</para>
#>       </section>
#>     </intellectualRights>
#>     <distribution>
#>       <online>
#>         <connectionDefinition scope="document">
#>           <schemeName system="CAP">sde</schemeName>
#>           <description>
#>             <para>The SDE scheme used at CAP LTER</para>
#>           </description>
#>           <parameterDefinition>
#>             <name>hostname</name>
#>             <definition>The host</definition>
#>             <defaultValue>mohave.asu.edu</defaultValue>
#>           </parameterDefinition>
#>           <parameterDefinition>
#>             <name>databaseName</name>
#>             <definition>The name of the database or catalog</definition>
#>           </parameterDefinition>
#>           <parameterDefinition>
#>             <name>owner</name>
#>             <definition>The owner catalog</definition>
#>             <defaultValue>dbo</defaultValue>
#>           </parameterDefinition>
#>         </connectionDefinition>
#>       </online>
#>     </distribution>
#>     <purpose>
#>       <para>Provide data to the whole world.</para>
#>     </purpose>
#>     <contact>
#>       <individualName>
#>         <surName>Johnson</surName>
#>       </individualName>
#>     </contact>
#>     <contact>
#>       <references>23445</references>
#>     </contact>
#>   </dataset>
#> </eml>

Validation helps ensure that an EML file can be accurately interpreted by any computer program designed to read EML. We can validate any EML against the official schema:

# An EML document with no validation errors
eml_validate(eml)
#> [1] TRUE
#> attr(,"errors")
#> character(0)
 
# An EML document with validation errors
invalid_eml <- system.file("xsd/test/example-eml-invalid.xml", package = "EML")
 
eml_validate(invalid_eml)
#> [1] FALSE
#> attr(,"errors")
#> [1] "Element 'creator': This element is not expected. Expected is one of ( references, alternateIdentifier, shortName, title )."

Write out as EML:

write_eml(eml, "example.xml")

Reading EML files

Please see the vignette, Parsing EML for a more thorough introduction to reading EML files and extracting relevant metadata.

Creating EML files

Please see the vignette, Creating EML for a proper introduction to creating your own EML files.

Working with custom units

Users may occassionally need to define custom unit types that EML does not know about. Please see the vignette, Working with units for an overview of how units work in EML, how to view the standard unit library, and how to access and define custom units and custom unit types.

Archiving, Sharing, and Publishing EML

One of the chief advantages of using EML to manage your own data is the improved ability to search all of your data files, e.g. for the ones that have the particular measurements you need on the particular location or species of interest, and be able to share this data either publicly or securely with select collaborators. To do so, you will need to upload your EML file and data to a scientific metadata repository that understands EML. The vignette, metadata repositories describes how to do this.

Developer notes

Creating EML class definitions

Class definitions (classes.R) and methods (methods.R) are created programmatically. From the root of the package, run: source("inst/create-package/create_package.R").

Meta

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

News

EML 1.0.3

  • Avoid vignette build errors on machines that lack pandoc (e.g. Solaris) using conditional checks

EML 1.0.2

  • Migrate dependency from XML to xml2
  • Improved performance in displaying and serializing XML
  • Added a NEWS.md file to track changes to the package
  • Minor bug fixes

EML 1.0.1

  • Initial release

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("EML")

1.0.3 by Carl Boettiger, a year ago


https://github.com/ropensci/EML


Report a bug at https://github.com/ropensci/EML/issues


Browse source code at https://github.com/cran/EML


Authors: Carl Boettiger [aut, cre], Matthew B. Jones [aut], Bryce Mecum [ctb], Maëlle Salmon [ctb]


Documentation:   PDF Manual  


FreeBSD license


Imports xml2, methods, tools, uuid

Suggests testthat, knitr, rmarkdown, listviewer, covr


Imported by finch.


See at CRAN