workflow dpvis-disease-progression-analysis template: define-unit (organise subjects) -> build-model (train candidates) -> assess (evaluate fit) -> generate-knowledge (select model) -> build-model (fit final) -> characterise (infer states) -> characterise (derive sequences) -> visualise (state summary) -> abstract (characterise states) -> abstract (mine transition patterns) -> visualise (transitions) -> abstract (identify trajectories) -> characterise (extract outcomes) -> visualise (static variables) -> loop(define-unit (build/update cohorts) -> characterise (cohort outcomes) -> visualise (cohort view) -> abstract (identify associations) -> assess -> generate-knowledge (refine criteria)) -> generate-knowledge (synthesise) description: "Assumed composite workflow (synthesised from the usage scenario and task structure T1-T5) for exploring disease progression pathways using hidden Markov models; a model is fitted and selected via cross-validated evaluation, latent disease states and their transition pathways are inferred, interpreted, and visualised, and multiple retained patient cohorts are iteratively built, refined, and compared to uncover associations between progression trajectories, outcomes, and patient characteristics" # ============================================================================ # INPUT # ============================================================================ artifact D_visits : entities origin: given internal structure: elementary embedment: {set, time} features: - id: f_subject_id value structure: atomic value type: reference description: "Identifier of the subject to whom the visit belongs" - id: f_observed_vars value structure: vector value type: numeric description: "Observed clinical variables chosen for state inference (e.g., autoantibody measures)" - id: f_static_vars value structure: vector value type: {categorical, numeric} description: "Static subject covariates (e.g., genetic profile, sex, family history)" - id: f_outcome_markers value structure: vector value type: {temporal, categorical} description: "Onset indicators and timing for outcome events (e.g., seroconversion, diagnosis)" description: "Longitudinal clinical visit records for multiple subjects from observational studies, each visit characterised by observed variables, static covariates, and outcome markers" # ============================================================================ # STEP 1: ORGANISE VISITS INTO PER-SUBJECT SEQUENCES # ============================================================================ transform T_define_subjects : intent: define-unit manner: "group visit records by subject identifier into per-subject sequences" input: D_visits output: D_subjects actor: machine description: "Organise visit records into per-subject sequences of time-ordered visits, forming the units of analysis for trajectory and cohort-level analysis" artifact D_subjects : entities internal structure: sequence embedment: set description: "Per-subject sequences of visits, each subject treated as a single trajectory for progression analysis" # ============================================================================ # SPECIFICATION FOR MODEL TRAINING # ============================================================================ artifact S_hmm_spec : specification origin: given representation form: "parameter settings" description: "Candidate numbers of hidden states, choice of observed variables, and transition constraints (e.g., no-backward progression) to be evaluated for hidden Markov model training" # ============================================================================ # STEP 2: TRAIN CANDIDATE MODELS AND SELECT CONFIGURATION # ============================================================================ transform T_train_candidates : intent: build-model manner: "fit hidden Markov model candidates across state counts and transition constraints, using subject visit sequences" input: D_subjects, D_visits, S_hmm_spec output: M_hmm_candidates actor: machine description: "Train candidate hidden Markov models for the specified state-count and constraint configurations" artifact M_hmm_candidates : model(D_subjects, D_visits, S_hmm_spec) model type: "hidden Markov model candidates" representation form: "candidate HMM parameterisations with differing state counts and transition constraints" description: "Candidate disease progression models awaiting selection" transform T_assess_model_fit : intent: assess manner: "evaluate cross-validated predictive fit and clinical usefulness" input: M_hmm_candidates, D_subjects output: K_model_fit actor: hybrid description: "Assess candidate models using validation likelihood and interpretability of exposed state patterns" artifact K_model_fit : knowledge(M_hmm_candidates) representation form: "model-selection assessment" description: "Assessment identifying an adequately fitting and clinically interpretable HMM configuration" transform T_select_model : intent: generate-knowledge manner: "select the best-performing and most interpretable configuration" input: K_model_fit, M_hmm_candidates output: S_hmm_selected actor: human description: "Select the final state count and transition-constraint configuration based on validation fit and clinical usefulness" artifact S_hmm_selected : specification representation form: "parameter settings" description: "Selected number of hidden states and transition constraints chosen from the evaluated candidates" transform T_fit_final_model : intent: build-model manner: "fit hidden Markov model with the selected configuration" input: D_subjects, D_visits, S_hmm_selected output: M_hmm actor: machine description: "Fit the final hidden Markov model using the selected state count and transition constraints" artifact M_hmm : model(D_subjects, D_visits, S_hmm_selected) model type: "hidden Markov model" representation form: "discrete latent states with state-conditional observation distributions and state-transition probabilities" description: "Final trained model inferring latent disease states and their temporal transitions from longitudinal observed variables" # ============================================================================ # STEP 3: INFER STATES AND DERIVE TRAJECTORY SEQUENCES # ============================================================================ transform T_infer_states : intent: characterise manner: "infer most probable hidden state and posterior probabilities per visit using the trained model" input: D_visits, M_hmm output: F_state_label, F_posterior actor: machine description: "Assign each visit a discrete disease state and a posterior probability distribution over states" artifact F_state_label : feature(D_visits) value structure: atomic value type: categorical description: "Inferred discrete disease state for each visit" artifact F_posterior : feature(D_visits) value structure: vector value type: numeric description: "Posterior probability distribution over hidden states for each visit, indicating assignment uncertainty" transform T_derive_sequences : intent: characterise manner: "aggregate per-visit state labels into ordered state sequences per subject" input: D_subjects, F_state_label output: F_state_sequence actor: machine description: "Compose each subject's time-ordered sequence of inferred states for trajectory-level analysis" artifact F_state_sequence : feature(D_subjects) value structure: list value type: categorical description: "Time-ordered sequence of inferred disease states for each subject, used to identify and compare progression trajectories" # ============================================================================ # STEP 4: CHARACTERISE AND INTERPRET STATES (T1) # ============================================================================ transform T_visualise_states : intent: visualise manner: "matrix and distribution views of observed variables per state" input: D_visits, F_state_label output: V_state_summary actor: machine description: "Display mean, variance, and distribution of observed variables for each inferred state to characterise state meanings" artifact V_state_summary : visualisation(D_visits, F_state_label) layout: "matrix with states as columns and observed variables as rows" form: "colour-coded cells and per-cell distribution glyphs (mean, standard deviation, histogram)" encoding: "columns from F_state_label; cell colour/values from per-state mean of each observed variable; glyph shows variance and missingness" description: "State summary panel showing distribution of observed variables per discovered disease state" transform T_interpret_states : intent: abstract manner: "perception and interpretation of per-state variable distributions to characterise and group states" input: V_state_summary output: P_state_characteristics actor: human description: "Interpret and categorise states according to their characteristic combinations of observed variables" artifact P_state_characteristics : pattern(F_state_label) representation form: "categorised state descriptions" description: "Interpreted groupings and semantic descriptions of states based on their characteristic variable profiles" # ============================================================================ # STEP 5: MINE AND VISUALISE TRANSITION PATHWAYS (T2) # ============================================================================ transform T_mine_transition_patterns : intent: abstract manner: "frequent sequential-pattern mining" input: D_subjects, F_state_sequence output: P_frequent_sequences actor: machine description: "Identify frequent multi-state transition patterns and their prevalence across subjects" artifact P_frequent_sequences : pattern(F_state_sequence) representation form: "ranked frequent state-sequence patterns" description: "Recurring state-transition patterns ranked by the number of subjects containing each pattern" transform T_visualise_transitions : intent: visualise manner: "coordinated transition views (time-aligned trajectories, flow diagram, radial transition diagram, ranked pattern list)" input: D_visits, F_state_label, F_state_sequence, P_frequent_sequences output: V_transitions actor: machine description: "Display state transition patterns across subjects over time using multiple complementary representations" artifact V_transitions : visualisation(D_visits, F_state_label, F_state_sequence, P_frequent_sequences) layout: "multiple coordinated views: time-aligned trajectory plot, stacked flow diagram, radial transition diagram, ranked pattern list" form: "trajectory lines over density-adjusted points; flow bands; arcs; ranked list with frequency bars" encoding: "position from visit time and state; colour from F_state_label; flow/arc thickness from transition frequency; ranked list from P_frequent_sequences, ordered by subject count" description: "Transition panel enabling exploration of state transition patterns and their prevalence across subjects" transform T_identify_trajectories : intent: abstract manner: "perception and interpretation of dominant transition pathways" input: V_transitions, P_state_characteristics output: P_trajectory_groups actor: human description: "Identify and name recurring state transition pathways representing distinct disease progression trajectory groups" artifact P_trajectory_groups : pattern(D_subjects, F_state_sequence) representation form: "named trajectory group descriptions" description: "Identified recurring state transition pathways, named according to their characteristic progression order" # ============================================================================ # STEP 6: EXTRACT SUBJECT-LEVEL OUTCOME SUMMARIES # ============================================================================ transform T_extract_outcomes : intent: characterise manner: "extract subject-level onset timing and static variable summaries from visit records" input: D_visits, D_subjects output: F_subject_outcomes actor: machine description: "Compute each subject's onset timing for key outcome events and summarise associated static covariates" artifact F_subject_outcomes : feature(D_subjects) value structure: vector value type: {temporal, categorical, numeric} description: "Per-subject onset timing for outcome events and static covariate values" # ============================================================================ # STEP 7: STATIC VARIABLES OVERVIEW (T3, T4) # ============================================================================ transform T_visualise_static_vars : intent: visualise manner: "static-variable distribution view" input: D_subjects, F_subject_outcomes output: V_static_vars actor: machine description: "Display distributions of static subject variables for population overview and cohort selection" artifact V_static_vars : visualisation(D_subjects, F_subject_outcomes) layout: "aligned horizontal bar charts" form: "categorical distribution bars" encoding: "bar length from population proportion of each static-variable category; interactive selections define static-variable cohort constraints" description: "Static Variables View for inspecting and selecting subject characteristics" # ============================================================================ # SPECIFICATION FOR COHORT DEFINITION (initial loop artifact) # ============================================================================ artifact S_cohort_criteria : specification origin: given representation form: "filter criteria" description: "Initial (unconstrained) filter criteria for defining a subject cohort based on state transitions, timing, or variables" # ============================================================================ # RETAINED COHORT COLLECTION (initial loop artifact) # ============================================================================ artifact D_cohorts : entities origin: given internal structure: group/cluster embedment: set description: "Initially empty or previously retained subject cohorts, each defined by a named set of selection criteria" artifact F_subject_cohort_memberships : feature(D_subjects) origin: given value structure: list value type: categorical description: "List of retained cohort memberships for each subject; memberships may overlap" # ============================================================================ # STEP 8: INTERACTIVE COHORT BUILDING AND ASSOCIATION ANALYSIS (T3, T5) # ============================================================================ loop L_cohort_analysis: purpose: "Iteratively build, refine, retain, and compare subject cohorts based on trajectory patterns, and examine their association with outcomes and static variables" until: "Retained cohort definitions are clinically meaningful and clear associations with outcomes or patient characteristics have been identified" body: transform T_build_or_update_cohorts : intent: define-unit manner: "interactive query-based cohort creation, refinement, and retention" input: D_subjects, F_state_sequence, D_visits, F_posterior, S_cohort_criteria, D_cohorts, F_subject_cohort_memberships, V_static_vars, V_transitions, V_state_summary output: D_cohorts_r, F_subject_cohort_memberships_r actor: hybrid description: "Create, update, name, and retain cohorts defined by transition, timing, outcome, or static-variable criteria, specified through direct interaction with diagnostic and transition views" artifact D_cohorts_r : entities internal structure: group/cluster embedment: set description: "Updated collection of retained subject cohorts" artifact F_subject_cohort_memberships_r : feature(D_subjects) value structure: list value type: categorical description: "Updated overlapping memberships of subjects in retained cohorts" assign: D_cohorts := D_cohorts_r F_subject_cohort_memberships := F_subject_cohort_memberships_r transform T_compute_outcome_stats : intent: characterise manner: "compute outcome timing and static variable distributions for each retained cohort relative to the overall population" input: D_cohorts, F_subject_cohort_memberships, F_subject_outcomes, D_subjects output: F_cohort_outcomes actor: machine description: "Compute distributions of onset timing and static variables for each retained cohort relative to the full population" artifact F_cohort_outcomes : feature(D_cohorts) value structure: vector value type: {numeric, categorical, temporal} description: "Outcome timing distributions and static variable summaries characterising each retained cohort relative to the population" transform T_visualise_cohorts : intent: visualise manner: "overlaid outcome-timing density plots, static-variable bar charts, and subject-level timelines; retained-cohort list for comparison" input: D_cohorts, F_subject_cohort_memberships, F_cohort_outcomes, D_subjects, D_visits, F_state_label, F_posterior output: V_cohorts actor: machine description: "Display selected-cohort outcome timing and static-variable distributions relative to the population, with subject-level state-sequence detail, and a list of retained cohorts for comparison" artifact V_cohorts : visualisation(D_cohorts, F_subject_cohort_memberships, F_cohort_outcomes, D_subjects, D_visits, F_state_label, F_posterior) layout: "overlaid density plots, bar charts, per-subject timelines, and a retained-cohort list" form: "dual density curves; horizontal bar charts; coloured visit timelines with posterior-probability glyphs; cohort list bars" encoding: "density curves from cohort and population outcome timing (F_cohort_outcomes); bar height from static-variable proportions; cohort highlighting from F_subject_cohort_memberships; visit-dot colour from F_state_label; glyph size or pie segments from F_posterior; cohort list bar height from relative cohort size" description: "Cohort view relating selected trajectory patterns to outcomes, static variables, and individual subject records, with support for comparing retained cohorts" transform T_identify_associations : intent: abstract manner: "perception and interpretation of outcome-timing and variable differences between cohorts and the population" input: V_cohorts output: P_associations actor: human description: "Identify associations between cohort trajectory patterns and outcome timing or static variables, including similarities and differences among retained cohorts" artifact P_associations : pattern(D_cohorts, F_cohort_outcomes) representation form: "descriptive association statements" description: "Identified associations between cohort trajectory patterns and outcome timing or static/genetic variables" transform T_assess_cohorts : intent: assess manner: "judge clarity and relevance of retained cohort definitions and their associations" input: V_cohorts, P_associations, D_cohorts output: K_cohort_quality actor: human description: "Assess whether the retained cohort definitions are clinically meaningful and their associations with outcomes are clear, or whether refinement of the selection criteria is needed" artifact K_cohort_quality : knowledge(D_cohorts) representation form: "quality judgment" description: "Assessment of cohort coherence and the clarity of their associations with outcomes, and whether refinement is needed" if K_cohort_quality indicates refinement needed: then: transform T_refine_criteria : intent: generate-knowledge manner: "adjust or combine filter criteria based on assessment" input: K_cohort_quality, P_associations, S_cohort_criteria output: S_cohort_criteria_r actor: human description: "Refine cohort selection criteria by adjusting, combining, or adding transition, timing, or variable constraints" artifact S_cohort_criteria_r : specification representation form: "filter criteria" description: "Updated cohort selection criteria after refinement" assign: S_cohort_criteria := S_cohort_criteria_r else: exit loop L_cohort_analysis end loop L_cohort_analysis # ============================================================================ # STEP 9: SYNTHESISE FINDINGS # ============================================================================ transform T_synthesise : intent: generate-knowledge manner: "formulate statements summarising trajectory groups, retained cohort definitions, and their associations with outcomes" input: P_trajectory_groups, P_associations, D_cohorts, K_cohort_quality output: K_findings actor: human description: "Synthesise and retain insights about disease progression trajectory groups, defined cohorts, and their clinical associations" artifact K_findings : knowledge(P_trajectory_groups, P_associations, D_cohorts, K_cohort_quality) representation form: "statements and retained cohort definitions" description: "Documented disease progression trajectory groups, their retained cohort definitions, and associations with outcomes and patient characteristics"