Overview

Code components are the building blocks that implement the actual derivations, transformations, and calculations in your ADaM datasets. Components come in two technical formats that determine how mighty processes and executes them:

R script components - Plain executable R code (.R files)
Mustache template components - Parameterizable templates (.mustache files)

Component metadata parsing and Mustache rendering are handled by the mighty.component package. This vignette describes the metadata format and file structure that components must follow; mighty.component is what mighty uses under the hood to read and render them. # Component types Beyond their technical format, components are classified by what they do to your data. @type takes one of four values: column, row, parameter, or internal.

Column components (@type column) create new columns in your dataset. They take existing columns as inputs and derive new variables. For example, calculating an age group from age, or computing a relative day from two dates. Column components:

Always create one or more new columns (specified in @outputs)
Can depend on columns from multiple datasets
Build on top of each other - one component’s output can be another’s input
Are the most common type of component
Are referenced in the column section of your YAML ADaM specification

Row components (@type row) add new rows to your dataset or modify existing rows. For example, computing summary statistics that create new observation rows. Row components:

Add new records to the dataset
May modify column values in the newly created rows
May modify existing rows (i.e. with a subset operation)
List any modified columns in @outputs
Do not create new columns - they only populate values in existing column structures
Are referenced in the row section of your YAML ADaM specification

Parameter components (@type parameter) create BDS parameter records, such as adding a new PARAMCD to a BDS dataset. They are processed the same way as row components. Parameter components:

Add new parameter records to the dataset
May modify column values in the newly created rows
List any modified columns in @outputs
Are referenced in the parameter section of your YAML ADaM specification

Internal components (@type internal) implement mighty’s own internal machinery, such as reading source data or initializing a domain. They are not referenced from a column, row, or parameter section of a YAML ADaM specification, and are not typically written by end users.

The key distinction between the user-facing types: column components expand your dataset horizontally (more variables), while row and parameter components expand it vertically (more records).

Component Structure

All components share a common structure:

A roxygen-like metadata header
A body containing the business logic

The format you choose depends on whether your derivation logic needs parameterization. R scripts execute fixed logic, while Mustache templates allow you to pass parameters from your ADaM specification to customize behavior.

Metadata Header

All components use the same metadata header structure with roxygen2-style tags. Mighty extracts this metadata to understand dependencies, outputs, and how to orchestrate components.

Metadata Tags

`@title`

Short descriptive title for the component.

#' @title Age Group Classification

`@description`

Detailed explanation of what the component does.

#' @description Categorizes subjects into age groups based on AGE variable

`@param`

Only for Mustache template components - Parameters to pass to the template, populated from the with section of the ADaM specification. See vignette("adam_specification").

#' @param domain Name of the ADaM domain
#' @param cut_points Vector of age cut points

`@type`

Component type: "column", "row", "parameter", or "internal".

#' @type column

`@origin`

CDISC origin of the column, one of "Assigned", "Collected", "Derived", "Not Available", "Other", "Predecessor", or "Protocol". Used for define.xml generation.

#' @origin Derived

`@method`

Description of how the column is derived, in prose. Used as the method description for define.xml generation.

#' @method Age cut into the groups < 18, 18-64, 65-74 and >= 75 years.

`@depends`

Input dependencies listing the required columns. Format: DOMAIN COLUMN1

Multiple depends are listed on separate lines:

#' @depends ADSL AGE
#' @depends ADLB LBSTRESN

Mighty uses this for dependency analysis and execution ordering.

`@outputs`

If the component is a column derivation, this specifies which column(s) the component creates. If the component is a row/parameter action, this specifies which column(s) the component modifies

Multiple outputs are listed on separate lines.

#' @outputs AGE_GRP1
#' @outputs COL1

Mighty uses this to track what each component produces or modifies.

`@code`

Marker indicating where the executable code (the component body) begins. All code must come after this tag.

#' @code

# Your R code here
ADSL <- ADSL |> dplyr::mutate(...)

R Script Components

R script components contain plain executable R code with fixed derivation logic. They are saved as .R files and execute the same way every time they are called.

When to Use

Use R script components when:

Derivation logic is fixed and does not need parameterization
The component is specific to a single use case
You want straightforward, readable code without template syntax

Code Structure

All executable code must come after the @code tag
Use roxygen2 comment style (#') for metadata
Regular R comments (#) can be used within the code

Example: Simple Column Derivation

#' @title Age Group Classification
#' @description Categorizes subjects into age groups based on AGE variable
#' @type column
#' @origin Derived
#' @method Age cut into the groups < 18, 18-64, 65-74 and >= 75 years.
#' @depends ADSL AGE
#' @outputs AGE_GRP1
#' @code

ADSL <- ADSL |>
  # This is an example comment
  dplyr::mutate(
    AGE_GRP1 = cut(
      AGE,
      breaks = c(-Inf, 18, 65, 75, Inf),
      labels = c("< 18 years", "18 - 64 years", "65 - 74 years", ">= 75 years"),
      right = FALSE
    )
  )

Example: Dependent Derivation

Components can depend on other derived columns:

#' @title Age Category Classification
#' @description Further categorizes age groups into expected vs unexpected ranges
#' @type column
#' @origin Derived
#' @method Age groups < 18 and >= 75 years are flagged as outside the expected range.
#' @depends ADSL AGE_GRP1
#' @outputs AGE_CAT1
#' @code

ADSL <- ADSL |>
  dplyr::mutate(
    AGE_CAT1 = dplyr::case_when(
      AGE_GRP1 %in% c("< 18 years", ">= 75 years") ~ "Outside expected range",
      TRUE ~ "Inside expected range"
    )
  )

Example: Multiple Dependencies

Components can depend on multiple columns from multiple datasets:

#' @title Minimum AVAL per Subject
#' @description Derives the minimum lab value for each subject from ADLB
#' @type column
#' @origin Derived
#' @method Lowest AVAL recorded for the subject in ADLB.
#' @depends ADSL USUBJID
#' @depends ADLB USUBJID
#' @depends ADLB AVAL
#' @outputs MIN_AVAL
#' @code

ADSL <- ADSL |>
  dplyr::left_join(
    ADLB |>
      dplyr::select(USUBJID, AVAL) |>
      dplyr::group_by(USUBJID) |>
      dplyr::summarise(MIN_AVAL = min(AVAL, na.rm = TRUE)) |>
      dplyr::ungroup(),
    by = "USUBJID"
  )

Mustache Template Components

Mustache template components use Mustache syntax to enable parameterization. They are saved as .mustache files and allow the same component logic to be reused with different parameters.

When to Use

Use Mustache template components when:

You want to reuse a component across multiple columns, datasets, trials, or projects
The same derivation logic needs to work with different parameters

Template Syntax

Mustache templates use triple curly braces {{{variable}}} as placeholders that get replaced with actual values when mighty renders the component. Triple braces avoid HTML escaping, which would corrupt R operators such as <- and > in generated code. See Template syntax in the special components vignette for a full explanation of double vs. triple mustache syntax.

Parameters are specified in the with: section of your YAML specification
Both metadata and code sections can contain placeholders

Code Structure

Metadata header uses @param tags to document expected parameters
Placeholders can appear in @depends, @outputs, and the code body
Mighty (via mighty.components) renders the template before execution, replacing all placeholders
The rendered output is plain R code

Example: Parameterized Column Derivation

Template file: relative_day.mustache

#' @title Analysis relative day
#' @description
#' Derives the relative day compared to the treatment start date.
#'
#' @param domain Name of ADaM domain
#' @param variable Name of new variable to create
#' @param date Name of date variable to use
#' @type column
#' @origin Derived
#' @method Number of days from TRTSDT to {{{date}}}, counting both endpoints.
#' @depends {{{domain}}} {{{date}}}
#' @depends {{{domain}}} TRTSDT
#' @outputs {{{variable}}}
#' @code
{{{domain}}} <- {{{domain}}} |>
  dplyr::mutate(
    {{{variable}}} = admiral::compute_duration(
      start_date = TRTSDT,
      end_date = {{{date}}},
      in_unit = "days",
      out_unit = "days",
      add_one = TRUE
    )
  )

Usage in ADaM specification:

columns:
  - id: ADYDT
    component:
      id: relative_day.mustache
      with:
        domain: ADVS
        date: ADT
        variable: ADYDT

Rendered output (what mighty sees):

#' @title Analysis relative day
#' @description
#' Derives the relative day compared to the treatment start date.
#'
#' @param domain Name of ADaM domain
#' @param variable Name of new variable to create
#' @param date Name of date variable to use
#' @type column
#' @origin Derived
#' @method Number of days from TRTSDT to ADT, counting both endpoints.
#' @depends ADVS ADT
#' @depends ADVS TRTSDT
#' @outputs ADYDT
#' @code
ADVS <- ADVS |>
  dplyr::mutate(
    ADYDT = admiral::compute_duration(
      start_date = TRTSDT,
      end_date = ADT,
      in_unit = "days",
      out_unit = "days",
      add_one = TRUE
    )
  )

Example: Reusing Templates with Different Parameters

The same Mustache template can be used multiple times with different parameters:

columns:
  - id: ADYDT
    component:
      id: relative_day.mustache
      with:
        domain: ADVS
        date: ADT
        variable: ADYDT


  - id: ASTDY
    component:
      id: relative_day.mustache
      with:
        domain: ADVS
        date: ASTDT
        variable: ASTDY

For the full rules on how mighty handles component reuse in ADaM specifications — including restrictions on overlapping outputs — see Component reuse rules.

Handling external dependencies

The YAML specification contains only columns that appear in the final ADaM dataset (see No intermediate columns). Components often need source columns that are not in the final dataset — for example, an SDTM character date used to derive an analysis date.

When a component declares @depends DOMAIN COLUMN, mighty adds that column to the data-reading step of the generated program. The column is available inside the component’s code without appearing in the YAML columns section. This is the intended mechanism for accessing source data that does not belong in the final output.

For example, a component that derives ASTDT and ASTDTF from the SDTM character date LBDTC:

#' @title Convert DTC to DT
#' @description Converts DTC to date (DT) format and computes the corresponding date flag (DTF) for the ADLB dataset.
#' @type column
#' @origin Derived
#' @method Analysis start date and date flag derived from the SDTM LBDTC character date.
#' @depends LB USUBJID
#' @depends LB STUDYID
#' @depends LB LBSEQ
#' @depends LB LBDTC
#' @depends ADLB USUBJID
#' @depends ADLB STUDYID
#' @depends ADLB LBSEQ
#' @outputs ASTDT
#' @outputs ASTDTF
#' @code
ADLB <- ADLB |>
  dplyr::left_join(
    LB |>
      dplyr::mutate(
        ASTDT = admiral::convert_dtc_to_dt(
          dtc = LBDTC,
          highest_imputation = "M",
          date_imputation = "first"
        ),
        ASTDTF = admiral::compute_dtf(
          dtc = LBDTC,
          dt = ASTDT
        )
      ),
    by = c("USUBJID", "STUDYID", "LBSEQ")
  )

Mighty reads LBDTC from the source domain because the component declares @depends LB LBDTC, even though LBDTC has no entry in the YAML columns section.

This approach may cause the same source column to be joined more than once across different components. This is an accepted trade-off:

Multiple columns can share a single component. If several derived columns need the same source data, group them in one component to avoid redundant reads.
Compute time is rarely the bottleneck in ADaM programming. Mighty optimizes for development time, not compute time.
Self-contained components are easier to test and reuse independently.

Standard vs. custom components

The classification of a component as either Standard or Custom is determined only by the governance of standard components. Mighty treats all components the same. Standard components and custom components can be either .mustache files or .R files.

How mighty finds a component

Mighty looks up the id of a component in the repositories listed under repos in _mighty.yml. To use a custom component, add the directory that contains it to repos. See vignette("mighty_config") for the lookup rules.

In-built components

A small number of in-built components provide core functionality managed by mighty itself:

Data I/O operations (reading from connectors, writing outputs)
Domain initialization and filtering
Join operations based on primary keys defined in _mighty.yml external_data
Not directly referenced by users in specifications

These are automatically generated and inserted by mighty as part of the program generation process.

Code Components

Overview

Component Structure

Metadata Header

Metadata Tags

@title

@description

@param

@type

@origin

@method

@depends

@outputs

@code

R Script Components

When to Use

Code Structure

Example: Simple Column Derivation

Example: Dependent Derivation

Example: Multiple Dependencies

Mustache Template Components

When to Use

Template Syntax

Code Structure

Example: Parameterized Column Derivation

Example: Reusing Templates with Different Parameters

Handling external dependencies

Standard vs. custom components

How mighty finds a component

In-built components

`@title`

`@description`

`@param`

`@type`

`@origin`

`@method`

`@depends`

`@outputs`

`@code`