Lineage and impact assessment

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

The lineage model

Lineage is a directed graph. An edge from -> to means “to depends on from”. Node identifiers follow a simple convention:

Identifier	Type
`ADSL`	dataset
`ADSL.TRT01P`	variable
`MMRM`	analysis
`Table_14_2_1`	output

library(trialdiff)
lineage <- define_lineage(
  lineage_edge("ADSL.TRT01P", "ADLB.TRT01P", relationship = "groups_by"),
  lineage_edge("ADLB.AVAL", "ADLB.BASE", relationship = "derives"),
  lineage_edge("ADLB.AVAL", "ADLB.CHG", relationship = "derives"),
  lineage_edge("ADLB.AVAL", "MMRM", relationship = "models"),
  lineage_edge("MMRM", "Table_14_2_1", relationship = "reports")
)
lineage
#> 
#> ── trialdiff lineage ───────────────────────────────────────────────────────────
#> 5 edges, 7 nodes
#> analysis: 1
#> output: 1
#> variable: 5

Edges can carry a condition, for example TRT01P == "Drug A", which is recorded for transparency but not evaluated by the package.

Tracing

trace_dependencies() performs a breadth-first traversal and returns the path taken, so every flag can be explained.

trace_dependencies(lineage, from = "ADLB.AVAL")
#> # A tibble: 4 × 5
#>   node         node_type depth path                            edge_relationship
#>   <chr>        <chr>     <int> <chr>                           <chr>            
#> 1 ADLB.BASE    variable      1 ADLB.AVAL -> ADLB.BASE          derives          
#> 2 ADLB.CHG     variable      1 ADLB.AVAL -> ADLB.CHG           derives          
#> 3 MMRM         analysis      1 ADLB.AVAL -> MMRM               models           
#> 4 Table_14_2_1 output        2 ADLB.AVAL -> MMRM -> Table_14_… reports

Upstream tracing is also supported:

trace_dependencies(lineage, from = "Table_14_2_1", direction = "upstream")
#> # A tibble: 2 × 5
#>   node      node_type depth path                              edge_relationship
#>   <chr>     <chr>     <int> <chr>                             <chr>            
#> 1 MMRM      analysis      1 Table_14_2_1 -> MMRM              reports          
#> 2 ADLB.AVAL variable      2 Table_14_2_1 -> MMRM -> ADLB.AVAL models

Impact assessment

assess_impact() maps classified changes onto the lineage graph. Each reached node is graded and given a rationale.

classified <- classify_changes(
  compare_cut(adsl_cut1, adsl_cut2, by = "USUBJID", dataset = "ADSL")
)
impact <- assess_impact(classified, adsl_adlb_lineage)
impact$impacts[, c("node", "node_type", "level", "depth", "requires_rerun")]
#> # A tibble: 8 × 5
#>   node                     node_type level                depth requires_rerun
#>   <chr>                    <chr>     <chr>                <int> <lgl>         
#> 1 ADLB.TRT01P              variable  definitely_affected      1 FALSE         
#> 2 ADSL.TRT01A              variable  definitely_affected      1 FALSE         
#> 3 Efficacy_Set             analysis  potentially_affected     1 TRUE          
#> 4 Safety_Set               analysis  potentially_affected     1 TRUE          
#> 5 Lab_Summary_By_Treatment analysis  potentially_affected     2 TRUE          
#> 6 MMRM                     analysis  potentially_affected     2 TRUE          
#> 7 Table_14_2_1             output    potentially_affected     3 TRUE          
#> 8 Table_14_2_2             output    potentially_affected     3 TRUE

The grading rules are exposed through [impact_policy()], so a study team can agree and document its own conventions.

impact_policy()
#> 
#> ── trialdiff impact policy
#> value_direct: "definitely_affected"
#> value_indirect: "potentially_affected"
#> record: "potentially_affected"
#> schema: "potentially_affected"
#> label: "unlikely"
#> max_depth: Inf

Why “definitely” versus “potentially”?

A downstream variable that is derived directly from a changed variable is marked definitely_affected, because the derivation deterministically reads the changed value. Analyses and outputs are marked potentially_affected: whether a summary or model result actually changes depends on the data and the method, and can only be confirmed by rerunning.

Lineage gaps

If a changed node has no declared lineage, trialdiff does not guess. It lists the gap and asks for review:

impact$unlinked
#> # A tibble: 1 × 2
#>   node  reason                                                                  
#>   <chr> <chr>                                                                   
#> 1 ADSL  No lineage edge declared for this node; downstream impact cannot be tra…

This is a feature, not a limitation: the impact assessment is only as complete as the lineage metadata, and the report makes that explicit.

Generating lineage from metadata

Hand-authoring lineage does not scale. If you already maintain a object (from Define-XML or a specification workbook), lineage_from_metadata() derives the data and derived-variable portion of the graph from the derivations and where metadata:

mc <- metacore::define_to_metacore("define.xml")
lin <- lineage_from_metadata(mc)
trace_dependencies(lin, from = "ADSL.TRT01P")

Edges carry their provenance, and anything that cannot be resolved is listed for review rather than guessed:

lineage_provenance(lin)
lineage_review(lin)

Analysis and output dependencies are not described by data metadata, so that part of the graph is still supplied by the study team and merged in.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.