## ATWL Workflow Review Report  
**Paper Title:** *UTOPIAN: User-Driven Topic Modeling Based on Interactive Nonnegative Matrix Factorization*  
**Workflow ID:** `utopian-interactive-topic-modeling`

### Overall Assessment
The representation captures UTOPIAN’s central workflow well: document encoding, NMF-based topic modelling, projection-based visualisation, human interpretation, assessment, and iterative user-driven refinement through semi-supervised constraints.

However, it needs revision for template consistency, a missing entity embedment declaration, and closer alignment with the paper’s modified t-SNE input and node-link encoding.

**Recommendation:**  
- [ ] Approve as-is  
- [ ] Approve with minor revisions  
- [x] Requires revision  

### Strengths
- Correctly represents topic modelling as a `build-model` transform producing an NMF topic model.
- Correctly models topics as derived analysis units and document-topic memberships as features.
- The refinement loop has appropriate explicit assessment, conditional branching, and `assign:` feedback for the updated specification.
- The five UTOPIAN interaction types are substantially captured in `T_specify_refinement`.
- The computed projection context correctly omits `embedment`, as it represents one reference space.

---

### Critical Issues (Must Fix)

#### Issue 1: Template omits iterative refinement specification
**Location:** Workflow header

**Problem:** The loop body contains `T_specify_refinement`, with intent `generate-knowledge`, but the template does not include this intent. The template should reflect the meaningful stages in the workflow body.

**Correction:**
```atwl
workflow utopian-interactive-topic-modeling
  template: characterise ->
            loop(build-model -> define-unit ->
                 characterise -> contextualise ->
                 visualise -> abstract -> assess ->
                 generate-knowledge (specify refinement)) ->
            generate-knowledge
```

**Why:** The refinement specification is central to UTOPIAN’s contribution: users transform interactions into semi-supervised NMF reference constraints for the next run.

---

#### Issue 2: Missing embedment for the topic collection
**Location:** `D_topics`

**Problem:** `D_topics` represents multiple topic entities but lacks an `embedment:` declaration.

**Correction:**
```atwl
artifact D_topics : entities
  internal structure: elementary
  embedment: set
  description: "Topics discovered by the factorisation, each
    representing a candidate semantic theme in the corpus"
```

**Why:** A collection of topics is an unordered set of peer entities. ATWL requires embedment for such collections.

---

#### Issue 3: Projection input is not fully aligned with the paper
**Location:** `T_project`

**Problem:** The paper states that modified t-SNE operates on document bag-of-words vectors or document similarities, then shrinks distances for documents with the same hard topic-cluster label. It does not state that the document-topic weights themselves are the t-SNE input.

**Correction:**
```atwl
transform T_project :
  intent: contextualise
  manner: "projection by dimensionality reduction with topic-cluster-
    aware distance shrinkage"
  input: D_documents, F_document_terms, F_topic_label
  output: D_projection_space, A_projection
  actor: machine
  description: "Compute a 2D document layout from document similarity,
    shrinking distances between documents assigned to the same topic
    cluster to emphasise topic structure"
```

**Why:** This better reflects the paper’s modified t-SNE procedure. `F_document_topics` may remain available for interpretation and topic-related interactions, but should not be presented as the primary projection input unless supported by the source.

---

### Recommended Improvements (Should Fix)

#### Improvement 1: Explicitly encode node-link edges
**Location:** `V_topics`

**Suggestion:** The visualisation is called a node-link diagram, but its form and encoding only describe points. The paper specifies edges between sufficiently close document pairs.

```atwl
artifact V_topics : visualisation(A_projection, F_topic_label,
    F_topic_keywords)
  layout: "2D projection"
  form: "coloured document points with proximity links and topic
    keyword summaries"
  encoding: "position from A_projection; colour from F_topic_label;
    links connect document pairs below a user-defined distance threshold;
    topic labels from F_topic_keywords; document text shown on demand"
  description: "Interactive node-link visualisation of documents and
    topics supporting topic interpretation and refinement"
```

**Why:** This preserves an important visual element of the published system.

---

#### Improvement 2: Include the visualisation in the refinement interaction
**Location:** `T_specify_refinement`

**Suggestion:** Add `V_topics` as an input.

```atwl
input: K_topic_quality, P_topics, V_topics, F_topic_keywords,
  F_document_topics, D_documents
```

**Why:** In UTOPIAN, users perform keyword editing, topic merging/splitting, and document selection directly through the interactive visual interface and document viewer.

---

#### Improvement 3: Avoid unsupported “refinement history” claims
**Location:** `T_synthesise` and `K_findings`

**Problem:** The workflow does not preserve a history artifact. Reassigning `S_topic_model` replaces the previous specification, so a refinement history cannot be derived from the declared inputs.

**Correction option:** Remove the history claim.

```atwl
description: "Synthesise interpreted topics and their quality assessment
  into findings about the corpus's thematic structure"
```

Also align the knowledge references with the transform inputs:

```atwl
artifact K_findings : knowledge(P_topics, K_topic_quality)
```

**Why:** Artifact references should reflect the evidence supporting the final knowledge, and descriptions should not claim provenance that the workflow does not represent.

---

### Minor Suggestions (Optional)
- Consider changing `D_documents` to `internal structure: sequence` if word order is analytically relevant. `elementary` is acceptable if documents are treated only as whole text objects and encoded as bag-of-words vectors.
- The workflow appropriately abstracts over implementation details such as NMF update rules and threading. No additional implementation-level detail is needed.
- If intermediate visual updates and animated topic-membership transitions are considered essential contributions, mention them in `V_topics`’ description. They need not be modelled as separate transforms.

---

### Alignment with Paper
- **Pass:** Main methodology phases — encoding, NMF topic modelling, topic/document representations, modified projection, visualisation, and interaction are represented.
- **Pass:** Iterative refinement procedures — explicit loop, assessment, refinement specification, and assignment are present.
- **Pass:** Key interaction capabilities — keyword refinement, merging, splitting, document-induced creation, and keyword-induced creation are included.
- **Partial:** Projection methodology — revise inputs to reflect bag-of-words/similarity-based modified t-SNE.
- **Partial:** Node-link visualisation — add explicit link encoding.
- **Partial:** Final knowledge synthesis — this is a reasonable analytical endpoint, but it is an inferred workflow phase rather than an explicitly formalised stage in the paper.

### Conclusion
The workflow is a strong high-level representation of UTOPIAN and correctly captures its human-guided semi-supervised topic-modelling loop. Fix the template mismatch, add `embedment: set` to `D_topics`, and align the projection and visualisation details more closely with the paper.