Analysis Specifications

An analysis specification is a versioned, reviewable description of expected ADaM datasets. Open Build → Analysis and create the trial’s Analysis specification. One specification can support primary, secondary, safety, descriptive and sensitivity analyses through shared datasets, parameters, populations and derivations.

The first visit shows an empty state. Create specification opens a naming step with an unnumbered default. Revise the existing specification with Save; edits create versions within that specification, and generation targets the selected specification.

Treatment codes, treatment labels and analysis values are optional. You can save generated or manually authored treatment mappings with these fields missing, and clear them later without losing the treatment rows.

Use Create additional specification in the header menu only for a separately governed deliverable. It requires a name and scope explanation, which is retained in the new specification’s description. The scope requirement is an authoring workflow rule; the API continues to permit multiple specifications. Existing specifications and their version histories remain available, with selection tabs when more than one exists. A new endpoint, population or interim analysis does not automatically require another specification.

This default organization is a TrialStack product choice, not a USDM requirement. The CDISC ADaM Traceability Examples v1.0 document, section 1.3, describes datasets supporting multiple statistical analyses. It does not prescribe separate workspace records for those analyses.

Use the context panel at the bottom right to chat with trial context from the Analysis tab. Source options load in the background; a source-loading failure remains visible for action.

Explore the standalone demo

The standalone demo starts with a synthetic draft containing ADSL and ADEFF. One EXSCORE parameter supports both observed-score and change-from-baseline summaries: AVAL, BASE and CHG remain columns on the same parameter records. The example includes a baseline flag, planned treatment, population membership, visit keys and the QS source sequence. It does not require a separate dataset for each analysis.

The example assumes one assessment per participant and planned visit, rejects duplicates, and treats visit zero as baseline. These are invented teaching assumptions, not the trial’s approved SAP. The source rows are proposed metadata with no complete Form lineage or participant records. This is a traceability excerpt, not a complete or validated submission dataset. The live workspace still starts empty.

Keep statistical intent and dataset metadata separate

The Statistical tab owns the trial’s populations, endpoints, estimands, analysis methods, multiplicity, and interim-analysis intent. Analysis owns the downstream dataset specification: expected SDTM source domains, ADaM datasets and variables, source mappings, derivations, population flags, treatment mappings, parameters, and value-level metadata.

Analysis does not copy participant data and does not execute an ADaM dataset build. It references immutable versions of the trial, design transaction, Statistical plan, Forms, and Form placements. If one of those sources changes, TrialStack marks the specification as stale. Refresh the source versions, review the draft, and save a new specification version; previous versions retain their original references.

Generate a review draft

Use Generate all or Improve all in the page header to propose the overview fields and all ten content sections from the pinned sources. Create additional specification remains in the header menu for a separate deliverable. Each content section keeps Add as its primary action and places its scoped Generate or Improve action in the section menu. Section generation is limited to that collection, so it does not replace authored content in sibling sections.

TrialStack generates independent sections together and waits for prerequisite sections before generating dependent traceability content. Generated row identities and ordering are normalized deterministically before the proposal is shown. Unsupported or insufficiently grounded content remains omitted with a finding for review. The result remains a draft: generation never verifies, approves, or silently replaces an existing specification.

Internal dataset, variable, derivation, parameter, and value-level references receive deterministic Analysis identities. Relationships to governed sources outside the specification are retained only when generation returns an exact governed identity. TrialStack omits ungrounded population, endpoint, arm, Form, SDTM mapping, and Statistical references with a finding rather than inventing a link. Executable derivation expressions are also omitted from this target-neutral configuration; their governed narrative remains reviewable and executable logic belongs in an authorized external build handoff.

Review traceability

The Analysis visualization section offers Diagram and Matrix views of the same Analysis configuration. The diagram shows explicit source mappings, cross-dataset derivation inputs, and output bindings. Click a dataset or output to open its editor; click a connection to inspect its mapping or derivation. Selecting a node highlights its upstream dependencies. Conditional source mappings use dashed connections. Within-dataset calculations remain in the detailed tables, avoiding misleading self-loop arrows.

The matrix groups bindings by planned output and combines the dataset, parameter and result variable under Analysis data. Readable variable labels and compact condition summaries support scanning; tooltips retain exact variable names, and the existing editors retain full selection notes and rules. No timing or population meaning is inferred from a variable name. Planned outputs without bindings remain visible with a Configure binding action that prefills the selected output. Click analysis data, population, grouping, selection, source or derivation details to open the corresponding existing editor. Dataset ordering remains in the Datasets table. These views describe configured dependencies, not executed participant-data lineage or statistical results.

The Source mappings table records declared inputs. Sources may include pinned SDTM variables, governed Form items, trial-design metadata and Statistical definitions. Collection intent alone does not establish participant-level data lineage.

Export an exact version

Open Build → Exports, choose ADaM specification as the profile, and then choose its format. Each export selects one immutable Analysis Specification version:

• JSON contains the complete canonical specification.
• Excel contains separate sheets for the specification, sources, datasets, variables, mappings, derivations, populations, treatments, parameters, value-level metadata, and validation status.
• Draft Define-XML contains metadata only and does not include physical dataset references.

The manifest records the selected version, source pins, review status, content hash, and standards versions. TrialStack currently labels CDISC CORE data rules and Define-XML XSD validation as not_run for this metadata-only workflow. The export is not an XPT dataset and is not a submission-ready Define-XML package.

The same page exposes SDTM → Trial Design package (ZIP) for the governed TA, TE, TV, TI, and TS Trial Design domains. That package does not require an Analysis Specification version and does not contain participant domains such as DM, AE, or LB.

Standards scope

The first profile is fixed to ADaM Model 2.1, ADaMIG 1.3, and draft Define-XML 2.1.7 metadata. TrialStack validates its own structural and cross-reference rules. A future profile can claim broader conformance only after the applicable licensed release assets, checksums, rule coverage, fixtures, and validators are pinned and proven.

Prepare and review source mappings

The Source mappings section uses the standard array table, with one row per source link. Add, edit, or delete rows directly, then save the Analysis form. Each row identifies its target variable, source, role, priority, conditions, and notes. Editing existing mappings does not require preparation.

To create or refresh source definitions, choose Prepare mappings from the section menu. Save any pending Analysis edits first. If several source specifications are available, select the one to review by name. Preparation opens a review drawer without saving changes.

Review and correct the proposed source definitions, then choose Save changes and provide a reason. TrialStack saves the reviewed definitions with the Analysis’s existing mappings and retains the exact source version. The refreshed sources are then available in the standard row editor. If sources or saved versions changed during review, prepare again. Cancel closes an untouched proposal without saving; edited proposals require discard confirmation.

Exports uses the selected Analysis’s source version and offers the same review editor. Draft metadata may retain findings; an ADaM build handoff still requires the server’s readiness checks to pass. These specifications describe mappings and derivations, not participant records or executable transformation programs.

From Exports, Review source definitions opens mapping review within the export dialog. Back returns to the current export settings. The editor offers the same governed source choices and labels as Analysis.

Resolve incomplete variable definitions

Before an ADaM build handoff, every direct variable needs a direct or conditional source mapping with a governed reference. A derivation-input mapping alone does not define a direct variable. Every derived variable needs a selected derivation that targets that variable. Assigned and protocol-sourced variables need a governed source or selected method. Derived value-level metadata needs its own method or one inherited from the parent variable. Selected derivations must also form an acyclic input sequence; circular dependencies block handoff.

Incomplete definitions remain available for draft review. Resolve the readiness findings and save a new governed version before preparing the handoff. Handoff creation also checks these definitions for older versions whose retained readiness report may predate the checks. Review exports remain available.

When an Analysis pins a Statistical version, readiness and handoff use that exact retained version’s planned outputs, including older versions beyond the recent history list. An unavailable pinned version blocks preparation instead of silently becoming an empty output list. Save Analysis to capture the current available source versions.

Readiness also resolves Form, Trial Design and Statistical sources, plus selected endpoint, population and arm links, against the governed source catalogue. A missing or changed relationship is retained as a draft finding; an optional unassigned relationship is permitted. If current source versions cannot be confirmed, resolve the source findings in Exports before handoff. Operational loading failures do not count as successful validation.

Each dataset needs an ordered list of unique row keys from its own variables. Key sequence numbers must match that list, starting at 1 without gaps; variables outside the list cannot carry a key sequence. These checks validate the metadata definition, not uniqueness in participant data. Handoff requires readiness validator 1.6.0 and rechecks source availability; older retained reports require a new readiness assessment.

Connect planned outputs

In Output bindings, select an output already defined in the pinned Statistical version. Choose its dataset, result variable and optional parameter. Add its population, grouping variables and a plain-language record selection when applicable. Parameter and variable choices are limited to the selected dataset.

One parameter can support several outputs. The synthetic example binds observed-score and change summaries to the same ADEFF EXSCORE parameter, using AVAL and CHG respectively. Both group by planned treatment and visit; change uses post-baseline records only. These teaching assumptions are not an approved SAP.

Bindings are retained in version history, canonical JSON, the Excel Output Bindings sheet and the neutral build handoff. Unavailable or ambiguous output identities and cross-dataset references block handoff. Generation omits invented output references with a finding. Refreshing sources never substitutes an output with the same label. An empty binding section remains a valid draft and does not prove that planned outputs are covered.

Selection conditions in the output-binding editor define a conjunction: every condition must match. They reference exact variables from the selected dataset and support equality, numeric comparisons, character containment and explicit blank checks. Numeric literals are validated against the variable type; dates use ISO values. Ordinary comparisons exclude missing values, including not-equal comparisons. An empty condition list leaves selection unspecified. The existing record-selection notes remain available for context.

Conditions are retained in JSON and the Excel Record Selection sheet, and compile into the existing neutral decision model in the handoff.

External consumers must supply canonical scalar values: numbers for numeric variables, ISO strings for dates and timestamps, and null for missing values, including space-padded character blanks and SAS special missing values. Date and timestamp equality compares their supplied ISO representation; literal conditions do not perform date arithmetic. Relative windows are declared separately below. Participant-data execution remains external. Draft Define-XML does not yet represent output bindings.

Define baseline candidates

The Derivations editor records candidate conditions, Time windows, Group records by, Candidate selection, Candidate order and Candidate count. These fields stay inside the row editor. Conditions, group keys and ordering keys use declared inputs from the target dataset. Legacy narrative-only derivations remain readable without invented selection rules.

Groups are formed before filtering. Every condition and time window must match. Unique candidate (also the default when selection is omitted) rejects multiple matches. First candidate or Last candidate selects from the ordered candidates. Ordering is lexicographic in the listed row order, with ascending or descending direction for each key. Add a secondary key to resolve equal primary values. Missing sort values and ties on the complete key are errors; no input-file order is implied. Numeric values sort numerically, dates chronologically, timestamps by UTC instant and character values by Unicode code points.

Zero or one allows no selected candidate and leaves the result missing; Exactly one requires a selected candidate. The external build enforces grouping, selection, missing-key rejection and counts against participant data.

Specify time-relative windows

Choose a candidate date/time input, a reference input and their representation. A window compares candidate minus reference with explicit lower and upper offsets. At least one bound is required; either bound can be inclusive or exclusive. Equal bounds require both to be inclusive. Several windows are combined with AND.

Numeric dates use days since 1 January 1960; numeric datetimes use seconds since that epoch. Calendar dates use ISO dates and whole calendar-day offsets. ISO timestamps use UTC instant comparisons and second offsets. Both inputs must fit the chosen representation. Missing or partial dates never qualify; these rules do not impute, truncate or convert representations. A reference can come from the target dataset or the declared lookup dataset.

For example, a lower offset of -28 inclusive and an upper offset of 0 exclusive describes the 28 days before a reference date. This is an authoring example, not a baseline rule prescribed by the CDISC paper. Select trial-specific rules from the approved analysis plan.

Declare cross-dataset lookups

Each derivation can declare one Lookup dataset, composite Lookup keys and Expected matches. Pair target-dataset inputs with same-type inputs in the other dataset. Every key pair must match exactly, with no missing keys or implicit coercion. Self-joins, duplicate key references and undeclared inputs are rejected.

The external build performs the lookup per target record before candidate filtering and never multiplies target rows. Exactly one requires one source match; Zero or one leaves joined values missing when no match exists. Both reject multiple source matches. Use separate derivations for additional lookups; arbitrary joins, row-expanding joins and join chains within one derivation are outside this contract.

The mock copies ADEFF identifiers directly from QS, then looks up ADSL treatment and enrollment with exact STUDYID/USUBJID key pairs. This avoids requiring a derived identifier to find its own predecessor. Its baseline example still uses the explicitly invented visit-zero unique-candidate rule; adding window support does not change that assumption automatically.

Review and hand off derivation rules

Saved versions, generation and canonical JSON retain the optional rules. Excel includes Time Windows, Candidate Order and Join Keys sheets alongside Derivations and Derivation Selection. The neutral handoff carries typed lookup plans and window/order metadata with the exact variable identities. Readiness 1.6.0 rejects inconsistent definitions and requires older reports to be reassessed.

These are TrialStack metadata contracts informed by CDISC traceability guidance. They do not execute derivations, establish participant-data uniqueness, prove operational validation or constitute submission-ready Define-XML. External consumers must support the new rule metadata before using the handoff.

Source changes

Analysis does not require a separate source-refresh review. Generation uses current governed sources and checks that they remain unchanged before saving its result. Saving Analysis records current source versions with the content and its readiness findings. A changed source baseline returns the saved Analysis to draft.

ADaM build handoff rechecks source availability and references and blocks invalid or outdated evidence. JSON and Excel draft exports may retain findings; downloading a draft is not approval or a successful build validation. Use Exports to prepare source definitions and resolve handoff findings.

Find and resolve acquisition QC issues

Source preparation in Exports retains the acquisition package’s QC findings for the Analysis specification. Review retained findings in the Verification drawer. Finding cards explain the issue and the next step in plain language. Validator details and evidence checksums remain available in the JSON export.

The shared drawer chooses actions from the finding’s repair target, regardless of whether AI or a deterministic validator reported it. Improve opens the owning view with the finding as context: decision-path findings go to Decisions, timeline and encounter-group findings go to Participant journeys, and missing visit numbers go to Design. Missing decision-condition values reported during journey validation go to Decisions. The existing governed Improve workflow handles the correction; it does not automatically resolve the finding.

Missing standards imports are identified as administrator setup issues. Unexecuted checks require validation evidence. Findings without an exact repair target remain available for review without offering an unsafe AI action. After correcting the source, prepare sources again in Exports. A new QC result supersedes earlier open acquisition QC findings without dismissing unrelated verification findings. An unchanged latest result preserves existing review decisions. Ordinary AI verification does not dismiss acquisition QC findings because it does not rerun those checks. A completed refresh or verification record does not mean every check passed.