Last updated: Sep 10, 2026

Week 1 — Introduction

Complete the preliminary setup from the syllabus before the first seminar. Two paths are offered below:

(a) Local computer — install the tools on your laptop.
(b) Browser (GitHub Codespaces) — no installation; recommended if you have little experience.

1. Set up

Both paths start the same way:

Create a GitHub account.
Collect your API key at keyreg.qhchina.org (class code: dhg502). Keep it private.
Go to https://github.com/mcjkurz/qh-starter, click Use this template, and create your own repository named dhg502. It already contains 明史.txt and the packages you need.

Then continue with your chosen path:

(a) Local: install Python, VS Code, OpenCode, and Chrome or Edge. Clone the dhg502 repo and open it in VS Code (File → Open Folder).
(b) Browser: in your new repo, click Code → Codespaces → Create codespace. First startup takes a few minutes; everything runs in the browser.

For OpenCode, follow the local install steps on the setup page: how to set up an AI coding agent.

2. Connect OpenCode

Open a terminal:
- (a) Local: in VS Code, Terminal → New Terminal.
- (b) Browser: use the terminal in the Codespace window.
Type opencode, then /connect, select OpenRouter, and paste your API key.
Type /models and select GLM-5.3-Flash.

3. In-class exercise

明史.txt (the History of Ming, classical Chinese, traditional characters, UTF-8) is already in your repo from the template. Paste the following into OpenCode:

Prompt 1

Task: Build a character-level LDA topic model on the Ming Dynasty history (明史.txt) using qhchina, and find the top 20 words for each topic.

Corpus & preprocessing:
- Input file: 明史.txt (UTF-8, classical Chinese in traditional characters).
- Split the text into segments of 1000 characters each; each segment = one document.
- Assume one character = one word (no tokenization/segmentation; treat every single character as a token).
- Remove stopwords BEFORE running the model, using qhchina's load_stopwords("zh_cl_tr") (classical Chinese, traditional characters). Also drop whitespace.

Model:
- Use LDAGibbsSampler from qhchina (e.g. from qhchina import LDAGibbsSampler, load_stopwords).
- Number of topics = 20.
- Usage pattern:
    from qhchina.analytics import LDAGibbsSampler
    documents = [segmented doc 1, segmented doc 2, ...]   # each doc is a list of single characters
    lda = LDAGibbsSampler(n_topics=20, iterations=100, random_state=42, min_word_count=2, stopwords=stopwords)
    lda.fit(documents)
    topics = lda.get_topics(n_words=20)
    # to get the top words for a single topic, you can also use:
    # lda.get_topic_words(topic_id, n_words=20)

Output:
- Produce a .txt file (e.g. 明史_topics.txt) listing all 20 topics, each with its top 20 words (word + probability), plus a short header (corpus, number of segments, topics, iterations).
- For each topic, also list the 3 top documents (segments) for that topic, i.e. the segments where the topic is strongest (lda.get_document_topics(doc_id=0, sort_by_prob=True)).

Open 明史_topics.txt and check the 20 topics, their top characters, and the strongest segments. Then paste:

Prompt 2

Build on the 明史_topics.txt results file from the previous step. Do not re-run the topic model; read that file and work from it.

For each of the 20 topics, look at its top 20 words and:
- write a short label (2-4 words) naming what the topic seems to be about;
- write a one-to-two sentence explanation of what these characters have in common and what the topic likely represents in the 明史.

Then create a single, well-styled HTML page (明史_topics.html) that shows, for each topic:
- the topic number and your label and explanation;
- the top 20 words with their probabilities;
- the 3 top documents (segments) for that topic.

Take all of this from 明史_topics.txt.

Open 明史_topics.html in Chrome or Edge:

(a) Local: double-click the file on your computer.
(b) Browser: if it won't open in the Codespace, right-click → Download, then open on your computer.

You should see each of the 20 topics with a label, explanation, top characters, and strongest segments.

4. Save to GitHub

Commit and push so your work is preserved — anything not pushed lives only in your Codespace (or on your laptop) and is lost if that environment is deleted. Three options:

Buttons: Source Control icon (left) → message (e.g. first commit) → Commit → Sync Changes / Push.

Terminal: /exit OpenCode, then:

git add -A
git commit -m "first commit"
git push

Ask the assistant: paste into OpenCode:

Prompt 3

Commit all changes with the message "first commit", then push to GitHub.