Describe Observed and Averaged Values Apart

Review ask

As a clinical trial statistician or programmer, answer two short questions in Your review: the task and the inputs and outputs. Agreeing with both approves this benchmark; disagreeing with either needs a comment. Propose a fix with the Edit button on any source file, or add it to your comments.

We suggest spending no more than 5 minutes on a review. The other tabs beside Your review are background for assessment, not under review.

Summary

EditUnder reviewWhat this benchmark means

README.md

Public entries: Python and R. Passing coverage requires an installed inventory.

Goal: build the analysis values of systolic blood pressure, AVAL, at each visit and as each subject's average, with PARAMCD, AVISIT and DTYPE, and give the observed and the averaged values their own definitions in the data-definition document.

Input: spec.yaml reads the subjects' systolic blood pressure, one row per subject per visit, and project.yaml submits the analysis dataset.

Variables:

PARAMCD is SYSBP, systolic blood pressure.
AVISIT is the visit of an observed value, and OVERALL for an average.
DTYPE is AVERAGE on a subject's average, and empty on an observed value.
AVAL is the observed value, or the mean of the subject's observed values over all visits.

Note: the data-definition document describes AVAL twice: once for the rows whose DTYPE is anything but AVERAGE, which takes in the observed rows, where it is empty, copied from the collected value; and once for the averaged rows, derived by the mean. The two descriptions select no common row.

YAML specification

1 spec file

spec.yaml

Edit121 lines

1yamaa: "1.0"23type: spec45model: ADaM6domain: ADVS7keys: [STUDYID, USUBJID, PARAMCD, AVISIT]8input:9  VS:10    path: input/vs.csv11    types: {VSSTRESN: float}1213output:14  path: advs.csv15  columns: [STUDYID, USUBJID, PARAMCD, AVISIT, DTYPE, AVAL]1617columns:18  - name: STUDYID19    type: str20    label: Study Identifier21    derivation: VS.STUDYID22    submission:23      core: Req24      mandatory: true25      length: 426      origins:27        - type: Predecessor28          description: VS.STUDYID2930  - name: USUBJID31    type: str32    label: Unique Subject Identifier33    derivation: VS.USUBJID34    submission:35      core: Req36      mandatory: true37      length: 838      origins:39        - type: Predecessor40          description: VS.USUBJID4142  - name: PARAMCD43    type: str44    label: Parameter Code45    derivation: "'SYSBP'"46    submission:47      core: Req48      mandatory: true49      length: 550      origins:51        - type: Assigned5253  - name: AVISIT54    type: str55    label: Analysis Visit56    submission:57      core: Cond58      mandatory: true59      length: 760      origins:61        - type: Assigned6263  - name: DTYPE64    type: str65    label: Derivation Type66    submission:67      core: Cond68      mandatory: false69      length: 770      origins:71        - type: Assigned7273  # An observed value has no derivation type, so only NE can select its74  # rows apart from the averages.75  - name: AVAL76    type: float77    label: Analysis Value78    submission:79      core: Cond80      mandatory: true81      length: 882      significant_digits: 183      origins:84        - type: Other85          description: Observed or averaged, as each86            value-level definition states87      value_level:88        - id: OBSERVED89          where: {DTYPE: {comparator: NE, values: [AVERAGE]}}90          origins:91            - type: Predecessor92              description: VS.VSSTRESN93        - id: AVERAGE94          where: {DTYPE: [AVERAGE]}95          origins:96            - type: Derived97          method: Mean of the subject's observed values over all visits9899# Each observed value, then one average per subject.100rows:101  - id: observed102    dataset: VS103    derivations:104      AVISIT: VS.VISIT105      DTYPE: null106      AVAL: VS.VSSTRESN107108  - id: average109    dataset: VS110    group_by: [VS.STUDYID, VS.USUBJID]111    derivations:112      AVISIT: "'OVERALL'"113      DTYPE: "'AVERAGE'"114      AVAL:115        aggregate: "MEAN(VS.VSSTRESN)"116117submission:118  label: Vital Signs Analysis Dataset119  class: BASIC DATA STRUCTURE120  structure: One record per subject per parameter per analysis visit121  repeating: true

Inputs

Under review1 source file

input/vs.csv

Edit4 rows

input/vs.csv
STUDYID	VSTESTCD	VISIT	VSSTRESN
BP01	SYSBP	WEEK 1	128
BP01	SYSBP	WEEK 2	124
BP01	SYSBP	WEEK 1	141
BP01	SYSBP	WEEK 2	137

Expected output

Under review6 expected rows

expected/advs.csv

Edit6 rows

expected/advs.csv
STUDYID	PARAMCD	AVISIT	DTYPE	AVAL
BP01	SYSBP	WEEK 1	—	128
BP01	SYSBP	WEEK 2	—	124
BP01	SYSBP	WEEK 1	—	141
BP01	SYSBP	WEEK 2	—	137
BP01	SYSBP	OVERALL	AVERAGE	126
BP01	SYSBP	OVERALL	AVERAGE	139

expected/define.xml

EditDefine-XML

Define-XML 2.1.11: BP01

Example study averaging each subject's blood pressure; BP-01; ADaMIG 1.3

Datasets
Dataset	Description	Class	Structure	Purpose	Keys	Documentation	Location
ADVS	Vital Signs Analysis Dataset	BASIC DATA STRUCTURE	One record per subject per parameter per analysis visit	Analysis	STUDYID, USUBJID, PARAMCD, AVISIT		advs.csv

ADVS

ADVS variables
Variable	Label / Description	Type	Length or Display Format	Origin / Source / Method / Comment
STUDYID	Study Identifier	text	4	Predecessor; VS.STUDYID
USUBJID	Unique Subject Identifier	text	8	Predecessor; VS.USUBJID
PARAMCD	Parameter Code	text	5	Assigned; Sponsor
AVISIT	Analysis Visit	text	7	Assigned; Sponsor
DTYPE	Derivation Type	text	7	Assigned; Sponsor
AVAL	Analysis Value	float	8	Other; Sponsor; Observed or averaged, as each value-level definition states

ADVS.AVAL value-level metadata
Where Condition	Variable	Label / Description	Type	Length or Display Format	Controlled Terms or ISO Format	Origin / Source / Method / Comment
DTYPE != AVERAGE	AVAL	Analysis Value	float	8		Predecessor; VS.VSSTRESN
DTYPE = AVERAGE	AVAL	Analysis Value	float	8		Derived; Sponsor Mean of the subject's observed values over all visits

Original source

<?xml version="1.0" encoding="UTF-8"?>
<ODM xmlns="http://www.cdisc.org/ns/odm/v1.3" xmlns:def="http://www.cdisc.org/ns/def/v2.1" xmlns:xlink="http://www.w3.org/1999/xlink" ODMVersion="1.3.2" FileType="Snapshot" FileOID="BP01.adam.Define-XML_2.1" CreationDateTime="2026-09-11T00:00:00" SourceSystem="yamaa" SourceSystemVersion="1.0" def:Context="Other">
  <Study OID="STDY.BP01">
    <GlobalVariables>
      <StudyName>BP01</StudyName>
      <StudyDescription>Example study averaging each subject's blood pressure</StudyDescription>
      <ProtocolName>BP-01</ProtocolName>
    </GlobalVariables>
    <MetaDataVersion OID="MDV.BP01.adam" Name="BP01 adam metadata" def:DefineVersion="2.1.11">
      <def:Standards>
        <def:Standard OID="STD.ADaMIG" Name="ADaMIG" Type="IG" Version="1.3" Status="Final"/>
      </def:Standards>
      <def:ValueListDef OID="VL.ADVS.AVAL">
        <ItemRef ItemOID="IT.ADVS.AVAL.OBSERVED" OrderNumber="1" Mandatory="Yes">
          <def:WhereClauseRef WhereClauseOID="WC.ADVS.AVAL.OBSERVED"/>
        </ItemRef>
        <ItemRef ItemOID="IT.ADVS.AVAL.AVERAGE" OrderNumber="2" Mandatory="Yes" MethodOID="MT.ADVS.AVAL.AVERAGE">
          <def:WhereClauseRef WhereClauseOID="WC.ADVS.AVAL.AVERAGE"/>
        </ItemRef>
      </def:ValueListDef>
      <def:WhereClauseDef OID="WC.ADVS.AVAL.OBSERVED">
        <RangeCheck Comparator="NE" SoftHard="Soft" def:ItemOID="IT.ADVS.DTYPE">
          <CheckValue>AVERAGE</CheckValue>
        </RangeCheck>
      </def:WhereClauseDef>
      <def:WhereClauseDef OID="WC.ADVS.AVAL.AVERAGE">
        <RangeCheck Comparator="EQ" SoftHard="Soft" def:ItemOID="IT.ADVS.DTYPE">
          <CheckValue>AVERAGE</CheckValue>
        </RangeCheck>
      </def:WhereClauseDef>
      <ItemGroupDef OID="IG.ADVS" Name="ADVS" Purpose="Analysis" SASDatasetName="ADVS" Repeating="Yes" IsReferenceData="No" def:Structure="One record per subject per parameter per analysis visit" def:ArchiveLocationID="LF.ADVS" def:StandardOID="STD.ADaMIG">
        <Description>
          <TranslatedText xml:lang="en">Vital Signs Analysis Dataset</TranslatedText>
        </Description>
        <ItemRef ItemOID="IT.ADVS.STUDYID" OrderNumber="1" Mandatory="Yes" KeySequence="1"/>
        <ItemRef ItemOID="IT.ADVS.USUBJID" OrderNumber="2" Mandatory="Yes" KeySequence="2"/>
        <ItemRef ItemOID="IT.ADVS.PARAMCD" OrderNumber="3" Mandatory="Yes" KeySequence="3"/>
        <ItemRef ItemOID="IT.ADVS.AVISIT" OrderNumber="4" Mandatory="Yes" KeySequence="4"/>
        <ItemRef ItemOID="IT.ADVS.DTYPE" OrderNumber="5" Mandatory="No"/>
        <ItemRef ItemOID="IT.ADVS.AVAL" OrderNumber="6" Mandatory="Yes"/>
        <def:Class Name="BASIC DATA STRUCTURE"/>
        <def:leaf ID="LF.ADVS" xlink:href="advs.csv">
          <def:title>advs.csv</def:title>
        </def:leaf>
      </ItemGroupDef>
      <ItemDef OID="IT.ADVS.STUDYID" Name="STUDYID" DataType="text" Length="4" SASFieldName="STUDYID">
        <Description>
          <TranslatedText xml:lang="en">Study Identifier</TranslatedText>
        </Description>
        <def:Origin Type="Predecessor">
          <Description>
            <TranslatedText xml:lang="en">VS.STUDYID</TranslatedText>
          </Description>
        </def:Origin>
      </ItemDef>
      <ItemDef OID="IT.ADVS.USUBJID" Name="USUBJID" DataType="text" Length="8" SASFieldName="USUBJID">
        <Description>
          <TranslatedText xml:lang="en">Unique Subject Identifier</TranslatedText>
        </Description>
        <def:Origin Type="Predecessor">
          <Description>
            <TranslatedText xml:lang="en">VS.USUBJID</TranslatedText>
          </Description>
        </def:Origin>
      </ItemDef>
      <ItemDef OID="IT.ADVS.PARAMCD" Name="PARAMCD" DataType="text" Length="5" SASFieldName="PARAMCD">
        <Description>
          <TranslatedText xml:lang="en">Parameter Code</TranslatedText>
        </Description>
        <def:Origin Type="Assigned" Source="Sponsor"/>
      </ItemDef>
      <ItemDef OID="IT.ADVS.AVISIT" Name="AVISIT" DataType="text" Length="7" SASFieldName="AVISIT">
        <Description>
          <TranslatedText xml:lang="en">Analysis Visit</TranslatedText>
        </Description>
        <def:Origin Type="Assigned" Source="Sponsor"/>
      </ItemDef>
      <ItemDef OID="IT.ADVS.DTYPE" Name="DTYPE" DataType="text" Length="7" SASFieldName="DTYPE">
        <Description>
          <TranslatedText xml:lang="en">Derivation Type</TranslatedText>
        </Description>
        <def:Origin Type="Assigned" Source="Sponsor"/>
      </ItemDef>
      <ItemDef OID="IT.ADVS.AVAL" Name="AVAL" DataType="float" Length="8" SignificantDigits="1" SASFieldName="AVAL">
        <Description>
          <TranslatedText xml:lang="en">Analysis Value</TranslatedText>
        </Description>
        <def:Origin Type="Other" Source="Sponsor">
          <Description>
            <TranslatedText xml:lang="en">Observed or averaged, as each value-level definition states</TranslatedText>
          </Description>
        </def:Origin>
        <def:ValueListRef ValueListOID="VL.ADVS.AVAL"/>
      </ItemDef>
      <ItemDef OID="IT.ADVS.AVAL.OBSERVED" Name="AVAL" DataType="float" Length="8" SignificantDigits="1" SASFieldName="AVAL">
        <Description>
          <TranslatedText xml:lang="en">Analysis Value</TranslatedText>
        </Description>
        <def:Origin Type="Predecessor">
          <Description>
            <TranslatedText xml:lang="en">VS.VSSTRESN</TranslatedText>
          </Description>
        </def:Origin>
      </ItemDef>
      <ItemDef OID="IT.ADVS.AVAL.AVERAGE" Name="AVAL" DataType="float" Length="8" SignificantDigits="1" SASFieldName="AVAL">
        <Description>
          <TranslatedText xml:lang="en">Analysis Value</TranslatedText>
        </Description>
        <def:Origin Type="Derived" Source="Sponsor"/>
      </ItemDef>
      <MethodDef OID="MT.ADVS.AVAL.AVERAGE" Name="ADVS.AVAL.AVERAGE" Type="Computation">
        <Description>
          <TranslatedText xml:lang="en">Mean of the subject's observed values over all visits</TranslatedText>
        </Description>
      </MethodDef>
    </MetaDataVersion>
  </Study>
</ODM>

Shaded columns are derived— = missing value

Human review and assessment

Dataset Name	Variable Name	Variable Label	Type	Core	Computational Method	Origin
ADVS	STUDYID	Study Identifier	character	Req	Copy value from VS.STUDYID.	Predecessor
ADVS	USUBJID	Unique Subject Identifier	character	Req	Copy value from VS.USUBJID.	Predecessor
ADVS	PARAMCD	Parameter Code	character	Req	Set constant value "SYSBP".	Assigned
ADVS	AVISIT	Analysis Visit	character	Cond	Set per constructed row; see the Row construction sheet.	Assigned
ADVS	DTYPE	Derivation Type	character	Cond	Set per constructed row; see the Row construction sheet.	Assigned
ADVS	AVAL	Analysis Value	numeric	Cond	Set per constructed row; see the Row construction sheet.	Other

Template	Include when	AVISIT	DTYPE	AVAL
observed		Copy VS.VISIT	Constant "None"	Copy VS.VSSTRESN
average		Constant "OVERALL"	Constant "AVERAGE"	Aggregate MEAN(VS.VSSTRESN) over records matching on the shared output keys

Version	Date	Author	Description
1.7	2026-10-20	yamaa docs build	Read a specification in the 1.0 surface as its 0.5 counterpart; state that missing values stay missing where a mapping declares no missing handler, and leave out a declared missing answer that restates a handler's default
1.6	2026-10-17	yamaa docs build	Describe collected date parts written as ISO 8601 date text and times of day counted in seconds since midnight
1.5	2026-10-17	yamaa docs build	Name collected precision in words instead of letter codes; state imputation fallbacks, minimum source precision, bounds ignored outside the collected period, and invalid text with no handler as an error; describe date and datetime shifts, imputation flag codes, and partial text giving no date part
1.4	2026-10-15	yamaa docs build	State datetime precision codes through the hour and minute, and complete only the time parts a collected datetime lacks
1.3	2026-09-29	yamaa docs build	Show study codelist names, external dictionaries, and ISO 8601 formats in variable rows; list the document's codelist values and metadata
1.2	2026-09-29	yamaa docs build	Classify ADaM copies from a declared input as Predecessor and recodes as Derived, and SDTM recodes of locally derived columns as Derived
1.1	2026-09-29	yamaa docs build	Resolve lookups into the donor record they select, and give every derivation shape a plain-language rule instead of its raw YAML
1.0		yamaa docs build	Initial generation from spec.yaml

R

Edit3 lines

1library(yamaa)23yamaa_project("project.yaml")$spec("ADVS")$run()$output

Python