A Time of Day as a Column Type

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: derive each adverse event's analysis start date and time (ASTDTM), its time of day as a time value (ASTTM), the time imputation flag (ASTTMF) and a flag for a start in the afternoon (ASTPMFL), and submit them in a Dataset-JSON file with the data-definition document.

Input: spec.yaml, one ADaM adverse event specification that project.yaml submits in Dataset-JSON with its data-definition document, reading SDTM adverse event (AE) records with the collected start (AESTDTC) as ISO 8601 text, collected to the second, the minute, the hour, the day or the month.

Variables:

AETERM is the adverse event as reported.
ASTDTM is the start date and time: a start collected to the hour or the minute takes zero for the rest of its time, and a start collected as a date alone takes midnight; missing when the start was not collected to the day.
ASTTM is the time of day of ASTDTM, a time written hh:mm:ss, so 2025-03-04T08:30:15 gives 08:30:15; missing when ASTDTM is.
ASTTMF says which part of the start time was imputed: H when the start was collected without a time, M when it stops at the hour and S when it stops at the minute; blank when the time was collected to the second or there is no start.
ASTPMFL is Y when ASTTM is at or after 12:00:00, and blank otherwise, including when there is no start time.

Note: a time column holds a time of day with no date and no zone, written hh:mm:ss. to_time takes it from a date and time, and it compares only with another time, such as the literal TIME '12:00'. In the Dataset-JSON file ASTTM keeps its hh:mm:ss text with dataType time and asks for the integer the data-definition document describes: an eight-byte integer of seconds since midnight shown with the SAS format TIME8., beside ASTDTM with DATETIME20..

YAML specification

1 spec file

spec.yaml

Edit145 lines

1yamaa: "1.0"2type: spec3model: ADaM4domain: ADAE5keys: [STUDYID, USUBJID, AESEQ]6input:7  AE: {path: input/ae.csv, types: {AESEQ: int}}89output:10  path: adae.csv11  columns: [STUDYID, USUBJID, AESEQ, AETERM, ASTDTM, ASTTM, ASTTMF, ASTPMFL]1213columns:14  - name: STUDYID15    type: str16    label: Study Identifier17    derivation: AE.STUDYID18    submission:19      core: Req20      mandatory: true21      length: 2022      origins:23        - type: Predecessor24          description: AE.STUDYID2526  - name: USUBJID27    type: str28    label: Unique Subject Identifier29    derivation: AE.USUBJID30    submission:31      core: Req32      mandatory: true33      length: 3034      origins:35        - type: Predecessor36          description: AE.USUBJID3738  - name: AESEQ39    type: int40    label: Sequence Number41    derivation: AE.AESEQ42    submission:43      core: Req44      mandatory: true45      length: 846      origins:47        - type: Predecessor48          description: AE.AESEQ4950  - name: AETERM51    type: str52    label: Reported Term for the Adverse Event53    derivation: AE.AETERM54    submission:55      core: Req56      mandatory: true57      length: 20058      origins:59        - type: Predecessor60          description: AE.AETERM6162  # A start collected to the hour or minute takes zero for the rest of its63  # time, and a date alone takes midnight; a start without its day gives64  # none.65  - name: ASTDTM66    type: datetime67    label: Analysis Start Date/Time68    derivation:69      impute:70        type: datetime71        source: AE.AESTDTC72        time: first73    submission:74      core: Perm75      mandatory: false76      origins:77        - type: Derived78      method: AESTDTC completed with the earliest time its collected parts79        admit; missing when AESTDTC carries no complete date.8081  # The time of day of the start, a time value: an ADaM submission carries82  # it as SAS seconds since midnight shown with TIME8.83  - name: ASTTM84    type: time85    label: Analysis Start Time86    derivation:87      to_time:88        source: ASTDTM89    submission:90      core: Perm91      mandatory: false92      origins:93        - type: Derived94      method: Time part of ASTDTM.9596  - name: ASTTMF97    type: str98    label: Analysis Start Time Imputation Flag99    derivation:100      imputation_flag:101        source: ASTDTM102        part: time103    verifications:104      - allowed_values:105          values: [H, M, S]106    submission:107      core: Cond108      mandatory: false109      length: 1110      origins:111        - type: Derived112      method: H when the start was collected without a time, M when it stops113        at the hour and S when it stops at the minute.114115  # A time compares with a time literal; a missing start time leaves the116  # flag missing.117  - name: ASTPMFL118    type: str119    label: Analysis Start in Afternoon Flag120    derivation:121      flag: "ASTTM >= TIME '12:00'"122    verifications:123      - allowed_values:124          values: [Y]125    submission:126      core: Perm127      mandatory: false128      length: 1129      origins:130        - type: Derived131      method: Y when ASTTM is at or after 12:00:00.132133verifications:134  - row_count:135      min: 5136      max: 5137  - all_or_none:138      id: analysis-start-completeness139      columns: [ASTDTM, ASTTM]140141submission:142  label: Adverse Events Analysis Dataset143  class: OCCURRENCE DATA STRUCTURE144  structure: One record per adverse event145  repeating: true

Inputs

Under review1 source file

input/ae.csv

Edit5 rows

input/ae.csv
STUDYID	AESEQ	AETERM	AESTDTC
CATH	1	HEADACHE	2025-03-04T08:30:15
CATH	2	NAUSEA	2025-03-06T14:05
CATH	1	RASH	2025-03-10
CATH	2	DIZZINESS	2025-03
CATH	1	FATIGUE	2025-03-12T21

Expected output

Under review5 expected rows

expected/adae.csv

Edit5 rows

expected/adae.csv
STUDYID	AESEQ	AETERM	ASTDTM	ASTTM	ASTTMF	ASTPMFL
CATH	1	HEADACHE	2025-03-04T08:30:15	08:30:15	—	—
CATH	2	NAUSEA	2025-03-06T14:05:00	14:05:00	S	Y
CATH	1	RASH	2025-03-10T00:00:00	00:00:00	H	—
CATH	2	DIZZINESS	—	—	—	—
CATH	1	FATIGUE	2025-03-12T21:00:00	21:00:00	M	Y

expected/adae.json

Edit

{
  "datasetJSONCreationDateTime": "2026-09-11T00:00:00",
  "datasetJSONVersion": "1.1.0",
  "fileOID": "CATH.adam.Define-XML_2.1.ADAE",
  "sourceSystem": {"name": "yamaa", "version": "1.0"},
  "studyOID": "STDY.CATH",
  "metaDataVersionOID": "MDV.CATH.adam",
  "metaDataRef": "define.xml",
  "itemGroupOID": "IG.ADAE",
  "records": 5,
  "name": "ADAE",
  "label": "Adverse Events Analysis Dataset",
  "columns": [
    {"itemOID": "IT.ADAE.STUDYID", "name": "STUDYID", "label": "Study Identifier", "dataType": "string", "length": 4, "keySequence": 1},
    {"itemOID": "IT.ADAE.USUBJID", "name": "USUBJID", "label": "Unique Subject Identifier", "dataType": "string", "length": 16, "keySequence": 2},
    {"itemOID": "IT.ADAE.AESEQ", "name": "AESEQ", "label": "Sequence Number", "dataType": "integer", "length": 8, "keySequence": 3},
    {"itemOID": "IT.ADAE.AETERM", "name": "AETERM", "label": "Reported Term for the Adverse Event", "dataType": "string", "length": 9},
    {"itemOID": "IT.ADAE.ASTDTM", "name": "ASTDTM", "label": "Analysis Start Date/Time", "dataType": "datetime", "targetDataType": "integer", "length": 8, "displayFormat": "DATETIME20."},
    {"itemOID": "IT.ADAE.ASTTM", "name": "ASTTM", "label": "Analysis Start Time", "dataType": "time", "targetDataType": "integer", "length": 8, "displayFormat": "TIME8."},
    {"itemOID": "IT.ADAE.ASTTMF", "name": "ASTTMF", "label": "Analysis Start Time Imputation Flag", "dataType": "string", "length": 1},
    {"itemOID": "IT.ADAE.ASTPMFL", "name": "ASTPMFL", "label": "Analysis Start in Afternoon Flag", "dataType": "string", "length": 1}
  ],
  "rows": [
    ["CATH", "CATH-UCSD-0001", 1, "HEADACHE", "2025-03-04T08:30:15", "08:30:15", null, null],
    ["CATH", "CATH-UCSD-0001", 2, "NAUSEA", "2025-03-06T14:05:00", "14:05:00", "S", "Y"],
    ["CATH", "CATH-UCSD-0002", 1, "RASH", "2025-03-10T00:00:00", "00:00:00", "H", null],
    ["CATH", "CATH-UCSD-0002", 2, "DIZZINESS", null, null, null, null],
    ["CATH", "CATH-MCGILL-0003", 1, "FATIGUE", "2025-03-12T21:00:00", "21:00:00", "M", "Y"]
  ]
}

expected/define.xml

EditDefine-XML

Define-XML 2.1.11: CATH

Example study submitting adverse event onset times of day in Dataset-JSON; CATH-01; ADaMIG 1.3

Datasets
Dataset	Description	Class	Structure	Purpose	Keys	Documentation	Location
ADAE	Adverse Events Analysis Dataset	OCCURRENCE DATA STRUCTURE	One record per adverse event	Analysis	STUDYID, USUBJID, AESEQ		adae.json

ADAE

ADAE variables
Variable	Label / Description	Type	Length or Display Format	Origin / Source / Method / Comment
STUDYID	Study Identifier	text	4	Predecessor; AE.STUDYID
USUBJID	Unique Subject Identifier	text	16	Predecessor; AE.USUBJID
AESEQ	Sequence Number	integer	8	Predecessor; AE.AESEQ
AETERM	Reported Term for the Adverse Event	text	9	Predecessor; AE.AETERM
ASTDTM	Analysis Start Date/Time	integer	DATETIME20.	Derived; Sponsor AESTDTC completed with the earliest time its collected parts admit; missing when AESTDTC carries no complete date.
ASTTM	Analysis Start Time	integer	TIME8.	Derived; Sponsor Time part of ASTDTM.
ASTTMF	Analysis Start Time Imputation Flag	text	1	Derived; Sponsor H when the start was collected without a time, M when it stops at the hour and S when it stops at the minute.
ASTPMFL	Analysis Start in Afternoon Flag	text	1	Derived; Sponsor Y when ASTTM is at or after 12:00:00.

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="CATH.adam.Define-XML_2.1" CreationDateTime="2026-09-11T00:00:00" SourceSystem="yamaa" SourceSystemVersion="1.0" def:Context="Submission">
  <Study OID="STDY.CATH">
    <GlobalVariables>
      <StudyName>CATH</StudyName>
      <StudyDescription>Example study submitting adverse event onset times of day in Dataset-JSON</StudyDescription>
      <ProtocolName>CATH-01</ProtocolName>
    </GlobalVariables>
    <MetaDataVersion OID="MDV.CATH.adam" Name="CATH 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>
      <ItemGroupDef OID="IG.ADAE" Name="ADAE" Purpose="Analysis" SASDatasetName="ADAE" Repeating="Yes" IsReferenceData="No" def:Structure="One record per adverse event" def:ArchiveLocationID="LF.ADAE" def:StandardOID="STD.ADaMIG">
        <Description>
          <TranslatedText xml:lang="en">Adverse Events Analysis Dataset</TranslatedText>
        </Description>
        <ItemRef ItemOID="IT.ADAE.STUDYID" OrderNumber="1" Mandatory="Yes" KeySequence="1"/>
        <ItemRef ItemOID="IT.ADAE.USUBJID" OrderNumber="2" Mandatory="Yes" KeySequence="2"/>
        <ItemRef ItemOID="IT.ADAE.AESEQ" OrderNumber="3" Mandatory="Yes" KeySequence="3"/>
        <ItemRef ItemOID="IT.ADAE.AETERM" OrderNumber="4" Mandatory="Yes"/>
        <ItemRef ItemOID="IT.ADAE.ASTDTM" OrderNumber="5" Mandatory="No" MethodOID="MT.ADAE.ASTDTM"/>
        <ItemRef ItemOID="IT.ADAE.ASTTM" OrderNumber="6" Mandatory="No" MethodOID="MT.ADAE.ASTTM"/>
        <ItemRef ItemOID="IT.ADAE.ASTTMF" OrderNumber="7" Mandatory="No" MethodOID="MT.ADAE.ASTTMF"/>
        <ItemRef ItemOID="IT.ADAE.ASTPMFL" OrderNumber="8" Mandatory="No" MethodOID="MT.ADAE.ASTPMFL"/>
        <def:Class Name="OCCURRENCE DATA STRUCTURE"/>
        <def:leaf ID="LF.ADAE" xlink:href="adae.json">
          <def:title>adae.json</def:title>
        </def:leaf>
      </ItemGroupDef>
      <ItemDef OID="IT.ADAE.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">AE.STUDYID</TranslatedText>
          </Description>
        </def:Origin>
      </ItemDef>
      <ItemDef OID="IT.ADAE.USUBJID" Name="USUBJID" DataType="text" Length="16" SASFieldName="USUBJID">
        <Description>
          <TranslatedText xml:lang="en">Unique Subject Identifier</TranslatedText>
        </Description>
        <def:Origin Type="Predecessor">
          <Description>
            <TranslatedText xml:lang="en">AE.USUBJID</TranslatedText>
          </Description>
        </def:Origin>
      </ItemDef>
      <ItemDef OID="IT.ADAE.AESEQ" Name="AESEQ" DataType="integer" Length="8" SASFieldName="AESEQ">
        <Description>
          <TranslatedText xml:lang="en">Sequence Number</TranslatedText>
        </Description>
        <def:Origin Type="Predecessor">
          <Description>
            <TranslatedText xml:lang="en">AE.AESEQ</TranslatedText>
          </Description>
        </def:Origin>
      </ItemDef>
      <ItemDef OID="IT.ADAE.AETERM" Name="AETERM" DataType="text" Length="9" SASFieldName="AETERM">
        <Description>
          <TranslatedText xml:lang="en">Reported Term for the Adverse Event</TranslatedText>
        </Description>
        <def:Origin Type="Predecessor">
          <Description>
            <TranslatedText xml:lang="en">AE.AETERM</TranslatedText>
          </Description>
        </def:Origin>
      </ItemDef>
      <ItemDef OID="IT.ADAE.ASTDTM" Name="ASTDTM" DataType="integer" Length="8" SASFieldName="ASTDTM" def:DisplayFormat="DATETIME20.">
        <Description>
          <TranslatedText xml:lang="en">Analysis Start Date/Time</TranslatedText>
        </Description>
        <def:Origin Type="Derived" Source="Sponsor"/>
      </ItemDef>
      <ItemDef OID="IT.ADAE.ASTTM" Name="ASTTM" DataType="integer" Length="8" SASFieldName="ASTTM" def:DisplayFormat="TIME8.">
        <Description>
          <TranslatedText xml:lang="en">Analysis Start Time</TranslatedText>
        </Description>
        <def:Origin Type="Derived" Source="Sponsor"/>
      </ItemDef>
      <ItemDef OID="IT.ADAE.ASTTMF" Name="ASTTMF" DataType="text" Length="1" SASFieldName="ASTTMF">
        <Description>
          <TranslatedText xml:lang="en">Analysis Start Time Imputation Flag</TranslatedText>
        </Description>
        <def:Origin Type="Derived" Source="Sponsor"/>
      </ItemDef>
      <ItemDef OID="IT.ADAE.ASTPMFL" Name="ASTPMFL" DataType="text" Length="1" SASFieldName="ASTPMFL">
        <Description>
          <TranslatedText xml:lang="en">Analysis Start in Afternoon Flag</TranslatedText>
        </Description>
        <def:Origin Type="Derived" Source="Sponsor"/>
      </ItemDef>
      <MethodDef OID="MT.ADAE.ASTDTM" Name="ADAE.ASTDTM" Type="Computation">
        <Description>
          <TranslatedText xml:lang="en">AESTDTC completed with the earliest time its collected parts admit; missing when AESTDTC carries no complete date.</TranslatedText>
        </Description>
      </MethodDef>
      <MethodDef OID="MT.ADAE.ASTTM" Name="ADAE.ASTTM" Type="Computation">
        <Description>
          <TranslatedText xml:lang="en">Time part of ASTDTM.</TranslatedText>
        </Description>
      </MethodDef>
      <MethodDef OID="MT.ADAE.ASTTMF" Name="ADAE.ASTTMF" Type="Computation">
        <Description>
          <TranslatedText xml:lang="en">H when the start was collected without a time, M when it stops at the hour and S when it stops at the minute.</TranslatedText>
        </Description>
      </MethodDef>
      <MethodDef OID="MT.ADAE.ASTPMFL" Name="ADAE.ASTPMFL" Type="Computation">
        <Description>
          <TranslatedText xml:lang="en">Y when ASTTM is at or after 12:00:00.</TranslatedText>
        </Description>
      </MethodDef>
    </MetaDataVersion>
  </Study>
</ODM>

Shaded columns are derived— = missing value

Human review and assessment

Dataset Name	Variable Name	Variable Label	Type	Codelist/Controlled Terms	Core	Computational Method	Origin
ADAE	STUDYID	Study Identifier	character		Req	Copy value from AE.STUDYID.	Predecessor
ADAE	USUBJID	Unique Subject Identifier	character		Req	Copy value from AE.USUBJID.	Predecessor
ADAE	AESEQ	Sequence Number	numeric		Req	Copy value from AE.AESEQ.	Predecessor
ADAE	AETERM	Reported Term for the Adverse Event	character		Req	Copy value from AE.AETERM.	Predecessor
ADAE	ASTDTM	Analysis Start Date/Time	numeric	ISO 8601	Perm	AESTDTC completed with the earliest time its collected parts admit; missing when AESTDTC carries no complete date.	Derived
ADAE	ASTTM	Analysis Start Time	time	ISO 8601	Perm	Time part of ASTDTM.	Derived
ADAE	ASTTMF	Analysis Start Time Imputation Flag	character	H, M, S	Cond	H when the start was collected without a time, M when it stops at the hour and S when it stops at the minute.	Derived
ADAE	ASTPMFL	Analysis Start in Afternoon Flag	character	Y	Perm	Y when ASTTM is at or after 12:00:00.	Derived

Variable	Permitted values
ASTTMF	H, M, S
ASTPMFL	Y

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("ADAE")$run()$output

Python