Help for package yamlet

Type:

Package

Title:

Versatile Curation of Table Metadata

Version:

1.2.5

Maintainer:

Tim Bergsma <bergsmat@gmail.com>

BugReports:

https://github.com/bergsmat/yamlet/issues

Description:

A YAML-based mechanism for working with table metadata. Supports compact syntax for creating, modifying, viewing, exporting, importing, displaying, and plotting metadata coded as column attributes. The 'yamlet' dialect is valid 'YAML' with defaults and conventions chosen to improve readability. See ?yamlet, ?decorate, ?modify, ?io_csv, and ?ggplot.decorated.

License:

GPL-3

Encoding:

UTF-8

Imports:

yaml, csv (≥ 0.6.2), encode, units, spork (≥ 0.3.3), ggplot2, scales, dplyr (≥ 1.1.0), rlang, xtable, tidyr, vctrs, pillar, knitr

RoxygenNote:

7.3.2

VignetteBuilder:

knitr

Suggests:

testthat (≥ 2.1.0), magrittr, table1, rmarkdown, gridExtra, haven, tablet (≥ 0.6.8), kableExtra

NeedsCompilation:

Packaged:

2025-06-20 15:32:19 UTC; tim.bergsma

Author:

Tim Bergsma [aut, cre]

Repository:

CRAN

Date/Publication:

2025-06-20 16:40:02 UTC

yamlet: Versatile Curation of Table Metadata

Description

The yamlet package supports storage and retrieval of table metadata in yaml format. The most important function is decorate.character: it lets you 'decorate' your data by attaching attributes retrieved from a file in yaml format. Typically your data will be of class 'data.frame', but it could be anything that is essentially a named list.

Storage Format

Storage format for 'yamlet' is a text file containing well-formed yaml. Technically, it is a map of sequences. Though well formed, it need not be complete: attributes or their names may be missing.

In the simplest case, the data specification consists of a list of column (item) names, followed by semicolons. Perhaps you only have one column:

mpg:

or maybe several:

mpg:
cyl:
disp:

If you know descriptive labels for your columns, provide them (skip a space after the colon).

mpg: fuel economy
cyl: number of cylinders
disp: displacement

If you know units, create a sequence with square brackets.

mpg: [ fuel economy, miles/gallon ]
cyl: number of cylinders
disp: [ displacement , in^3 ]

If you are going to give units, you probably should give a key first, since the first anonymous element is 'label' by default, and the second is 'guide'. (A guide can be units for numeric variables, factor levels/labels for categorical variables, or a format string for dates, times, and datetimes.) You could give just the units but you would have to be specific:

mpg: [units: miles/gallon]

You can over-ride default keys by providing them in your data:

mpg: [units: miles/gallon]
_keys: [label, units]

Notice that stored yamlet can be informationally defective while syntactically correct. If you don't know an item key at the time of data authoring, you can omit it:

race: [race, [white: 0, black: 1, 2, asian: 3 ]]

Or perhaps you know the key but not the value:

race: [race, [white: 0, black: 1, asian: 2, ? other ]]

Notice that race is factor-like; the factor sequence is nested within the attribute sequence. Equivalently:

race: [label: race, guide: [white: 0, black: 1, asian: 2, ? other ]]

If you have a codelist of length one, you should still enclose it in brackets:

sex: [Sex, [ M ]]

To get started using yamlet, see ?as_yamlet.character and examples there. See also ?decorate which adds yamlet values to corresponding items in your data. See also ?print.decorated which uses label attributes, if present, as axis labels.

Note: the quinidine and phenobarb datasets in the examples are borrowed from nlme (?Quinidine, ?Phenobarb), with some reorganization.

Author(s)

Maintainer: Tim Bergsma bergsmat@gmail.com

Assign Subset of Classified

Description

Assigns subset of classified factor, retaining attributes.

Usage

## S3 replacement method for class 'classified'
x[...] <- value

Arguments

x

classified factor

...

passed to next method

Value

class 'classified' 'factor'

Examples

a <- classified(letters[1:3])
a[2:3] <- 'a'
str(a)
class(a)

Assign Subset of Decorated

Description

Assigns subset of decorated, retaining attributes.

Usage

## S3 replacement method for class 'decorated'
x[...] <- value

Arguments

x

decorated

...

passed to next method

Value

decorated

Examples

a <- as_decorated(as.list(setNames(letters[1:3], LETTERS[1:3])))
a[2:3] <- 'a'
str(a)
class(a)

Assign Subset of Decorated Vector

Description

Assigns subset of decorated vector, retaining attributes.

Usage

## S3 replacement method for class 'dvec'
x[...] <- value

Arguments

x

decorated vector

...

passed to next method

Value

dvec

Examples

a <- as_dvec(letters[1:3], label = 'foo')
a[2:3] <- 'a'
str(a)
class(a)

Subset Classified

Description

Subsets classified factor, retaining attributes.

Usage

## S3 method for class 'classified'
x[...]

Arguments

x

classified factor

...

passed to next method

Value

class 'classified' 'factor'

Examples

a <- classified(letters[1:3])
attr(a, 'label') <- 'foo'
a <- a[1:3]
attributes(a)

a <- as_decorated(as.list(setNames(letters[1:3], LETTERS[1:3]))) attr(a$B, 'label') <- 'foo' a <- a[1:3] attributes(a) Subset Decorated

Description

Subsets decorated. Calls promote internally to improve ambiguous conditional attributes where possible.

Usage

## S3 method for class 'decorated'
x[..., .promote = getOption("yamlet_promote", TRUE)]

Arguments

x

decorated

...

passed to next method

.promote

whether to auto-promote plural attributes

Value

decorated (unless dimension is dropped)

Examples

library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','phenobarb.csv')
x <- file %>% decorate
x %>% decorations(event, value)

# Subsetting promotes automatically.
x[x$event == 'dose',] %>% decorations(event, value)
x[x$event == 'conc',] %>% decorations(event, value)

# Dimension may be dropped
x[1,1]

# Conventional subsetting
a <- as_decorated(as.list(setNames(letters[1:3], LETTERS[1:3])))
attr(a$B, 'label') <- 'foo'
a <- a[1:3]
attributes(a)

Subset Decorated Vector

Description

Subsets decorated vector, retaining attributes.

Usage

## S3 method for class 'dvec'
x[...]

Arguments

x

decorated vector

...

passed to next method

Value

dvec

Examples

a <- as_dvec(letters, label = 'foo')
a <- a[1:3]
attributes(a)
names(a) <- a
a[1:2]

Subset Unit String

Description

Subsets unit_string, retaining class.

Usage

## S3 method for class 'unit_string'
x[...]

Arguments

x

unit_string

...

passed to next method

Value

unit_string

Examples

x <- c(
  'm',
  's',
  'ng/mL'
)
x <- as_unit_string(x)
class(x)
class(x[1])

Subset Yamlet

Description

Subsets yamlet. Preserves class, since a subset of yamlet is still yamlet.

Usage

## S3 method for class 'yamlet'
x[...]

Arguments

x

object to subset

...

passed to next method

Value

yamlet

Examples

meta <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
meta <- as_yamlet(meta)
class(meta)
stopifnot(inherits(meta[1:2],'yamlet'))

Assign Element of Classified

Description

Assigns element of classified factor, retaining attributes.

Usage

## S3 replacement method for class 'classified'
x[[...]] <- value

Arguments

x

classified factor

...

passed to next method

Value

class 'classified' 'factor'

Examples

a <- classified(letters[1:3])
a[[3]] <- 'a'
str(a)
class(a)

Assign Element of Decorated

Description

Assigns element of decorated, retaining attributes.

Usage

## S3 replacement method for class 'decorated'
x[[...]] <- value

Arguments

x

decorated

...

passed to next method

Value

decorated

Examples

a <- as_decorated(as.list(setNames(letters[1:3], LETTERS[1:3])))
a[[2]]
a[[2]] <- 'c'
class(a)

Assign Element of Decorated Vector

Description

Assigns element of decorated vector, retaining attributes.

Usage

## S3 replacement method for class 'dvec'
x[[...]] <- value

Arguments

x

decorated vector

...

passed to next method

Value

dvec

Examples

a <- as_dvec(letters[1:3], label = 'foo')
a[[3]] <- 'a'
str(a)
class(a)

Element-select Classified

Description

Selects element of classified factor, retaining attributes.

Usage

## S3 method for class 'classified'
x[[...]]

Arguments

x

classified factor

...

passed to next method

Value

class 'classified' 'factor'

Examples

a <- classified(letters[1:3])
attr(a, 'label') <- 'foo'
a <- a[[2]]
attributes(a)

Element-select Decorated.

Description

Selects element of decorated, retaining attributes.

Usage

## S3 method for class 'decorated'
x[[...]]

Arguments

x

decorated

...

passed to next method

Value

decorated

Examples

a <- as_decorated(as.list(setNames(letters[1:3], LETTERS[1:3])))
a[[2]]

Element-select Decorated Vector

Description

Selects element of decorated vector, retaining attributes.

Usage

## S3 method for class 'dvec'
x[[...]]

Arguments

x

decorated vector

...

passed to next method

Value

dvec

Examples

a <- as_dvec(letters[1:3], label = 'foo')
a <- a[[2]]
attributes(a)

Element-select Unit String

Description

Element-selects unit_string, retaining class.

Usage

## S3 method for class 'unit_string'
x[[...]]

Arguments

x

unit_string

...

passed to next method

Value

unit_string

Examples

x <- c(
  'm',
  's',
  'ng/mL'
)
x <- as_unit_string(x)
class(x)
class(x[[1]])

Alias a Data Frame

Description

Aliases a data.frame. Replaces column names with labels, where present. Stores column name as 'alias' attribute.

Usage

## S3 method for class 'data.frame'
alias(object, ...)

Arguments

object

data.frame

...

optional unquoted names of target columns

Value

aliased data.frame

Examples

library(magrittr)
d <- data.frame(x = 1:10, y = 1:10, z = 1:10)
d %<>% modify(x, label = 'Independent Value')
d %<>% modify(y, label = 'Dependent Value')
d
alias(d)
alias(d, y)

Anti_join Decorated

Description

Preserves class when joining decorated.

Usage

## S3 method for class 'decorated'
anti_join(x, y, by = NULL, copy = FALSE, ...)

Arguments

x, y

A pair of data frames, data frame extensions (e.g. a tibble), or lazy data frames (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

by

A join specification created with join_by(), or a character vector of variables to join by.

If NULL, the default, ⁠*_join()⁠ will perform a natural join, using all variables in common across x and y. A message lists the variables so that you can check they're correct; suppress the message by supplying by explicitly.

To join on different variables between x and y, use a join_by() specification. For example, join_by(a == b) will match x$a to y$b.

To join by multiple variables, use a join_by() specification with multiple expressions. For example, join_by(a == b, c == d) will match x$a to y$b and x$c to y$d. If the column names are the same between x and y, you can shorten this by listing only the variable names, like join_by(a, c).

join_by() can also be used to perform inequality, rolling, and overlap joins. See the documentation at ?join_by for details on these types of joins.

For simple equality joins, you can alternatively specify a character vector of variable names to join by. For example, by = c("a", "b") joins x$a to y$a and x$b to y$b. If variable names differ between x and y, use a named character vector like by = c("x_a" = "y_a", "x_b" = "y_b").

To perform a cross-join, generating all combinations of x and y, see cross_join().

copy

If x and y are not from the same data source, and copy is TRUE, then y will be copied into the same src as x. This allows you to join tables across srcs, but it is a potentially expensive operation so you must opt into it.

...

Other parameters passed onto methods.

Append Units

Description

Appends units attribute to label attribute. Generic, with methods append_units.default and append_units.data.frame. For a more general strategy see modify.

Usage

append_units(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

# see methods

Append Units for Data Frame

Description

Appends units for data.frame. For finer control, consider applying append_units.default to individual columns.

Usage

## S3 method for class 'data.frame'
append_units(x, ...)

Arguments

x

data.frame

...

named arguments passed to default method, un-named are columns to alter scope

Value

data.frame

Examples

library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
file %>% decorate %>% explicit_guide %>% append_units %>% decorations(Age, glyco)
file %>% decorate %>% explicit_guide %>% append_units(glyco) %>% decorations(Age, glyco)

Append Units By Default

Description

Units attribute is wrapped in open and close, and appended to label. Result is assigned to target attribute (default: 'label'). If style is 'latex' or 'plotmath', all elements are treated as spork (as_spork) and coerced to canonical form before concatenation.

Usage

## Default S3 method:
append_units(
  x,
  ...,
  open = getOption("yamlet_append_units_open", " ("),
  close = getOption("yamlet_append_units_close", ")"),
  style = getOption("yamlet_append_units_style", "plain"),
  target = getOption("yamlet_append_units_target", "label")
)

Arguments

x

object

...

passed to as_latex, as_plotmath

open

character to precede units

close

character to follow units

style

one of 'plain', 'latex', or 'plotmath'

target

attribute name for appended result

Value

same class as x, with sub-class 'latex' or 'plotmath' depending on style

Examples

library(units)
library(magrittr)
x <- 1:10
attr(x, 'label') <- 'acceleration'
units(x) <- 'm/s^2'
y <- as_units('kg')
x %>% attr('label')
x %>% append_units %>% attr('label')
y %>% attr('label')
y %>% append_units %>% attr('label')
x %>% append_units(style = 'plain')
x %>% append_units(style = 'plotmath')
x %>% append_units(style = 'latex')

Arbitrate Two Attributes

Description

Arbitrates two attribute sets. Generic, with methods arbitrate.NULL, arbitrate.namedList, arbitrate.list, arbitrate.default.

Usage

arbitrate(x, y, ...)

Arguments

x

left attribute set

y

right attribute set

...

passed arguments

Value

list (of attributes)

Arbitrate Null

Description

Arbitrates two attributes, the first of which is NULL. Simply returns the second.

Usage

## S3 method for class ''NULL''
arbitrate(x, y, ...)

Arguments

x

left attribute

y

right attribute

...

passed arguments

Value

class of y

Arbitrate Default

Description

Arbitrates two attributes, the first of which is non-NULL and non-list. If y is list, x is promoted to list and re-arbitrated thus. Otherwise, x is returned, with warning if y not identical and not NULL.

Usage

## Default S3 method:
arbitrate(x, y, tag = "", ...)

Arguments

x

left attribute

y

right attribute

...

passed arguments

Value

list if y is list, else x

Arbitrate List

Description

Arbitrates two attributes, the first of which is a list. If x has names, it is cast as namedList and arbitrated thus.

Usage

## S3 method for class 'list'
arbitrate(x, y, ...)

Arguments

x

left attribute

y

right attribute

...

passed arguments

Value

list

Arbitrate Named List

Description

Arbitrates two attributes, the first of which is a named list.

Usage

## S3 method for class 'namedList'
arbitrate(x, y, ...)

Arguments

x

left attribute

y

right attribute

...

passed arguments

Value

list

Arrange Decorated

Description

Preserves class when arranging decorated.

Usage

## S3 method for class 'decorated'
arrange(.data, ...)

Arguments

.data

A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

...

<data-masking> Variables, or functions of variables. Use desc() to sort a variable in descending order.

Coerce Yam to Character

Description

Coerces class yam to character. Forms the basis for a yamlet emitter.

Usage

## S3 method for class 'yam'
as.character(x, ...)

Arguments

x

yam

...

ignored; keys is an attribute of yam

Value

character

Examples

foo <- as_yamlet(c('id: subject','amt: dose'))
class(foo)
bar <- as_yam(foo)
class(bar)
as.character(bar)
as.character(
as_yam(
as_yamlet(
"race: [label: race, guide: [ white: 0, black: 1, asian: 2 ], multiple: ['yes': 1, 'no': 0]]"
)))

Coerce Yamlet to Character

Description

Coerces yamlet to character. See also as_yamlet.character.

Usage

## S3 method for class 'yamlet'
as.character(x, sort = TRUE, ...)

Arguments

x

yamlet

sort

whether to coerce attribute order using canonical.yamlet

...

passed to as.character.yam and as_yam.yamlet

Value

character

Examples


as.character(as_yamlet('ID: subject identifier'))
as.character(as_yamlet(c('id: subject','amt: dose')))
as.character(as_yamlet(c('id: subject\namt: dose')))
foo <- as_yamlet(system.file(package = 'yamlet', 'extdata','quinidine.yaml'))
class(foo)
writeLines(as.character(foo))
identical(foo, as_yamlet(as.character(foo)))
identical(as.character(foo), as.character(as_yamlet(as.character(foo))))
file <- system.file(package = 'yamlet','extdata','quinidine.csv')
file
foo <- resolve(decorate(file))
as.character(as_yamlet(foo))
as.character(as_yamlet(foo, exclude_attr = 'class'))

Coerce Decorated Vector to Data Frame

Description

Coerces decorated vector to data.frame.

Usage

## S3 method for class 'dvec'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  nm = deparse1(substitute(x))
)

Arguments

x

dvec

row.names

passed to next method

optional

passed to next method

...

passed to next method

nm

name for new column

Value

data.frame

Examples

as.data.frame(as_dvec(letters[1:3]))
L <- as_dvec(letters[1:3], label = 'My Letters')
d <- data.frame(letters = L )
str(d)

Coerce Yamlet to Data Frame

Description

Coerces yamlet to data.frame. Columns are constructed in the order that attributes are encountered, beginning with top-level 'item' (default). Cell contents are calculated using getOption('yamlet_cell_value', yamlet::cell_value) to which is passed the cell-specific metadata as well as sep and def.

Usage

## S3 method for class 'yamlet'
as.data.frame(
  x,
  row.names = "item",
  optional = FALSE,
  sep = "\n",
  def = ": ",
  ...
)

Arguments

x

yamlet; see decorations and read_yamlet

row.names

a name for a column to hold top-level names, or NULL to represent these as row.names

optional

if TRUE and row.names is NULL, row.names will not be set

sep

separator for multiple items within an attribute

def

definition string: separator between items and their (preceding) names, if any

...

ignored

Value

data.frame

Examples


library(magrittr)

file <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
file %>% read_yamlet %>% explicit_guide %>% as.data.frame
file <- system.file(package = 'yamlet', 'extdata','phenobarb.csv')

# phenobarb.yaml has conditional metadata that benefits
# from interpretation in the context of the data itself.
# thus, we
# * read the whole 'decorated' object (not just yaml),
# * resolve the 'guide' ambiguity,
# extract the best-guess decorations, and
# convert to data.frame.

file %>% io_csv %>% resolve %>% decorations %>% as.data.frame

Coerce Classified to Integer

Description

Coerces classified to integer. Result is like as.integer(as.numeric(x)) + offset but has a guide attribute: a list of integers whose names are the original levels of x. If you need a simple integer, consider coercing first to numeric.

Usage

## S3 method for class 'classified'
as.integer(
  x,
  offset = 0L,
  ...,
  persistence = getOption("yamlet_persistence", TRUE)
)

Arguments

x

classified, see classified

offset

an integer value to add to intermediate result

...

passed to desolve

persistence

whether to return 'dvec' (is.integer(): TRUE) or just integer.

Value

integer (possibly of class dvec)

Examples

library(magrittr)

# create factor with codelist attribute
classified(c('knife','fork','spoon'))

# give back a simple numeric
classified(c('knife','fork','spoon')) %>% as.numeric

# intentionally preserve levels as 'guide' attribute
classified(c('knife','fork','spoon')) %>% as.integer

# implement offset
classified(c('knife','fork','spoon')) %>% as.integer(-1)

# globally defeat the 'persistence' paradigm
options(yamlet_persistence = FALSE)
c('knife','fork','spoon') %>% 
  classified %>%
  as.integer %>% 
  class # integer
  
# remove option to restore default persistence paradigm
options(yamlet_persistence = NULL)
c('knife','fork','spoon') %>% 
  classified %>%
  as.integer %>% 
  class # dvec
  
# locally defeat persistence paradigm
c('knife','fork','spoon') %>% 
  classified %>%
  as.integer(persistence = FALSE) %>% 
  class # integer

Coerce to Decorated

Description

Coerces to class 'decorated'. Generic, with method as_decorated.default.

Usage

as_decorated(x, ...)

Arguments

x

object

...

passed arguments

Value

decorated

Examples

class(Puromycin)
class(as_decorated(Puromycin))

Coerce to Decorated by Default

Description

Coerces to class 'decorated' by decorating (by default) with an empty list.

Usage

## Default S3 method:
as_decorated(x, meta = "-", ...)

Arguments

x

object

meta

see decorate.list

...

passed arguments

Value

decorated

Examples

class(Puromycin)
class(as_decorated(Puromycin))

Coerce to Decorated Vector

Description

Coerces to Decorated Vector. Generic, with methods as_dvec.logical, as_dvec.integer, as_dvec.numeric, as_dvec.complex, and as_dvec.character.

Usage

as_dvec(x, ...)

Arguments

x

object of dispatch

...

ignored arguments

Value

dvec

Examples

as_dvec(0)

Coerce Character to Decorated Vector

Description

Coerces character to decorated vector. Assigns class 'dvec' and any named attributes in dots.

Usage

## S3 method for class 'character'
as_dvec(x, ...)

Arguments

x

character

...

attributes to assign

Value

dvec

Examples

as_dvec(letters)

Coerce Complex to Decorated Vector

Description

Coerces complex to decorated vector. Assigns class 'dvec' and any named attributes in dots.

Usage

## S3 method for class 'complex'
as_dvec(x, ...)

Arguments

x

complex

...

attributes to assign

Value

dvec

Examples

as_dvec(c(complex(1), complex(2)))

Coerce Decorated Vector to Decorated Vector

Description

Coerces decorated vector to decorated vector. Assigns any named attributes in dots.

Usage

## S3 method for class 'dvec'
as_dvec(x, ...)

Arguments

x

character

...

attributes to assign

Value

dvec

Examples

as_dvec(as_dvec(letters[1:3]), label = 'Letters')
as_dvec(as_dvec(letters[1:3], label = 'Letters'))

Coerce Integer to Decorated Vector

Description

Coerces integer to decorated vector. Assigns class 'dvec' and any named attributes in dots.

Usage

## S3 method for class 'integer'
as_dvec(x, ...)

Arguments

x

integer

...

attributes to assign

Value

dvec

Examples

as_dvec(1:3)

Coerce Logical to Decorated Vector

Description

Coerces logical to decorated vector. Assigns class 'dvec' and any named attributes in dots.

Usage

## S3 method for class 'logical'
as_dvec(x, ...)

Arguments

x

logical

...

attributes to assign

Value

dvec

Examples

as_dvec(c(FALSE, TRUE))

Coerce Numeric to Decorated Vector

Description

Coerces numeric to decorated vector. Assigns class 'dvec' and any named attributes in dots.

Usage

## S3 method for class 'numeric'
as_dvec(x, ...)

Arguments

x

numeric

...

attributes to assign

Value

dvec

Examples

as_dvec(c(10.3, 1.2))
as_dvec(1, label = 'yin')
as_dvec(structure(1, label = 'yin'))
as_dvec(structure(1, label = 'yin'), label = 'yang')

Coerce Units to Decorated Vector

Description

Coerces units to dvec.

Usage

## S3 method for class 'units'
as_dvec(x, ...)

Arguments

x

units

...

passed arguments

Examples

library(magrittr)
library(dplyr)
a <- data.frame(id = 1:4, wt = c(70, 80, 70, 80), sex = c(0,1,0,1))
a %<>% decorate('wt: [ body weight, kg ]')
a %<>% decorate('sex: [ sex, [ female: 0, male: 1]]')
a %<>% decorate('id: identifier')
a %<>% resolve
a %<>% mutate(wt = as_units(wt))
a %<>% mutate(wt = as_dvec(wt))
str(a$wt)

Coerce Symbolic Units to Spork

Description

Coerces symbolic units to spork by coercing first to unit_string.

Usage

## S3 method for class 'symbolic_units'
as_spork(x, canonical = TRUE, ...)

Arguments

x

symbolic_units; see as_units

...

ignored arguments

Value

spork

Examples

library(units)
library(spork)
x <- as_units('kg.m/s^2')
names(attributes(x))
y <- attr(x,'units')
class(y)
as.character(y)
as.character(attr(x, 'units'))
as_spork(y)
library(magrittr)
'kg.m^2/s^2' %>% as_units %>% attr('units') %>% as_spork
'kg.m2 s-2' %>% as_units %>% attr('units') %>% as_spork
'kg.m^2/s^2' %>% as_units %>% attr('units') %>% as_spork(FALSE)
'kg.m2 s-2' %>% as_units %>% attr('units') %>% as_spork(FALSE)

Coerce Unit String to Spork

Description

Coerces unit string to spork. A literal dot means different things in spork vs. units, and there may be some other subtleties as well. Unit string is character that is_parseable.

Usage

## S3 method for class 'unit_string'
as_spork(x, ...)

Arguments

x

unit_string

...

ignored arguments

Value

units

Examples

library(magrittr)
library(spork)
'kg.m^2/s^2' %>% as_unit_string %>% as_spork
'kg.m2 s-2' %>% as_unit_string %>% as_spork

Coerce Units to Spork

Description

Coerces units to spork by coercing first to unit_string.

Usage

## S3 method for class 'units'
as_spork(x, canonical = TRUE, ...)

Arguments

x

units; see as_units

...

ignored arguments

Value

spork

Examples

library(units)
library(magrittr)
library(spork)
'kg.m^2/s^2' %>% as_units %>% as_spork
'kg.m2 s-2' %>% as_units %>% as_spork
'kg.m^2/s^2' %>% as_units %>% as_spork(FALSE)
'kg.m2 s-2' %>% as_units %>% as_spork(FALSE)

Coerce to Unit String

Description

Coerces to class 'unit_string'. Generic, with method as_unit_string.character. A unit string is character text suitable as input for as_units. See also is_parseable.

Usage

as_unit_string(x, ...)

Arguments

x

object

...

passed arguments

Value

unit_string

Examples

as_unit_string('kg.m^2/s^2')
as_unit_string('kg.m2 s-2')

Coerce Character to Unit String

Description

Coerces character to class 'unit_string'. See description for as_unit_string.

Usage

## S3 method for class 'character'
as_unit_string(x, ...)

Arguments

x

character

...

ignored arguments

Value

unit_string

Examples

as_unit_string('kg m2 s-2')

Coerce Factor to Unit String

Description

Coerces factor to class 'unit_string' by converting to character and calling as_unit_string.

Usage

## S3 method for class 'factor'
as_unit_string(x, ...)

Arguments

x

factor

...

ignored arguments

Value

unit_string

Examples

as_unit_string(as.factor('kg m2 s-2'))

Coerce Symbolic Units to Unit String.

Description

Coerces symbolic units to unit_string.

Usage

## S3 method for class 'symbolic_units'
as_unit_string(x, canonical = TRUE, ...)

Arguments

x

symbolic_units; see as_units

canonical

whether to return the form having all positive exponents

...

ignored arguments

Value

unit_string

Examples

library(units)
x <- as_units('kg.m/s^2')
names(attributes(x))
y <- attr(x,'units')
class(y)
as.character(y)
as.character(attr(x, 'units'))
as_unit_string(y)
library(magrittr)
'kg.m^2/s^2' %>% as_units %>% attr('units') %>% as_unit_string
'kg.m2 s-2' %>% as_units %>% attr('units') %>% as_unit_string
'kg.m^2/s^2' %>% as_units %>% attr('units') %>% as_unit_string(FALSE)
'kg.m2 s-2' %>% as_units %>% attr('units') %>% as_unit_string(FALSE)

Coerce Units to Unit String.

Description

Coerces units to unit_string. Extracts units attribute (of class(symbolic_units)) and converts.

Usage

## S3 method for class 'units'
as_unit_string(x, canonical = TRUE, ...)

Arguments

x

units; see as_units

...

ignored arguments

Value

unit_string

Examples

library(units)
x <- as_units('kg.m/s^2')
as_unit_string(x)
as_unit_string(x, canonical = FALSE)

Coerce Decorated Vector to Units

Description

Coerces dvec to units. If x has a units attribute, it is used to create class 'units'. It is an error if x has no units attribute.

Usage

## S3 method for class 'dvec'
as_units(x, ..., preserve = getOption("yamlet_as_units_preserve", "label"))

Arguments

x

dvec

...

ignored

preserve

attributes to preserve; just label by default (class and units are handled implicitly)

Examples

library(magrittr)
a <- data.frame(id = 1:4, wt = c(70, 80, 70, 80), sex = c(0,1,0,1))
a %<>% decorate('wt: [ body weight, kg ]')
a %<>% decorate('sex: [ sex, [ female: 0, male: 1]]')
a %<>% decorate('id: identifier')
a %<>% resolve
a$wt %>% as_units

Coerce to Yam

Description

Coerce to yam, a precursor to yamlet. Generic, with character method: as_yam.character.

Usage

as_yam(x, ...)

Arguments

x

object

...

passed arguments

Value

list

Coerce Character to Yam

Description

Coerces character to yam. Length-one character can be a filepath, otherwise treated as data. Proceeds by importing the data and determining the default keys.

Usage

## S3 method for class 'character'
as_yam(
  x,
  as.named.list,
  handlers = list(seq = parsimonious, map = function(x) lapply(x, unclass), str =
    function(x) {
     if (identical(x, "yamlet_NA_literal_")) {
         return("NA")
  
      }
     if (identical(x, "NA")) {
         return(NA_character_)
     }
    
    return(x)
 }),
  ...
)

Arguments

x

length-one filepath or actual data

as.named.list

enforced as TRUE

...

passed to read_yaml and yaml.load if supported

Value

a named list

Examples


# Read sample data from file.
file <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
file
as_yam(file)

# Read yamlet directly from character vector.
as_yam(c('ID:','TIME:'))

# Read from length-one character (same result).
as_yam('ID:\nTIME:')

Coerce Yamlet to Yam

Description

Coerces class yamlet to yam, negotiating the default keys. For each member of x, names of sub-members will be dropped if all previous such have been dropped. I.e., attribute order is preserved, and 'guide' (by default) will not be made implicit unless 'label' has already been encountered (and made implicit). Default keys are attached as the 'keys' attribute of the result.

Usage

## S3 method for class 'yamlet'
as_yam(
  x,
  ...,
  default_keys = getOption("yamlet_default_keys", list("label", "guide"))
)

Arguments

x

yamlet

...

ignored

default_keys

names that may be omitted in left subsets

Value

yam

Examples

as_yam(as_yamlet(c('id: subject','amt: dose')))
as_yam(as_yamlet(c('amt: [ dose, mg ]')))
as_yam(as_yamlet(c('amt: [ guide: mg, label: dose ]')))

Coerce to Yamlet

Description

Coerces something to yamlet format. If the object or user specifies default keys, these are applied. See as_yamlet.character.

Usage

as_yamlet(x, ...)

Arguments

x

object

...

passed arguments

Value

a named list

Examples

file <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
file
identical(as_yamlet(as_yam(file)), as_yamlet(file))

# Read yamlet from storage and apply default keys.
as_yamlet(file)

Coerce Character To Yamlet Format

Description

Coerces character to yamlet format. Length-one character is understood as a file path if the file exists. Otherwise, it is treated as data. The file is a mapping of (nested) sequences, where map keys are data item names, and sequences represent data item attributes. Attributes may be named or anonymous.

Usage

## S3 method for class 'character'
as_yamlet(
  x,
  default_keys = getOption("yamlet_default_keys", list("label", "guide")),
  ...
)

Arguments

x

length-one filepath or actual data

default_keys

character: default keys for the first n anonymous members of each element

...

passed to as_yam.character and as_yamlet.yam

Details

If an attribute is anonymous, an attempt is made to name it using available defaults. A special item named '_keys' if present identifies a sequence of key names that over-ride default_keys. Attribute names are sought first in the explicit yaml, then in the special item named '_keys', then in the default_keys argument passed to as_yamlet, then in options()$yamlet_default_keys, then in the defaults for argument default_keys.

Value

yamlet: a named list with default keys applied

Examples

file <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
as_yamlet(file)
as_yamlet('ID: subject identifier')
as_yamlet(c('id: subject','amt: dose'))
as_yamlet(c('id: subject\namt: dose'))

Coerce Data Frame to Yamlet

Description

Coerces data.frame to yamlet by calling decorations.

Usage

## S3 method for class 'data.frame'
as_yamlet(x, ...)

Arguments

x

data.frame

...

passed to decorations

Value

yamlet

Examples

library(csv)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(as.csv(file))
as_yamlet(x)

Coerce List to Yamlet

Description

Coerces list to yamlet. Assigns class 'yamlet'. Checks that list has names.

Usage

## S3 method for class 'list'
as_yamlet(x, ...)

Arguments

x

list

...

ignored

Value

yamlet

Examples

x <- list(a = 2, b = 3)
as_yamlet(x)

Coerce Yam To Yamlet Format

Description

Coerces yam to yamlet format. If the object or user specifies default keys, these are applied See as_yamlet.character.

Usage

## S3 method for class 'yam'
as_yamlet(
  x,
  default_keys = getOption("yamlet_default_keys", list("label", "guide")),
  ...
)

Arguments

x

a yam object; see as_yam

default_keys

character: default keys for the first n anonymous members of each element

...

ignored

Value

yamlet: a named list with default keys applied

Examples

file <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
file
as_yamlet(as_yam(file))

Coerce Yamlet to Yamlet

Description

Coerces yamlet to yamlet. Currently a non-operation.

Usage

## S3 method for class 'yamlet'
as_yamlet(x, ...)

Arguments

x

yamlet

...

ignored

Value

yamlet

Examples

meta <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
x <- as_yamlet(meta)
as_yamlet(x)

Combine Classified

Description

Combines classified factor, retaining attributes. Attributes other than levels and codelist are taken from the first argument. Attribute 'levels' is supplied by next method. Attribute 'codelist' is the combined codelists in sequence of all (dots) arguments, after silently removing exact duplicates. If any names are duplicated, the entire codelist is replaced by the effective levels, with optional warning.

Usage

## S3 method for class 'classified'
c(
  ...,
  recursive = TRUE,
  warn_conflicted = getOption("yamlet_warn_conflicted", FALSE)
)

Arguments

...

passed to next method

recursive

passed to unlist() internally

warn_conflicted

logical: warn if any duplicated codelist names?

Value

class 'classified' 'factor'

Examples

a <- classified(letters[1:3])
b <- classified(letters[3:5])
c <- c(a,b)
c
class(c)

Combine Decorated Vector

Description

Combines decorated vectors. Tries to preserve attributes by resolving pairwise conflicts intelligently. The attributes of the first item are reconciled with those of the second, then those of the third, etc. the class attribute is untouched.

Usage

## S3 method for class 'dvec'
c(...)

Arguments

...

items to be combined, presumably all vectors

Details

By default, the first version of any attribute is preserved, with warning if the alternative differs. NULLs are largely ignored. If either attribute is a list the other is coerced to a list with as.list(). If either of two lists has names, then names are enforced for the other (blank names if necessary). Lists are combined in forward order, and elements that are duplicates in value and name (if present) are removed. If the result has only blank names, these are removed as well.

Value

dvec

Examples

a <- as_dvec(letters[1:3], label = 'foo')
b <- as_dvec(letters[3:5], label = 'foo')
c <- c(a,b)
c
class(c)

Enforce Canonical Order

Description

Enforce canonical order. Generic, with method: canonical.decorated.

Usage

canonical(x, ...)

Arguments

x

object

...

passed arguments

Value

list

Sort Decorations

Description

Enforces canonical attribute order for class 'decorated'. Set of default_keys will be augmented with all observed attribute names and will be expanded or reduced as necessary for each data item.

Usage

## S3 method for class 'decorated'
canonical(
  x,
  default_keys = getOption("yamlet_default_keys", list("label", "guide")),
  ...
)

Arguments

x

decorated

default_keys

attribute names in preferred order

...

ignored

Value

decorated

Examples

# make some decorated data
library(magrittr)
x <- data.frame(x = 1, y = 1, z = factor('a'))
x %<>% decorate('
x: [ guide: mm, desc: this, label: foo ]
"y": [ guide: bar, desc: other ]
')

# retrieve decorations: label not first!
decorations(x)

# sort label first by default
decorations(canonical(x))

# equivalent invocation
canonical(decorations(x))

Sort Yamlet

Description

Enforces canonical attribute order for class 'yamlet'. Set of default_keys will be augmented with all observed attribute names and will be expanded or reduced as necessary for each data item.

Usage

## S3 method for class 'yamlet'
canonical(
  x,
  default_keys = getOption("yamlet_default_keys", list("label", "guide")),
  ...
)

Arguments

x

yamlet

default_keys

attribute names in preferred order

...

ignored

Value

decorated

Examples

library(magrittr)
x <- data.frame(x = 1, y = 1, z = factor('a'))
x %<>% decorate('
x: [ guide: mm, desc: this, label: foo ]
"y": [ guide: bar, desc: other ]
')

decorations(x)
decorations(canonical(x))
canonical(decorations(x))
write_yamlet(x)

Calculate a Cell Value

Description

Calculates a cell value.

Usage

cell_value(x, sep = "\n", def = ": ")

Arguments

x

list of character, possibly named

sep

separator for multiple items within an attribute

def

definition string: separator between items and their (preceding) names, if any

Classify Something

Description

Classifies something. Generic, with method classified.default

Usage

classified(x, ...)

Arguments

x

object of dispatch

...

passed arguments

Value

see methods

Examples

example(classified.default)

Create Classified from Classified

Description

See classified.default. Formerly (version 0.10.10), calling classified() on a classified object was a non-operation. Currently we call factor(x, ...) and then try to reconcile the codelist attribute with resulting levels.

Usage

## S3 method for class 'classified'
classified(
  x,
  levels,
  labels,
  exclude = NULL,
  ordered = is.ordered(x),
  nmax = NA,
  drop = FALSE,
  ...
)

Arguments

x

classified

levels

passed to factor; defaults to levels(x)

labels

passed to factor; must be same length as levels(after removing values in exclude and unused levels if drop is TRUE) and must not contain duplicates

exclude

passed to factor

ordered

passed to factor

nmax

passed to factor

drop

whether to drop unused levels

...

ignored

Details

By default classified is idempotent, such that classified(classified(x)) is the same as classified(x). In contrast, factor(factor(x)) will drop unused levels (not shown). To drop unused levels, use classified(classified(x), drop = TRUE).

Value

'classified' 'factor'

Examples


a <- 4:6
attr(a, 'codelist') <- list(d = 4, e = 5, f = 6, g = 7)
b <- classified(a)
a
b
class(b)
classified(b)
identical(b, classified(b))

Classify Data Frame

Description

Coerces items in data.frame with codelist attribute to 'classified': a factor with a codelist attribute.

Usage

## S3 method for class 'data.frame'
classified(x, ..., exclude = NA, ordered = is.ordered(x), nmax = NA)

Arguments

x

data.frame

...

passed to select to limit column scope

exclude

see factor

ordered

see factor

nmax

see factor

Value

data.frame

Examples

library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)
x %>% explicit_guide %>% decorations(Age, Race, Heart:glyco)
x %>% explicit_guide %>% classified %>% decorations(Age, Race, Heart:glyco)
x %>% explicit_guide %>% classified(Heart:glyco) %>% decorations(Age, Race, Heart:glyco)

Create Classified by Default

Description

Creates a factor of subclass 'classified', for which there are attribute-preserving methods. In particular, classified has a codelist attribute indicating the origin of its levels: it is constructed from the codelist attribute of x if available, or from 'levels' and 'labels' by default. Unlike the case for factor, length of labels cannot be one (i.e., different from length of levels).

Usage

## Default S3 method:
classified(
  x = character(),
  levels,
  labels,
  exclude = NA,
  ordered = is.ordered(x),
  nmax = NA,
  token = character(0),
  ...
)

Arguments

x

see factor

levels

see factor

labels

see factor, must have same length as levels

exclude

see factor

ordered

see factor

nmax

see factor

token

informative label for messages

...

ignored

Value

'classified' 'factor'

Examples


# classified creates a factor with a corresponding codelist attribute
classified(c('a','b','c'))

# codelist 'remembers' the origins of levels
classified(c('a','b','c'), labels = c('A','B','C'))

# classified is 'reversible'
library(magrittr)
c('a','b','c') %>%
  classified(labels = c('A','B','C')) %>%
  unclassified

Classify Decorated Vector

Description

Coerces dvec to 'classified': a factor with a codelist attribute. Results may differ if explicit_guide() is called first.

Usage

## S3 method for class 'dvec'
classified(
  x,
  ...,
  exclude = NA,
  ordered = is.ordered(x),
  nmax = NA,
  token = character(0)
)

Arguments

x

dvec

...

un-named arguments ignored. Named arguments passed to classified.default to modify behavior

exclude

see factor

ordered

see factor

nmax

see factor

token

informative label for messages

Value

classified

Examples

library(magrittr)
x <- as_dvec(1:3)
attr(x, 'guide') <- list(a = 1, b = 2, c = 3)
x %>% str
x %>% classified %>% str
x %>% explicit_guide %>% classified %>% str

Create Classified from Factor

Description

Creates classified from factor. Uses classified.default, but supplies existing levels by default.

Usage

## S3 method for class 'factor'
classified(
  x = character(),
  levels,
  labels,
  exclude = NA,
  ordered = is.ordered(x),
  nmax = NA,
  token = character(0),
  ...
)

Arguments

x

see factor

levels

passed to classified.default; defaults to levels(x)

labels

passed to classified.default; must be same length as levels(after removing values in exclude) and must not contain duplicates

exclude

see factor

ordered

see factor

nmax

see factor

token

informative label for messages

...

ignored

Value

'classified' 'factor'

Examples

a <- factor(c('c','b','a'))
levels(classified(a))
attr(classified(a), 'codelist')

Conditionalize Attributes

Description

Conditionalizes attributes of something. Generic, with method for data.frame.

Usage

conditionalize(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(conditionalize.data.frame)

Conditionalize Attributes of Data Frame

Description

Conditionalizes attributes of data.frame. Creates a conditional attribute definition for column by mapping value to test. Only considers records where both test and value are defined, and gives an error if there is not one-to-one mapping. Can be used with write methods as an alternative to hand-coding conditional metadata.

Usage

## S3 method for class 'data.frame'
conditionalize(x, column, attribute, test, value, ...)

Arguments

x

data.frame

column

unquoted name of column to conditionalize

attribute

unquoted name of attribute to create for column

test

unquoted name of column to test

value

unquoted name of column supplying attribute value

...

ignored arguments

Details

If the test column is character, individual elements should not contain both single and double quotes. For the conditional expressions, these values will be single-quoted by default, or double-quoted if they contain single quotes.

Value

class 'decorated' 'data.frame'

Examples

library(magrittr)
library(dplyr)
library(csv)
file <- system.file(package = 'yamlet', 'extdata','phenobarb.csv')
x <- as.csv(file)
head(x,3)

# suppose we have an event label stored as a column:

x %<>% mutate(evid = ifelse(
  event == 'dose',
  'dose of drug administered',
  'serum phenobarbital concentration'
 )
)

# We can define a conditional label for 'value'
# by mapping evid to event:

x %<>% conditionalize(value, label, event, evid)

x %>% as_yamlet
x %>% write_yamlet

Coerce Data.frame to Decorated

Description

Coerces data.frame to decorated. Wrapper for df_cast.

Usage

dd_cast(x, to, ...)

Arguments

x

subclass of data.frame

to

subclass of data.frame

...

passed arguments

Value

decorated

Coerce Common Type to Decorated

Description

Coerces common type to decorated. Wrapper for df_ptype2.

Usage

dd_ptype2(x, y, ...)

Arguments

x

subclass of data.frame

y

subclass of data.frame

...

passed arguments

Value

decorated

Decorate a List-like Object

Description

Decorates a list-like object. Generic. See decorate.character.

Usage

decorate(x, ...)

Arguments

x

object

...

passed arguments

Value

a list-like object, typically data.frame

Examples

library(csv)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(as.csv(file))
identical(decorate(as.csv(file)), decorate(file))
decorations(x)

Decorate Character

Description

Treats x as a file path. By default, metadata is sought from a file with the same base but the 'yaml' extension.

Usage

## S3 method for class 'character'
decorate(
  x,
  meta = NULL,
  ...,
  read = getOption("yamlet_import", as.csv),
  ext = getOption("yamlet_extension", ".yaml")
)

Arguments

x

file path for table data

meta

file path for corresponding yamlet metadata, or a yamlet object

...

passed to read (if accepted) and to as_yamlet.character

read

function or function name for reading x

ext

file extension for metadata file, if relevant

Value

class 'decorated' 'data.frame'

Examples


# find data file
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
file

# find metadata file
meta <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
meta

# decorate with explicit metadata reference
a <- decorate(file, meta)

# rely on default metadata path
b <- decorate(file)

# in this case: same
stopifnot(identical(a, b))

Decorate Data Frame

Description

Decorates a data.frame. Expects metadata in yamlet format, and loads it onto columns as attributes.

Usage

## S3 method for class 'data.frame'
decorate(
  x,
  meta = NULL,
  ...,
  persistence = getOption("yamlet_persistence", TRUE)
)

Arguments

x

data.frame

meta

file path for corresponding yaml metadata, or a yamlet; an attempt will be made to guess the file path if x has a 'source' attribute

...

passed to decorate.list

persistence

whether to coerce decorated columns to 'dvec' where suitable method exists

Details

As of v0.8.8, the data.frame method for decorate() coerces affected columns using as_dvec if persistence is true and a suitable method exists. 'vctrs' methods are implemented for class dvec to help attributes persist during tidyverse operations. Details are described in c.dvec. Disable this functionality with options(yamlet_persistence = FALSE).

Value

class 'decorated' 'data.frame'

Examples


# find data path
library(csv)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
file
dat <- as.csv(file) # dat now has 'source' attribute

# use source attribute to find metadata 
a <- decorate(as.csv(file))

# supply metadata path (or something close) explicitly
b <- decorate(dat, meta = file)

# these are equivalent
stopifnot(identical(a, b))

Decorate List

Description

Decorates a list-like object. Takes metadata in yamlet format and loads it onto corresponding list elements as attributes.

Usage

## S3 method for class 'list'
decorate(
  x,
  meta = NULL,
  ...,
  ext = getOption("yamlet_extension", ".yaml"),
  persistence = getOption("yamlet_persistence", FALSE),
  overwrite = getOption("yamlet_overwrite", FALSE)
)

Arguments

x

object inheriting from list

meta

file path for corresponding yaml metadata, or a yamlet or something coercible to yamlet; an attempt will be made to guess the file path if x has a 'source' attribute (as for as.csv)

...

passed to as_yamlet.character (by method dispatch)

ext

file extension for metadata file, if relevant

persistence

whether to coerce decorated items to 'dvec' where suitable method exists

overwrite

whether to overwrite attributes that are already present (else give warning)

Details

As of v0.8.8, attribute persistence is supported by optionally coercing decorated items to class 'dvec' where suitable methods exist. persistence is false by default for the list method but true by default for the data.frame method. See also decorate.data.frame.

Value

like x but with 'decorated' as first class element

Examples

example(decorate.data.frame)

Capture Groups as Decorations

Description

Captures groups as decorations. Generic, with method decorate_groups.data.frame

Usage

decorate_groups(x, ...)

Arguments

x

object of dispatch

...

passed

Capture Groups as Decorations for Data Frame

Description

Captures groups as decorations for class 'data.frame'. Creates a sequentially-valued integer attribute with name 'groups' for each corresponding column (after clearing all such existing designations). It is an error if not all such columns are present. Defaults to groups(x). If no columns are specified and x has no groups, x is returned with any existing column-level 'groups' attributes removed.

Usage

## S3 method for class 'data.frame'
decorate_groups(x, ...)

Arguments

x

data.frame

...

unquoted names of columns to assign as groups; defaults to groups(x)

Value

same class as x

Examples

library(magrittr)
library(dplyr)
Theoph %>% decorate_groups(Subject, Time) %>% groups # nothing!
Theoph %>% decorate_groups(Subject, Time) %>% decorations # note well
Theoph %>% group_by(Subject, Time) %>% decorate_groups %>% decorations # same

Retrieve Decorations

Description

Retrieve the decorations of something. Generic, with method decorations.data.frame.

Usage

decorations(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

library(csv)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(as.csv(file))
decorations(x)

Retrieve Decorations for Data Frame

Description

Retrieve the decorations of a data.frame; i.e., the metadata used to decorate it. Returns a list with same names as the data.frame. By default, 'class' and 'level' attributes are excluded from the result, as you likely don't want to manipulate these independently.

Usage

## S3 method for class 'data.frame'
decorations(
  x,
  ...,
  exclude_attr = getOption("yamlet_exclude_attr", c("class", "levels"))
)

Arguments

x

data.frame

...

optional unquoted column names to limit output (passed to select)

exclude_attr

attributes to remove from the result

Value

named list of class 'yamlet'

Examples

# prepare a decorated data.frame
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)

# retrieve the decorations
decorations(x, Subject, time, conc)

Recover Groups Decorations

Description

Recovers groups decorations. Generic, with method decorations_groups.data.frame

Usage

decorations_groups(x, ...)

Arguments

x

object of dispatch

...

passed

Recover Groups Decorations for Data Frame

Description

Recovers groups decorations for class 'data.frame'. Seeks a sequentially-valued integer attribute with name 'groups' for each column, sorts these, and returns a character vector like group_vars(x).

Usage

## S3 method for class 'data.frame'
decorations_groups(x, ...)

Arguments

x

data.frame

...

ignored

Value

character: names of groups columns

Examples

library(magrittr)
library(dplyr)
Theoph %<>% group_by(Subject, Time)
Theoph %>% group_vars
Theoph %>% decorations_groups # nothing!
Theoph %<>% decorate_groups
Theoph %>% decorations_groups # something!
Theoph %<>% ungroup
Theoph %>% group_vars # gone!
Theoph %<>% group_by(across(all_of(decorations_groups(.))))
Theoph %>% group_vars # recovered!
Theoph %<>% group_by_decorations
Theoph %>% group_vars # same
rm(Theoph)

Desolve Guide

Description

Un-resolves explicit versions of 'guide' to implicit usage. Generic, with methods desolve.decorated, desolve.classified, and desolve.dvec.

Usage

desolve(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(resolve.decorated)

Desolve Guide for Classified

Description

Un-resolves explicit usage of default key 'guide' to implicit usage for class 'classified'. Calls drop_title (a non-action by default), unclassified, followed by implicit_guide.

Usage

## S3 method for class 'classified'
desolve(x, ...)

Arguments

x

classified

...

passed to drop_title, unclassified, and unclassified

Value

dvec

Examples

library(magrittr)
x <- as_dvec(
  4:6, 
  guide = list(a = 4L, b = 5L, c = 6L)
)

# untouched
x %>% str

# resolved
x %>% resolve %>% str

# resolved and desolved
x %>% resolve %>% desolve %>% str

Desolve Data Frame

Description

Desolves data.frame. Coerces first using as_decorated().

Usage

## S3 method for class 'data.frame'
desolve(x, ...)

Arguments

x

data.frame

...

ignored

Value

decorated

Examples

head(desolve(Theoph))

Desolve Guide for Decorated

Description

Un-resolves explicit usage of default key 'guide' to implicit usage for 'decorated' class. Simply calls drop_title, unclassified, and implicit_guide.

Usage

## S3 method for class 'decorated'
desolve(x, ...)

Arguments

x

decorated

...

passed to drop_title, unclassified, and implicit_guide

Value

decorated

Examples

library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)

# this is how Age, glyco, Race look when resolved
x %>% resolve %>% decorations(Age, glyco, Race)

# we can resolve two of them and then 'unresolve' all of them
x %>% resolve(glyco, Race) %>% desolve %>% decorations(Age, glyco, Race)

Desolve Guide for Decorated Vector

Description

Un-resolves explicit usage of default key 'guide' to implicit usage for class dvec. Calls drop_title, unclassified, and implicit_guide.

Usage

## S3 method for class 'dvec'
desolve(x, ...)

Arguments

x

...

passed to drop_title, unclassified, and implicit_guide

Value

dvec

Examples

library(magrittr)
x <- as_dvec(4:6)
attr(x, 'guide') <- 'kg'
x %>% str
x %>% resolve %>% str
x %>% resolve %>% desolve %>% str

Drop Title

Description

Drop title attribute. Generic, with methods drop_title.default, drop_title.decorated, and drop_title.dvec.

Usage

drop_title(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

# see methods

Drop Title for Decorated

Description

Drops title for 'decorated' class. Limits scope to requested variables, and then calls class-specific methods for each.

Usage

## S3 method for class 'decorated'
drop_title(x, ...)

Arguments

x

object

...

optional names of variables to limit scope

Value

decorated

Examples

library(magrittr)
x <- data.frame(length = 1:10)
x %>% 
  decorate('length: [ Length, mm ]') %>%
  resolve %>% 
  desolve %>%
  decorations

Drop Title by Default

Description

Drops title by default. To be specific: this is the default method for the generic function drop_title, and it actually does nothing. Individual methods are written for those classes where 'drop title' behavior is expected.

Usage

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

Arguments

x

object

...

ignored

Value

same as x

Drop Title for Decorated Vector

Description

Drops title for decorated vectors. If option with_title is TRUE and x has a 'units' attribute, it removes the title attribute. See also make_title for coordinated use.

Usage

## S3 method for class 'dvec'
drop_title(x, ..., with_title = getOption("yamlet_with_title", TRUE))

Arguments

x

dvec

...

ignored arguments

with_title

whether to drop title

Value

dvec

Examples

library(magrittr)
1 %>% 
as_dvec(label = 'length', guide = 'mm') %>%
resolve %>%
desolve

Encode Yamlet

Description

Encodes yamlet. Each 'guide' element with length > 1 is converted to an encoding, if possible. If data is supplied, conditional guides will be ignored.

Usage

## S3 method for class 'yamlet'
encode(x, ..., target = "guide", data = NULL)

Arguments

x

yamlet

...

ignored

target

attribute to encode

data

optional data.frame for guide context

Value

yamlet, with guide elements possibly transformed to encodings

Examples

meta <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
meta <- as_yamlet(meta)
meta <- encode(meta)

Render Scripted Attributes of Indicated Components

Description

Renders the scripted attributes of indicated components. Generic, with method enscript.default.

Usage

enscript(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(enscript.default)

Render Scripted Attributes of Indicated Components by Default

Description

Modifies specific attributes of each indicated element (all elements by default).

Usage

## Default S3 method:
enscript(
  x,
  ...,
  open = getOption("yamlet_append_units_open", " ("),
  close = getOption("yamlet_append_units_close", ")"),
  format = getOption("yamlet_format", ifelse(knitr::is_latex_output(), "latex", "html"))
)

Arguments

x

object

...

indicated columns, or name-value pairs; passed to resolve and selected

open

character to precede units

close

character to follow units

format

one of 'latex' or 'html'

Details

The goal here is to render labels and units (where present) in a way that supports subscripts and superscripts for both plots and tables in either html or latex contexts.

The current implementation writes an 'expression' attribute to support figure labels and a 'title' attribute to support tables. print.decorated_ggplot will attempt to honor the expression attribute if it exists. tablet.data.frame will attempt to honor the title attribute if it exists (see Details there). An attempt is made to guess the output format (html or latex).

In addition to the 'title' and 'expression' attributes, enscript() writes a 'plotmath' attribute to store plotmath versions of factor levels, where present. By default, factor levels are converted to their latex or html equivalents. However, print.decorated_ggplot will use the plotmath versions of factor labels for legends and facet labels. If a 'plotmath' attribute already exists, it is not overwritten, preventing the same variable from being accidentally transformed twice.

To flexibly support latex, html, and plotmath, this function expects column labels and units to be encoded in "spork" syntax. See as_spork for details and examples. Briefly, "_" precedes a subscript, "^" precedes a superscript, and "." is used to force the termination of either a superscript or a subscript where necessary. For best results, units should be written using *, /, and ^; e.g. "kg*m^2/s^2" not "kg m2 s-2" (although both are valid: see is_parseable). A literal backslash followed by "n" represents a newline. Greek letters are represented by their names, except where names are enclosed in backticks.

enscript() always calls resolve() for the indicated columns, to make units present where appropriate.

Value

'enscript', a superclass of x

Examples

library(magrittr)
library(ggplot2)
x <- data.frame(time = 1:10, work = (1:10)^1.5)
x %<>% decorate('
  time: [ Time_elapsed, h ]
  work: [ Work_total_observed, kg*m^2/s^2 ]
')

x %>% decorations
x %>% ggplot(aes(time, work)) + geom_point()
x %>% enscript %>% ggplot(aes(time, work)) + geom_point()
x %>% enscript(format = 'html') %$% work %>% attr('title')
testthat::expect_equal(enscript(x), enscript(enscript(x)))

Coerce Guide to Something More Explicit

Description

Coerces 'guide' to something more explicit. Generic, with methods for data.frame and yamlet. The key 'guide' generally suggests a guide to interpretation of a data item, such as units, formats, codelists, and encodings. The idea here is to replace 'guide' with something explicit in case required downstream.

Usage

explicit_guide(x, ...)

Arguments

x

object of dispatch

...

passed arguments

Value

see methods

Coerce Data Frame Guide to Something More Explicit

Description

Coerces data.frame 'guide' attributes to something more explicit. The attribute 'guide' generally suggests a guide to interpretation of a data item, such as units, formats, codelists, and encodings. The idea here is to replace 'guide' with something explicit in case required downstream.

Usage

## S3 method for class 'data.frame'
explicit_guide(
  x,
  ...,
  overwrite = getOption("yamlet_explicit_guide_overwrite", TRUE),
  simplify = getOption("yamlet_explicit_guide_simplify", TRUE),
  expand = getOption("yamlet_expand_codelist", TRUE)
)

Arguments

x

data.frame

...

named arguments passed to as_yamlet, explicit_guide, and decorate; un-named arguments limit scope

overwrite

passed as TRUE

simplify

whether to remove guide attribute

expand

whether to expand empty guide list using sorted unique values. NA likely excluded.

Details

This method pulls the 'decorations' off of the data.frame, converts to yamlet, applies explicit_guide.yamlet, purges 'guide' attributes from the data.frame, and then re-decorates using overwrite = TRUE.

Value

data.frame

Examples

library(magrittr)
x <- data.frame(
 ID = 1,
 CONC = 1,
 RACE = 1,
 SEX = 1,
 DATE = 1
)
x %<>% modify(ID, label = 'subject identifier')
x %<>% modify(CONC, label = 'concentration', guide = 'ng/mL')
x %<>% modify(RACE, label = 'race', guide = list(white = 0, black = 1, asian = 2))
x %<>% modify(SEX, label = 'sex', guide = list(female = 0, male = 1))
x %<>% modify(DATE, label  = 'date', guide = '%Y-%m-%d')
x %>% decorations
x %>% explicit_guide %>% decorations
x %>% explicit_guide(DATE) %>% decorations # limit scope

Coerce Decorated Vector Guide to Something More Explicit

Description

Coerces dvec 'guide' attribute to something more explicit. The attribute 'guide' generally suggests a guide to interpretation of a data item, such as units, formats, codelists, and encodings. The idea here is to replace 'guide' with something explicit in case required downstream.

Usage

## S3 method for class 'dvec'
explicit_guide(
  x,
  ...,
  overwrite = getOption("yamlet_explicit_guide_overwrite", TRUE),
  simplify = getOption("yamlet_explicit_guide_simplify", TRUE),
  expand = getOption("yamlet_expand_codelist", TRUE)
)

Arguments

x

dvec

...

named arguments passed to as_yamlet, explicit_guide, and decorate; un-named arguments ignored

overwrite

whether to overwrite attributes

simplify

whether to remove guide attribute

expand

whether to expand empty guide list using sorted unique values. NA likely excluded.

Value

dvec

Examples

library(magrittr)
x <- data.frame(
 ID = as_dvec(1),
 CONC = as_dvec(1),
 RACE = as_dvec(1),
 SEX = as_dvec(1),
 DATE = as_dvec(1)
)
x %<>% modify(ID, label = 'subject identifier')
x %<>% modify(CONC, label = 'concentration', guide = 'ng/mL')
x %<>% modify(RACE, label = 'race', guide = list(white = 0, black = 1, asian = 2))
x %<>% modify(SEX, label = 'sex', guide = list(female = 0, male = 1))
x %<>% modify(DATE, label  = 'date', guide = '%Y-%m-%d')
x %>% decorations
x %>% explicit_guide %>% decorations
x %>% explicit_guide(DATE) %>% decorations # limit scope
x %$% DATE %>% explicit_guide

Coerce Yamlet Guide to Something More Explicit

Description

Coerces yamlet 'guide' keys to something more explicit. The key 'guide' generally suggests a guide to interpretation of a data item, such as units, formats, codelists, and encodings. The idea here is to replace 'guide' with something explicit in case required downstream.

Usage

## S3 method for class 'yamlet'
explicit_guide(
  x,
  ...,
  test = getOption("yamlet_infer_guide", yamlet::infer_guide),
  expand = getOption("yamlet_expand_codelist", TRUE),
  data = NULL
)

Arguments

x

yamlet

...

passed to select to limit scope

test

function or function name; supply non-default or globally set options(yamlet_infer_guide = ).

expand

whether to expand empty guide list using sorted unique values. NA likely excluded.

data

optional data.frame for testing guides with length > 1

Details

If data is supplied, guides that are lists are checked to see if they evaluate to conditions in data context (see isConditional.list). If so, inferences are based on the first guide element rather than the guide as a whole.

This method iterates across the guide elements, renaming them as specified by the value of test. (default: infer_guide). test should be a function (or name of one) that accepts x, data, and dots. If a data.frame is passed to explicit_guide(), the relevant column will be passed as data to test.

Value

yamlet

Examples

library(magrittr)
'CONC: [ concentration, µg/mL ]' %>% as_yamlet %>% explicit_guide
'RACE: [ subject race, [ Caucasian: 0, Latin: 1, Black: 2 ]]' %>% as_yamlet %>% explicit_guide
'RACE: [ subject race, [ Caucasian, Latin, Black ]]' %>% as_yamlet %>% explicit_guide
'RACE: [ subject race, //0/Caucasian//1/Latin//2/Black// ]' %>% as_yamlet %>% explicit_guide
'DATE: [ date, "%Y-%m-%d" ]' %>% as_yamlet %>% explicit_guide
'PRSE: [ standard error, "%" ]' %>% as_yamlet %>% explicit_guide

Filter Decorated

Description

Filters a decorated data.frame. After a filter operation, promote() is called to see if ambiguous conditional attributes can be improved.

Usage

## S3 method for class 'decorated'
filter(
  .data,
  ...,
  .preserve = FALSE,
  .promote = getOption("yamlet_promote", TRUE)
)

Arguments

.data

passed to filter

...

passed to filter

.preserve

passed to filter

.promote

whether to auto-promote plural attributes

Value

decorated

Examples

library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','phenobarb.csv')
x <- file %>% decorate

# Note that there are two elements each for value label and value guide.
x %>% decorations(event, value)

# Filtering promotes the relevant conditional attributes automatically.
x %>% filter(event == 'dose') %>% decorations(value)
x %>% filter(event == 'conc') %>% decorations(value)

Footnote Something

Description

Footnotes something. Generic, with method footnote.decorated.

Usage

footnote(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

# see methods

Footnote Decorated

Description

Footnotes a decorated data.frame. Generates a text string that defines column names using label and unit attributes.

Usage

## S3 method for class 'decorated'
footnote(x, ..., equal = ":", collapse = "; ")

Arguments

x

decorated

...

passed to append_units

equal

character: a symbol suggesting equality between a name and its note

collapse

used to paste column-wise footnotes

Value

character

Examples

library(magrittr)
set.seed(0)
x <- data.frame(
 auc = rnorm(100, mean = 2400, sd = 200),
 bmi = rnorm(100, mean = 20, sd = 5),
 gen = 0:1
)
x %<>% decorate('auc: [AUC_0-24, ng*h/mL]')
x %<>% decorate('bmi: [Body Mass Index, kg/m^2]')
x %<>% decorate('gen: [Gender, [Male: 1, Female: 0]]')
x %<>% resolve
footnote(x)
footnote(x, auc)

Format Decorated Vector

Description

Formats a decorated vector.

Usage

## S3 method for class 'dvec'
format(x, ...)

Arguments

x

dvec

...

passed arguments

Value

character

Full_join Decorated

Description

Preserves class when joining decorated.

Usage

## S3 method for class 'decorated'
full_join(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

Arguments

x, y

A pair of data frames, data frame extensions (e.g. a tibble), or lazy data frames (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

by

A join specification created with join_by(), or a character vector of variables to join by.

To join on different variables between x and y, use a join_by() specification. For example, join_by(a == b) will match x$a to y$b.

join_by() can also be used to perform inequality, rolling, and overlap joins. See the documentation at ?join_by for details on these types of joins.

To perform a cross-join, generating all combinations of x and y, see cross_join().

copy

suffix

If there are non-joined duplicate variables in x and y, these suffixes will be added to the output to disambiguate them. Should be a character vector of length 2.

...

Other parameters passed onto methods.

Gather a Decorated Data Frame

Description

Gathers a decorated data.frame. I.e. a gather method for class 'decorated'. Invokes tidyr::gather(), converting gathered labels to the guide attribute of key, and converting gathered guides ... if all the same ... to the guide attribute of value. Somewhat experimental!

Usage

## S3 method for class 'decorated'
gather(
  data,
  key = "key",
  value = "value",
  ...,
  na.rm = FALSE,
  convert = FALSE,
  factor_key = FALSE
)

Arguments

data

see gather

key

see gather

value

see gather

...

see gather

na.rm

see gather

convert

see gather

factor_key

see gather

Value

decorated

Examples

library(magrittr)
library(tidyr)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)
x %>% gather('key', 'value', time, interval) %>% decorations

Get Labels

Description

Gets labels for a ggplot object. Not exported, to avoid confusion. Development version of ggplot2 implements new get_labs() interface. This function is an abstraction that supports new vs old approaches, solely for yamlet's interests. See https://github.com/tidyverse/ggplot2/pull/6078.

Usage

get_labs(plot)

Arguments

plot

the ggplot

Detect Revised Label Strategy

Description

Detects the existence of qqplot's updated label strategy after v. 3.5.1, e.g. ggplot2_3.5.1.9000. For internal use to accommodate breaking changes.

Usage

gg_new()

Create a New ggplot for a Decorated Data Frame

Description

Creates a new ggplot object for a decorated data.frame. This is the ggplot() method for class 'decorated'. It creates a ggplot object using the default method, but reclassifies it as 'decorated_ggplot' so that a custom print method is invoked; see print.decorated_ggplot.

Usage

## S3 method for class 'decorated'
ggplot(data, ...)

Arguments

data

decorated, see decorate

...

passed to ggplot

Details

This approach is similar to but more flexible than the method for ggready. For fine control, you can switch between 'data.frame' and 'decorated' using as_decorated (supplies null decorations) and as.data.frame (preserves decorations).

Value

return value like ggplot but inheriting 'decorated_ggplot'

Examples

file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
library(ggplot2)
library(dplyr)
library(magrittr)
# par(ask = FALSE)

x <- decorate(file)
x %<>% filter(!is.na(conc))

# Manipulate class to switch among ggplot methods.
class(x)
class(data.frame(x))
class(as_decorated(data.frame(x)))

# The bare data.frame gives boring labels and un-ordered groups.
# (After ggplot2 v. 3.5.1 label attributes are honored as axis labels.)
map <- aes(x = time, y = conc, color = Heart)
data.frame(x) %>% ggplot(map) + geom_point()

# Decorated data.frame uses supplied labels.
# Notice CHF levels are still not ordered. (Moderate first.)
x %>% ggplot(map) + geom_point()

# If we resolve Heart, CHF levels are ordered.
x %>% resolve(Heart) %>% ggplot(map) + geom_point()

# We can map aesthetics as decorations.
x %>% 
  decorate('Heart: [ color: [gold, purple, green]]') %>%
  ggplot(map) + geom_point()

# Colors are matched to particular levels. Purple drops out here:
x %>% 
  decorate('Heart: [ color: [gold, purple, green]]') %>%
  filter(Heart != 'Moderate') %>%
  ggplot(map) + geom_point()

# We can resolve other columns for a chance to enrich the output with units.
x %>%
  resolve %>%
  ggplot(map) + geom_point()

# Underscore and circumflex imply subscript and superscript:
x %>% 
  redecorate("conc: [ conc_serum, mg*L^-1 ]") %>%
  ggplot(map) + geom_point()

# If we invoke enscript(), the subscripts and superscripts are rendered: 
x %>% 
  redecorate("conc: [ conc_serum, mg*L^-1 ]") %>%
  redecorate("Heart: [ CHF^\\* ]") %>%
  enscript %>%
  ggplot(map) + geom_point()

# Here we try a dataset with conditional labels and units.

file <- system.file(package = 'yamlet', 'extdata','phenobarb.csv')
x <- file %>% decorate %>% resolve
# Note that value has two elements for label, etc.
x %>% decorations(value)

# The print method defaults to the first, with warning.
map <- aes(x = time, y = value, color = event)

x %>% ggplot(map) + geom_point()


# If we subset appropriately, the relevant value is substituted.
x %>% filter(event == 'conc') %>% ggplot(map) + geom_point()

x %>% filter(event == 'conc') %>%
ggplot(aes(x = time, y = value, color = ApgarInd)) + geom_point()

x %>% filter(event == 'dose') %>%
ggplot(aes(x = time, y = value, color = Wt)) +
geom_point() +
scale_y_log10() +
scale_color_gradientn(colours = rainbow(4))

# print.decorated_ggplot will attempt to honor coordinated aesthetics.
x <- data.frame(x = c(1:6, 3:8), y = c(1:6,1:6), z = letters[c(1:6,1:6)])
x %<>% decorate('z: [color: ["red", "blue", "green", "gold", "black", "magenta"]]')
x %<>% decorate('z: [fill: ["red", "blue", "green", "gold", "black", "magenta"]]')
x %<>% decorate('z: [shape: [20, 21, 22, 23, 24, 25]]')
x %<>% decorate('z: [linetype: [6, 5, 4, 3, 2, 1]]')
x %<>% decorate('z: [alpha: [ .9, .8, .7, .6, .5, .4]]')
x %<>% decorate('z: [size: [1, 1.5, 2, 2.5, 3, 3.5]]')
x %>% ggplot(aes(
 x, y,
  color = z,
  fill = z,
  shape = z,
  linetype = z, 
  alpha = z,
  size = z,
)) + 
  geom_point() +
  geom_line(size = 1)

Add Isometry to Plot Object

Description

Adds isometry to plot object.

Usage

## S3 method for class 'ggplot_isometric'
ggplot_add(object, plot, object_name, ...)

Value

Examples

example(isometric)

Add Symmetry to Plot Object

Description

Adds y axis symmetry to plot object.

Usage

## S3 method for class 'ggplot_symmetric'
ggplot_add(object, plot, object_name, ...)

Value

Examples

example(symmetric)

Enable Automatic Labels and Units for ggplot

Description

Enable automatic labels and units for ggplot. Substitutes column label, if present, for default. Supports arrangements of ggplot objects. Defined similarly to print.decorated_ggplot and respects global options yamlet_decorated_ggplot_search, yamlet_decorated_ggplot_discrete, and yamlet_decorated_ggplot_drop.

Usage

## S3 method for class 'decorated_ggplot'
ggplot_build(plot, ...)

Arguments

plot

class 'decorated_ggplot' from ggplot.decorated

Value

see ggplot_build

Prepare Data for GGplot

Description

Prepares data for ggplot. Generic, with methods for data.frame, and decorated.

Usage

ggready(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)
decorations(x, Weight)
decorations(as.data.frame(x), Weight) # downgrade still has attributes
class(x)
class(ggready(as.data.frame(x)))
class(ggready(x))
class(ggready(resolve(x)))
x <- ggready(x)
library(magrittr)
library(ggplot2)

# Here we filter on-the-fly
# without loss of attributes.
# Notice mg/L rendering; this is actually part of an expression.
file %>%
 decorate %>%
 filter(!is.na(conc)) %>%
 ggready %>%
 ggplot(aes(x = time, y = conc, color = Heart)) +
 geom_point()

# By default ggready resolves everything that is decorated.
# But we can intervene to resolve selectively,
# And further intervene to 'ggready' selectively.
#
x <- file %>% decorate %>% filter(!is.na(conc))
x %>%
resolve(conc, time) %>%   # Heart left unresolved!
ggready(conc, Heart, resolve = FALSE) %>%  # time left unreadied!
ggplot(aes(x = time, y = conc, color = Heart)) + geom_point()

# Still, all the labels were actually expressions:
x %>%
resolve(conc, time) %>%
ggready(conc, Heart, resolve = FALSE) %>%
decorations(conc, time, Heart)

Prepare Data Frame for GGplot

Description

Prepares data.frame for ggplot. Appends units to label using append_units (passing style = 'plotmath' if parse is true, else style = 'plain'). Enforces classes 'decorated' and 'ggready'.

Usage

## S3 method for class 'data.frame'
ggready(x, ..., parse = getOption("yamlet_ggready_parse", TRUE))

Arguments

x

object

...

passed to append_units; may include unquoted column names

parse

passed to append_units

Value

ggready decorated

Examples

example(ggready)

Prepare Decorated Data Frame for GGplot

Description

Prepares decorated data.frame for ggplot. Calls resolve and appends units to label using append_units (passing style = 'plotmath' if parse is true, else style = 'plain'). Enforces classes 'decorated' and 'ggready'.

Usage

## S3 method for class 'decorated'
ggready(
  x,
  ...,
  parse = getOption("yamlet_ggready_parse", TRUE),
  resolve = TRUE
)

Arguments

x

object

...

passed to append_units and resolve; may include unquoted column names

parse

passed to append_units

resolve

whether to resolve guide attributes

Value

ggready decorated

Examples

example(ggready)

Group_by Decorated

Description

Preserves class when grouping decorated.

Usage

## S3 method for class 'decorated'
group_by(.data, ..., add = FALSE, .drop = group_by_drop_default(.data))

Arguments

.data

A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

...

In group_by(), variables or computations to group by. Computations are always done on the ungrouped data frame. To perform computations on the grouped data, you need to use a separate mutate() step before the group_by(). Computations are not allowed in nest_by(). In ungroup(), variables to remove from the grouping.

add

When FALSE, the default, group_by() will override existing groups. To add to the existing groups, use .add = TRUE.

This argument was previously called add, but that prevented creating a new grouping variable called add, and conflicts with our naming conventions.

.drop

Drop groups formed by factor levels that don't appear in the data? The default is TRUE except when .data has been previously grouped with .drop = FALSE. See group_by_drop_default() for details.

Group by Decorations

Description

Groups according to decorations. Generic, with method group_by_decorations.data.frame

Usage

group_by_decorations(x, ...)

Arguments

x

object of dispatch

...

passed

Groups by Decorations for Data Frame

Description

Invokes group_by using whatever groups are recovered by decorations_groups.

Usage

## S3 method for class 'data.frame'
group_by_decorations(x, ...)

Arguments

x

grouped_df

...

ignored

Value

list of symbols

Examples

library(magrittr)
library(dplyr)
Theoph %>% group_vars # nothing!
Theoph %<>% decorate_groups(Subject, Time) 
Theoph %<>% group_by_decorations
Theoph %>% group_vars # something
rm(Theoph)

Coerce Guide to Something More Implicit

Description

Coerces 'guide' to something more implicit. Generic, with methods for data.frame. The key 'guide' generally suggests a guide to interpretation of a data item, such as units, formats, codelists, and encodings. The idea here is to replace these with 'guide': i.e., to undo the effects of explicit_guide.

Usage

implicit_guide(x, ...)

Arguments

x

object of dispatch

...

passed arguments

Value

see methods

Coerce Data Frame Guide to Something More Implicit

Description

Coerces data.frame guide-like attributes to 'guide'. The attribute 'guide' generally suggests a guide to interpretation of a data item, such as units, formats, codelists, and encodings. The idea here is to replace these with 'guide': i.e., to undo the effects of explicit_guide.data.frame. If guide attribute is still present, the explicit attribute is removed. Otherwise the explicit element is renamed.

Usage

## S3 method for class 'data.frame'
implicit_guide(x, ..., collapse = getOption("yamlet_collapse_codelist", Inf))

Arguments

x

data.frame

...

named arguments ignored; un-named arguments limit scope

collapse

numeric: substitute empty codelist if number of levels exceeds this. Set to Inf (default) to ensure levels are always stored explicitly; if zero, empty codelist will always be substituted if codelist elements are un-named and exactly match sort(unique(x)).

Value

data.frame

Examples

library(magrittr)
x <- data.frame(
 ID = 1,
 CONC = 1,
 RACE = 1,
 SEX = 1,
 DATE = 1
)
x %<>% modify(ID, label = 'subject identifier')
x %<>% modify(CONC, label = 'concentration', guide = 'ng/mL')
x %<>% modify(RACE, label = 'race', guide = list(white = 0, black = 1, asian = 2))
x %<>% modify(SEX, label = 'sex', guide = list(female = 0, male = 1))
x %<>% modify(DATE, label  = 'date', guide = '%Y-%m-%d')
x %>% decorations
x %>% explicit_guide %>% decorations
x %>% explicit_guide %>% implicit_guide %>% decorations
x %>% explicit_guide %>% implicit_guide(DATE) %>% decorations # limit scope
x %>% explicit_guide(simplify = FALSE) %>% decorations
x %>% explicit_guide(simplify = FALSE) %>% implicit_guide %>% decorations

Coerce Decorated Vector Guide to Something More Implicit

Description

Coerces dvec guide-like attributes to 'guide'. The attribute 'guide' generally suggests a guide to interpretation of a data item, such as units, formats, codelists, and encodings. The idea here is to replace these with 'guide': i.e., to undo the effects of explicit_guide.dvec. If guide attribute is still present, the explicit attribute is removed. Otherwise the explicit element is renamed.

Usage

## S3 method for class 'dvec'
implicit_guide(x, ...)

Arguments

x

dvec

...

ignored

Value

dvec

Examples

library(magrittr)
x <- data.frame(
 ID = as_dvec(1),
 CONC = as_dvec(1),
 RACE = as_dvec(1),
 SEX = as_dvec(1),
 DATE = as_dvec(1)
)
x %<>% modify(ID, label = 'subject identifier')
x %<>% modify(CONC, label = 'concentration', guide = 'ng/mL')
x %<>% modify(RACE, label = 'race', guide = list(white = 0, black = 1, asian = 2))
x %<>% modify(SEX, label = 'sex', guide = list(female = 0, male = 1))
x %<>% modify(DATE, label  = 'date', guide = '%Y-%m-%d')
x %>% decorations
x %>% explicit_guide %>% decorations
x %>% explicit_guide %>% implicit_guide %>% decorations
x %>% explicit_guide %>% implicit_guide(DATE) %>% decorations # limit scope
x %>% explicit_guide(simplify = FALSE) %>% decorations
x %>% explicit_guide(simplify = FALSE) %>% implicit_guide %>% decorations
x %<>% explicit_guide
a <- x$DATE
str(a)
str(a %>% implicit_guide)

Infer Type of Guide

Description

Infers type of guide. Default mapping function for explicit_guide.yamlet where it replaces the key 'guide' with the return value.

Usage

infer_guide(x, data = NULL, default = "guide", token = "data", ...)

Arguments

x

character or list

data

atomic

default

value for unrecognized guides

token

character: discriptive term for 'data' used in warning

...

ignored

Details

* If x is a list, the result is 'codelist'.

* If x otherwise has length greater than 1, result is the default value.

* If x is_parseable, result is 'units'. Use install_unit to register a non-default unit.

* If x contains two or more percent signs, result is 'format' (i.e. a 'format' string for a date or time class).

* If x is (encoded), result is 'encoding'.

* A length-one value of x not otherwise recognized is assumed to be an attempt to provide a length-one 'codelist'.

If data is supplied (not NULL), a warning is issued for a codelist with elements not present.

Value

length-one character

Examples

infer_guide('a') # recognized unit
infer_guide('z') # unrecognized as unit, evaluates to guide
## Not run: 
# evaluates to codelist but data suggests otherwise (warning)
infer_guide(as.list(letters), data = LETTERS)

## End(Not run)
infer_guide(c(1,2,3))                   # guide
infer_guide(list('a','b','c'))          # codelist
infer_guide(list(a = 1, b = 2, c = 3))  # codelist
infer_guide(list(a = 1))                # codelist
infer_guide('kg/m^2')                   # units
infer_guide('%')                        # units
infer_guide('%Y-%m-%d')                 # format
infer_guide('//a/1//b/2//c/3//')        # encoding

Inner_join Decorated

Description

Preserves class when joining decorated.

Usage

## S3 method for class 'decorated'
inner_join(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

Arguments

x, y

A pair of data frames, data frame extensions (e.g. a tibble), or lazy data frames (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

by

A join specification created with join_by(), or a character vector of variables to join by.

To join on different variables between x and y, use a join_by() specification. For example, join_by(a == b) will match x$a to y$b.

join_by() can also be used to perform inequality, rolling, and overlap joins. See the documentation at ?join_by for details on these types of joins.

To perform a cross-join, generating all combinations of x and y, see cross_join().

copy

suffix

If there are non-joined duplicate variables in x and y, these suffixes will be added to the output to disambiguate them. Should be a character vector of length 2.

...

Other parameters passed onto methods.

Import and Export Documented Tables as CSV

Description

Imports or exports documented tables as comma-separated variable. Generic, with methods that extend as.csv.

Usage

io_csv(x, ...)

Arguments

x

object

...

passed arguments

Value

See methods.

Examples

# generate some decorated data
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)

# get a temporary filepath
out <- file.path(tempdir(), 'out.csv')

# save file using io_csv (returns filepath)
foo <- io_csv(x, out)
stopifnot(identical(out, foo))

# read using this filepath
y <- io_csv(foo)

# lossless round-trip (ignoring source attribute)
attr(x, 'source') <- NULL
attr(y, 'source') <- NULL
stopifnot(identical(x, y))

Import Documented Table as CSV

Description

Imports a documented table as comma-separated variable. A wrapper for as.csv.character that also reads associated yamlet metadata, if present, and applies it as attributes.

Usage

## S3 method for class 'character'
io_csv(
  x,
  ext = getOption("yamlet_extension", ".yaml"),
  meta = NULL,
  gz = NULL,
  ...
)

Arguments

x

character file path; passed to as.csv.character (by method dispatch)

ext

extension for metadata equivalent of x

meta

explicit file path for metadata; if null, ext is appended to x after removing (final) extension, if any

gz

logical; guessed by default from x; if TRUE, '.gz' extension enforced present for x and absent for default meta

...

passed to as.csv.character and to decorate

Value

data.frame

Examples

example(io_csv)

Export Documented Table as CSV

Description

Exports a data.frame as comma-separated variable, as well as a yamlet version of its decorations. A wrapper for as.csv.data.frame.

Usage

## S3 method for class 'data.frame'
io_csv(
  x,
  file = "",
  ext = getOption("yamlet_extension", ".yaml"),
  meta = stdout(),
  gz = NULL,
  useBytes = FALSE,
  default_keys = getOption("yamlet_default_keys", list("label", "guide")),
  ...
)

Arguments

x

data.frame

file

passed to as.csv.data.frame (by method dispatch)

ext

= extension for metadata equivalent of x

meta

passed as con to io_yamlet

gz

logical; guessed by default from x; if TRUE, '.gz' extension enforced present for (character) file and absent for default meta

useBytes

passed to io_yamlet

default_keys

passed to io_yamlet

...

passed to as.csv and to io_yamlet

Details

You should be able to supply exactly the connections you want for file (the data file) and meta (the metadata file) if gz is FALSE. If gz is NULL, it will be guessed from file (TRUE for character ending with '.gz' or '.GZ'). If TRUE, character file will have '.gz' extension enforced, but any '.gz' ('.GZ') will be stripped when calculating meta.

Value

invisible(file)

Examples

example(io_csv)

Import and Export Resolved Tables

Description

Inter-converts between tables as comma-separated variable and fully resolved data frames. Generic, with character and data.frame methods that extend io_csv.

Usage

io_res(x, ...)

Arguments

x

object

...

passed arguments

Value

See methods.

Examples

example(io_res.character)

Import Documented Table as Resolved

Description

Imports a documented table and resolves ambiguous guide elements. A wrapper for io_csv.character that also reads associated yamlet metadata, if present, and applies it as attributes. Invokes resolve to resolve ambiguity of 'guide' attribute, if possible. A short-cut for resolve(io_csv(x)).

Usage

## S3 method for class 'character'
io_res(x, ext = getOption("yamlet_extension", ".yaml"), ...)

Arguments

x

character file path; passed to io_csv.character

ext

extension for metadata equivalent of x

...

passed to io_csv.character

Value

decorated

Examples

library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- io_csv(file) %>% resolve
y <- io_res(file)
identical(x, y)

Export Resolved Table

Description

Exports a documented table. "Desolves" attributes to standard form, then writes data and metadata to storage. A short-cut for (io_csv(desolve(x)).

Usage

## S3 method for class 'decorated'
io_res(x, file = "", ...)

Arguments

x

decorated; passed to io_csv.data.frame

file

passed to io_csv.data.frame

...

passed to io_csv.character and desolve.decorated

Value

decorated (invisible)

Examples

library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- io_res(file)
tmp <- tempfile(fileext = '.csv')
io_res(x, tmp)
a <- io_csv(tmp, source = FALSE)
b <- io_csv(file, source = FALSE)
stopifnot(identical(a, b))

Import and Export Documented Tables

Description

Imports or exports documented tables. Generic, with methods that extend read.table and write.table.

Usage

io_table(x, ...)

Arguments

x

object

...

passed arguments

Value

See methods.

Examples

# generate some decorated data
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)

# get a temporary filepath
out <- file.path(tempdir(), 'out.tab')

# save file using io_table (returns filepath)
foo <- io_table(x, out)
stopifnot(identical(out, foo))

# read using this filepath
y <- io_table(foo, as.is = TRUE)

# lossless round-trip
attr(x, 'source') <- NULL
rownames(x) <- NULL
rownames(y) <- NULL
stopifnot(identical(x, y))

Import Documented Table

Description

Imports a documented table. A wrapper for read.table() that also reads associated yamlet metadata, if present, and applies it as attributes.

Usage

## S3 method for class 'character'
io_table(x, ext = getOption("yamlet_extension", ".yaml"), meta = NULL, ...)

Arguments

x

character file path; passed to read.table

ext

extension for metadata equivalent of x

meta

explicit file path for metadata

...

passed to read.table (if accepted) and to decorate

Value

data.frame

Examples

example(io_table)

Export Documented Table

Description

Exports a data.frame and a yamlet version of its decorations. A wrapper for write.table.

Usage

## S3 method for class 'data.frame'
io_table(
  x,
  file = "",
  ext = getOption("yamlet_extension", ".yaml"),
  meta = stdout(),
  useBytes = FALSE,
  default_keys = getOption("yamlet_default_keys", list("label", "guide")),
  ...
)

Arguments

x

data.frame

file

passed to write.table

ext

= extension for metadata equivalent of x

meta

passed as con to io_yamlet

useBytes

passed to io_yamlet

default_keys

passed to io_yamlet

...

passed to write.table (if accepted) and to io_yamlet

Value

invisible(file)

Examples

example(io_table)

Import and Export Yamlet

Description

Imports and exports yamlet. Generic, with a read method io_yamlet.character for character and a write method io_yamlet.data.frame for data.frame. See also io_yamlet.yamlet.

Usage

io_yamlet(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

file <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
x <- io_yamlet(file)
tmp <- tempdir()
out <- file.path(tmp, 'tmp.yaml')

# we can losslessly 'round-trip' x using to generic calls
identical(x, io_yamlet(io_yamlet(x, out)))

Import Yamlet

Description

Imports yamlet. Character method for io_yamlet. Similar to read_yamlet, but only reads files.

Usage

## S3 method for class 'character'
io_yamlet(
  x,
  default_keys = getOption("yamlet_default_keys", list("label", "guide")),
  ...
)

Arguments

x

file path for yamlet

default_keys

character: default keys for the first n anonymous members of each element

...

passed to as_yamlet

Value

yamlet: a named list with default keys applied

Examples

example(io_yamlet)

Export Data Frame Attributes as Yamlet

Description

Writes data.frame attributes as yamlet. The data.frame method for io_yamlet. Similar to write_yamlet, but returns (description of) con.

Usage

## S3 method for class 'data.frame'
io_yamlet(
  x,
  con = stdout(),
  eol = "\n",
  useBytes = FALSE,
  default_keys = getOption("yamlet_default_keys", list("label", "guide")),
  fileEncoding = getOption("encoding"),
  ...
)

Arguments

x

data.frame

con

passed to writeLines

eol

end-of-line; passed to writeLines as sep

useBytes

passed to writeLines

default_keys

character: default keys for the first n anonymous members of each element

fileEncoding

if con is character, passed to file as encoding

...

passed to as_yamlet

Value

invisible description of con: i.e., a file path

Examples

library(csv)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)
out <- file.path(tempdir(), 'out.yamlet')
io_yamlet(x, out)
io_yamlet(out)

Export Yamlet

Description

Exports yamlet. The archetype method for io_yamlet. Similar to write_yamlet but returns (description of) con.

Usage

## S3 method for class 'yamlet'
io_yamlet(
  x,
  con = stdout(),
  eol = "\n",
  useBytes = FALSE,
  default_keys = getOption("yamlet_default_keys", list("label", "guide")),
  fileEncoding = getOption("encoding"),
  ...
)

Arguments

x

yamlet

con

passed to writeLines

eol

end-of-line; passed to writeLines as sep

useBytes

passed to writeLines

default_keys

character: default keys for the first n anonymous members of each element

fileEncoding

if con is character, passed to file as encoding

...

passed to as.character.yamlet

Value

invisible description of con: i.e., a file path

Examples

library(csv)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)
out <- file.path(tempdir(), 'out.yamlet')
io_yamlet(as_yamlet(x), out)
io_yamlet(out)

Test Object is Conditional

Description

Tests whether object is conditional.

Usage

isConditional(x, ...)

Arguments

x

character

...

passed arguments

Value

logical

Test Object is Conditional by Default

Description

Tests whether object is conditional by default. Coerces to list.

Usage

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

Arguments

x

default

...

passed arguments

Value

logical

Test List is Conditional

Description

Tests whether a list is conditional. Evaluates names of x on data and looks for meaningful result. Returns TRUE if list has names and all evaluate to logicals with length equal to number of rows in data.

Usage

## S3 method for class 'list'
isConditional(x, data, ...)

Arguments

x

list

data

environment for variable lookup

...

passed arguments

Value

length-one logical

Test Value is Levels

Description

Tests whether value is levels.

Usage

isLevels(x, ...)

Arguments

x

character

...

passed arguments

Value

logical

Test Character Value is Levels

Description

Tests whether character value is levels. Looks for any matches to vector. Uses intersect, which is fairly flexible respecting underlying data types (character 0 can match integer 0, etc.).

Usage

## S3 method for class 'character'
isLevels(x, table, ...)

Arguments

x

default

table

lookup vector

...

passed arguments

Value

logical

Test Value is Levels by Default

Description

Tests whether value is levels by default. Coerces to character.

Usage

## Default S3 method:
isLevels(x, table, ...)

Arguments

x

default

...

passed arguments

Value

logical

Test if Class is dvec

Description

Tests whether x inherits 'dvec'.

Usage

is_dvec(x)

Arguments

x

object

Value

logical

Examples

is_dvec(1L)
is_dvec(as_dvec(1L))

Check Parseable as Units

Description

Checks if something is parseable as units. Generic, with default method.

Usage

is_parseable(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(is_parseable.character)

Check Something is Parseable as Units by Default

Description

Checks if something is parseable as units. Tests against the udunits library in units. See as_units. See also install_unit for finer control.

Usage

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

Arguments

x

character

...

passed arguments

Value

logical

Examples

is_parseable(c('kg/m2','kg/m^2','kg.m/s2','µg/L'))
is_parseable('foo')
library(units)
install_unit('foo')
is_parseable('foo')

Enforce Isometry

Description

Enforces isometric plot design: aspect ratio of 1, identical ranges for x and y axes. Can be used meaningfully with + facet_wrap(scales = 'free' ...).

Usage

isometric()

Value

ggplot_isometric

Examples

library(magrittr)
library(ggplot2)
data.frame(x = 1:5, y = 3:7) %>%
ggplot(aes(x, y)) + geom_point() + isometric()

Left_join Decorated

Description

Preserves class when joining decorated.

Usage

## S3 method for class 'decorated'
left_join(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

Arguments

x, y

A pair of data frames, data frame extensions (e.g. a tibble), or lazy data frames (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

by

A join specification created with join_by(), or a character vector of variables to join by.

To join on different variables between x and y, use a join_by() specification. For example, join_by(a == b) will match x$a to y$b.

join_by() can also be used to perform inequality, rolling, and overlap joins. See the documentation at ?join_by for details on these types of joins.

To perform a cross-join, generating all combinations of x and y, see cross_join().

copy

suffix

If there are non-joined duplicate variables in x and y, these suffixes will be added to the output to disambiguate them. Should be a character vector of length 2.

...

Other parameters passed onto methods.

Get Length of a Decorated Vector

Description

Gets the length of a decorated vector. Simply calls next method.

Usage

## S3 method for class 'dvec'
length(x)

Arguments

x

decorated vector

Value

integer

Examples

length(as_dvec(1:3))

Coerce List to Encoding

Description

Tries to coerce a list to an encoding. Names are understood as decodes, and list values as codes. On failure, the list is returned unchanged.

Usage

list2encoding(x, ...)

Arguments

x

list

...

ignored

Value

an encoding (length-one character), or original list if error occurs

Examples

meta <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
meta <- as_yamlet(meta)
list2encoding(meta$Creatinine$guide)

Make Title

Description

Make title attribute. Generic, with methods make_title.default, make_title.decorated, and make_title.dvec.

Usage

make_title(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

# see methods

Make Title for Decorated

Description

Make title for class 'decorated'. Limits scope to requested variables, and then calls class-specific methods for each.

Usage

## S3 method for class 'decorated'
make_title(x, ...)

Arguments

x

object

...

optional names of variables to limit scope

Value

decorated

Examples

library(magrittr)
x <- data.frame(length = 1:10)
x %>% 
  decorate('length: [ Length, mm ]') %>%
  resolve %>%
  decorations

Make Title by Default

Description

Make title by default. To be specific: this is the default method for the generic function make_title, and it actually does nothing. Individual methods are written for those classes where 'make title' behavior is expected.

Usage

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

Arguments

x

object

...

ignored

Value

same as x

Make Title for Decorated Vector

Description

Makes title for decorated vectors. If option with_title is TRUE and x has a 'units' attribute, it adds the title attribute. See also drop_title for coordinated use.

Usage

## S3 method for class 'dvec'
make_title(x, ..., with_title = getOption("yamlet_with_title", TRUE))

Arguments

x

dvec

...

ignored arguments

with_title

whether to drop title

Value

dvec

Examples

library(magrittr)
1 %>% 
as_dvec(label = 'length', guide = 'mm') %>%
resolve

Merge Decorated

Description

Preserves class for 'decorated' during merge().

Usage

## S3 method for class 'decorated'
merge(x, y, ...)

Arguments

x

decorated

y

passed to merge

...

passed to merge

Value

class 'decorated' 'data.frame'

Examples

library(magrittr)
library(dplyr)
x <- data.frame(foo = 1, bar = 2)
x %<>% decorate('foo: [distance, mm]')
x %<>% decorate('bar: [height, mm]')
class(merge(x,x))

Try To Look Like Something Else

Description

Tries to make an object look like something else. Generic, with method mimic.default

Usage

mimic(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(mimic.default)

Try To Make Classified Look Like Another Equal-length Variable

Description

Tries to mimic another vector or factor for 'classified'. See classified.default. If meaningful and possible, x updates its codelist attribute with labels from corresponding values in y. Codes that don't occur (i.e. unused levels) are removed from the codelist.

Usage

## S3 method for class 'classified'
mimic(x, y = x, ...)

Arguments

x

classified

y

vector-like, same length as x

...

ignored arguments

Value

classified

Examples

let <- letters[1:5]
LET <- LETTERS[1:5]
int <- 0L:4L
num <- as.numeric(int)
fac <- factor(let)
css <- classified(let)

mimic(LET)
mimic(LET, let)
mimic(let, let)
mimic(num, let)
mimic(int, let)
mimic(fac, let)
mimic(css, let)
mimic(character(0))
mimic(numeric(0))
mimic(let, num)
mimic(fac, num)
mimic(css, num)
mimic(num, css)
mimic(let, css)

util <- c('knife','fork','spoon')
util
factor(util)
classified(util)
mimic(util)
mimic(factor(util))
mimic(classified(util))

x <- data.frame(let, LET)
library(dplyr)
library(magrittr)
x %<>% mutate(let = mimic(let, LET), LET = mimic(LET))
str(x)

Try To Look Like Another Equal-length Variable

Description

Tries to mimic another vector or factor. If meaningful and possible, x acquires a guide attribute with labels from corresponding values in y. Any codelist attribute is removed. No guide is created for zero-length x. If x is a factor, unused levels are removed.

Usage

## Default S3 method:
mimic(x, y = x, ...)

Arguments

x

vector-like

y

vector-like, same length as x

...

passed to link{factor}

Value

same class as x

Examples

library(magrittr)
library(dplyr)
let <- letters[1:5]
LET <- LETTERS[1:5]
int <- 0L:4L
num <- as.numeric(int)
fac <- factor(let)
css <- classified(let)

# any of these can mimic any other
str(mimic(LET, let))
str(mimic(num, let))
str(mimic(let, num))

# factors get a guide and classifieds get a named codelist
str(mimic(fac, int))
str(mimic(css, int))

# int can 'pick up' the factor levels as guide names
str(mimic(int, css))

# if two variables mean essentially the same thing,
# mimic lets you save space
x <- data.frame(id = 1:2, ID = c('A','B'))
x
x %<>% mutate(id = mimic(id, ID)) %>% select(-ID)
x
# ID still available, in principle:
x %>% as_decorated %>% resolve

Modify Attributes of Indicated Components

Description

Modifies the attributes of indicated components. Generic, with method modify.default.

Usage

modify(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(modify.default)

Modify Attributes of Indicated Components by Default

Description

Modifies the attributes of each indicated element (all elements by default). Tries to assign the value of an expression to the supplied label, with existing attributes and the object itself (.) available as arguments. Gives a warning if the supplied label is considered reserved. Intends to support anything with one or more non-empty names.

Usage

## Default S3 method:
modify(
  x,
  ...,
  .reserved = getOption("yamlet_modify_reserved", c("class", "levels", "labels",
    "names"))
)

Arguments

x

object

...

indicated columns, or name-value pairs

.reserved

reserved labels that warn on assignment

Details

The name of the component itself is available during assignments as attribute 'name' (any pre-existing attribute 'name' is temporarily masked). After all assignments are complete, the value of 'name' is enforced at the object level. Thus, modify expressions can modify component names.

As currently implemented, the expression is evaluated by eval_tidy, with attributes supplied as the data argument. Thus, names in the expression may be disambiguated, e.g. with .data. See examples.

Value

same class as x

Examples

library(magrittr)
library(dplyr)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)

# modify selected columns
x %<>% modify(title = paste(label, '(', guide, ')'), time)
x %>% select(time, conc) %>% decorations

# modify (almost) all columns
x %<>% modify(title = paste(label, '(', guide, ')'), -Subject)
x %>% select(time, conc) %>% decorations

# use column itself
x %<>% modify(`defined values` = sum(!is.na(.)))
x %>% select(time) %>% decorations

# rename column
x %<>% modify(time, name = label)
names(x)

# warn if assignment fails
## Not run: 
\donttest{
x %<>% modify(title = foo, time)
}
## End(Not run)

# support lists
list(a = 1, b = 1:10, c = letters) %>%
modify(length = length(.), b:c)

x %<>% select(Subject) %>% modify(label = NULL, `defined values` = NULL)

# distinguish data and environment
location <- 'environment'
x %>% modify(where = location) %>% decorations
x %>% modify(where = .env$location) %>% decorations
## Not run: 
\donttest{
x%>% modify(where = .data$location) %>% decorations
}
## End(Not run)
x %>% modify(location = 'attributes', where = location) %>% decorations
x %>% modify(location = 'attributes', where = .data$location) %>% decorations

Mutate Decorated

Description

Preserves class when mutating decorated.

Usage

## S3 method for class 'decorated'
mutate(.data, ...)

Arguments

.data

A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

...

<data-masking> Name-value pairs. The name gives the name of the column in the output.

The value can be:

A vector of length 1, which will be recycled to the correct length.
A vector the same length as the current group (or the whole data frame if ungrouped).
NULL, to remove the column.
A data frame or tibble, to create multiple columns in the output.

Evaluate Named Arguments

Description

Evaluates named arguments in ....

Usage

named(...)

Arguments

...

possibly a mix of named and un-named arguments.

Value

named list

Examples

named(a = 1, b = 2 + 3, 4, 'd')

Assign Names of Decorated

Description

Assigns names of decorated, retaining attributes.

Usage

## S3 replacement method for class 'decorated'
names(x) <- value

Arguments

x

decorated

value

passed to next method

Value

decorated

Examples

a <- as_decorated(as.list(setNames(letters[1:3], LETTERS[1:3])))
a[[2]]
names(a[[2]]) <- 'c'
class(a)

Reduce Something to its Simplest Sufficient Version

Description

Reduces something to its simplest sufficient version. Generic, with method parsimonious.list.

Usage

parsimonious(x, ...)

Arguments

x

object of dispatch

...

ignored

Examples

example(parsimonious.list)

Reduce by Default to Simplest Sufficient Version

Description

Reduces by default to simplest sufficient version. This is a companion to parsimonious.list and currently returns an unmodified object.

Usage

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

Arguments

x

object for which no specific parsimonious method exists

...

ignored

Reduce A List to its Simplest Sufficient Version

Description

Reduces a list to its simplest sufficient version. Used internally with yaml.load as a custom handler for objects of type 'seq'. Consider: str(yaml.load('[a: 1, b: 2]')). The result is technically correct. By default, the parser returns a sequence of two maps. Not reducible to a base type, The sequence is an anonymous list. The maps themselves are named lists. In the special case that all elements are of length one, this structure can be collapsed without semantic loss to a named list. More generally, if an anonymous list consists entirely of length one members, those members which are lists (but not already parsimonious lists) can be replaced with their first elements; the list becomes named if any of those elements has a name. In that case, any elements without names get the name ” (empty string).

Usage

## S3 method for class 'list'
parsimonious(x, ...)

Arguments

x

object of dispatch

...

passed arguments

Value

list

Examples

library(magrittr)
library(yaml)
# Parsimonious:
'[a: 1, b: 2]' %>% yaml.load
'[a: 1, b: 2]' %>% yaml.load(handlers = list(seq = parsimonious))

# No effect on vector types:
'[1, 2]' %>% yaml.load
'[1, 2]' %>% yaml.load(handlers = list(seq = parsimonious))

# Respects mixed-length vector types:
'RACE: [ race, [white, black, asian ]]' %>% yaml.load
'RACE: [ race, [white, black, asian ]]' %>% yaml.load(handlers = list(seq = parsimonious))

# Anonymous elements get a blank name:
'[a: 1, 2]' %>% yaml.load %>% sapply(names)
'[a: 1, 2]' %>% yaml.load(handlers = list(seq = parsimonious)) %>% names

# Also works for sequence of length one:
'[a: 1]' %>% yaml.load
'[a: 1]' %>% yaml.load(handlers = list(seq = parsimonious))

# Works for NULL:
yaml.load('-')
yaml.load('-', handlers = list(seq = parsimonious))

# And for empty list:
yaml.load('[]')
yaml.load('[]', handlers = list(seq = parsimonious))

# Limited to first (most deeply nested) encounter:
'[[[a: 1]]]' %>% yaml.load
'[[[a: 1]]]' %>% yaml.load(handlers = list(seq = parsimonious))

# Works for mixed-depth nesting:
'ITEM: [ label: item, [ foo: bar, hey: baz ]]' %>% yaml.load
'ITEM: [ label: item, [ foo: bar, hey: baz ]]' %>% yaml.load(handlers = list(seq = parsimonious))

Substitute Expressions, Titles, Labels and Aesthetics in ggplots

Description

Default labels (e.g. mappings for x, y, etc.) will be used to search data for more meaningful labels, taking first available from attributes with names in search. Likewise, if mappings for colour (color), fill, size, etc. (see defaults for discrete) indicate columns that have these defined as attributes, an attempt is made to add a corresponding discrete scale if one does not exist already. Values are recycled if necessary and are specific by ordinal position to the corresponding level of the corresponding variable. Levels are defined in increasing priority by sort(unique(x)), any guide attribute, any factor levels, any codelist attribute, or any plotmath attribute.

Usage

## S3 method for class 'decorated_ggplot'
print(
  x,
  ...,
  search = getOption("yamlet_decorated_ggplot_search", c("expression", "title", "label")),
  discrete = getOption("yamlet_decorated_ggplot_discrete", c("colour", "fill", "size",
    "shape", "linetype", "linewidth", "alpha")),
  drop = getOption("yamlet_decorated_ggplot_drop", TRUE)
)

Arguments

x

class 'decorated_ggplot' from ggplot.decorated

...

ignored

search

attribute names from which to seek label substitutes

discrete

discrete aesthetics to map from data decorations where available

drop

should unused factor levels be omitted from data-driven discrete scales?

Value

see print.ggplot

Examples

example(ggplot.decorated)

Print Decorated Xtable

Description

Prints a decorated xtable. Supplies a footnote. Experimental.

Usage

## S3 method for class 'decorated_xtable'
print(x, ...)

Arguments

x

decorated

...

passed to other methods

Value

character

Examples

library(magrittr)
library(xtable)
set.seed(0)
x <- data.frame(
 auc = rnorm(4, mean = 2400, sd = 200),
 bmi = rnorm(4, mean = 20, sd = 5),
 gen = 0:1
)
x %<>% decorate('auc: [AUC_0-24, ng*h/mL]')
x %<>% decorate('bmi: [Body Mass Index, kg/m^2]')
x %<>% decorate('gen: [Gender, [Male: 1, Female: 0]]')
x %>% resolve
x %>% resolve %>% xtable

Print Decorated Vector

Description

Prints a decorated vector.

Usage

## S3 method for class 'dvec'
print(x, ...)

Arguments

x

dvec

...

passed arguments

Value

character

Print a Yamlet

Description

Prints a yamlet object for interactive inspection. By default, lists with no names (recursively) that unlist to identical length are displayed in one line for compactness. If this seems misleading, you can turn it of with options(yamlet_print_simplify = FALSE).

Usage

## S3 method for class 'yamlet'
print(x, ..., simplify = getOption("yamlet_print_simplify", TRUE))

Arguments

x

yamlet

...

ignored

simplify

whether to collapse the display of very simple lists into one line of output

Value

invisible(x)

Examples

as_yamlet('mpg: [efficiency, mi/gallon]\nvs: [Engine, [V-shaped: 0, straight: 1]]')

Promote Something

Description

Promotes something. Generic, with default method.

Usage

promote(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(promote.data.frame)

Promote Data Frame

Description

Promotes a data.frame by calling promote.list.

Usage

## S3 method for class 'data.frame'
promote(x, ...)

Arguments

x

data.frame

...

passed arguments

Value

same class as x

Examples

example(promote.list)

Promote by Default

Description

Promotes by default. Currently a non-operation.

Usage

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

Arguments

x

object

...

other arguments

Promote a List

Description

Promotes attributes of list-like objects. For the plural attributes of each element, any singularity is promoted to the sole attribute. Reserved attributes are untouched. Methods filter.decorated and [.decorated automatically attempt to promote attributes for all elements.

Usage

## S3 method for class 'list'
promote(
  x,
  ...,
  .reserved = getOption("yamlet_promote_reserved", c("class", "levels", "labels",
    "names"))
)

Arguments

x

list, or list-like

...

indicated elements

.reserved

attributes to leave untouched

Value

same class as x

Examples

library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','phenobarb.csv')
x <- file %>% decorate

# Note that there are two elements each for value label and value guide.
x %>% decorations(event, value)

# After filtering, only one set is relevant.
# promote() identifies and retains such.
x %>% dplyr:::filter.data.frame(event == 'dose') %>% decorations(value)
x %>% dplyr:::filter.data.frame(event == 'dose') %>% promote %>% decorations(value)

# If for some reason we do a partial promote, value attributes are unaffected.
# Nonsense example:
x %>% dplyr:::filter.data.frame(event == 'dose') %>% promote(event) %>% decorations(value)

# However, the 'decorated' method for filter() calls promote() internally.
x %>% filter(event == 'dose') %>% decorations(value)

Calculate Substitute Values

Description

Calculates substitute values. Generic, with method proxy.factor

Usage

proxy(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(proxy.factor)

Calculate Substitute Values for Factor Levels

Description

Calculates substitute values for factor levels. If x and y have same length and there is a one-to-one correspondence of their elements, then unique elements of y are returned in an order corresponding to levels(x).

Usage

## S3 method for class 'factor'
proxy(x, y = as.numeric(x), ...)

Arguments

x

factor

y

factor or vector

...

ignored

Value

same class as y

Examples

proxy(factor(1:3), letters[1:3])
proxy(factor(1:3), factor(letters[1:3]))
proxy(factor(letters[4:6]))
foo <- classified(letters[1:5])
as_yamlet(attributes(foo))
foo <- classified(foo, labels = proxy(foo))
as_yamlet(attributes(foo))

Read Yamlet

Description

Reads yamlet from file. Similar to io_yamlet.character but also reads text fragments.

Usage

read_yamlet(
  x,
  ...,
  default_keys = getOption("yamlet_default_keys", list("label", "guide"))
)

Arguments

x

file path for yamlet, or vector of yamlet in storage syntax

...

passed to as_yamlet

default_keys

character: default keys for the first n anonymous members of each element

Value

yamlet: a named list with default keys applied

Examples

library(csv)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
meta <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
x <- as.csv(file)
y <- read_yamlet(meta)
x <- decorate(x, meta = y)
stopifnot(identical(x, decorate(file)))

Reconcile Atttributes

Description

Reconciles attributes. Generic, with method reconcile.list.

Usage

reconcile(x, ...)

Arguments

x

object of dispatch

...

passed arguments

Value

list (of attributes)

Reconcile Atttributes of List Members

Description

Reconciles attributes of list members. Recursively arbitrates list members pairwise, returning the accumulated attributes.

Usage

## S3 method for class 'list'
reconcile(x, ...)

Arguments

x

list

...

passed arguments

Value

list (of attributes)

Examples

library(magrittr)
library(dplyr)
a <- data.frame(study = 1) %>% decorate('study: [Study, [A: 1]]')
b <- data.frame(study = 2) %>% decorate('study: [Study, [B: 2]]')
bind_rows(a, b) %>% decorations
c(a$study, b$study)
reconcile(list(a$study, b$study))

Redecorate a List-like Object

Description

Redecorates a list-like object. Equivalent to decorate( ..., overwrite = TRUE). If meta is not supplied, an attempt will be made to redecorate with existing decorations, if any.

Usage

redecorate(x, meta = NULL, ..., overwrite = TRUE)

Arguments

x

object

meta

file path for corresponding yamlet metadata, or a yamlet object

...

passed arguments

overwrite

passed to decorate

Value

a list-like object, typically data.frame

Examples

library(dplyr)
library(magrittr)
library(csv)
library(haven)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(as.csv(file))
x %>% select(Subject) %>% decorations
x %<>% redecorate('Subject: Patient Identifier')
x %>% select(Subject) %>% decorations

# xpt may already have labels:

dm <- 'extdata/dm.xpt.gz' %>% 
  system.file(package = 'yamlet') %>% 
  gzfile %>% 
  read_xpt

dm %>% class  
dm %>% decorations(AGE, SEX, RACE)

# but technically not decorated, and poor persistence:
bind_rows(dm, dm) %>% decorations(AGE, SEX, RACE)

# self-redecorating helps:
dm %<>% redecorate
bind_rows(dm, dm) %>% decorations(AGE, SEX, RACE)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

dplyr: filter
encode: encode
ggplot2: ggplot_add
pillar: type_sum
spork: latexToken, plotmathToken
units: as_units
vctrs: vec_ptype_abbr

Rescale dvec

Description

Rescales dvec

Usage

## S3 method for class 'dvec'
rescale(x, to = c(0, 1), from = range(x, na.rm = TRUE, finite = TRUE), ...)

Arguments

x

dvec

to

numeric

from

numeric

...

passed arguments

Resolve Guide

Description

Resolves implicit usage of default key 'guide' to explicit usage. Generic, with methods resolve.decorated and resolve.dvec.

Usage

resolve(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(resolve.decorated)

Resolve Classified

Description

Resolves classified. A non-operation since classified already has an explicit guide. Useful to make resolve() idempotent for 'dvec'.

Usage

## S3 method for class 'classified'
resolve(x, ...)

Arguments

x

classified

...

ignored

Value

classified

Examples

library(magrittr)
x <- as_dvec(1:3, guide = list(a = 1, b = 2, c = 3))
x %>% str
x %>% classified %>% str
x %>% explicit_guide %>% classified %>% str
x %>% resolve %>% str
# idempotent:
x %>% resolve %>% resolve %>% str

Resolve Data Frame

Description

Resolves data.frame. Coerces first using as_decorated().

Usage

## S3 method for class 'data.frame'
resolve(x, ...)

Arguments

x

data.frame

...

ignored

Value

decorated

Examples

head(resolve(Theoph))

Resolve Guide for Decorated

Description

Resolves implicit usage of default key 'guide' to explicit usage for decorated class. Calls explicit_guide, classified, and make_title.

Usage

## S3 method for class 'decorated'
resolve(x, ...)

Arguments

x

decorated

...

passed to explicit_guide, classified, and make_title

Value

decorated

Examples

# generate some decorated data
library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)
x %>% decorations(Age, glyco)

# resolve everything, and show selected decorations
x %>% resolve %>% decorations(Age, glyco)

# resolve selectively, and show selected decorations
x %>% resolve(glyco) %>% decorations(Age, glyco)

Resolve Guide for Decorated Vector

Description

Resolves implicit usage of default key 'guide' to explicit usage for class dvec. Simply calls explicit_guide followed by classified if x has a codelist attribute. If option yamlet_with_title is not NULL, and if 'units' present, label and units will be concatenated by default to create a title attribute.

Usage

## S3 method for class 'dvec'
resolve(x, ...)

Arguments

x

dvec

...

passed to explicit_guide, classified, and make_title

Value

dvec or classified

Examples

library(magrittr)
x <- as_dvec(1:3, guide = list(a = 1, b = 2, c = 3))
x %>% str
x %>% classified %>% str
x %>% explicit_guide %>% classified %>% str
x %>% resolve %>% str

Right_join Decorated

Description

Preserves class when joining decorated.

Usage

## S3 method for class 'decorated'
right_join(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

Arguments

x, y

A pair of data frames, data frame extensions (e.g. a tibble), or lazy data frames (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

by

A join specification created with join_by(), or a character vector of variables to join by.

To join on different variables between x and y, use a join_by() specification. For example, join_by(a == b) will match x$a to y$b.

join_by() can also be used to perform inequality, rolling, and overlap joins. See the documentation at ?join_by for details on these types of joins.

To perform a cross-join, generating all combinations of x and y, see cross_join().

copy

suffix

If there are non-joined duplicate variables in x and y, these suffixes will be added to the output to disambiguate them. Should be a character vector of length 2.

...

Other parameters passed onto methods.

Determine Scale Type for dvec

Description

Determines scale type for dvec.

Usage

## S3 method for class 'dvec'
scale_type(x)

Arguments

x

dvec

Render Scripted Attributes of Indicated Components

Description

Renders the scripted attributes of indicated components. Generic: an alias for enscript.

Usage

scripted(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Select Decorated

Description

Preserves class when selecting decorated.

Usage

## S3 method for class 'decorated'
select(.data, ...)

Arguments

.data

A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

...

<tidy-select> One or more unquoted expressions separated by commas. Variable names can be used as if they were positions in the data frame, so expressions like x:y can be used to select a range of variables.

Identify Selected Names

Description

Identifies Selected Names. Generic, with default method.

Usage

selected(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(modify.data.frame)

Identify Selected Names by Default

Description

Evaluates un-named arguments in ... using select rules, returning explicit names in x. Returns all (non-empty) names by default (if no dots supplied).

Usage

## Default S3 method:
selected(x, ..., expand = TRUE)

Arguments

x

object

...

to select

expand

if true, selecting nothing expands to selecting everything

Value

character: names in x

Examples

library(magrittr)
list(a = 1, b = 1:10, c = letters) %>%
selected(b:c)

Semi_join Decorated

Description

Preserves class when joining decorated.

Usage

## S3 method for class 'decorated'
semi_join(x, y, by = NULL, copy = FALSE, ...)

Arguments

x, y

A pair of data frames, data frame extensions (e.g. a tibble), or lazy data frames (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

by

A join specification created with join_by(), or a character vector of variables to join by.

To join on different variables between x and y, use a join_by() specification. For example, join_by(a == b) will match x$a to y$b.

join_by() can also be used to perform inequality, rolling, and overlap joins. See the documentation at ?join_by for details on these types of joins.

To perform a cross-join, generating all combinations of x and y, see cross_join().

copy

...

Other parameters passed onto methods.

Choose Singular Expression

Description

For a list of expressions evaluated within data, this returns the index of the one expression that evaluates to an all-true vector (after coercing NA to FALSE). Returns 0 if no expressions succeed, and NA_integer_ if more than one succeed. Returns -1 if any expression does not evaluate to logical or if list is empty.

Usage

singularity(x, data, ...)

Arguments

x

list of expressions

data

something coercible to a data environment (typically data.frame)

...

ignored

Value

integer, possibly NA

Examples

meta <- system.file(package = 'yamlet', 'extdata','phenobarb.csv')
x <- read.csv(meta)
singularity(
  data = x,
  list(
    "event == 'conc'",
    "event == 'dose'",
    "event == 'metabolite'"
  )
)
singularity(
  data = x[x$event == 'dose',],
  list(
    "event == 'conc'",
    "event == 'dose'",
    "event == 'metabolite'"
  )
)
singularity(
  data = x[x$event == 'dose',],
  list(
    "time >= 0",
    "event == 'dose'"
  )
)

Slice Decorated

Description

Preserves class when slicing decorated.

Usage

## S3 method for class 'decorated'
slice(.data, ..., .preserve = FALSE)

Arguments

.data

A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

...

For slice(): <data-masking> Integer row values.

Provide either positive values to keep, or negative values to drop. The values provided must be either all positive or all negative. Indices beyond the number of rows in the input are silently ignored.

For ⁠slice_*()⁠, these arguments are passed on to methods.

.preserve

Relevant when the .data input is grouped. If .preserve = FALSE (the default), the grouping structure is recalculated based on the resulting data, otherwise the grouping is kept as is.

Place Units Under Label

Description

Places units attribute below label attribute. Makes the most sense for figures (style = 'plotmath') and useful for tables (style = 'latex') in combination with alias. See also append_units.

Usage

sub_units(
  x,
  ...,
  open = if (style == "plain") "\n(" else "\\n(",
  close = ")",
  style = "latex",
  math_open = "",
  math_close = "",
  label_open = "$\\begin{gathered}",
  label_close = "\\end{gathered}$",
  newline = "\\\\"
)

Arguments

x

object

...

passed to append_units

open

character to precede units

close

character to follow units

style

one of 'plain', 'latex', or 'plotmath'

math_open, math_close, label_open, label_close, newline

passed to as_latex.spar if style = 'latex'

Value

see methods for append_units

Examples

library(units)
library(magrittr)
library(dplyr)
library(ggplot2)
x <- 1:10
attr(x, 'label') <- 'acceleration'
units(x) <- 'm/s^2'
y <- as_units('kg')
x %>% attr('label')
x %>% sub_units %>% attr('label')
x %>% sub_units(style = 'plotmath') %>% attr('label')
x %>% sub_units(style = 'plain') %>% attr('label') %>% writeLines
y %>% attr('label')
y %>% sub_units(style = 'plain') %>% attr('label')
x %>% sub_units(style = 'plotmath')
x %>% sub_units(style = 'latex')

file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
file %>% decorate %>% resolve %>%
sub_units(style = 'plotmath') %>%
ggplot(data = ., aes(x = time, y = conc, color = Heart)) %>%
add(geom_point())

Summarise Decorated

Description

Preserves class when summarising decorated.

Usage

## S3 method for class 'decorated'
summarise(.data, ...)

Arguments

.data

A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

...

<data-masking> Name-value pairs of summary functions. The name will be the name of the variable in the result.

The value can be:

A vector of length 1, e.g. min(x), n(), or sum(is.na(y)).
A data frame, to add multiple columns from a single expression.

Returning values with size 0 or >1 was deprecated as of 1.1.0. Please use reframe() for this instead.

Summarize Decorated

Description

Preserves class when summarizing decorated.

Usage

## S3 method for class 'decorated'
summarize(.data, ...)

Arguments

.data

A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details.

...

<data-masking> Name-value pairs of summary functions. The name will be the name of the variable in the result.

The value can be:

A vector of length 1, e.g. min(x), n(), or sum(is.na(y)).
A data frame, to add multiple columns from a single expression.

Returning values with size 0 or >1 was deprecated as of 1.1.0. Please use reframe() for this instead.

Enforce Symmetry

Description

Enforces symmetric plot design: y axis includes opposites of the range of the data.

Usage

symmetric()

Value

ggplot_symmetric

Examples

library(magrittr)
library(ggplot2)
data.frame(x = 1:10, y = c(-2, 5, 0, -1, 4, 0, 1, -3, 3, 0)) %>%
ggplot(aes(x, y)) + geom_point() + symmetric()

Coerce to Yamlet Storage Format

Description

Coerces to yamlet storage format. Generic, with methods for default, null, character and list which together implement the yamlet storage syntax. Always returns length-one character, possibly the empty string.

Usage

to_yamlet(x, ...)

Arguments

x

object

...

ignored

Value

length-one character

Coerce Null to Yamlet Storage Format

Description

Coerces null to yamlet storage format (returns empty string).

Usage

## S3 method for class ''NULL''
to_yamlet(x, ...)

Arguments

x

object

...

ignored

Value

length-one character

Examples

to_yamlet(NULL)

Coerce Character to Yamlet Storage Format

Description

Coerces character to yamlet storage format. Named character is processed as a named list. NA_character_ is is stored as unquoted NA and read back as NA by as_yam.character. Use quoted "NA" or 'NA' to store the literal string, which will be read back as a string by as_yam.character.

Usage

## S3 method for class 'character'
to_yamlet(x, block = FALSE, ...)

Arguments

x

character

block

whether to write block scalars

...

ignored

Details

If block is TRUE, an attempt will be made to represent character strings as literal block scalars if they contain newlines (experimental in yamlet >= 0.8).

Value

length-one character, never NA, no names

Examples

to_yamlet('foo')
to_yamlet(c('a','b'))
to_yamlet(c(a = 'a',b = 'b'))
to_yamlet(c(no = 'n', yes = 'y'))
to_yamlet(NA)
to_yamlet("NA")

Coerce Default to Yamlet Storage Format

Description

Coerces to yamlet storage format by default conversion to character.

Usage

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

Arguments

x

object

...

ignored

Value

length-one character

Examples

to_yamlet(3)
to_yamlet(c(a = '4',b = '5.8'))
to_yamlet(c(a = 4,b = 5.8))
to_yamlet(TRUE)

Coerce list to yamlet Storage Format

Description

Coerces list to yamlet storage format. Operates recursively on list members.

Usage

## S3 method for class 'list'
to_yamlet(x, ..., bracket_all = FALSE)

Arguments

x

object

...

ignored

bracket_all

FALSE at top level, but TRUE recursively downward; supports 'ITEM: definition' which would otherwise be bracketted

Value

length-one character

Examples

to_yamlet(list())
to_yamlet(list(a = 1, b = 2, c = NULL))
to_yamlet(list(a = 1, b = list(c = 3, d = list(e = 4, f = 'g', 'h'))))
to_yamlet(setNames(1:3, c('a','b',NA)))
to_yamlet(setNames(c(1,2,NA), c('a','b','c')))

Coerce Numeric to Yamlet Storage Format

Description

Coerces numeric to yamlet storage format. By default, numeric values would be processed as character. But character values with a leading dash are ordinarily quoted, since in character context a leading dash could be mistaken for a yaml metacharacter. In the case of a numeric value, however, we can be fairly certain that, despite appearances, the dash if any is actually a negative sign. This method intends to leave negative numerics unquoted, like their positive counterparts.

Usage

## S3 method for class 'numeric'
to_yamlet(x, ...)

Arguments

x

object

...

ignored

Value

length-one character

Examples

library(magrittr)
 'a: [[d: [-1, 0, 1, 2]]]' %>% as_yamlet %>% to_yamlet
 to_yamlet(c(a = 4, b = 5.8))
 to_yamlet(list(a = 4, b = 5.8))
 to_yamlet(numeric(0))

Coerce Yamlet to Yamlet Storage Format

Description

Coerces yamlet to yamlet storage format by unclassing to list.

Usage

## S3 method for class 'yamlet'
to_yamlet(x, ...)

Arguments

x

object

...

ignored

Value

length-one character

Examples

library(magrittr)
 'a: [[d: [-1, 0, 1, 2]]]' %>% as_yamlet %>% to_yamlet

Summarize Type of Classified

Description

Summarizes type of classified.

Usage

## S3 method for class 'classified'
type_sum(x)

Arguments

x

classified

Examples

type_sum(classified(0))

Unclassify Something

Description

Unclassify something. Generic, with method unclassified.classified. See also classified.

Usage

unclassified(x, ...)

Arguments

x

object

...

passed arguments

Value

see methods

Examples

example(unclassified.classified)

Unclassify Classified

Description

Unclassifies classified. Uses codelist attribute to restore original values, preserving other attributes (and rebuilding codelist).

Usage

## S3 method for class 'classified'
unclassified(x, ..., persistence = getOption("yamlet_persistence", TRUE))

Arguments

x

classified

...

ignored

persistence

whether to reclass as dvec

Value

vector

Examples

example(unclassified.data.frame)

Unclassify Data Frame

Description

Unclassifies data.frame. Coerces 'classified' items to original values, rebuilding codelist attribute.

Usage

## S3 method for class 'data.frame'
unclassified(x, ...)

Arguments

x

data.frame

...

passed to select to limit scope

Value

data.frame

Examples

library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
x <- decorate(file)
x %>% explicit_guide %>% decorations(Age, Race, Heart:glyco)
x %>% explicit_guide %>% classified %>% unclassified %>% decorations(Age, Race, Heart:glyco)

Unclassify Decorated Vector

Description

Unclassifies dvec. A non-operation, since dvec is not classified. Needed for completness by resolve.dvec.

Usage

## S3 method for class 'dvec'
unclassified(x, ...)

Arguments

x

dvec

...

ignored

Value

dvec

Examples

library(magrittr)
x <- structure(as_dvec(1), guide = 'misc')
unclassified(x)

Ungroup Decorated

Description

Preserves class when ungrouping decorated.

Usage

## S3 method for class 'decorated'
ungroup(x, ...)

Arguments

x

A tbl()

...

Collapse Uninformative Levels

Description

Each element of a list that is itself a list and does not have a name but has exactly one element that DOES have a name should become that element and have that name (recursively, from depth). Collapses uninformative levels of nested lists. Formerly used in as_yam; now superceded by parsimonious.list.

Usage

unnest(x, ...)

Arguments

x

object

Value

named list

Examples


# yaml.load reads this as a list of two un-named lists whose elements are named.
str(yaml::yaml.load('[foo: 1, bar: 3]'))

# yamlet treats it as a list of two named integers.
str(unnest(yaml::yaml.load('[foo: 1, bar: 3]')))

Collapse Uninformative Levels by Default

Description

The default unnest() method returns the unmodified object.

Usage

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

Arguments

x

object

Value

list

Examples

unnest(yaml::yaml.load('ITEM:'))

Collapse Uninformative Levels of a List

Description

The list method for unnest() recursively ascends a nested list, removing uninformative levels.

Usage

## S3 method for class 'list'
unnest(x, ...)

Arguments

x

list

Value

list

Examples


a <- 'ITEM: [ label: sunshine, [foo: 1, bar: 3]]'

#  yaml.load() sees label nested one-deep, and foo nested two-deep:
yaml::yaml.load(a)

# unnest() sees label nested zero-deep, and foo nested one-deep:
unnest(yaml::yaml.load(a))

# as_yamlet() provides explicit name (default key) for second element of ITEM:
as_yamlet(a)

Cast to character from dvec

Description

Cast to character from dvec.

Usage

## S3 method for class 'character.dvec'
vec_cast(x, to, ...)

## S3 method for class 'character.dvec'
vec_cast(x, to, ...)

Arguments

to

character

...

ignored

Cast to classified from classified

Description

Cast to classified from classified.

Usage

## S3 method for class 'classified.classified'
vec_cast(x, to, ...)

Arguments

x

classified

to

classified

...

ignored

Cast to classified from factor

Description

Cast to classified from factor

Usage

## S3 method for class 'classified.factor'
vec_cast(x, to, ...)

Arguments

x

factor

to

classified

...

ignored

Cast to complex from dvec

Description

Cast to complex from dvec.

Usage

## S3 method for class 'complex.dvec'
vec_cast(x, to, ...)

## S3 method for class 'complex.dvec'
vec_cast(x, to, ...)

Arguments

to

complex

...

ignored

Cast to Data.frame from Decorated

Description

Casts to data.frame from decorated.

Usage

## S3 method for class 'data.frame.decorated'
vec_cast(x, to, ...)

Arguments

x

decorated

to

data.frame

...

passed arguments

Value

data.frame

Cast to Decorated from Data.frame

Description

Casts to decorated from data.frame.

Usage

## S3 method for class 'decorated.data.frame'
vec_cast(x, to, ...)

Arguments

x

data.frame

to

decorated

...

passed arguments

Value

decorated

Cast to Decorated from Decorated

Description

Casts to decorated from decorated.

Usage

## S3 method for class 'decorated.decorated'
vec_cast(x, to, ...)

Arguments

x

decorated

to

decorated

...

passed arguments

Value

decorated

Cast to double from dvec

Description

Cast to double from dvec.

Usage

## S3 method for class 'double.dvec'
vec_cast(x, to, ...)

## S3 method for class 'double.dvec'
vec_cast(x, to, ...)

Arguments

to

double

...

ignored

Cast to dvec from character

Description

Cast to dvec from character.

Usage

## S3 method for class 'dvec.character'
vec_cast(x, to, ...)

## S3 method for class 'dvec.character'
vec_cast(x, to, ...)

Arguments

to

dvec

...

ignored

Cast to dvec from complex

Description

Cast to dvec from complex.

Usage

## S3 method for class 'dvec.complex'
vec_cast(x, to, ...)

## S3 method for class 'dvec.complex'
vec_cast(x, to, ...)

Arguments

to

dvec

...

ignored

Cast to dvec from double

Description

Cast to dvec from double.

Usage

## S3 method for class 'dvec.double'
vec_cast(x, to, ...)

## S3 method for class 'dvec.double'
vec_cast(x, to, ...)

Arguments

to

dvec

...

ignored

Cast to dvec from dvec

Description

Cast to dvec from dvec.

Usage

## S3 method for class 'dvec.dvec'
vec_cast(x, to, ...)

## S3 method for class 'dvec.dvec'
vec_cast(x, to, ...)

Arguments

x

dvec

to

dvec

...

ignored

Cast to dvec from integer

Description

Cast to dvec from integer.

Usage

## S3 method for class 'dvec.integer'
vec_cast(x, to, ...)

## S3 method for class 'dvec.integer'
vec_cast(x, to, ...)

Arguments

to

dvec

...

ignored

Cast to dvec from logical

Description

Cast to dvec from logical

Usage

## S3 method for class 'dvec.logical'
vec_cast(x, to, ...)

## S3 method for class 'dvec.logical'
vec_cast(x, to, ...)

Arguments

x

logical

to

dvec

...

ignored

Cast to factor from classified

Description

Cast to factor from classified.

Usage

## S3 method for class 'factor.classified'
vec_cast(x, to, ...)

Arguments

x

classified

to

factor

...

ignored

Cast to integer from dvec

Description

Cast to integer from dvec.

Usage

## S3 method for class 'integer.dvec'
vec_cast(x, to, ...)

## S3 method for class 'integer.dvec'
vec_cast(x, to, ...)

Arguments

to

integer

...

ignored

Cast to logical from dvec

Description

Cast to logical from dvec.

Usage

## S3 method for class 'logical.dvec'
vec_cast(x, to, ...)

## S3 method for class 'logical.dvec'
vec_cast(x, to, ...)

Arguments

x

dvec

to

logical

...

ignored

Find Common Type for character, dvec

Description

Find common type for character, dvec.

Usage

## S3 method for class 'character.dvec'
vec_ptype2(x, y, ...)

## S3 method for class 'character.dvec'
vec_ptype2(x, y, ...)

Arguments

x

character

y

dvec

...

ignored

Find Common Type for classified, classified

Description

Find common type for classified, classified.

Usage

## S3 method for class 'classified.classified'
vec_ptype2(x, y, ...)

Arguments

x

classified

y

classified

...

ignored

Examples

library(vctrs)
library(magrittr)
c1 <- classified('a', levels = c('a','b')) %>% structure(label = 'c1')
c2 <- classified('b', levels = c('a','b')) %>% structure(label = 'c2')
c3 <- classified('c', levels = c('a','c')) %>% structure(label = 'c3')
f1 <- factor('a', levels = c('a','b')) %>% structure(label = 'f1')
f2 <- factor('b', levels = c('a','b')) %>% structure(label = 'f2')
f3 <- factor('c', levels = c('a','c')) %>% structure(label = 'f3')

vec_c(c1, c1) # combined data, same codelist
vec_c(c1, c2) # combined data, same codelist
vec_c(c2, c1) # reversed data, same codelist

vec_c(c1, c3) # combined data, combined codelist
vec_c(c3, c1) # reversed data, revised codelist
vec_c(c1, f1) # matching levels: return classified
vec_c(f1, c1) # matching levels: return classified

vec_c(c1, f2) # matching levels: return classified
vec_c(f2, c1) # matching levels: return classified

vec_c(c1, f3) # mismatched levels: return factor
vec_c(f3, c1) # mismatched levels: return factor

Find Common Type for classified, factor

Description

Find common type for classified, factor.

Usage

## S3 method for class 'classified.factor'
vec_ptype2(x, y, ...)

Arguments

x

classified

y

factor

...

ignored

Find Common Type for complex, dvec

Description

Find common type for complex, dvec.

Usage

## S3 method for class 'complex.dvec'
vec_ptype2(x, y, ...)

## S3 method for class 'complex.dvec'
vec_ptype2(x, y, ...)

Arguments

x

complex

y

dvec

...

ignored

Determine Common Type for Data.frame and Decorated

Description

Determines common type for data.frame and decorated.

Usage

## S3 method for class 'data.frame.decorated'
vec_ptype2(x, y, ...)

Arguments

x

data.frame

y

decorated

...

passed arguments

Value

decorated

Determine Common Type for Decorated and Data.frame

Description

Determines common type for decorated and data.frame.

Usage

## S3 method for class 'decorated.data.frame'
vec_ptype2(x, y, ...)

Arguments

x

decorated

y

data.frame

...

passed arguments

Value

decorated

Determine Common Type for Decorated

Description

Determines common type for decorated.

Usage

## S3 method for class 'decorated.decorated'
vec_ptype2(x, y, ...)

Arguments

x

decorated

y

decorated

...

passed arguments

Value

decorated

Find Common Type for double, dvec

Description

Find common type for double, dvec.

Usage

## S3 method for class 'double.dvec'
vec_ptype2(x, y, ...)

## S3 method for class 'double.dvec'
vec_ptype2(x, y, ...)

Arguments

x

double

y

dvec

...

ignored

Find Common Type for dvec, dvec

Description

Find common type for dvec, dvec.

Usage

## S3 method for class 'dvec.character'
vec_ptype2(x, y, ...)

## S3 method for class 'dvec.character'
vec_ptype2(x, y, ...)

Arguments

x

dvec

y

dvec

...

ignored

Find Common Type for dvec, complex

Description

Find common type for dvec, complex.

Usage

## S3 method for class 'dvec.complex'
vec_ptype2(x, y, ...)

## S3 method for class 'dvec.complex'
vec_ptype2(x, y, ...)

Arguments

x

dvec

y

complex

...

ignored

Find Common Type for dvec, double

Description

Find common type for dvec, double.

Usage

## S3 method for class 'dvec.double'
vec_ptype2(x, y, ...)

## S3 method for class 'dvec.double'
vec_ptype2(x, y, ...)

Arguments

x

dvec

y

double

...

ignored

Examples

str(vctrs::vec_ptype2(as_dvec(1), 1))
str(vctrs::vec_ptype2(1, as_dvec(1)))

str(vctrs::vec_ptype2(as_dvec(1, label = 'x'), 1))
str(vctrs::vec_ptype2(1, as_dvec(1, label= 'x')))
str(vctrs::vec_ptype2(as_dvec(1), structure(1, label = 'x')))

str(vctrs::vec_ptype2(as_dvec(1), 1))
str(vctrs::vec_ptype2(1, as_dvec(1)))

str(vctrs::vec_ptype2(as_dvec(1, label = 'x'), 1))
str(vctrs::vec_ptype2(1, as_dvec(1, label= 'x')))
str(vctrs::vec_ptype2(as_dvec(1), structure(1, label = 'x')))

Find Common Type for dvec, dvec

Description

Find common type for dvec, dvec.

Usage

## S3 method for class 'dvec.dvec'
vec_ptype2(x, y, ...)

## S3 method for class 'dvec.dvec'
vec_ptype2(x, y, ...)

Arguments

x

dvec

y

dvec

...

ignored

Examples

str(vctrs::vec_ptype2(as_dvec(1L), as_dvec(1)))
str(vctrs::vec_ptype2(as_dvec(1), as_dvec(1L)))
str(vctrs::vec_ptype2(as_dvec(TRUE), as_dvec(1L)))
str(vctrs::vec_ptype2(as_dvec(TRUE), as_dvec(1)))
str(vctrs::vec_ptype2(as_dvec(1), as_dvec(1+0i)))

vctrs::vec_ptype2(
  structure(as_dvec(1), guide = 'mg'),
  structure(as_dvec(1), guide = 'kg')
)
str(vctrs::vec_ptype2(as_dvec(1L), as_dvec(1)))
str(vctrs::vec_ptype2(as_dvec(1), as_dvec(1L)))
str(vctrs::vec_ptype2(as_dvec(TRUE), as_dvec(1L)))
str(vctrs::vec_ptype2(as_dvec(TRUE), as_dvec(1)))
str(vctrs::vec_ptype2(as_dvec(1), as_dvec(1+0i)))

vctrs::vec_ptype2(
  structure(as_dvec(1), guide = 'mg'),
  structure(as_dvec(1), guide = 'kg')
)

Find Common Type for dvec, integer

Description

Find common type for dvec, integer.

Usage

## S3 method for class 'dvec.integer'
vec_ptype2(x, y, ...)

## S3 method for class 'dvec.integer'
vec_ptype2(x, y, ...)

Arguments

x

dvec

y

integer

...

ignored

Find Common Type for dvec, logical

Description

Find common type for dvec, logical.

Usage

## S3 method for class 'dvec.logical'
vec_ptype2(x, y, ...)

## S3 method for class 'dvec.logical'
vec_ptype2(x, y, ...)

Arguments

x

dvec

y

logical

...

ignored

Find Common Type for factor, classified

Description

Find common type for factor, classified.

Usage

## S3 method for class 'factor.classified'
vec_ptype2(x, y, ...)

Arguments

x

factor

y

classified

...

ignored

Find Common Type for integer, dvec

Description

Find common type for integer, dvec.

Usage

## S3 method for class 'integer.dvec'
vec_ptype2(x, y, ...)

## S3 method for class 'integer.dvec'
vec_ptype2(x, y, ...)

Arguments

x

integer

y

dvec

...

ignored

Find Common Type for logical, dvec

Description

Find common type for logical, dvec.

Usage

## S3 method for class 'logical.dvec'
vec_ptype2(x, y, ...)

## S3 method for class 'logical.dvec'
vec_ptype2(x, y, ...)

Arguments

x

logical

y

dvec

...

ignored

Abbreviate Decorated Vector

Description

Abbreviated class name for dvec.

Usage

## S3 method for class 'dvec'
vec_ptype_abbr(x, ...)

Arguments

x

classified

...

ignored

Value

character

Examples

cat(vec_ptype_abbr(as_dvec(0)))

Write Yamlet

Description

Writes yamlet to file. Similar to io_yamlet.yamlet but returns invisible storage format instead of invisible storage location.

Usage

write_yamlet(
  x,
  con = stdout(),
  eol = "\n",
  useBytes = FALSE,
  default_keys = getOption("yamlet_default_keys", list("label", "guide")),
  fileEncoding = getOption("encoding"),
  block = FALSE,
  ...
)

Arguments

x

something that can be coerced to class 'yamlet', like a yamlet object or a decorated data.frame

con

passed to writeLines

eol

end-of-line; passed to writeLines as sep

useBytes

passed to writeLines

default_keys

character: default keys for the first n anonymous members of each element

fileEncoding

if con is character, passed to file as encoding

block

whether to write block scalars

...

passed to as_yamlet and to as.character.yamlet

Value

invisible character representation of yamlet (storage syntax)

Examples

library(csv)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')
meta <- system.file(package = 'yamlet', 'extdata','quinidine.yaml')
x <- as.csv(file)
y <- read_yamlet(meta)
x <- decorate(x, meta = y)
identical(x, decorate(file))
tmp <- tempfile()
write_yamlet(x, tmp)
stopifnot(identical(read_yamlet(meta), read_yamlet(tmp)))

Create Export Table for Decorated

Description

Creates an export table for decorated data.frame by adding a footnote attribute.

Usage

## S3 method for class 'decorated'
xtable(x, ..., label = NULL, style = "latex")

Arguments

x

decorated

...

passed to footnote and (if named) xtable

label

passed to xtable

style

passed to footnote

Value

class 'decorated_xtable','xtable', 'data.frame'

Examples

library(magrittr)
library(xtable)
set.seed(0)
x <- data.frame(
 auc = rnorm(100, mean = 2400, sd = 200),
 bmi = rnorm(100, mean = 20, sd = 5),
 gen = 0:1
)
x %<>% decorate('auc: [AUC_0-24, ng*h/mL]')
x %<>% decorate('bmi: [Body Mass Index, kg/m^2]')
x %<>% decorate('gen: [Gender, [Male: 1, Female: 0]]')
y <- xtable(x)
attr(y, 'footnote')
y <- xtable(x, auc:bmi)
attr(y, 'footnote')

Display Global Yamlet Options

Description

Displays global yamlet options: those options whose names begin with 'yamlet_'.

yamlet_append_units_open: see append_units.default. Controls how labels are constructed for variables with 'units' attributes. In brief, units are wrapped in parentheses, and appended to the label.
yamlet_append_units_close: see append_units.default. Controls how labels are constructed for variables with 'units' attributes. In brief, units are wrapped in parentheses, and appended to the label.
yamlet_append_units_style: see append_units.default. Determines parsing as 'plotmath' or 'latex', or 'plain' for no parsing.
yamlet_append_units_target: see append_units.default. By default, append result is assigned to attribute 'label', but could be something else like 'title'.
yamlet_default_keys: see as_yamlet.character. The first two yaml attributes without specified names are assumed to be 'label' and 'guide'.
yamlet_persistence: see decorate.list and as.integer.classified. By default, persistence of column attributes is implemented by creating 'dvec' objects (decorated vectors) using vctrs methodology.
yamlet_cell_value: see as.data.frame.yamlet. Controls how cells are calculated when converting yamlet (decorations) to a data.frame.
yamlet_import: see decorate.character. Controls how primary data is read from file (default: as.csv()).
yamlet_extension: see decorate.character. Controls what file extension is expected for yaml metadata (default: '.yaml')
yamlet_overwrite: see decorate.list. Controls whether existing decorations are overwritten.
yamlet_exclude_attr: see decorations.data.frame Controls what attributes are excluded from display.
yamlet_with_title: see make_title.dvec and drop_title.dvec. For objects with (implied) units attributes, titles are by default automatically created on resolve() and destroyed on desolve(). Interacts with yamlet_append_units_*.
yamlet_infer_guide: see explicit_guide.yamlet. Identifies the function that will be used to reclassify 'guide' as something more explicit.
yamlet_explicit_guide_overwrite: see explicit_guide.data.frame and explicit_guide.dvec. In the latter case, controls whether existing attributes are overwritten.
yamlet_explicit_guide_simplify: explicit_guide.data.frame and explicit_guide.dvec. Ordinarily, the 'guide' attribute is removed if something more useful can be inferred.
yamlet_decorated_ggplot_search: see print.decorated_ggplot. The print method for decorated_ggplot populates axis labels by searching first for attributes named 'expression', 'title', and 'label'. Customizable.
yamlet_decorated_ggplot_discrete: see print.decorated_ggplot. Discrete aesthetics to map from data decorations where available.
yamlet_decorated_ggplot_drop: see print.decorated_ggplot. Should unused factor levels be omitted from data-driven discrete scales?
yamlet_ggready_parse: see ggready.data.frame, ggready.decorated. Whether to parse axis labels. TRUE by default, but may be problematic if unintended.
yamlet_modify_reserved: see modify.default. A list of reserved labels that warn on reassignment.
yamlet_promote_reserved: see promote.list. Attributes to leave untouched when promoting singularities.
yamlet_promote: see filter.decorated. Whether to promote when filtering 'decorated'.
yamlet_as_units_preserve: as_units.dvec. What attributes to preserve when converting dvec to units. Just 'label' by default. Assign options(yamlet_as_units_preserve = character(0)) to remove all.
yamlet_print_simplify: print.yamlet. Whether to collapse interactively-displayed decorations into a single line for lists that have no (nested) names and have the same length when unlisted. True by default. Can be misleading for lists with fine detail, but in most cases fine detail will likely have names.
yamlet_format: enscript.default. Choice of 'html' or 'latex', guessed if not supplied.
yamlet_warn_conflicted: c.classified. Whether to warn when codelists for combined classified factors have conflicting names (which will be dropped).
yamlet_expand_codelist: explicit_guide.yamlet. If TRUE (default) an empty list as a guide attribute is short-hand for sort(unique(x)).
yamlet_collapse_codelist: implicit_guide.data.frame. An integer (default: Inf) giving the maximum number of (un-named) codelist elements to store explicitly. Else, if sort(unique(x)) has exactly the same values as codelist, implicit_guide will substitute an empty list.

Usage

yamlet_options()

Value

list

Examples

yamlet_options()

yamlet: Versatile Curation of Table Metadata

Description

Storage Format

Author(s)

See Also

Assign Subset of Classified

Description

Usage

Arguments

Value

See Also

Examples

Assign Subset of Decorated

Description

Usage

Arguments

Value

See Also

Examples

Assign Subset of Decorated Vector

Description

Usage

Arguments

Value

See Also

Examples

Subset Classified

Description

Usage

Arguments

Value

See Also

Examples

a <- as_decorated(as.list(setNames(letters[1:3], LETTERS[1:3]))) attr(a$B, 'label') <- 'foo' a <- a[1:3] attributes(a) Subset Decorated

Description

Usage

Arguments

Value

See Also

Examples

Subset Decorated Vector

Description

Usage

Arguments

Value

See Also

Examples

Subset Unit String

Description

Usage

Arguments

Value

See Also

Examples

Subset Yamlet

Description

Usage

Arguments

Value

See Also

Examples

Assign Element of Classified

Description

Usage

Arguments

Value

See Also

Examples

Assign Element of Decorated

Description

Usage

Arguments

Value

See Also

Examples

Assign Element of Decorated Vector

Description

Usage

Arguments

Value