Package {mighty.component}

Find a component

Description

Find a component in one or more repos. Returns NULL if no repo contains it, while get_component() raises an error. Local repo directories must exist, otherwise an error is raised.

Usage

find_component(component, repos = NULL)

Arguments

Value

A mighty_component object, or NULL if no repo contains the component.

See Also

get_component(), list_components()

Examples

path <- system.file("examples", package = "mighty.component")
find_component("ady", repos = path)

find_component("does_not_exist", repos = path)

Retrieve a component

Description

• get_component(): Find a component. Raises an error if it is not found.

• get_rendered_component(): Find a component and render it with params.

Usage

get_component(component, repos = NULL)

get_rendered_component(component, params = list(), repos = NULL)

Arguments

Details

Components are .mustache or .R files. Both use the tags described in mighty_component.

• .mustache files are Mustache templates.

• .R files are plain R components. They cannot have ⁠@param⁠ tags or Mustache placeholders.

Value

• get_component(): A mighty_component object.

• get_rendered_component(): A mighty_component_rendered object.

See Also

find_component(), mighty_component, mighty_component_rendered

Examples

path <- system.file("examples", "ady.mustache", package = "mighty.component")
get_component(path)

get_rendered_component(
  component = path,
  params = list(domain = "ADAE", variable = "ASTDY", date = "ASTDT")
)

# Find by name in a repo
repo <- system.file("examples", package = "mighty.component")
get_component("ady", repos = repo)

Create a test component

Description

Retrieve and render a component as a mighty_component_test object, for unit tests with code coverage. See mighty_component_test for the workflow.

Requires the callr and covr packages.

Usage

get_test_component(
  component,
  params = list(),
  repos = NULL,
  check_coverage = TRUE,
  teardown_env = parent.frame()
)

Arguments

Value

A mighty_component_test object.

See Also

get_rendered_component(), mighty_component_test

Examples

path <- system.file("examples", "ady.mustache", package = "mighty.component")
x <- get_test_component(
  component = path,
  params = list(domain = "adae", variable = "ASTDY", date = "ASTDT"),
  check_coverage = FALSE
)

adae <- data.frame(
  TRTSDT = as.Date("2024-01-01"),
  ASTDT = as.Date(c("2024-01-01", "2024-01-10"))
)

x$assign("adae", adae)$eval()
x$get("adae")
x$percent_coverage
x$close()

List components in repos

Description

List the components in one or more repos. See mighty_repo() for the component layout. Files starting with ⁠test-⁠ are not listed.

Usage

list_components(repos, as = c("character", "list", "tibble"))

Arguments

Value

Depending on as:

• "character": character vector of unique component names.

• "list": list with one element per component, each a named list with id, title, description, type, origin, method, params, depends, outputs and code.

• "tibble": tibble with one row per component and the same columns.

See Also

get_component(), find_component()

Examples

path <- system.file("examples", package = "mighty.component")
list_components(path)

list_components(path, as = "list") |>
  str(max.level = 2)

Options for mighty.component

Description

verbosity_level

Verbosity level for functions in mighty.component. See zephyr::verbosity_level for details.

• Default: NA_character_

• Option: mighty.component.verbosity_level

• Environment: R_MIGHTY.COMPONENT_VERBOSITY_LEVEL

max_tries

Maximum number of attempts for GitHub and URL requests. See mighty_repo_github() and mighty_repo_url() for which errors are retried.

• Default: 3L

• Option: mighty.component.max_tries

• Environment: R_MIGHTY.COMPONENT_MAX_TRIES

timeout

Maximum number of seconds per URL request attempt. See mighty_repo_url().

• Default: 5

• Option: mighty.component.timeout

• Environment: R_MIGHTY.COMPONENT_TIMEOUT

Internal parameters for reuse in functions

Description

Internal parameters for reuse in functions

Arguments

Details

See mighty.component-options for more information.

Mighty component class

Description

R6 class for a component.

A component is a code template. Its code takes an input data set and returns a modified version with new or changed columns or rows. Components are documented with roxygen-like tags.

Use get_component() to create a component from a file or repo.

Details

Templates

A template starts with tags in roxygen comments (⁠#'⁠). All lines below the ⁠@code⁠ tag are the R code.

Templates use Mustache placeholders. ⁠$render()⁠ fills them in with whisker::whisker.render().

• {{{name}}} inserts the value of parameter name. Always use triple braces. Double braces ({{name}}) HTML-escape the value, e.g. a<b becomes ⁠a<b⁠.

• ⁠{{#name}}...{{/name}}⁠ repeats the enclosed text for each element of the vector name. Use {{{.}}} to insert the current element.

Tags

A tag continues until the next tag. Required tags must appear exactly once.

⁠@origin⁠ must be one of Assigned, Collected, Derived, ⁠Not Available⁠, Other, Predecessor, Protocol.

⁠@depends⁠ is split at the first space into domain and column. Do not use spaces inside its placeholders, e.g. use {{{domain}}}, not {{{ domain }}}.

Types

• column: Adds or modifies columns. The row count is unchanged.

• row: Adds, removes or modifies rows.

• parameter: Derives a new PARAMCD (BDS parameter).

• internal: Helper step with no define.xml output.

Conventions

1. The input data set is {{{domain}}}.

2. The code assigns the result back to {{{domain}}}.

3. Every placeholder is declared with ⁠@param⁠.

4. Functions are called with explicit namespaces, e.g. dplyr::mutate().

5. Joins specify by. This is enforced when rendering.

Validation

When a component is rendered, the code is parsed and must be valid R. Joins from dplyr, tidylog and dbplyr without a by argument raise an error. Column existence is not checked.

Example

This template creates a new column output as two times the existing column input:

#' @title Double a column
#' @description
#' Creates a new column as two times an existing column.
#'
#' @param domain `character` Name of the domain
#' @param output `character` Name of the new column
#' @param input `character` Name of the existing column
#' @type column
#' @origin Derived
#' @method Two times the input column
#' @depends {{{domain}}} {{{input}}}
#' @outputs {{{output}}}
#' @code
{{{domain}}} <- {{{domain}}} |>
  dplyr::mutate(
    {{{output}}} = 2 * {{{input}}}
  )

Rendered with domain = "ADSL", output = "A" and input = "B", the code (⁠$code⁠) is:

ADSL <- ADSL |>
  dplyr::mutate(
    A = 2 * B
  )

The tags are rendered too, e.g. ⁠$depends⁠ has domain ADSL and column B.

Active bindings

Methods

Public methods

• mighty_component$new()

• mighty_component$print()

• mighty_component$render()

• mighty_component$document()

• mighty_component$clone()

mighty_component$new()

Create a component from a template.

Usage

mighty_component$new(template, id)

Arguments

mighty_component$print()

Print the component.

Usage

mighty_component$print()

Returns

(invisible) self

mighty_component$render()

Render the component with whisker::whisker.render().

Usage

mighty_component$render(...)

Arguments

Returns

Object of class mighty_component_rendered

mighty_component$document()

Create documentation in markdown format. Requires the knitr package.

Usage

mighty_component$document()

Returns

(invisible) character(1) Markdown documentation. Also printed to the console.

mighty_component$clone()

The objects of this class are cloneable with this method.

Usage

mighty_component$clone(deep = FALSE)

Arguments

See Also

get_component(), mighty_component_rendered, vignette("mighty-component")

Examples

path <- system.file("examples", "ady.mustache", package = "mighty.component")
x <- mighty_component$new(template = readLines(path), id = "ady")
x

x$params
x$depends

x$render(domain = "ADAE", variable = "ASTDY", date = "ASTDT")


x$document()

Rendered mighty component class

Description

R6 class for a rendered component, created by mighty_component⁠$render()⁠ or get_rendered_component().

A rendered component can be:

• Streamed into an R script with ⁠$stream()⁠.

• Evaluated in an environment with ⁠$eval()⁠.

Super class

mighty_component -> mighty_component_rendered

Methods

Public methods

• mighty_component_rendered$new()

• mighty_component_rendered$print()

• mighty_component_rendered$stream()

• mighty_component_rendered$eval()

• mighty_component_rendered$clone()

mighty_component_rendered$new()

Create a rendered component from a rendered template. The code is validated. See the Validation section in mighty_component.

Usage

mighty_component_rendered$new(template, id)

Arguments

mighty_component_rendered$print()

Print the rendered component, including its code.

Usage

mighty_component_rendered$print()

Returns

(invisible) self

mighty_component_rendered$stream()

Write the code to an R script. The code is appended if the file exists.

Usage

mighty_component_rendered$stream(path)

Arguments

Returns

(invisible) self

mighty_component_rendered$eval()

Evaluate the code.

Usage

mighty_component_rendered$eval(envir = parent.frame())

Arguments

Returns

Value of the last evaluated expression of the code.

mighty_component_rendered$clone()

The objects of this class are cloneable with this method.

Usage

mighty_component_rendered$clone(deep = FALSE)

Arguments

See Also

get_rendered_component(), mighty_component

Examples

path <- system.file("examples", "ady.mustache", package = "mighty.component")
x <- get_component(path)$render(
  domain = "adae",
  variable = "ASTDY",
  date = "ASTDT"
)
x$code

# Write the code to an R script
script <- tempfile(fileext = ".R")
x$stream(script)
readLines(script)
unlink(script)


# Evaluate the code in a new environment
env <- new.env()
env$adae <- data.frame(
  TRTSDT = as.Date("2024-01-01"),
  ASTDT = as.Date(c("2024-01-01", "2024-01-10"))
)
x$eval(envir = env)
env$adae

Test mighty component class

Description

R6 class for unit testing a component with code coverage tracking. The code runs in a separate R process (the test session), and the lines executed are counted.

Details

Test session

get_test_component() starts a new R process with 'callr', the test session. Input data, the component code and its results all live in the global environment of the test session. Your own R session and its global environment are never modified.

The test session is closed with ⁠$close()⁠, or when the object is garbage collected. After that, ⁠$assign()⁠, ⁠$get()⁠, ⁠$ls()⁠ and ⁠$eval()⁠ raise an error.

Workflow

1. Create the test component with get_test_component().

2. Assign input data in the test session with ⁠$assign()⁠.

3. Run the code in the test session and update coverage with ⁠$eval()⁠.

4. Retrieve results from the test session with ⁠$get()⁠.

5. Test the results with testthat ⁠expect_*()⁠ functions.

6. Close the test session with ⁠$close()⁠.

By default, get_test_component() checks coverage with ⁠$check_coverage()⁠ when the test ends. Coverage is kept in your R session, so it can still be checked after ⁠$close()⁠.

Super classes

mighty_component -> mighty_component_rendered -> mighty_component_test

Active bindings

Methods

Public methods

• mighty_component_test$new()

• mighty_component_test$print()

• mighty_component_test$assign()

• mighty_component_test$get()

• mighty_component_test$ls()

• mighty_component_test$eval()

• mighty_component_test$check_coverage()

• mighty_component_test$close()

• mighty_component_test$clone()

mighty_component_test$new()

Create a test component from a rendered template. Starts a new R session. Requires the callr and covr packages.

Usage

mighty_component_test$new(template, id)

Arguments

mighty_component_test$print()

Print the test component with its code coverage.

Usage

mighty_component_test$print()

Returns

(invisible) self

mighty_component_test$assign()

Assign a variable in the global environment of the test session. Your R session is not modified.

Usage

mighty_component_test$assign(x, value)

Arguments

Returns

(invisible) self

mighty_component_test$get()

Get a variable from the global environment of the test session.

Usage

mighty_component_test$get(x)

Arguments

Returns

A copy of the variable's value.

mighty_component_test$ls()

List the variables in the global environment of the test session.

Usage

mighty_component_test$ls()

Returns

character Variable names.

mighty_component_test$eval()

Run the code in the global environment of the test session and update the coverage.

Usage

mighty_component_test$eval()

Returns

(invisible) self

mighty_component_test$check_coverage()

Check that every line of the code has run at least once. Raises an error otherwise.

Usage

mighty_component_test$check_coverage()

Returns

(invisible) self

mighty_component_test$close()

Close the test session. Called automatically when the object is garbage collected.

Usage

mighty_component_test$close()

Returns

(invisible) self

mighty_component_test$clone()

The objects of this class are cloneable with this method.

Usage

mighty_component_test$clone(deep = FALSE)

Arguments

See Also

get_test_component()

Examples

path <- system.file("examples", "ady.mustache", package = "mighty.component")
x <- get_test_component(
  component = path,
  params = list(domain = "adae", variable = "ADY", date = "ADT"),
  check_coverage = FALSE
)
x$percent_coverage

x$assign(
  "adae",
  data.frame(TRTSDT = as.Date("2024-01-01"), ADT = as.Date("2024-01-05"))
)
x$eval()
x$ls()
x$get("adae")$ADY
x$percent_coverage
x$check_coverage()
x$close()

Component repos

Description

• mighty_repo(): Create a component repo from a spec.

• mighty_repo_class: Abstract parent class of all component repos. It has no properties and cannot be created directly.

Specs have the form type::path. Supported types:

• local: A local directory, e.g. local::inst/examples. A spec without a prefix is treated as local.

• github: A GitHub repository, e.g. github::owner/repo/subdir@ref. See mighty_repo_github().

• url: Raw files under a base URL, e.g. ⁠url::https://example.com/components⁠. See mighty_repo_url().

All repo types share one layout. A component name is the file ⁠<name>.R⁠ or ⁠<name>.mustache⁠, either directly in the repo or in a directory named after the component (⁠<name>/<name>.R⁠). A name with an extension only matches that file.

Usage

mighty_repo(spec)

Arguments

Value

mighty_repo(): An object inheriting from mighty_repo_class.

See Also

mighty_repo_local(), mighty_repo_github(), mighty_repo_url(), mighty_repos()

Examples

path <- system.file("examples", package = "mighty.component")
mighty_repo(path)
mighty_repo(paste0("local::", path))

GitHub component repo

Description

A component repo hosted on GitHub. When the object is created, ref is resolved to a commit SHA and the repository tarball for that commit is downloaded and extracted to a temporary directory. Resolved SHAs are cached per ref and tarballs per commit for the session, so all lookups afterwards are local. Restart the session to pick up new commits on a branch.

spec is a remotes-style repository reference: owner/repo, owner/repo/subdir, owner/repo@ref or a combination.

Transient API errors (HTTP 5xx and network failures) are retried. The number of attempts is set by the max_tries option. See mighty.component-options.

Requires the gh and remotes packages. Private repositories need a GitHub token. gh reads it from the GITHUB_PAT or GITHUB_TOKEN environment variable, or the Git credential store. See gh::gh_token().

Usage

mighty_repo_github(spec)

Arguments

Value

A mighty_repo_github object. It inherits from mighty_repo_local(), with path set to the downloaded repository or its subdir.

See Also

mighty_repo()

Examples

repo <- mighty_repo_github(
  spec = "NovoNordisk-OpenSource/mighty.standards/components@main"
)
find_component(component = "dummy", repos = repo)

Local component repo

Description

A component repo in a local directory. See mighty_repo() for the component layout. An error is raised if more than one file matches a component.

Usage

mighty_repo_local(path)

Arguments

Value

A mighty_repo_local object.

Examples

path <- system.file("examples", package = "mighty.component")
mighty_repo_local(path = path)

URL component repo

Description

A component repo served as raw files under a base URL. Requires httr2 (>= 1.2.2).

See mighty_repo() for the component layout. .mustache is tried before .R, and ⁠<name>/⁠ before files directly under url. The first found is used. Status 404 and 410 count as not found; other errors are raised. name is percent-encoded, and names containing / are not found. Responses are not cached.

Listing components (see list_components()) requires an HTML directory index at ⁠<url>/⁠, and at ⁠<url>/<dir>/⁠ for nested components, e.g. Apache or nginx autoindex, or ⁠python -m http.server⁠. Listing aborts if an index is unavailable or not HTML.

Transient errors (see httr2::req_retry()) and network failures are retried. The number of attempts is set by the max_tries option, and each attempt is limited by the timeout option (see mighty.component-options).

Usage

mighty_repo_url(url)

Arguments

Value

A mighty_repo_url object.

Examples

repo <- mighty_repo_url(
  url = paste0(
    "https://raw.githubusercontent.com/",
    "NovoNordisk-OpenSource/mighty.standards/main/components"
  )
)
format(repo)


find_component(component = "dummy", repos = repo)

Collection of component repos

Description

An ordered collection of component repos. Lookups search the repos in order, and the first match wins.

Each element of repos is either a repo spec, passed to mighty_repo(), or an object inheriting from mighty_repo_class. Repos are created once when the collection is created.

Usage

mighty_repos(repos = character(0))

Arguments

Value

A mighty_repos object: a list of repos.

See Also

find_component(), list_components()

Examples

path <- system.file("examples", package = "mighty.component")
repos <- mighty_repos(repos = c(path, paste0("local::", path)))
repos

find_component(component = "ady", repos = repos)