workflow nodetrix-hybrid-network-exploration
  template: contextualise -> define-unit -> contextualise ->
            characterise -> visualise -> abstract ->
            loop(define-unit (adjust aggregation) ->
                 contextualise (reposition aggregates) ->
                 characterise (update attributes) ->
                 visualise -> abstract -> assess) ->
            generate-knowledge
  description: "Assumed composite workflow (synthesised from the co-authorship case
    study) for exploring social networks using a hybrid node-link/matrix
    representation; dense subgraphs are interactively aggregated into adjacency
    matrices and repositioned within the network layout, while sparse
    inter-community structure remains a node-link diagram, supporting iterative
    exploration of communities, central actors, and collaboration roles"

# ============================================================================
# INPUT
# ============================================================================

artifact D_researchers : entities
  origin: given
  internal structure: elementary
  embedment: relational structure
  features:
    - id: f_name
      value structure: atomic
      value type: text
      description: "Researcher identifier"
    - id: f_citation_count
      value structure: atomic
      value type: numeric
      description: "Number of citations"
  description: "Researchers (vertices) embedded within the co-authorship
    collaboration network"

artifact F_collaboration : feature(D_researchers)
  origin: given
  value structure: relational configuration
  value type: numeric
  representation form: "co-authorship graph with weighted edges representing
    collaboration strength"
  description: "Pairwise collaboration relationships between researchers,
    with associated collaboration-strength attributes"

# ============================================================================
# STEP 1: INITIAL NODE-LINK LAYOUT OF THE UNDERLYING NETWORK
# ============================================================================

transform T_layout :
  intent: contextualise
  manner: "energy-based cluster-prominent graph layout"
  input: D_researchers, F_collaboration
  output: D_layout_space, A_node_link
  actor: machine
  description: "Compute an initial graph layout that gives prominence to
    densely connected clusters and exposes the sparse global structure"

artifact D_layout_space : entities
  internal structure: elementary
  features:
    - id: f_dimensions
      value structure: atomic
      value type: numeric
      description: "Number of spatial dimensions (2)"
  description: "Two-dimensional layout space for positioning researchers and
    aggregate communities"

artifact A_node_link : arrangement(D_researchers)
  context: D_layout_space
  principle: "energy-based layout emphasising dense clusters"
  description: "Node-link positions of individual researchers reflecting
    global network structure and cluster prominence"

# ============================================================================
# STEP 2: INITIAL AGGREGATION INTO COMMUNITIES
# ============================================================================

transform T_initial_aggregate :
  intent: define-unit
  manner: "interactive selection and aggregation of densely connected
    subgraphs into community units"
  input: D_researchers, F_collaboration, A_node_link
  output: D_communities, F_community_membership
  actor: hybrid
  description: "Select and aggregate densely connected groups of researchers
    into community units guided by cluster prominence in the layout;
    researchers not aggregated remain as individual units"

artifact D_communities : entities
  internal structure: group/cluster
  embedment: relational structure
  features:
    - id: f_community_size
      value structure: atomic
      value type: numeric
      description: "Number of researchers in the community"
  description: "Aggregated groups of researchers representing dense
    collaboration communities, connected to each other through remaining
    inter-community collaborations; a community may contain a single
    researcher"

artifact F_community_membership : feature(D_researchers)
  value structure: atomic
  value type: categorical
  description: "Community membership assignment for each researcher"

# ============================================================================
# STEP 3: ARRANGE AGGREGATE COMMUNITIES IN THE LAYOUT SPACE
# ============================================================================

transform T_arrange_communities :
  intent: contextualise
  manner: "derive aggregate-node positions from the initial network layout"
  input: D_communities, F_community_membership, A_node_link, D_layout_space
  output: A_community_layout
  actor: machine
  description: "Place aggregate communities in the layout space using the
    positions of their underlying researchers in the initial node-link
    layout"

artifact A_community_layout : arrangement(D_communities)
  context: D_layout_space
  principle: "aggregate-node placement derived from member positions in the
    initial node-link layout"
  description: "Initial positions of NodeTrix aggregate nodes and matrices
    in the two-dimensional network layout"

# ============================================================================
# STEP 4: PROPAGATE ATTRIBUTES TO COMMUNITIES
# ============================================================================

transform T_initial_characterise :
  intent: characterise
  manner: "aggregate underlying node and edge attributes into
    community-level attributes"
  input: D_communities, F_community_membership, D_researchers, F_collaboration
  output: F_community_attributes
  actor: machine
  description: "Compute community-level attributes (e.g., averaged values for
    numeric attributes, concatenated values for nominal attributes) from
    member researcher and collaboration attributes"

artifact F_community_attributes : feature(D_communities)
  value structure: vector
  value type: {numeric, categorical, text}
  description: "Aggregated attributes of each community derived from its
    member researchers and their collaborations"

# ============================================================================
# STEP 5: INITIAL HYBRID VISUALISATION AND OVERVIEW
# ============================================================================

transform T_initial_visualise :
  intent: visualise
  manner: "hybrid node-link and matrix visualisation"
  input: A_community_layout, D_communities, D_researchers,
    F_community_membership, F_collaboration, F_community_attributes
  output: V_nodetrix
  actor: machine
  description: "Render aggregate communities as adjacency matrices, with
    inter-community collaborations shown as node-link connections and
    intra-community collaborations shown as matrix cells"

artifact V_nodetrix : visualisation(A_community_layout, D_communities,
    D_researchers, F_community_membership, F_collaboration,
    F_community_attributes)
  layout: "node-link diagram of aggregate communities with adjacency
    matrices overlaid on multi-member aggregate nodes"
  form: "matrices for communities and links for inter-community
    collaborations"
  encoding: "aggregate-node position from A_community_layout; matrix rows
    and columns represent member researchers and can be manually reordered;
    axis labels from f_name; axis colour from f_citation_count; matrix
    cells and inter-community links from F_collaboration; matrix background
    colour from F_community_attributes"
  description: "Interactive hybrid visualisation showing global network
    structure through node-link connections and dense communities through
    adjacency matrices"

transform T_initial_interpret :
  intent: abstract
  manner: "perception and interpretation of community density, bridging
    actors, and connection patterns"
  input: V_nodetrix
  output: P_patterns
  actor: human
  description: "Identify collaboration pattern types, central or bridging
    actors, and community cohesion from the visualisation"

artifact P_patterns : pattern(D_communities, D_researchers)
  representation form: "categorized collaboration patterns with descriptions"
  description: "Identified collaboration pattern types among communities
    (e.g., hub-dominated, clique-like, intermediate structures) and
    bridging or central actors"

# ============================================================================
# STEP 6: INTERACTIVE EXPLORATION LOOP
# ============================================================================

loop L_exploration:
  purpose: "Iteratively adjust aggregation and spatial positioning of
    communities to explore community structure, central actors, and
    collaboration patterns at an appropriate level of detail"
  until: "The representation provides a readable, informative view
    sufficient to identify communities, central actors, and collaboration
    roles for the current analytical goal"
  body:

    transform T_adjust_aggregation :
      intent: define-unit
      manner: "merge, split, add, remove, or transfer members of aggregate
        communities through direct manipulation"
      input: D_communities, F_community_membership, V_nodetrix
      output: D_communities_r, F_community_membership_r
      actor: human
      description: "Refine community aggregation by merging matrices,
        splitting matrices, adding or removing researchers, and
        transferring researchers between aggregate communities"

    artifact D_communities_r : entities
      internal structure: group/cluster
      embedment: relational structure
      features:
        - id: f_community_size
          value structure: atomic
          value type: numeric
          description: "Number of researchers in the community"
      description: "Updated community groupings after interactive
        adjustment"

    artifact F_community_membership_r : feature(D_researchers)
      value structure: atomic
      value type: categorical
      description: "Updated community membership assignment for each
        researcher"

    assign:
      D_communities := D_communities_r
      F_community_membership := F_community_membership_r

    transform T_reposition_communities :
      intent: contextualise
      manner: "direct manipulation of aggregate-node positions"
      input: D_communities, A_community_layout, V_nodetrix
      output: A_community_layout_r
      actor: human
      description: "Move aggregate nodes or matrices to improve readability
        of the hybrid network representation"

    artifact A_community_layout_r : arrangement(D_communities)
      context: D_layout_space
      principle: "user-defined aggregate-node placement"
      description: "Updated positions of aggregate nodes and matrices after
        direct manipulation"

    assign:
      A_community_layout := A_community_layout_r

    transform T_update_attributes :
      intent: characterise
      manner: "recompute aggregated community-level attributes"
      input: D_communities, F_community_membership, D_researchers,
        F_collaboration
      output: F_community_attributes_r
      actor: machine
      description: "Recompute community-level attributes reflecting the
        updated aggregation"

    artifact F_community_attributes_r : feature(D_communities)
      value structure: vector
      value type: {numeric, categorical, text}
      description: "Updated aggregated attributes of each community after
        re-aggregation"

    assign:
      F_community_attributes := F_community_attributes_r

    transform T_visualise_r :
      intent: visualise
      manner: "update hybrid node-link and matrix visualisation through
        direct manipulation and display controls"
      input: V_nodetrix, A_community_layout, D_communities, D_researchers,
        F_community_membership, F_collaboration, F_community_attributes
      output: V_nodetrix_r
      actor: hybrid
      description: "Update the NodeTrix view after aggregation,
        positioning, or visual-variable adjustments such as link thickness,
        matrix size, and axis-label visibility"

    artifact V_nodetrix_r : visualisation(A_community_layout, D_communities,
        D_researchers, F_community_membership, F_collaboration,
        F_community_attributes)
      layout: "node-link diagram of aggregate communities with adjacency
        matrices overlaid on multi-member aggregate nodes"
      form: "matrices for communities and links for inter-community
        collaborations"
      encoding: "same encoding as V_nodetrix, reflecting updated
        aggregation, positioning, and display settings"
      description: "Updated hybrid visualisation reflecting current
        aggregation, positioning, and display settings"

    assign:
      V_nodetrix := V_nodetrix_r

    transform T_interpret_r :
      intent: abstract
      manner: "perception and interpretation of community density, bridging
        actors, and connection patterns"
      input: V_nodetrix
      output: P_patterns_r
      actor: human
      description: "Identify or refine collaboration pattern types, central
        or bridging actors, and community cohesion from the updated
        visualisation"

    artifact P_patterns_r : pattern(D_communities, D_researchers)
      representation form: "categorized collaboration patterns with
        descriptions"
      description: "Updated or refined collaboration pattern types and
        identification of central or bridging actors"

    assign:
      P_patterns := P_patterns_r

    transform T_assess :
      intent: assess
      manner: "judge readability and adequacy of the current aggregation
        and positioning for the current analytical goal"
      input: V_nodetrix, P_patterns
      output: K_exploration_quality
      actor: human
      description: "Evaluate whether the current aggregation level, layout,
        and visual encoding adequately support community, central-actor,
        and role analysis, or whether further adjustment is needed"

    artifact K_exploration_quality : knowledge(D_communities)
      representation form: "quality judgment"
      description: "Assessment of whether the current representation
        sufficiently supports community identification, central actor
        identification, and role analysis"

end loop L_exploration

# ============================================================================
# STEP 7: SYNTHESISE FINDINGS
# ============================================================================

transform T_synthesise :
  intent: generate-knowledge
  manner: "formulate statements about community structure and collaboration
    roles"
  input: P_patterns, K_exploration_quality
  output: K_findings
  actor: human
  description: "Synthesise findings about collaboration communities, central
    and bridging actors, and characteristic collaboration pattern types"

artifact K_findings : knowledge(P_patterns, K_exploration_quality)
  representation form: "statements and explanations"
  description: "Documented findings about collaboration communities, central
    and bridging actors, and collaboration pattern types revealed through
    hybrid network exploration"