| Title: | Clinical Data Standardization Using 'YAML' Specifications |
| Version: | 0.6.2 |
| 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. |
| License: | MIT + file LICENSE |
| URL: | https://elong0527.github.io/yamaa/, https://github.com/elong0527/yamaa |
| BugReports: | https://github.com/elong0527/yamaa/issues |
| Copyright: | The yamaa contributors; for the bundled and linked third-party code and data, the holders that inst/AUTHORS lists and that inst/LICENSE-THIRD-PARTY.txt, inst/LICENSE-READSTAT.txt, inst/LICENSE-UNICODE.txt and inst/LICENSE-YAML.txt name. |
| Encoding: | UTF-8 |
| Depends: | R (≥ 4.2.0) |
| Imports: | utils |
| Suggests: | arrow (≥ 23.0.1), jsonlite (≥ 2.0.0), knitr (≥ 1.42), rmarkdown (≥ 2.20) |
| VignetteBuilder: | knitr |
| SystemRequirements: | Cargo (Rust's package manager) (>= 1.82.0), rustc (>= 1.82.0) |
| NeedsCompilation: | yes |
| Packaged: | 2026-10-26 08:45:31 UTC; runner |
| Author: | 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 <elong0527@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-17 12:00:02 UTC |
The conditions of this release and their history
Description
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.
Usage
yamaa_conditions()
Value
A data frame with one row per condition, in name order, and these columns:
conditionThe condition, as an issue's
conditioncolumn 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;
NAfor a retired condition. Messages may change in any release, so match onconditionandrule, 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", orNAfor a condition the engine may report.
Examples
catalogue <- yamaa_conditions()
nrow(catalogue)
catalogue[!is.na(catalogue$renamed_from), c("condition", "renamed_from")]
catalogue$condition[!is.na(catalogue$retired_in)]
What the engine is and where it runs
Description
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.
Usage
yamaa_info()
Value
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.
Examples
info <- yamaa_info()
info$version
info$platform
Lint yamaa files against the style guide
Description
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.
Usage
yamaa_lint(paths, fix = FALSE)
Arguments
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. |
Details
A comment # yamaa-lint: allow <finding> -- <reason> directly above a
field or an entry suppresses the named findings within it.
Value
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.
Examples
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)
A project file, read only when a method runs
Description
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.
Usage
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)
Arguments
path |
Path of a |
x |
A project, a project run, one specification's run of a project run, or a submission. |
i |
The |
... |
Unused. |
Value
An object with a read-only field and four methods:
$namesThe
domainnames 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
domainisname, with the project's codelists and functions.$check()Static findings for every listed specification, with
$statusand$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,$reportand$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,$issuesand$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: jsonordatasets: xpt, with$status,$created, the ISO 8601 creation time the documents carry (thecreatedgiven, or else the time read once for every section),$issuesand$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.
Examples
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)
Read the clinical items of an ODM XML file
Description
Reads an ODM 1.3 or 2.0 XML file, or one member of a TAR archive, into one row per clinical item.
Usage
yamaa_read_odm(source, archive_member = NULL, max_archive_members = 10000,
max_expanded_bytes = 268435456, max_xml_depth = 64)
Arguments
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. |
Value
A data frame with one row per clinical item. A refusal raises a condition of
class yamaa_error.
Examples
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)
The JSON Schema of a yamaa file type
Description
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.
Usage
yamaa_schema(file_type)
Arguments
file_type |
The file type, as a file writes it in its |
Details
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.
Value
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.
Examples
schema <- yamaa_schema("spec")
nchar(schema)
substr(schema, 1, 40)
Run the bundled selftest cases through the installed engine
Description
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.
Usage
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)
Arguments
x |
A selftest result. |
... |
Unused. |
Value
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,statusandmessage. 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 isNAwhen it passed.$infoA named list: the engine
version, thelanguage_versionsit reads, its compiledfeatures, thehost("r"), thehost_versionand theplatform.
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.
Examples
result <- yamaa_selftest()
result
result$cases
One specification, read only when a method runs
Description
Holds the path of one specification. Nothing is read until a method runs, and each method rereads the files.
Usage
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)
Arguments
path |
Path of a specification file. |
x |
A specification, a check or a run. |
... |
Unused. |
Value
An object with three methods:
$check(parent = NULL)A check:
$statusis"failed"when the check found a problem, and"succeeded"otherwise, and the$issuesdata frame lists the problems found without reading study data or running project code. Withparent, the path of another specification, the specification is checked as a fragment whose parent isparent, as it would compose in a file that namesparentas itsparent, includes the fragment and writes nothing else; a specification that declaresparentorincludeis no fragment, and the call fails with ayamaa_errorcondition.$resolve()The specification after its layers are composed, as a named list.
$run()A run:
$statusis"succeeded"when the run built its dataset with no issue, and"failed"otherwise,$outputis the dataset (NULLwhen the run failed),$issueswhat is wrong,$reportwhat 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:$outputis an Arrow C stream, an external pointer of classnanoarrow_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.
Examples
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)