Package 'dmdScheme'

Description

Generic function to convert the data stored in the object x into a new object of class dmdScheme...

Usage

as_dmdScheme(x, keepData = FALSE, ..., verbose = FALSE)

## S3 method for class 'dmdSchemeData_raw'
as_dmdScheme(
  x,
  keepData = TRUE,
  convertTypes = TRUE,
  warnToError = TRUE,
  checkVersion = TRUE,
  ...,
  verbose = FALSE
)

## S3 method for class 'dmdSchemeSet_raw'
as_dmdScheme(
  x,
  keepData = FALSE,
  warnToError = TRUE,
  convertTypes = TRUE,
  checkVersion = TRUE,
  ...,
  verbose = FALSE
)

## S3 method for class 'xml_document'
as_dmdScheme(x, keepData = TRUE, useSchemeInXml = NULL, ..., verbose = FALSE)

Arguments

Value

dmdScheme as object of class dmdScheme_set

Examples

as_dmdScheme(dmdScheme_raw(), keepData = TRUE)
as_dmdScheme(dmdScheme_raw()$Experiment)

xml <- as_xml(dmdScheme_example())
x <- as_dmdScheme(xml)
all.equal(dmdScheme_example(), x)

Description

Generic function to convert the data stored in the object x into a new object of class dmdScheme_raw...

Usage

as_dmdScheme_raw(x, ...)

## S3 method for class 'dmdSchemeData'
as_dmdScheme_raw(x, ...)

## S3 method for class 'dmdSchemeSet'
as_dmdScheme_raw(x, ...)

## S3 method for class 'xml_document'
as_dmdScheme_raw(x, useSchemeInXml = NULL, ...)

Arguments

Value

dmdScheme as object of class dmdScheme_raw

Examples

as_dmdScheme_raw(dmdScheme(), keepData = TRUE)

Description

Generic function to convert an object to an object which can be saved as EML

Usage

as_eml(x, ...)

## Default S3 method:
as_eml(x, ...)

Arguments

Value

A list object which can be converted to EML. It can be written to a file using write_eml(). The resulting eml file can be validated using eml_validate().

NB: This does only validate the EML format, and NOT the validation as defined in the scheme definition package!

Description

Generic function to convert an object to xml

Usage

as_xml(x, output = "metadata", ...)

## S3 method for class 'dmdSchemeData'
as_xml(x, output = "metadata", ...)

## S3 method for class 'dmdSchemeSet'
as_xml(x, output = "metadata", ...)

Arguments

Value

an xml_document object

Examples

x <- as_xml( dmdScheme_example() )
x

## returns \code{xml_document} object

Description

Generic function to convert an object to a list containing xml(s)

Usage

as_xml_list(x, output = "metadata", ...)

## S3 method for class 'dmdSchemeSet'
as_xml_list(x, output = "metadata", ...)

Arguments

Value

a list() where each element is xml_document object

Examples

x <- as_xml_list( dmdScheme_example() )
x

## returns a \code{list()} with one \code{xml_document} object

Description

If the cache folder does not exist, and createPermanent = FALSE, a temporary location is used. To make the cache permanent, call

Usage

cache(..., delete = FALSE, createPermanent = FALSE)

Arguments

Details

cache(createPermanent = TRUE)

and restart your R session.

Value

fully qualified path to the cache folder

Description

Copied from tibble:::cat_line()

Usage

cat_ln(...)

Arguments

Description

The dataset contains the authorative definition of the dmdScheme. It contains no data, except one row NA. There are two S3 classes defined and used:

dmdSchemeData:

a data.frame with the class dmdSchemeData. Each column is one property of the metadata. It has the following attributes:

propertyName:

name of the data. In the spreadsheet, it is in the cell below (in the Experiment tab) or to the right (other tabs).

unit:

the unit of the data in each column.

type:

the type of the data in the column. These will be validated in the validate function. See there for details.

suggestedValues:

suggested values for the data of each column. These will be validated in the validate function. See there for details.

allowedValues:

allowed values for the data of each column. These will be validated in the validate function. See there for details.

Description:

general description of the columns.

names:

the names of the columns.

dmdSchemeSet:

a list with where each element is a dmdSchemeData object with additional attributes:

propertyName:

name of the dmdScheme used. In the spreadsheet, it is in the cell H1 in ther in the Experiment tab (DATA dmeScheme v0.9.9.)

dmdSchemeVersion:

version of the dmdScheme used. In the spreadsheet, it is in the cell H1 in ther in the Experiment tab (DATA dmeScheme v0.9.9.)

names:

the names of the dmdSchemeData sets. In the spreadsheet, the names of the tabs.

Usage

dmdScheme()

Examples

dmdScheme()

Description

The dataset contains example data. It was created by using the code below.

Usage

dmdScheme_example()

Examples

dmdScheme_example()

Description

The dataset contains raw data. An object of class dmdScheme_raw is returned by the function read_excel_raw with the argument raw = TRUE and read_excel_raw. It is usually an intermediate object, as in the normal workflow, this object is automatically converted to an object of class dmdSchemeSet.

Usage

dmdScheme_raw()

Details

dmdSchemeData_raw:

a data.frame as returned by the function read_excel with the class dmdSchemeData_raw

dmdSchemeSet_raw:

a list with where each element is a dmdSchemeData_raw object with additional attributes:

propertyName:

name of the dmdScheme for which this object contains the raw data. In the spreadsheet, it is in the cell H1 in ther in the Experiment tab (DATA dmeScheme v0.9.9.)

dmdSchemeVersion:

version of the dmdScheme used. In the spreadsheet, it is in the cell H1 in ther in the Experiment tab (DATA dmeScheme v0.9.9.)

names:

the names of the dmdSchemeData_raw sets. In the spreadsheet, the names of the tabs.

Examples

dmdScheme_raw()

Description

Loads fn_org), formats it and saves it as fn_new.

Usage

format_dmdScheme_xlsx(fn_org, fn_new, keepData = TRUE)

Arguments

Value

invisibly the workbook as a workbook object as created by xlsx.crerateWorkbook()

Description

For a detailed explanation of these tokens see the vignette Create and Customize the index Template.

Usage

lookup_tokens(tokens, scheme, author = "")

Arguments

Value

a list of the length of the input vector tokens containing the objects returned by the tokens. Null if the tokens contains invalid values.

Examples

lookup_tokens(
  tokens = c(
      "%%Treatments.*.2%%",
     "%%Experiment.*.*%%",
     "Measurement.method.3"
   ),
  scheme = dmdScheme_example(),
)

Description

Each package based on a dmdScheme can contain examples. This function is the interface to these examples. In the package dmdScheme, no examples are included. The function has two basic usages:

1. by using make_example(schemeName = "NameOfTheScheme") all included examples are listed

2. by using make_example(name = "basic", schemeName = "NameOfTheScheme") it will create the example named basic in a subdirectory in the current working directory. An existing directory with the same name, will nod be overwritten!

Usage

make_example(name)

Arguments

Details

The examples have to be located in a directory called example_data. The function is doing two things:

1. Copying the complete directory from the example_data directory to the current working directory

2. running knitr::purl on all ⁠./code/*.Rmd⁠ to extract the code into .R script files. If you want to include an RMarkdown files in the ./code directory from thisa, use the .rmd extension (small letters).

Value

invisibly NULL

Examples

make_example()
## Not run: 
make_example("basic")

## End(Not run)

Description

Generic function to create the index.md file to accompany the data deposit package

Title

Usage

make_index(
  scheme,
  path = ".",
  overwrite = FALSE,
  template = scheme_path_index_template(),
  author = NULL,
  make = c("html", "pdf"),
  pandoc_bin = "pandoc",
  pandoc_args = "-s",
  ...
)

## S3 method for class 'dmdSchemeSet'
make_index(
  scheme,
  path = ".",
  overwrite = FALSE,
  template = scheme_path_index_template(),
  author = NULL,
  make = c("pdf", "html"),
  pandoc_bin = "pandoc",
  pandoc_args = "-s",
  ...
)

Arguments

Value

returns path to the created index.md file

Examples

## Not run: 
  # takes to long for CRAN
  make_index( dmdScheme_example(), path = tempdir() )

## End(Not run)

Description

This function is not for the user of a scheme, but for the development process of a new scheme.

Usage

make_new_package(path = ".")

Arguments

Details

A new metadata scheme can be created by using the function scheme_make. This function will create a package to add functionality to the currently used scheme as a package which will depend on scheme_active(). This function uses the function package.skeleton() from the utils package to create a new directory for the new metadata scheme, and adds a function aaa.R which loads the current package whenever the new package is loaded as well as some fields to the DESCRIPTION file.

For a documentation of the workflow to create a new scheme, see the vignette Howto Create a new scheme.

Value

invisibly NULL

Examples

make_new_package(
  path = tempdir()
)

Description

Create new dmdScheme_validation object

Usage

new_dmdScheme_validation()

Value

new dmdScheme_validation object

Description

Open system.file(paste0(schemeName, ".xlsx"), package = schemeName) in excel. New data can be entered and the file has to be saved at a different location as it is a read-only file.

Usage

open_new_spreadsheet(
  file = NULL,
  open = TRUE,
  keepData = FALSE,
  format = TRUE,
  overwrite = FALSE,
  verbose = FALSE
)

Arguments

Value

invisibly the fully qualified path to the file which would have been opened, if open == TRUE.

Examples

## Not run: 
  open_new_spreadsheet(schemeName = "dmdScheme", format = FALSE, verbose = TRUE)

## End(Not run)

Description

Metadata is essential for the managing and archiving of data. Consequentially, metadata schemes, which standardise the property names used in specifying the metadata, play an essential role in this. Nevertheless (or because of this), metadata schemes are usually big, complex, difficult to read and understand, and, in consequence, are not used as often as they should be.

Details

This package provides a framework called dmdScheme, which

• makes it easier to develop a domain specific metadata scheme: by using a spreadsheet as the base for defining the new scheme

• provides basic functionality for the new metadata scheme: including entering, validating, exporting and saving of the new metadata

• makies it easier to enter new metadata: by uising a spreadsheet to enter the new metadata which can than be imported and exported as xml

This package provides for the creator of a new Domain Specific MetaData Scheme:

1. a simple way of discussing and developing a new scheme as it is represented in a spreadsheet

2. a function to create a new R package for a new domain specific metadata scheme which is based on a spreadsheet containing the definition and inherits all the functionality of this package (validation, printing, export, import, ...)

3. easy update of the new scheme based by re-importing the new version of the scheme from the spreadsheet by simply calling one function

4. easy extension of the functionality as the whole architecture is based on S3 methods and the new scheme inherits from the dmdScheme objects.

This package provides for the user of a Domain Specific MetaData Scheme:

1. the authorative definition of an example dmdScheme

2. object definitions for this scheme for R

3. Excel spreadsheet for entering the metadata for an experiment

4. functions to validate this metadata

5. functions to export the metadata to xml files, one per data file

Description

Internal function to ptint dmdScheme_validation of format summary

Usage

print_dmdScheme_validation_details(
  x,
  level,
  listLevel,
  format,
  error = c(0, 1, 2, 3, NA),
  ...
)

Arguments

Value

as in print.dmdScheme_validation

Description

Internal function to ptint dmdScheme_validation of format summary

Usage

print_dmdScheme_validation_summary(
  x,
  level,
  listLevel,
  error = c(0, 1, 2, 3, NA)
)

Arguments

Value

as in print.dmdScheme_validation

Description

When using different values for format, different outputs are generated:

• "default"print x as list

• "summary"print the description and errors of x as structured output, using the format as specified in the argument format

• "details"print the details of x as structured output, using the format as specified in the argument format

Usage

## S3 method for class 'dmdScheme_validation'
print(
  x,
  level = 1,
  listLevel = 3,
  type = "default",
  format = "markdown",
  error = c(0, 1, 2, 3, NA),
  ...
)

Arguments

Value

invisibly returns x

Examples

x <- validate(dmdScheme_raw())

## default printout as list
x

## the same as
print(x, type = "default")

## the summary
print(x, type = "summary")

## and the details
print(x, type = "details")

## can be used in a Rmd file like:
# ```{r, results = "asis"}
#    print(result, level = 2, listLevel = 20, type = "summary")
# ```

Description

Print method for dmdSchemeData object

Usage

## S3 method for class 'dmdSchemeData'
print(
  x,
  ...,
  printAttr = TRUE,
  printExtAttr = FALSE,
  printData = TRUE,
  .prefix = ""
)

Arguments

Value

invisibly x

Description

Print method for dmdSchemeSet object

Usage

## S3 method for class 'dmdSchemeSet'
print(
  x,
  ...,
  printAttr = TRUE,
  printExtAttr = FALSE,
  printData = TRUE,
  .prefix = ""
)

Arguments

Value

invisibly x

Description

Reads the data from an Excel file. Validation of the scheme version and scheme name is always done. Additional validations are done depending on the arguments validate. See detals below.

Usage

read_excel(
  file,
  keepData = TRUE,
  verbose = FALSE,
  raw = FALSE,
  validate = TRUE
)

Arguments

Value

either if raw = TRUE a list of data.frames from the worksheets of Class dmdScheme_raw, otherwise an object of class dmdSchemeSet

Examples

fn <- scheme_path_xlsx()
read_excel(
  file = fn
)

read_excel(
  file = fn,
  raw = TRUE
)

Read scheme data from Excel file into dmdScheme_raw object

Description

Reads the data from an Excel file as is and no validation. Only validation of the scheme version and scheme name is done (when checkVersion = TRUE).

Usage

read_excel_raw(file, verbose = FALSE, checkVersion = TRUE)

Arguments

Value

object of class dmdScheme_raw

Examples

read_excel_raw( scheme_path_xlsx() )

Description

Read the XML file file and convert it to a dmdScheme object using the function as_dmdScheme().

Usage

read_xml(file, keepData = TRUE, useSchemeInXml = NULL, verbose = FALSE)

Arguments

Examples

# write_xml(dmdScheme_raw(), file = tempfile())

Description

This generic function creates a report based on the object.

Usage

report(
  x,
  file = tempfile(),
  open = TRUE,
  report = "html",
  report_author = "Myself",
  report_title = "Report of something",
  ...
)

## S3 method for class 'character'
report(
  x,
  file = tempfile(),
  open = TRUE,
  report = "html",
  report_author = "Tester",
  report_title = "Validation of data against dmdScheme",
  ...
)

## S3 method for class 'dmdScheme_validation'
report(
  x,
  file = tempfile(),
  open = TRUE,
  report = "html",
  report_author = "Tester",
  report_title = "Validation of data against dmdScheme",
  ...
)

Arguments

Details

report.character creates a report of the object returnes from a validate().

report.dmdScheme_validation creates a report of the object returnes from a validate().

Value

return the path and filename of the report

Methods (by class)

• report(character): report of a dmdScheme_validation object.

• report(dmdScheme_validation): report of a dmdScheme_validation object.

Examples

## Not run: 
## This examples requires pandoc
## Report of `dmdScheme_validation`
report( scheme_path_xlsx() )

## End(Not run)


## Report of `dmdScheme_validation`
## Not run: 
# This needs pandoc to run successfully
report( validate(dmdScheme_raw()) )
report(
   x = dmdScheme_raw(),
   report = "html",
   report_author = "The Author I am",
   report_title = "A Nice Report"
)

## End(Not run)

Description

The shiny app allows the entering, validating, and exporting of the metadata without using R. See https://deanattali.com/2015/04/21/r-package-shiny-app/

Usage

run_app()

Value

return value from runApp()

Examples

## Not run: 
run_app()

## End(Not run)

Description

scheme_active(): Shows the name and version of the active scheme.

scheme_default(): Shows the name of the default scheme which comes with the package and can not be deleted. If nameand version is specified, the default scheme to be used will be set. There is no need to do this only internally!. Otherwise, the scheme repository used is only returned.

scheme_download(): Scheme definitions can be stored in an online repo. The default is a github repo at https://github.com/Exp-Micro-Ecol-Hub/dmdSchemeRepository. This function dowloads a scheme definition, specified by name and version, and saves it locally under the name destfile

scheme_install(): Installed schemes are copied to cache("installedSchemes") and , if necessary, an .xlsx definition is saved in addition. These can be listed by using scheme_list.

scheme_install_r_package(): Install R package for scheme name version definition using the script install_R_package.R in the scheme package.

scheme_installed(): Checks if a scheme is installed

scheme_list(): Lists all definitions for schemes which are installed. Each follows the pattern SCHEMENAME_SCHEMEVERSION.EXT. All files with the same basename but different extensions represent different representations of the same scheme definition and are effectively equivalent, only that the tab Documentation can only be found in the .xls files.

scheme_list_in_repo(): Scheme definitions can be stored in an online repo.

scheme_repo(): Get or set scheme repository. If repo is specified, the scheme repository to be used is set. Otherwise, the scheme repository used is only returned.

scheme_uninstall(): Installed schemes are deleted from cache("installedSchemes") and moved to a temporary folder which is rteturned invisibly.

scheme_use(): Switch from the current scheme to a new scheme as defined in the scheme schemeDefinition. Installed schemes can be listed by using scheme_list(). New schemes can be added to the library via a call to scheme_add(). The name of the active scheme is saved in dmdScheme_active

Usage

scheme_active()

scheme_default(name = NULL, version = NULL)

scheme_download(
  name,
  version,
  destfile = NULL,
  overwrite = FALSE,
  baseurl = scheme_repo(),
  ...
)

scheme_install(
  name,
  version,
  repo = scheme_repo(),
  file = NULL,
  overwrite = FALSE,
  install_package = FALSE
)

scheme_install_r_package(name, version, reinstall = FALSE)

scheme_installed(name, version)

scheme_list()

scheme_list_in_repo(baseurl = scheme_repo(), ...)

scheme_repo(repo = NULL)

scheme_uninstall(name = NULL, version = NULL)

scheme_use(name = NULL, version = NULL)

Arguments

Value

data.frame with two columns containing name and version of the default scheme

data.frame with two columns containing name and version of the default scheme

invisibly the value of destfile

invisibly NULL

invisibly NULL

TRUE if the theme is installed, FALSE if not

data.frame with two columns containing name and version of the intalled schemes

Returns the info about the scheme definitions in this repo as a list.

URL of the repo toi be used. If not set previously, the default repo at https://github.com/Exp-Micro-Ecol-Hub/dmdSchemeRepository/ is used.

invisibly returns the temporary location where the scheme definition is moved to.

Examples

scheme_active()

scheme_default()

scheme_download(
  name = "dmdScheme",
  version = "0.9.5"
)
## Not run: 
scheme_install("path/to/definition.xml")
scheme_install("path/to/definition.xlsx")

## End(Not run)

## Not run: 
scheme_install_r_package()

## End(Not run)

## Not run: 
scheme_installed("dmdScheme", "0.9.9")
scheme_installed("dmdScheme", "0.7.3")

## End(Not run)
scheme_list_in_repo()

# returns the repo used:
scheme_repo()
## Not run: 
scheme_uninstall(name = "schemename", version = "schemeversion")

## End(Not run)

scheme_list()
scheme_use(name = "dmdScheme", version = "0.9.9")

Description

Functions to manage schemes

Usage

scheme_make(
  schemeDefinition,
  examples = NULL,
  install_R_package = NULL,
  path = ".",
  overwrite = FALSE,
  index_template = NULL
)

Arguments

Value

fully qualified path to the created scheme

Description

Functions to manage schemes

Usage

scheme_path_index_template()

Value

fully qualified path to the index template file

Examples

scheme_path_index_template()

Description

Functions to manage schemes

Usage

scheme_path_xlsx()

Value

fully qualified path to the xlsx file containing the scheme definitipn and the example, NULL if it does not exist.

Examples

scheme_path_xlsx()

Description

Functions to manage schemes

Usage

scheme_path_xml()

Value

fully qualified path to the xml file containing the scheme definitipn and the example, NULL if it does not exist.

Examples

scheme_path_xlsx()

Description

Tabs in the Excel document need to be, for processing, transposed, if they are vertical as the Experiment tab is.

Usage

toTranspose(tabs = NULL)

Arguments

Value

if tabs is null, the character vector containing the sheets which need to be transposed. If tabs is not NULL, a logical vector of the same length as tabs which is TRUE, if the tab needs to be transposed, otherwise FALSE.

Examples

toTranspose()
# [1] "Experiment"     "MdBibliometric"

toTranspose(c("Experiment", "Not"))
# [1]  TRUE FALSE

Description

Only the newest versions of xlsx and xml files can be processed by this package. To gurantee, this function provides a mechanism to convert older versions of xlsx and xml files to newer versions.

Usage

upgrade_old_files(file, to = scheme_active()$version)

Arguments

Value

if a conversion has been done, file name of upgraded spreadsheet (BASENAME(x).to.EXTENSION(x) where x is the original file name and to is the new version), otherwise NULL.

Examples

## Not run: 
upgrade("dmdScheme.xlsx")
upgrade("dmdScheme.xml")

## End(Not run)

Description

Extract all fields named error of class dmdScheme_validation

Usage

valErr_extract(x, returnRootError = FALSE)

Arguments

Value

named numeric vector of the error levels of the different validations done

Description

Return info about error representation

Usage

valErr_info(error)

Arguments

Value

the row from valErr_errorLevels corresponding to the argument error

Description

Creates data.frame from object of class dmdScheme_validation for usage in details of validation

Usage

valErr_isOK(x, returnRootError = FALSE)

Arguments

Value

named numeric vector of the error levels of the different validations done

Description

Colour the text by using the error colour

Usage

valErr_TextErrCol(text, error, addError = TRUE)

Arguments

Value

the coloured text or error text

Description

This function validates an object representing a dmdScheme. The result can be used as a basis for a report by running report() on the resultiung object of class dmdScheme_validation.

Usage

validate(x, path = ".", validateData = TRUE, errorIfStructFalse = TRUE)

## S3 method for class 'character'
validate(x, path = ".", validateData = TRUE, errorIfStructFalse = TRUE)

## S3 method for class 'dmdSchemeSet_raw'
validate(x, path = ".", validateData = TRUE, errorIfStructFalse = TRUE)

Arguments

Value

return the dmdScheme_validation object

Methods (by class)

• validate(character): validate a character object referring to a spreadsheet file which contains the metadata.

• validate(dmdSchemeSet_raw): validate a dmdSchemeSet_raw object

Examples

## validata an Excel file containing the metadata
validate(
    x = scheme_path_xlsx()
)

## validate a `dmdScheme_raw object`
validate(
   x = dmdScheme_raw()
)

## use `read_raw()` to read an Excel spreadsheet into a `dmdScheme_raw` object
x <- read_excel_raw( scheme_path_xlsx() )
validate( x = x )

Description

Validate allowed values

Usage

validateAllowedValues(sraw)

Arguments

Value

dmdScheme_validation object

Description

Validate suggested values

Usage

validateDataFileMetaDataDataFileExists(xraw, path)

Arguments

Value

dmdScheme_validation object

Description

Validate id field

Usage

validateIDField(sraw)

Arguments

Value

dmdScheme_validation object

Description

Validate structure of dmdScheme object

Usage

validateStructure(x)

Arguments

Value

dmdScheme_validation object

Description

Validate suggested values

Usage

validateSuggestedValues(sraw)

Arguments

Value

dmdScheme_validation object

Description

Validate type of tab

Usage

validateTypes(sraw, sconv)

Arguments

Value

dmdScheme_validation object

Description

Convert the object x to an xml_document object using the function as_xml() and write it to a file. If no method as_xml() exists for the object |classx, an error will be raised.

Usage

write_excel(x, file, ...)

Arguments

Value

invisibly returns the path to the file saved to

Examples

write_excel(dmdScheme(), file = tempfile())
write_excel(dmdScheme_raw(), file = tempfile())

Description

Convert the object x to an xml_document object using the function as_xml() and write it to a file. If no method as_xml() exists for the object |classx, an error will be raised.

Usage

write_xml(x, file, output = "metadata", ...)

Arguments

Examples

write_xml(dmdScheme(), file = tempfile())