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 parametername. Always use triple braces. Double braces ({{name}}) HTML-escape the value, e.g.a<bbecomesa<b.{{#name}}...{{/name}}repeats the enclosed text for each element of the vectorname. Use{{{.}}}to insert the current element.
Tags
A tag continues until the next tag. Required tags must appear exactly once.
| Tag | Required | Description | Example |
@title | Yes | Title of the component. | @title Double a column |
@description | Yes | Description of the component. | @description Creates a new column. |
@param | No | Name, then description. One per placeholder. | @param domain `character` Name of the domain |
@type | Yes | Component type. See Types below. | @type column |
@origin | Yes | CDISC origin. See allowed values below. | @origin Derived |
@method | Yes | Free-text method description for define.xml. | @method Two times the input column |
@depends | No | Input domain, then column. Repeat for each. | @depends {{{domain}}} USUBJID |
@outputs | No | Column created. Repeat for each. | @outputs {{{output}}} |
@code | Yes | Last tag. All lines below are the code. | @code |
@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 newPARAMCD(BDS parameter).internal: Helper step with no define.xml output.
Conventions
The input data set is
{{{domain}}}.The code assigns the result back to
{{{domain}}}.Every placeholder is declared with
@param.Functions are called with explicit namespaces, e.g.
dplyr::mutate().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
idcharacter(1)Component name without file extension.titlecharacter(1)Title of the component.descriptioncharacter(1)Description of the component.codecharacterLines below@code.templatecharacterFull template.typecharacter(1)Component type. One ofcolumn,row,parameter,internal.origincharacter(1)CDISC origin. One ofAssigned,Collected,Derived,Not Available,Other,Predecessor,Protocol.methodcharacter(1)Method description for define.xml.dependsdata.framewith columnsdomainandcolumn.outputscharacterColumns created by the component.paramsdata.framewith columnsnameanddescription.
Methods
mighty_component$render()
Render the component with whisker::whisker.render().
Arguments
...Named parameters used to render the template. Supply one for each
@paramtag and no others.For
@type rowcomponents,domaincan be a subset marker:".mighty_subset(<domain>, '<subset>')", where<subset>is an R expression in a string, e.g.domain = ".mighty_subset(ADLB, 'PARAMCD == \"ALB\"')". The code then only processes the rows where<subset>isTRUE. Other rows are kept unchanged. The marker is not allowed for other parameters or types.
Returns
Object of class mighty_component_rendered
Examples
path <- system.file("examples", "ady.mustache", package = "mighty.component")
x <- mighty_component$new(template = readLines(path), id = "ady")
x
#> <mighty_component/R6>
#> ady: Analysis relative day
#> Type: column
#> Parameters:
#> • domain: `character` Name of new domain being created
#> • variable: `character` Name of new variable to create
#> • date: `character` Name of date variable to use
#> Depends:
#> • {{{domain}}}.{{{date}}}
#> • {{{domain}}}.TRTSDT
#> Outputs:
#> • {{{variable}}}
x$params
#> name description
#> 1 domain `character` Name of new domain being created
#> 2 variable `character` Name of new variable to create
#> 3 date `character` Name of date variable to use
x$depends
#> domain column
#> 1 {{{domain}}} {{{date}}}
#> 2 {{{domain}}} TRTSDT
x$render(domain = "ADAE", variable = "ASTDY", date = "ASTDT")
#> <mighty_component_rendered/mighty_component/R6>
#> ady: Analysis relative day
#> Type: column
#> Depends:
#> • ADAE.ASTDT
#> • ADAE.TRTSDT
#> Outputs:
#> • ASTDY
#> Code:
#> ADAE <- ADAE |>
#> dplyr::mutate(
#> ASTDY = admiral::compute_duration(
#> start_date = TRTSDT,
#> end_date = ASTDT,
#> in_unit = 'days',
#> out_unit = 'days',
#> add_one = TRUE
#> )
#> )
x$document()
#> ## ady: Analysis relative day
#> *type: column*
#> *origin: Derived*
#> *method: Relative day computed from treatment start date*
#>
#> Derives the relative day compared to the treatment start date.
#>
#> ### Parameters
#>
#> |name |description |
#> |:--------|:--------------------------------------------|
#> |domain |`character` Name of new domain being created |
#> |variable |`character` Name of new variable to create |
#> |date |`character` Name of date variable to use |
#>
#> ### Depends
#>
#> |domain |column |
#> |:------------|:----------|
#> |{{{domain}}} |{{{date}}} |
#> |{{{domain}}} |TRTSDT |
#>
#> ### Outputs
#>
#> * {{{variable}}}
#>
#> ### Code
#>
#> ```r
#> {{{domain}}} <- {{{domain}}} |>
#> dplyr::mutate(
#> {{{variable}}} = admiral::compute_duration(
#> start_date = TRTSDT,
#> end_date = {{{date}}},
#> in_unit = 'days',
#> out_unit = 'days',
#> add_one = TRUE
#> )
#> )
#> ```
