workflow utopian-interactive-topic-modeling template: characterise -> loop(build-model -> define-unit -> characterise -> contextualise -> visualise -> abstract -> assess -> generate-knowledge (specify refinement)) -> generate-knowledge description: "Assumed composite workflow (synthesised from usage scenarios) for interactive topic modeling of document corpora via semi-supervised nonnegative matrix factorization; the analyst iteratively inspects a projection-based visualisation of documents and topics, and refines the topic structure through keyword- or document-based interactions until the topics are coherent and reflect the analytical interests" # ============================================================================ # INPUT # ============================================================================ artifact D_documents : entities origin: given internal structure: elementary embedment: set features: - id: f_text value structure: atomic value type: text description: "Document text content" description: "Collection of text documents forming the corpus to be analysed" # ============================================================================ # STEP 1: ENCODE DOCUMENTS # ============================================================================ transform T_encode : intent: characterise manner: "encode documents as weighted term-frequency vectors" input: D_documents output: F_document_terms actor: machine description: "Represent each document as a weighted bag-of-words vector over the corpus vocabulary" artifact F_document_terms : feature(D_documents) value structure: vector value type: numeric representation form: "term-frequency weight vector over corpus vocabulary" description: "Weighted term-frequency representation of each document" # ============================================================================ # SPECIFICATION FOR TOPIC MODELING (initial loop artifact) # ============================================================================ artifact S_topic_model : specification origin: given representation form: "parameter settings and reference constraints" description: "Initial number of topics with no reference constraints (unsupervised run)" # ============================================================================ # STEP 2: TOPIC MODELING LOOP -- INTERACTIVELY REFINE TOPICS # ============================================================================ loop L_topic_modeling: purpose: "Iteratively fit and refine a topic model so that the resulting topics are coherent and reflect the analyst's interests" until: "Topics are judged semantically coherent, well-separated, and adequately reflect the analytical interests" body: transform T_fit_model : intent: build-model manner: "fit semi-supervised nonnegative matrix factorization with reference-based constraints" input: F_document_terms, S_topic_model output: M_topic_model actor: machine description: "Factorise the term-document representation into topic-keyword and document-topic weight matrices, optionally constrained by user-specified reference information" artifact M_topic_model : model(F_document_terms, S_topic_model) model type: "topic model" representation form: "nonnegative matrix factorization (topic-keyword and document-topic weights)" description: "Factorised representation decomposing documents into weighted combinations of topics and topics into weighted combinations of keywords" transform T_define_topics : intent: define-unit manner: "derive topics from the factorisation" input: M_topic_model output: D_topics, F_topic_keywords actor: machine description: "Define topics as analysis units, each characterised by a weighted combination of keywords from the factorisation" artifact D_topics : entities internal structure: elementary embedment: set description: "Topics discovered by the factorisation, each representing a candidate semantic theme in the corpus" artifact F_topic_keywords : feature(D_topics) value structure: vector value type: numeric representation form: "keyword weight vector" description: "Weighted combination of corpus keywords representing each topic" transform T_document_topics : intent: characterise manner: "extract document-topic weights and assign dominant topic label by hard clustering" input: D_documents, M_topic_model output: F_document_topics, F_topic_label actor: machine description: "Compute each document's weighted combination of topics and its dominant (hard-clustered) topic label" artifact F_document_topics : feature(D_documents) value structure: vector value type: numeric description: "Weighted combination of topics representing each document" artifact F_topic_label : feature(D_documents) value structure: atomic value type: categorical description: "Dominant topic label assigned to each document" transform T_project : intent: contextualise manner: "modified t-SNE projection 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" artifact D_projection_space : entities internal structure: elementary features: - id: f_dimensions value structure: atomic value type: numeric description: "Number of spatial dimensions (2)" description: "Computed 2D projection space where proximity reflects topic similarity" artifact A_projection : arrangement(D_documents) context: D_projection_space principle: "similarity-preserving 2D projection with topic-cluster- aware distance shrinkage" description: "Spatial arrangement of documents where proximity indicates topical similarity" transform T_visualise_topics : intent: visualise manner: "node-link diagram with colour-coded topic clusters and keyword-based topic summaries" input: A_projection, F_topic_label, F_topic_keywords, D_documents output: V_topics actor: machine description: "Display documents positioned by projection and coloured by topic membership, with keyword-based topic summaries and document text available for inspection" 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" transform T_interpret_topics : intent: abstract manner: "perception and interpretation of topic keyword summaries and representative documents" input: V_topics, F_topic_keywords output: P_topics actor: human description: "Interpret the semantic meaning of each topic and identify topics warranting refinement or further investigation" artifact P_topics : pattern(D_topics, F_topic_keywords) representation form: "topic labels with keyword-based descriptions" description: "Interpreted semantic meanings of topics based on their representative keywords and documents" transform T_assess_topics : intent: assess manner: "judge topic coherence, separation, and relevance to analytical interests" input: V_topics, P_topics output: K_topic_quality actor: human description: "Evaluate whether topics are coherent, well-separated, and adequately reflect the analyst's interests, or whether refinement is needed" artifact K_topic_quality : knowledge(D_topics) representation form: "quality judgment" description: "Assessment of topic coherence and adequacy, and whether further user-driven refinement is warranted" if K_topic_quality indicates satisfactory topics: then: exit loop L_topic_modeling else: transform T_specify_refinement : intent: generate-knowledge manner: "formulate reference constraints via keyword refinement, topic merging, topic splitting, or document- or keyword-induced topic creation" input: K_topic_quality, P_topics, V_topics, F_topic_keywords, F_document_topics, D_documents output: S_topic_model_r actor: human description: "Specify semi-supervised reference information (keyword- and/or document-based) encoding the desired topic adjustment for the next factorisation run" artifact S_topic_model_r : specification representation form: "reference constraints and weights" description: "Updated reference information constraining the next factorisation run to reflect the analyst's desired topic adjustment" assign: S_topic_model := S_topic_model_r end loop L_topic_modeling # ============================================================================ # STEP 3: SYNTHESISE FINDINGS # ============================================================================ transform T_synthesise : intent: generate-knowledge manner: "formulate statements summarising discovered topics" input: P_topics, K_topic_quality output: K_findings actor: human description: "Synthesise interpreted topics and their quality assessment into findings about the corpus's thematic structure" artifact K_findings : knowledge(P_topics, K_topic_quality) representation form: "statements and topic summaries" description: "Documented understanding of the corpus's thematic structure, including interpreted topics and their assessed adequacy"