| Title: | Clinical Data Standardization Using 'YAML' Specifications |
|---|---|
| Description: | Builds standardized clinical trial datasets using 'YAML' specifications. Supports the Study Data Tabulation Model (SDTM) and Analysis Data Model (ADaM), with specification checks, data derivations, and structured diagnostics. Generates submission metadata in 'Define-XML' format. |
| Authors: | Yilong Zhang [aut, cre, cph], Ming-Chun Chen [ctb], Peng Zhang [ctb], Bingjun Wang [ctb], Jingwei Xiong [ctb], The authors of the bundled Rust crates [ctb, cph] (listed in inst/AUTHORS), Evan Miller and the ReadStat authors [ctb, cph] (bundled ReadStat C sources, inst/LICENSE-READSTAT.txt) |
| Maintainer: | Yilong Zhang <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.6.2 |
| Built: | 2026-11-17 15:41:59 UTC |
| Source: | https://github.com/cran/yamaa |
Returns the condition catalogue: every condition the engine may report in an
issue, and every condition a release retired, with what a program needs to
match it. The catalogue is part of the installed engine, so nothing is read
from disk, and the same table comes from every host. The file
yaml/conditions.yaml of the source repository at a release's tag holds
the same catalogue.
yamaa_conditions()yamaa_conditions()
A data frame with one row per condition, in name order, and these columns:
conditionThe condition, as an issue's condition
column names it.
severityThe severity of its issues: "error" for every
condition.
phasesA list column: the phases that may report the condition, as a character vector; empty for a retired condition.
rulesA list column: the rule cards that its issues cite, such
as "VALUE-3", in card order; empty for a condition whose issues
cite no rule and for a retired condition.
messageThe template its issues' messages are written from;
NA for a retired condition. Messages may change in any release,
so match on condition and rule, never on the message.
renamed_fromThe name the condition had before a release
renamed it, or NA.
retired_inThe release that retired the condition, such as
"1.0.0", or NA for a condition the engine may report.
catalogue <- yamaa_conditions() nrow(catalogue) catalogue[!is.na(catalogue$renamed_from), c("condition", "renamed_from")] catalogue$condition[!is.na(catalogue$retired_in)]catalogue <- yamaa_conditions() nrow(catalogue) catalogue[!is.na(catalogue$renamed_from), c("condition", "renamed_from")] catalogue$condition[!is.na(catalogue$retired_in)]
Returns the facts that identify the installed engine: its version, the
language versions it reads, the features it was built with, the host and the
platform. A selftest's info holds the same record, and the command line
prints it for yamaa --version. It reads and writes no file.
yamaa_info()yamaa_info()
A named list, in this order:
versionThe engine version, the same in every host; a release
candidate reads like "1.0.0-rc.1".
language_versionsEvery yamaa: language version the
engine reads, oldest first.
featuresThe optional features the engine was built with,
sorted, among "odm", "parquet", "readstat" and
"yaml"; every released package has all four.
host"r".
host_versionThe version of R, as getRversion() gives
it.
platformThe operating system and architecture of the engine,
such as "linux-x86_64".
packageVersion("yamaa") stays the version of the package, which keeps
1.0.0 while the release candidates carry their own engine version.
info <- yamaa_info() info$version info$platforminfo <- yamaa_info() info$version info$platform
Reports how each yamaa file departs from the written form the yamaa style guide fixes: field order, blank lines, line width, the canonical spellings of a 1.0 file and the authoring findings. A finding describes the text, never its meaning, and a file runs as its canonical form does.
yamaa_lint(paths, fix = FALSE)yamaa_lint(paths, fix = FALSE)
paths |
Paths of yamaa files. A directory names the yamaa files of every file type beneath it, outside hidden directories. |
fix |
Whether to apply the proved fixes first. A file is replaced only when the fixed text reads as the same values with the same comments, or as those values with exactly the canonical rewrite a finding names. |
A comment # yamaa-lint: allow <finding> -- <reason> directly above a
field or an entry suppresses the named findings within it.
A data frame with one row per finding that remains and the columns
file (the absolute path, with forward slashes), line,
column, finding, spec_path and message. A file
that cannot be read or parsed, or a directory that cannot be listed, raises a
condition of class yamaa_error, and nothing is written.
study <- tempfile("yamaa-") dir.create(study) spec <- file.path(study, "dm.yaml") writeLines('yamaa: "1.0" type: spec domain: DM input: {RAW: {path: input.csv, types: {USUBJID: str, AGE: int}}} keys: [USUBJID] columns: - {name: USUBJID, type: str, derivation: RAW.USUBJID} - {name: AGE, type: int, derivation: RAW.AGE} output: {path: dm.csv, columns: [USUBJID, AGE]} ', spec) findings <- yamaa_lint(study) findings[, c("line", "finding", "message")] remaining <- yamaa_lint(spec, fix = TRUE) remaining[, c("line", "finding", "message")] unlink(study, recursive = TRUE)study <- tempfile("yamaa-") dir.create(study) spec <- file.path(study, "dm.yaml") writeLines('yamaa: "1.0" type: spec domain: DM input: {RAW: {path: input.csv, types: {USUBJID: str, AGE: int}}} keys: [USUBJID] columns: - {name: USUBJID, type: str, derivation: RAW.USUBJID} - {name: AGE, type: int, derivation: RAW.AGE} output: {path: dm.csv, columns: [USUBJID, AGE]} ', spec) findings <- yamaa_lint(study) findings[, c("line", "finding", "message")] remaining <- yamaa_lint(spec, fix = TRUE) remaining[, c("line", "finding", "message")] unlink(study, recursive = TRUE)
Holds the path of a project.yaml: the study's specifications, codelists,
submission metadata, function files and per-language locks. Nothing is read
until a method runs.
yamaa_project(path) ## S3 method for class 'yamaa_project_run' x[[i, ...]] ## S3 method for class 'yamaa_project' print(x, ...) ## S3 method for class 'yamaa_project' format(x, ...) ## S3 method for class 'yamaa_project_run' print(x, ...) ## S3 method for class 'yamaa_project_run' format(x, ...) ## S3 method for class 'yamaa_project_run' names(x) ## S3 method for class 'yamaa_project_run' length(x) ## S3 method for class 'yamaa_member_run' print(x, ...) ## S3 method for class 'yamaa_member_run' format(x, ...) ## S3 method for class 'yamaa_member_run' names(x) ## S3 method for class 'yamaa_member_run' length(x) ## S3 method for class 'yamaa_submission' print(x, ...) ## S3 method for class 'yamaa_submission' format(x, ...) ## S3 method for class 'yamaa_submission' names(x) ## S3 method for class 'yamaa_submission' length(x)yamaa_project(path) ## S3 method for class 'yamaa_project_run' x[[i, ...]] ## S3 method for class 'yamaa_project' print(x, ...) ## S3 method for class 'yamaa_project' format(x, ...) ## S3 method for class 'yamaa_project_run' print(x, ...) ## S3 method for class 'yamaa_project_run' format(x, ...) ## S3 method for class 'yamaa_project_run' names(x) ## S3 method for class 'yamaa_project_run' length(x) ## S3 method for class 'yamaa_member_run' print(x, ...) ## S3 method for class 'yamaa_member_run' format(x, ...) ## S3 method for class 'yamaa_member_run' names(x) ## S3 method for class 'yamaa_member_run' length(x) ## S3 method for class 'yamaa_submission' print(x, ...) ## S3 method for class 'yamaa_submission' format(x, ...) ## S3 method for class 'yamaa_submission' names(x) ## S3 method for class 'yamaa_submission' length(x)
path |
Path of a |
x |
A project, a project run, one specification's run of a project run, or a submission. |
i |
The |
... |
Unused. |
An object with a read-only field and four methods:
$namesThe domain names of the listed specifications,
in the order that a run of every section builds them, each after the ones
it reads from, read without study data. A project file that cannot be read,
or that lists a name twice, raises.
$spec(name)The listed specification whose domain is
name, with the project's codelists and functions.
$check()Static findings for every listed specification, with
$status and $issues.
$run(section = NULL)Builds every specification of one section
("sdtm", "adam" or "send"), or of all sections. The
project run has $status, "succeeded" when every
specification succeeded, $names, $issues, $report and
$save(), which writes each declared report file and then each output
dataset in run order, only the reports when a specification failed;
runs[["ADSL"]] is one specification's run, with $status,
$output, $issues and $report. Its status is
"skipped" when a specification that it reads from did not
complete.
$submission(section = NULL, created = NULL)define.xml, and
a Dataset-JSON or SAS Transport version 5 file per dataset where a section
sets datasets: json or datasets: xpt, with $status,
$created, the ISO 8601 creation time the documents carry (the
created given, or else the time read once for every section),
$issues and $save(), which writes each section's transport
files and then its define.xml.
$check(), $run() and $submission() also take
progress, a function called with one named list per event, as
yamaa_spec describes: each specification of a check or run is
named by its domain, and each section of a submission is one
"composition" phase. A progress function that signals an error
is called no more: the call checks, builds or composes nothing further, and
its result fails with one engine_rejected issue whose code is
host_progress_failure and refuses its save. A check, a project run,
one specification's run and a submission hold $timings, a data frame
of each phase the call ran; no saved file holds them.
Each $save() returns the absolute paths it wrote invisibly, in
publication order. A failure raises a condition of class yamaa_error
whose issues data frame says why; for a refused $save(), its
paths lists the files written before the refusal.
format() returns the lines that the engine renders for an object, the
same words that Python and the command line print, and print() writes
them and returns the object invisibly. A project prints
yamaa project <path>, since it has read nothing. A project run prints
its status, its number of specifications and its issue count, then one line
per specification with its status, size and issue count, then its first
issue; one specification's run prints as a run does. A submission prints its
status, its define.xml and transport files and its issue count.
names() of a project run gives the names of its specifications, as
$names does, and length() counts them. names() of one
specification's run or of a submission lists its fields and methods in the
order above, starting with status, and length() counts them;
ls() lists the same names, sorted.
study <- tempfile("yamaa-") dir.create(study) writeLines(c("USUBJID,AGE", "01,35", "02,42"), file.path(study, "input.csv")) writeLines('yamaa: "1.0" type: spec model: SDTM domain: DM keys: [USUBJID] input: {RAW: {path: input.csv, types: {USUBJID: str, AGE: int}}} output: {path: dm.csv, columns: [USUBJID, AGE]} columns: - {name: USUBJID, type: str, derivation: RAW.USUBJID} - {name: AGE, type: int, derivation: RAW.AGE} ', file.path(study, "dm.yaml")) writeLines('yamaa: "1.0" type: project sdtm: {specs: [dm.yaml]} ', file.path(study, "project.yaml")) project <- yamaa_project(file.path(study, "project.yaml")) project$names project$check() runs <- project$run("sdtm") runs runs[["DM"]]$output basename(runs$save()) unlink(study, recursive = TRUE)study <- tempfile("yamaa-") dir.create(study) writeLines(c("USUBJID,AGE", "01,35", "02,42"), file.path(study, "input.csv")) writeLines('yamaa: "1.0" type: spec model: SDTM domain: DM keys: [USUBJID] input: {RAW: {path: input.csv, types: {USUBJID: str, AGE: int}}} output: {path: dm.csv, columns: [USUBJID, AGE]} columns: - {name: USUBJID, type: str, derivation: RAW.USUBJID} - {name: AGE, type: int, derivation: RAW.AGE} ', file.path(study, "dm.yaml")) writeLines('yamaa: "1.0" type: project sdtm: {specs: [dm.yaml]} ', file.path(study, "project.yaml")) project <- yamaa_project(file.path(study, "project.yaml")) project$names project$check() runs <- project$run("sdtm") runs runs[["DM"]]$output basename(runs$save()) unlink(study, recursive = TRUE)
Reads an ODM 1.3 or 2.0 XML file, or one member of a TAR archive, into one row per clinical item.
yamaa_read_odm(source, archive_member = NULL, max_archive_members = 10000, max_expanded_bytes = 268435456, max_xml_depth = 64)yamaa_read_odm(source, archive_member = NULL, max_archive_members = 10000, max_expanded_bytes = 268435456, max_xml_depth = 64)
source |
Path of an ODM XML file or TAR archive. |
archive_member |
Name of the XML member to read from a TAR, or
|
max_archive_members |
Most members a TAR may hold. |
max_expanded_bytes |
Most bytes the input may expand to. |
max_xml_depth |
Deepest element nesting accepted. |
A data frame with one row per clinical item. A refusal raises a condition of
class yamaa_error.
odm <- tempfile(fileext = ".xml") writeLines('<?xml version="1.0" encoding="UTF-8"?> <ODM xmlns="http://www.cdisc.org/ns/odm/v1.3" ODMVersion="1.3" FileOID="F.1"> <ClinicalData StudyOID="S.1" MetaDataVersionOID="M.1"> <SubjectData SubjectKey="01"> <StudyEventData StudyEventOID="SE.SCREEN"> <FormData FormOID="F.DM"> <ItemGroupData ItemGroupOID="IG.DM"> <ItemData ItemOID="IT.DM.AGE" Value="35"/> <ItemData ItemOID="IT.DM.SEX" Value="F"/> </ItemGroupData> </FormData> </StudyEventData> </SubjectData> </ClinicalData> </ODM> ', odm) items <- yamaa_read_odm(odm) items[, c("SubjectKey", "ItemOID", "Value")] unlink(odm)odm <- tempfile(fileext = ".xml") writeLines('<?xml version="1.0" encoding="UTF-8"?> <ODM xmlns="http://www.cdisc.org/ns/odm/v1.3" ODMVersion="1.3" FileOID="F.1"> <ClinicalData StudyOID="S.1" MetaDataVersionOID="M.1"> <SubjectData SubjectKey="01"> <StudyEventData StudyEventOID="SE.SCREEN"> <FormData FormOID="F.DM"> <ItemGroupData ItemGroupOID="IG.DM"> <ItemData ItemOID="IT.DM.AGE" Value="35"/> <ItemData ItemOID="IT.DM.SEX" Value="F"/> </ItemGroupData> </FormData> </StudyEventData> </SubjectData> </ClinicalData> </ODM> ', odm) items <- yamaa_read_odm(odm) items[, c("SubjectKey", "ItemOID", "Value")] unlink(odm)
Returns the JSON Schema that a file of one type is checked against, so that an editor can validate and complete the file as it is typed. The schema is part of the installed engine, so nothing is read from disk, and the same text comes from every host.
yamaa_schema(file_type)yamaa_schema(file_type)
file_type |
The file type, as a file writes it in its |
A specification file may be one layer of an inheritance chain, so the
"spec" schema checks what one layer may write, and its
$defs/root_class checks a complete specification. Every field carries
its kind as x-yamaa-kind and its schema-notation type as
x-yamaa-type.
One character string: the JSON Schema as canonical JSON text, on one line with
its members in key order. Any other file type raises a condition of class
yamaa_error whose issue names the condition
unexpected_file_type.
schema <- yamaa_schema("spec") nchar(schema) substr(schema, 1, 40)schema <- yamaa_schema("spec") nchar(schema) substr(schema, 1, 40)
Runs the selftest cases that the package carries, benchmarks with their independently authored expected files, through the installed engine and compares each result with its expected files. It reads and writes no file and uses no network. Its report is the installation and operational qualification evidence of an installation.
yamaa_selftest() ## S3 method for class 'yamaa_selftest' print(x, ...) ## S3 method for class 'yamaa_selftest' format(x, ...) ## S3 method for class 'yamaa_selftest' names(x) ## S3 method for class 'yamaa_selftest' length(x)yamaa_selftest() ## S3 method for class 'yamaa_selftest' print(x, ...) ## S3 method for class 'yamaa_selftest' format(x, ...) ## S3 method for class 'yamaa_selftest' names(x) ## S3 method for class 'yamaa_selftest' length(x)
x |
A selftest result. |
... |
Unused. |
An object with three read-only fields:
$status"failed" when a case failed, and
"succeeded" otherwise.
$casesA data frame with one row per case and the columns
case, status and message. A case's status is
"succeeded", "failed", or "skipped" when this build
does not compile a feature the case needs; its message says why it
failed or was skipped, and is NA when it passed.
$infoA named list: the engine version, the
language_versions it reads, its compiled features, the
host ("r"), the host_version and the
platform.
format() returns the lines of the report, and print() writes
them and returns the result invisibly. The first line reads
yamaa selftest: <status>, <p> of <c> cases passed. The first failed
case and the adapters that no case covered follow, then the engine version,
the language versions, the host and the platform. names() lists the
three fields in that order, and length() counts them.
result <- yamaa_selftest() result result$casesresult <- yamaa_selftest() result result$cases
Holds the path of one specification. Nothing is read until a method runs, and each method rereads the files.
yamaa_spec(path) ## S3 method for class 'yamaa_spec' print(x, ...) ## S3 method for class 'yamaa_spec' format(x, ...) ## S3 method for class 'yamaa_check' print(x, ...) ## S3 method for class 'yamaa_check' format(x, ...) ## S3 method for class 'yamaa_check' names(x) ## S3 method for class 'yamaa_check' length(x) ## S3 method for class 'yamaa_run' print(x, ...) ## S3 method for class 'yamaa_run' format(x, ...) ## S3 method for class 'yamaa_run' names(x) ## S3 method for class 'yamaa_run' length(x)yamaa_spec(path) ## S3 method for class 'yamaa_spec' print(x, ...) ## S3 method for class 'yamaa_spec' format(x, ...) ## S3 method for class 'yamaa_check' print(x, ...) ## S3 method for class 'yamaa_check' format(x, ...) ## S3 method for class 'yamaa_check' names(x) ## S3 method for class 'yamaa_check' length(x) ## S3 method for class 'yamaa_run' print(x, ...) ## S3 method for class 'yamaa_run' format(x, ...) ## S3 method for class 'yamaa_run' names(x) ## S3 method for class 'yamaa_run' length(x)
path |
Path of a specification file. |
x |
A specification, a check or a run. |
... |
Unused. |
An object with three methods:
$check(parent = NULL)A check: $status is
"failed" when the check found a problem, and "succeeded"
otherwise, and the $issues data frame lists the problems found
without reading study data or running project code. With parent,
the path of another specification, the specification is checked as a
fragment whose parent is parent, as it would compose in a file
that names parent as its parent, includes the fragment and
writes nothing else; a specification that declares parent or
include is no fragment, and the call fails with a
yamaa_error condition.
$resolve()The specification after its layers are composed, as a named list.
$run()A run: $status is "succeeded" when the run
built its dataset with no issue, and "failed" otherwise,
$output is the dataset (NULL when the run failed),
$issues what is wrong, $report what the run read, counted
and checked, and $save() writes the declared report file, then the
output dataset, and returns their absolute paths invisibly, in that order.
A failed run writes only its report file.
$run(stream = TRUE) builds the dataset as its output is read, and
reads nothing until then: $output is an Arrow C stream, an
external pointer of class nanoarrow_array_stream, which nanoarrow
and arrow read, one batch per pull; the first pull builds the run. The
other fields give the run once its stream has ended, and run it whole
when nothing has read the output, whose stream then reads the dataset it
keeps. Releasing the stream before its last batch cancels the run, which
then saves nothing.
$check() and $run() also take progress, a function
called on the calling thread with one named list per event as each phase
starts and ends: name, phase, kind ("start",
"end", "partition" or "batch"), outcome,
number and rows, the last three NULL where the event has
none. A progress function that signals an error is called no more,
and the check or run then fails with one engine_rejected issue whose
code is host_progress_failure; such a run saves nothing. A check and
a run hold $timings, a data frame of each phase the call ran, with the
columns name, phase, started_ms, elapsed_ms and
outcome; no saved file holds them.
A failure raises a condition of class yamaa_error whose issues
data frame says why; for a refused $save(), its paths lists
the files written before the refusal.
format() returns the lines that the engine renders for an object, the
same words that Python and the command line print, and print() writes
them and returns the object invisibly. A specification prints
yamaa spec <path>, with the path as given, since it has read nothing.
A check prints yamaa check of <path>: <status>, <n> issues, and a run
yamaa run of <dataset>: <status>, <size>, <n> issues, where the size
is <r> rows x <c> columns or no output; either then prints its
first issue on a line of its own.
names() of a check or a run lists its fields and methods in the order
above, starting with status, and length() counts them;
ls() lists the same names, sorted.
study <- tempfile("yamaa-") dir.create(study) writeLines(c("USUBJID,AGE", "01,35", "02,42"), file.path(study, "input.csv")) writeLines('yamaa: "1.0" type: spec domain: DM keys: [USUBJID] input: {RAW: {path: input.csv, types: {USUBJID: str, AGE: int}}} output: {path: dm.csv, columns: [USUBJID, AGE]} columns: - {name: USUBJID, type: str, derivation: RAW.USUBJID} - {name: AGE, type: int, derivation: RAW.AGE} ', file.path(study, "dm.yaml")) spec <- yamaa_spec(file.path(study, "dm.yaml")) spec$check() run <- spec$run() run run$output basename(run$save()) unlink(study, recursive = TRUE)study <- tempfile("yamaa-") dir.create(study) writeLines(c("USUBJID,AGE", "01,35", "02,42"), file.path(study, "input.csv")) writeLines('yamaa: "1.0" type: spec domain: DM keys: [USUBJID] input: {RAW: {path: input.csv, types: {USUBJID: str, AGE: int}}} output: {path: dm.csv, columns: [USUBJID, AGE]} columns: - {name: USUBJID, type: str, derivation: RAW.USUBJID} - {name: AGE, type: int, derivation: RAW.AGE} ', file.path(study, "dm.yaml")) spec <- yamaa_spec(file.path(study, "dm.yaml")) spec$check() run <- spec$run() run run$output basename(run$save()) unlink(study, recursive = TRUE)