workflow hybrid-network-community-analysis
  template: contextualise (LinLog layout) -> visualise (node-link) ->
            abstract (identify clusters) ->
            loop(generate-knowledge (select community) ->
                 define-unit (aggregate) ->
                 contextualise (hybrid layout) -> visualise (NodeTrix) ->
                 abstract (identify patterns) ->
                 abstract (test membership) -> assess) ->
            generate-knowledge (synthesis)
  description: "Social network analysts explore globally-sparse,
    locally-dense networks by iteratively aggregating identified
    communities into adjacency matrices within a node-link diagram.
    The hybrid NodeTrix representation enables simultaneous inspection
    of global structure (bridging actors, component topology) and
    community-level detail (collaboration patterns, missing edges,
    cliques). Interactive manipulation — moving actors in/out of
    matrices, merging, splitting, adjusting link thickness — supports
    progressive community identification, central actor detection, and
    role/position analysis."

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

artifact D_actors : entities
  origin: given
  internal structure: elementary
  embedment: set
  features:
    - id: f_name
      value structure: atomic
      value type: categorical
      description: "Actor name (e.g., researcher name)"
    - id: f_citations
      value structure: atomic
      value type: numeric
      description: "Numerical attribute (e.g., citation count)"
    - id: f_affiliation
      value structure: atomic
      value type: categorical
      description: "Categorical attribute (e.g., institution, country)"
  description: "Actors (vertices) in the social network: researchers in
    the InfoVis coauthorship network with associated attributes (name,
    citation count, affiliation); 1,104 actors total, 122 in the largest
    connected component"

artifact D_relationships : entities
  origin: given
  internal structure: elementary
  embedment: set
  features:
    - id: f_source
      value structure: atomic
      value type: reference
      description: "Source actor of the relationship"
    - id: f_target
      value structure: atomic
      value type: reference
      description: "Target actor of the relationship"
    - id: f_strength
      value structure: atomic
      value type: numeric
      description: "Relationship strength (e.g., number of co-authored
        papers)"
  description: "Relationships (edges) in the social network: co-authorship
    links between researchers with collaboration strength; 1,787 total
    edges; network is globally sparse but locally dense (small-world
    properties: high clustering coefficient, short average path length)"

# ============================================================================
# STEP 1: INITIAL LAYOUT
# ============================================================================

transform T_compute_layout :
  intent: contextualise
  manner: "apply LinLog energy-based layout algorithm to the full network;
    this layout gives prominence to clusters by placing densely connected
    subgraphs as compact spatial groups while separating loosely connected
    regions; produces 2D positions for all actors"
  input: D_actors, D_relationships
  output: A_network
  actor: machine
  description: "Compute cluster-emphasising node-link layout for the full
    network using LinLog energy model"

artifact A_network : arrangement(D_actors)
  context: "LinLog energy-based layout"
  principle: "2D positions computed by LinLog algorithm; densely connected
    communities appear as tight spatial groups; sparse inter-community
    connections span larger distances; hub nodes positioned between
    communities they bridge"
  description: "Initial node-link arrangement emphasising cluster structure
    through energy-based spatial grouping"

transform T_vis_nodelink :
  intent: visualise
  manner: "render actors as nodes with configurable shape, size, and colour;
    render relationships as links with configurable thickness and colour;
    map citation count to node colour; map collaboration strength to link
    opacity or thickness; support pan, zoom, lasso selection, and
    drag-and-drop interactions"
  input: A_network
  output: V_network
  actor: machine
  description: "Generate the initial node-link diagram with interactive
    manipulation support"

artifact V_network : visualisation(A_network)
  layout: "2D canvas with LinLog-positioned nodes and straight-line edges"
  form: "filled circles for actors; straight lines for relationships;
    labels on nodes"
  encoding: "node position: LinLog layout; node colour: citation count;
    link thickness: collaboration strength; link opacity: configurable
    via slider"
  description: "Initial node-link diagram showing the network with
    cluster-emphasising layout, configurable visual mappings, and
    interactive manipulation support (lasso, drag-and-drop)"

# ============================================================================
# STEP 2: GLOBAL STRUCTURE INSPECTION
# ============================================================================

transform T_identify_clusters :
  intent: abstract
  manner: "inspect node-link diagram for spatial clusters (tight groups of
    actors indicating communities); identify hub nodes with many visible
    links radiating outward; note bridges between clusters (actors
    connecting separate groups); identify isolated peripheral actors;
    form initial hypotheses about community boundaries"
  input: V_network
  output: P_community_findings
  actor: human
  description: "Inspect the node-link diagram to identify community
    clusters, hub nodes, and bridging actors at the global level"

artifact P_community_findings : pattern(D_actors)
  representation form: "identified communities, structural roles, and
    collaboration patterns"
  description: "Accumulated findings about network structure: identified
    communities with collaboration patterns, central/bridging actors,
    role categorisations, and overall topology; initially contains global
    structure observations from the node-link overview; grows across
    iterations as communities are aggregated and inspected"

# ============================================================================
# STEP 3: ITERATIVE HYBRID CONSTRUCTION AND EXPLORATION
# ============================================================================

# Accumulated community aggregations (initially empty)
artifact D_communities : entities
  origin: given
  internal structure: group/cluster
  embedment: set
  features:
    - id: f_member_actors
      value structure: set
      value type: reference
      description: "Set of actors comprising this community"
    - id: f_internal_density
      value structure: atomic
      value type: numeric
      description: "Edge density within the community"
    - id: f_community_label
      value structure: atomic
      value type: categorical
      description: "Community label (e.g., 'Berkeley', 'PARC')"
  description: "Aggregated community entities represented as matrices in
    the hybrid NodeTrix visualisation; internal connections shown as
    filled matrix cells, external connections as links from axis items;
    initially empty; grows as communities are progressively aggregated"

loop L_exploration:
  purpose: "Iteratively aggregate communities into matrices, inspect
    intra-community collaboration patterns and inter-community bridges,
    manipulate actor membership to test boundaries, and build up a
    comprehensive understanding of communities, central actors, and
    connection roles"
  until: "Analyst has identified all significant communities, characterised
    their collaboration patterns (cross, block, intermediate), identified
    all bridging actors, and constructed a readable hybrid layout suitable
    for communication"
  body:

    # ========================================================================
    # Step 3a: Select community for aggregation
    # ========================================================================

    transform T_select_community :
      intent: generate-knowledge
      manner: "identify a dense cluster in the current visualisation that
        would benefit from matrix representation; lasso-select the actors
        comprising this community; or drag a single node onto another to
        begin a 2x2 matrix; or drag a node into an existing matrix to
        extend it; or decide to merge two adjacent matrices, split a
        heterogeneous matrix, or rearrange node positions; selection
        guided by spatial proximity in layout and by accumulated findings"
      input: V_network, P_community_findings
      output: S_aggregation_spec
      actor: human
      description: "Select actors to aggregate into a matrix community,
        or decide on a structural manipulation (merge, split, rearrange)
        based on identified cluster structure and exploration progress"

    artifact S_aggregation_spec : specification
      representation form: "manipulation directive: actor set for new
        aggregation, merge/split instruction, or rearrangement parameters"
      description: "Aggregation or manipulation specification: set of
        actors to combine into a new matrix, instruction to merge or
        split existing matrices, or parameters for rearrangement"

    # ========================================================================
    # Step 3b: Aggregate into matrix
    # ========================================================================

    transform T_aggregate :
      intent: define-unit
      manner: "execute the specified manipulation: create an aggregated
        node for newly selected actors (internal relationships become
        matrix cells, external relationships become links from axis items);
        or merge existing matrices into one larger matrix; or split one
        matrix into separate sub-matrices; animate the transition to
        maintain mental model; compute aggregated attributes"
      input: D_actors, D_relationships, D_communities, S_aggregation_spec
      output: D_communities_r
      actor: machine
      description: "Execute the structural manipulation: aggregate
        selected actors into a community matrix, merge or split existing
        matrices, updating the accumulated community set"

    artifact D_communities_r : entities
      internal structure: group/cluster
      embedment: set
      features:
        - id: f_member_actors
          value structure: set
          value type: reference
          description: "Set of actors comprising this community"
        - id: f_internal_density
          value structure: atomic
          value type: numeric
          description: "Edge density within the community"
        - id: f_community_label
          value structure: atomic
          value type: categorical
          description: "Community label"
      description: "Updated set of aggregated communities reflecting the
        latest aggregation, merge, or split operation"

    # ========================================================================
    # Step 3c: Arrange and visualise hybrid
    # ========================================================================

    transform T_arrange_hybrid :
      intent: contextualise
      manner: "position matrices at aggregated node locations; display
        internal relationships as filled cells (colour-coded by
        collaboration strength); display external relationships as links
        from matrix axis items to outside nodes or other matrices;
        maintain node-link layout for non-aggregated actors; axis labels
        show individual actor names; matrix size adjustable via slider"
      input: D_communities_r, D_actors, D_relationships
      output: A_hybrid
      actor: machine
      description: "Arrange the hybrid NodeTrix representation with
        matrices embedded in the node-link layout"

    artifact A_hybrid : arrangement(D_actors, D_communities_r)
      context: "hybrid node-link + matrix layout"
      principle: "aggregated communities as matrices positioned at their
        LinLog centroid; non-aggregated actors as standard nodes;
        inter-community links as edges from matrix axis items; intra-
        community links as matrix cells; link thickness adjustable for
        overview vs. detail"
      description: "Hybrid NodeTrix arrangement combining node-link
        global structure with matrix community detail"

    transform T_vis_hybrid :
      intent: visualise
      manner: "render matrices with cells coloured by collaboration
        strength; axis labels showing actor names with citation colour;
        render inter-community links with adjustable thickness (slider
        from thin individual links to thick merged bands); support
        drag-and-drop of actors in/out of matrices, matrix merging,
        matrix splitting, row/column reordering, and geometric zoom on
        matrices via sliders"
      input: A_hybrid
      output: V_network_r
      actor: machine
      description: "Render the NodeTrix hybrid visualisation with full
        interactive manipulation support"

    artifact V_network_r : visualisation(A_hybrid)
      layout: "2D canvas: matrices positioned at community centroids;
        standard nodes at LinLog positions; links connecting matrices
        to external elements"
      form: "square matrices with coloured cells and labelled axes;
        circles for non-aggregated actors; lines/bands for inter-
        community links; animated transitions on aggregation"
      encoding: "matrix cell colour intensity: collaboration strength;
        axis label colour: citation count; link thickness: adjustable
        (thin = individual underlying links, thick = merged band
        approximating aggregated link); matrix background colour:
        aggregated community attribute; node size: configurable"
      description: "NodeTrix hybrid visualisation: matrices for
        communities within a node-link global structure, with
        interactive manipulation (drag-and-drop, merge, split, thickness
        slider, size slider, label toggle)"

    # ========================================================================
    # Step 3d: Identify intra-community collaboration patterns
    # ========================================================================

    transform T_identify_patterns :
      intent: abstract
      manner: "inspect matrix fill patterns to categorise collaboration
        structure: 'cross pattern' (single complete row/column in sparse
        matrix — one central actor collaborates with all, but others do
        not collaborate among themselves, indicating supervisor-student
        structure); 'block pattern' (near-clique — most cells filled,
        indicating tight mutual collaboration); 'intermediate pattern'
        (central actor plus partial block); identify missing edges within
        near-cliques; note community density and size"
      input: V_network_r, P_community_findings
      output: P_community_findings_r
      actor: human
      description: "Inspect matrix patterns to categorise community
        collaboration structures (cross, block, intermediate)"

    artifact P_community_findings_r : pattern(D_actors)
      representation form: "updated community and pattern descriptions"
      description: "Updated findings: identified collaboration patterns
        per community (cross = star topology indicating hierarchical
        group, block = clique indicating peer collaboration, intermediate
        = mixed); noted community densities and sizes; identified missing
        relationships within near-cliques"

    # ========================================================================
    # Step 3e: Test community membership and identify bridges
    # ========================================================================

    transform T_test_membership :
      intent: abstract
      manner: "drag actors in and out of matrices to test community
        boundaries: extract a suspected bridging actor and observe if the
        matrix becomes disconnected (confirming articulation point role);
        add peripheral actors to matrices to test if they belong to the
        community; inspect inter-community links to identify which actors
        bridge communities; adjust link thickness slider to switch between
        'how are communities linked?' (thick bands) and 'who links them?'
        (thin individual links)"
      input: V_network_r, P_community_findings_r
      output: P_community_findings_r2
      actor: human
      description: "Test community boundaries and identify bridging actors
        through interactive manipulation and observation"

    artifact P_community_findings_r2 : pattern(D_actors)
      representation form: "further updated findings with bridge and role
        information"
      description: "Further refined findings: confirmed articulation
        points (actors whose removal disconnects a community), identified
        bridges between communities, validated or adjusted community
        boundaries, and characterised actor roles (supervisor, peer,
        bridge, peripheral)"

    # ========================================================================
    # Step 3f: Assess exploration progress
    # ========================================================================

    transform T_assess_exploration :
      intent: assess
      manner: "judge whether all significant communities have been
        aggregated and their patterns characterised; evaluate whether
        all bridging actors have been identified; determine if the current
        hybrid layout is sufficiently readable for communication; consider
        whether remaining non-aggregated clusters warrant matrix treatment
        or whether further merging/splitting would clarify the structure"
      input: P_community_findings_r2, V_network_r
      output: K_exploration_state
      actor: human
      description: "Assess whether all communities and central actors have
        been sufficiently characterised"

    artifact K_exploration_state : knowledge(P_community_findings_r2)
      representation form: "quality judgment"
      description: "Assessment of exploration progress: all communities
        identified and characterised, all bridges found, and layout
        suitable for communication; or further aggregation, splitting, or
        manipulation needed for specific regions of the network"

    if K_exploration_state indicates sufficient characterisation:
      then:
        assign:
          D_communities := D_communities_r
          V_network := V_network_r
          P_community_findings := P_community_findings_r2
        exit loop L_exploration
      else:
        assign:
          D_communities := D_communities_r
          V_network := V_network_r
          P_community_findings := P_community_findings_r2

end loop L_exploration

# ============================================================================
# STEP 4: KNOWLEDGE SYNTHESIS AND PRESENTATION
# ============================================================================

transform T_compose_presentation :
  intent: generate-knowledge
  manner: "compose a final NodeTrix layout optimised for communication:
    adjust matrix positions to minimise link crossings; reduce axis labels
    (via slider) for compactness in overview mode or keep them visible for
    detailed mode; choose appropriate colour mappings (axis colour =
    citations, cell intensity = collaboration strength); set link thickness
    for desired overview/detail balance; add community labels; produce the
    summary visualisation communicating global structure and community-level
    patterns simultaneously"
  input: P_community_findings, V_network
  output: K_network_understanding
  actor: human
  description: "Compose final summary visualisation and synthesise
    analytical findings about communities, central actors, and roles"

artifact K_network_understanding : knowledge(P_community_findings)
  representation form: "analytical conclusions and summary visualisation"
  description: "Synthesised social network understanding: (1) identified
    communities with characterised collaboration patterns — Berkeley
    (block/clique pattern indicating tight mutual collaboration),
    Shneiderman et al. (cross pattern indicating supervisor-student
    structure), PARC (block pattern), Roth/CMU (intermediate pattern);
    (2) identified central and bridging actors (e.g., Ed Chi as
    articulation point in PARC); (3) characterised inter-community
    relationships (sparse bridges connecting dense communities,
    confirming small-world properties); (4) final NodeTrix summary
    visualisation simultaneously communicating global topology and
    community detail without the readability problems of either pure
    node-link (cluttered in dense regions) or pure matrix (no path
    following for global structure)"