dataspice: Create Lightweight Schema.org Descriptions of Data

Description

The goal of 'dataspice' is to make it easier for researchers to create basic, lightweight, and concise metadata files for their datasets. These basic files can then be used to make useful information available during analysis, create a helpful dataset "README" webpage, and produce more complex metadata formats to aid dataset discovery. Metadata fields are based on the 'Schema.org' and 'Ecological Metadata Language' standards.

Author(s)

Maintainer: Bryce Mecum brycemecum@gmail.com (https://github.com/amoeba)

Authors:

• Carl Boettiger (https://github.com/cboettig)

• Scott Chamberlain (https://github.com/sckott)

• Auriel Fournier (https://github.com/aurielfournier)

• Kelly Hondula (https://github.com/khondula)

• Anna Krystalli (https://github.com/annakrystalli)

• Maëlle Salmon (https://github.com/maelle)

• Kate Webbink (https://github.com/magpiedin)

• Kara Woo (https://github.com/karawoo)

Other contributors:

• Irene Steves (https://github.com/isteves) [contributor]

See Also

Useful links:

• https://github.com/ropensci/dataspice

• Report bugs at https://github.com/ropensci/dataspice/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Convert a list object to JSON-LD

Description

Convert a list object to JSON-LD

Usage

as_jsonld(
  x,
  context = "http://schema.org",
  pretty = TRUE,
  auto_unbox = TRUE,
  ...
)

Arguments

Build a dataspice site

Description

Build a dataspice site

Usage

build_site(
  path = "data/metadata/dataspice.json",
  template_path = system.file("template.html5", package = "dataspice"),
  out_path = "docs/index.html"
)

Arguments

Value

Nothing. Creates/overwrites docs/index.html

Examples

## Not run: 
# Create JSON+LD from a set of metadata templates
json <- write_json(biblio, access, attributes, creators)
build_site(json)

## End(Not run)

Put metadata templates within a metadata subdirectory

Description

Put metadata templates within a metadata subdirectory

Usage

create_spice(dir = "data")

Arguments

Examples

## Not run: 
create_spice()

# Create templates from the data in a folder other than `data`
create_spice("my_data")

## End(Not run)

Crosswalk a term

Description

Crosswalk a term

Usage

crosswalk(doc, term)

Arguments

Value

(list) The result of the crosswalk. May be an empty list on failure.

Crosswalk a Schema.org/Organization

Description

Crosswalk a Schema.org/Organization

Usage

crosswalk_Organization(creator)

Arguments

Crosswalk functions for as_eml Crosswalk a Schema.org/Person

Description

Crosswalk functions for as_eml Crosswalk a Schema.org/Person

Usage

crosswalk_Person(creator)

Arguments

Crosswalk a Schema.org/creator

Description

Crosswalk a Schema.org/creator

Usage

crosswalk_creator(creator)

Arguments

Convert a date(time) of unknown format into EML

Description

A quick and dirty crosswalk of an unknown date(time) input to EML that really only works for ISO8601 input. All other formats will fail and be returned as-is as a calendarDate. From there the user will need to do a conversion themselves.

Usage

crosswalk_datetime(input)

Arguments

Value

(list) A list with members calendarDate and time. time will be NULL if parsing fails or if the time string inside input isn't ISO8601

Crosswalk a Schema.org/distribution

Description

Crosswalk a Schema.org/distribution

Usage

crosswalk_distribution(distribution)

Arguments

Crosswalk dataspice variables to EML

Description

See set_attributes for more information on what must be filled out after this is run in order to get a valid EML attributeList.

Usage

crosswalk_variables(spice)

Arguments

Value

(data.frame) A partial EML attributes table

Examples

## Not run: 
# Load an example dataspice JSON that comes installed with the package
spice <- system.file(
  "examples", "annual-escapement.json",
  package = "dataspice")

# Convert it to EML (notice the warning)
eml_doc <- suppressWarnings({spice_to_eml(spice)})
attributes <- crosswalk_variables(spice)

# Now fill in the attributes data.frame. See `EML::set_attributes`.

# And last, set the attributes on our EML document
eml_doc$dataset$dataTable[[1]]$attributeList <-
  EML::set_attributes(attributes)

## End(Not run)

Shiny apps for editing dataspice metadata tables

Description

Launch Shiny app for editing individual dataspice metadata tables. Use ⁠edit_*()⁠ where * is one of the four dataspice metadata tables attributes, biblio, access or creators.

Usage

edit_access(metadata_dir = file.path("data", "metadata"))

Arguments

Examples

## Not run: 
edit_attributes()
edit_biblio()
edit_access()
edit_creators()

# Specifying a different dataspice metadata directory
edit_attributes(metadata_dir = "analysis/data/metadata/"))

## End(Not run)

Shiny apps for editing dataspice metadata tables

Description

Launch Shiny app for editing individual dataspice metadata tables. Use ⁠edit_*()⁠ where * is one of the four dataspice metadata tables attributes, biblio, access or creators.

Usage

edit_attributes(metadata_dir = "data/metadata")

Arguments

Examples

## Not run: 
edit_attributes()
edit_biblio()
edit_access()
edit_creators()

# Specifying a different dataspice metadata directory
edit_attributes(metadata_dir = "analysis/data/metadata/"))

## End(Not run)

Shiny apps for editing dataspice metadata tables

Description

Launch Shiny app for editing individual dataspice metadata tables. Use ⁠edit_*()⁠ where * is one of the four dataspice metadata tables attributes, biblio, access or creators.

Usage

edit_biblio(metadata_dir = file.path("data", "metadata"))

Arguments

Examples

## Not run: 
edit_attributes()
edit_biblio()
edit_access()
edit_creators()

# Specifying a different dataspice metadata directory
edit_attributes(metadata_dir = "analysis/data/metadata/"))

## End(Not run)

Shiny apps for editing dataspice metadata tables

Description

Launch Shiny app for editing individual dataspice metadata tables. Use ⁠edit_*()⁠ where * is one of the four dataspice metadata tables attributes, biblio, access or creators.

Usage

edit_creators(metadata_dir = file.path("data", "metadata"))

Arguments

Examples

## Not run: 
edit_attributes()
edit_biblio()
edit_access()
edit_creators()

# Specifying a different dataspice metadata directory
edit_attributes(metadata_dir = "analysis/data/metadata/"))

## End(Not run)

Create dataspice metadata tables from EML

Description

Create dataspice metadata tables from EML

Usage

eml_to_spice(eml, path = NULL)

Arguments

Value

A list with names attributes, access, biblio, and creators. Optionally, if path is specified, saves the four tables as CSV files.

Examples

## Not run: 
# First, load up an example EML record
library(EML)

eml_path <- system.file(
 file.path("example-dataset", "broodTable_metadata.xml"),
 package = "dataspice")
eml <- read_eml(eml_path)


# Generate the four dataspice tables
my_spice <- eml_to_spice(eml)

# Or save them as a file
# Generate the four dataspice tables
eml_to_spice(eml, ".")

## End(Not run)

Get access from EML

Description

Return EML access in the dataspice access.csv format.

Usage

es_access(eml, path = NULL)

Arguments

Get attributes from EML

Description

Return EML attributes in the dataspice attributes.csv format.

Usage

es_attributes(eml, path = NULL)

Arguments

Get biblio from EML

Description

Return EML biblio in the dataspice biblio.csv format.

Usage

es_biblio(eml, path = NULL)

Arguments

Get creators from EML

Description

Return EML creators in the dataspice creators.csv format.

Usage

es_creators(eml, path = NULL)

Arguments

Convert JSONLD to a list suitable for Mustache templating

Description

Convert JSONLD to a list suitable for Mustache templating

Usage

jsonld_to_mustache(path)

Arguments

Value

(list) Mustache-appropriate list

Parse spatialCoverage$geo$box section for use in a Leaflet map

Description

Parse spatialCoverage$geo$box section for use in a Leaflet map

Usage

parse_GeoShape_box(box)

Arguments

Value

(list) Template-specific variables for Leaflet

Parse spatialCoverage section for use in a Leaflet map

Description

Parse spatialCoverage section for use in a Leaflet map

Usage

parse_spatialCoverage(spatialCoverage)

Arguments

Value

(list) Template-specific variables for Leaflet

Prepare access

Description

Extract fileNames from data file(s) and add them to access.csv. The helper validate_file_paths can be used to create vectors of valid file paths that can be checked and then passed as data_path argument to prep_access.

Usage

prep_access(data_path = "data", access_path = "data/metadata/access.csv", ...)

Arguments

Value

Updates access.csv and writes to access_path.

Examples

## Not run: 
# First create the metadata tempaltes
create_spice()

# Then begin filling them in from your data files
prep_access()

## End(Not run)

Prepare attributes

Description

Extract variableNames from data file(s) and add them to attributes.csv. The helper validate_file_paths can be used to create vectors of valid file paths that can be checked and then passed as data_path argument to prep_attributes.

Usage

prep_attributes(
  data_path = "data",
  attributes_path = "data/metadata/attributes.csv",
  ...
)

Arguments

Value

prep_attributes() updates the attributes.csv and writes to attributes_path.

Examples

## Not run: 
create_spice()
# extract attributes from all `csv`, `tsv`, `rds` files in the data folder
# (non recursive)
prep_attributes()
# recursive
prep_attributes(recursive = TRUE)
# extract attributes from a single file using file path
data_path <- system.file("example-dataset","BroodTables.csv",
                         package = "dataspice")
prep_attributes(data_path)
# extract attributes from a single file by file path pattern matching
data_path <- system.file("example-dataset", package = "dataspice")
prep_attributes(data_path, pattern = "StockInfo")
# extract from a folder using folder path
data_path <- system.file("example-dataset", package = "dataspice")
prep_attributes(data_path)

## End(Not run)

Serve site

Description

Serve site

Usage

serve_site(path = "docs")

Arguments

Value

Nothing.

Examples

## Not run: 
# Build your site
json <- write_json(biblio, access, attributes, creators)
build_site(json)

# Serve it
serve_site()

## End(Not run)

Convert dataspice metadata to EML

Description

Performs an (imperfect) conversion of dataspice metadata to EML. It's very likely you will get validation errors and need to fix them afterwards but spice_to_eml is a good way to a richer metadata schema (EML) when you're already using dataspice but need a richer metadata schema.

Usage

spice_to_eml(spice = file.path("data", "metadata", "dataspice.json"))

Arguments

Value

(emld) The crosswalked emld object

Examples

# Load an example dataspice JSON that comes installed with the package
spice <- system.file(
  "examples", "annual-escapement.json",
  package = "dataspice"
)

# And crosswalk it to EML
spice_to_eml(spice)

# We can also create dataspice metadata from scratch and crosswalk it to EML
myspice <- list(
  name = "My example spice",
  creator = "Me",
  contact = "Me"
)
spice_to_eml(myspice)

Validate access.csv

Description

Validate access.csv

Usage

validate_access(access)

Arguments

Value

Nothing. Side-effect: Can stop execution if validation fails.

Validate attributes.csv

Description

Validate attributes.csv

Usage

validate_attributes(attributes)

Arguments

Value

Nothing. Side-effect: Can stop execution if validation fails.

Validate biblio.csv

Description

Validate biblio.csv

Usage

validate_biblio(biblio)

Arguments

Value

Nothing. Side-effect: Can stop execution if validation fails.

Validate creators.csv

Description

Validate creators.csv

Usage

validate_creators(creators)

Arguments

Value

Nothing. Side-effect: Can stop execution if validation fails.

Validate file paths

Description

Helper function to return a set of file paths for use in other functions

Usage

validate_file_paths(data_path = "data", ...)

Arguments

Value

One or more data file paths

Examples

## Not run: 
# Assuming some data files in "./data"
my_files <- validate_file_paths()

# If your data files are in `another_folder`
my_files <- validate_file_paths("another_folder")

## End(Not run)

Write a list out as object to JSON-LD

Description

Write a list out as object to JSON-LD

Usage

write_jsonld(
  x,
  path,
  context = "http://schema.org",
  pretty = TRUE,
  auto_unbox = TRUE,
  ...
)

Arguments

Write spice

Description

Write out your metadata as a dataspice JSON-LD document

Usage

write_spice(path = "data/metadata", ...)

Arguments

Value

A JSON-LD file at the path specified

Examples

## Not run: 
# First create your metadata templates
create_spice()

# Then fill in the template files however you like

# Then write out your dataspice file
write_spice()

## End(Not run)