DATA 8020 Course Design Instructions

Scope: everything under courses/data-8020/ — syllabus, project handout, lecture notes, lecture slides, computational companions, datasets, and the public landing page for this course.

This file is the canonical instruction file for course design. It sits under the personal-website repository, whose root AGENTS.md governs the site as a whole (Jekyll build, navigation, page collections, plan/ convention, Git practice). Follow the root file for site-wide work. For files under courses/data-8020/, this file is more specific and takes precedence; where the root file already states a DATA 8020 rule, the two must agree — fix the disagreement rather than choosing silently.

Keep CLAUDE.md in this folder as a relative symbolic link to AGENTS.md. Do not maintain a second copy that can drift.

1. Canonical course facts

Two published documents are authoritative and everything else must follow them:

• syllabus/data-8020-syllabus.tex — administrative facts, description, prerequisites, references, assessment weights, late policy, weekly topics.
• project/data-8020-project.tex — project rules, milestone dates, deliverables, assessment criteria, AI-use rules, candidate directions.

Never restate a date, weight, deadline, page limit, or policy from memory or from an older draft. Read it out of the source first. If a change is needed, change the authoritative source and then propagate.

Quick reference, current as of this writing — verify before relying on it:

Audience: research postgraduate students — data-science master's students with a minority of statistics/economics PhD students. Assume probability, linear regression, and basic machine learning; do not assume measure theory, empirical process theory, or semiparametric efficiency theory.

2. Folder layout

courses/data-8020/
  AGENTS.md, CLAUDE.md      instruction file and its symlink
  README.md                 contributor-facing build and contents notes
  index.md                  public landing page (Jekyll, permalink /courses/data-8020/)
  Makefile                  builds every committed PDF
  references.bib            single shared, verified BibTeX database
  tex/ee290.sty             shared notes style (\lecturetitle)
  syllabus/                 syllabus source + PDF
  project/                  project handout source + PDF
  lectures/lecture-NN/
    lecture-NN.tex          instructor notes (article, ee290.sty)
    lecture-NN-slides.tex   student-facing Beamer deck (metropolis)
    lecture-NN-demo.py      percent-format Python source (readable, reviewable)
    lecture-NN-demo.ipynb   notebook generated from the .py source
    *.csv                   deterministic synthetic data and results
    figs/                   generated .pdf/.png figures; ATTRIBUTIONS.md if any
                            figure is externally sourced

The related course page lives outside this folder at _teaching/data-8020-advanced-causal-inference.md. Reference material lives outside the repository at /Users/dujinhong/Documents/study/HKU/2026 Fall/teaching/DATA 8020 Advanced Causal Inference/materials. Treat that directory as read-only: consult and reuse ideas, do not modify, move, or bulk-copy its contents unless explicitly asked.

3. Design principles

These are the standing commitments of the course. A lecture that violates one of them needs a stated reason, not a quiet exception.

1. Identification before estimation. Every method is introduced after the estimand and the assumptions that make it meaningful. Machine learning improves estimation; it never supplies identification.
2. One argument per lecture. A lecture is a single line of reasoning with a stated question, not a survey of adjacent techniques. State the question on the second frame and answer it on the last.
3. Explicit assumption audit. Each method block names what must hold, what is testable, what is not, and what breaks first.
4. Teach the critique with the tool. Sensitivity analysis comes with its misreadings; discovery benchmarks come with their artefacts; a method's known failure modes are part of the method, not an optional appendix.
5. Set the theory dial once. Each advanced lecture should mark one block as expandable for a technical room and compressible to a statement-of-result for an applied one. Choose the setting early in the term and keep it consistent across lectures.
6. Budget 115 working minutes. A 2:00–4:50 slot is roughly two 52-minute halves with a 10-minute break, leaving slack for logistics. Write an explicit time budget and an explicit cut-first list; the cut-first list is what lets the plan survive a class that asks questions.
7. Target a misconception. Name the specific wrong belief the lecture is meant to dislodge, and give the demonstration that dislodges it.
8. Continuity is content. Open each lecture by stating what the previous one established and what changes now; carry one running example across lectures where possible (the constructed AI-tutor study links L3 and L4).
9. Reproducibility is taught by example. Anything shown numerically must be reproducible from committed source with a fixed seed.
10. Human responsibility over AI use. Course materials present AI as a tool inside a human research process: decide, verify, revise or reject, take responsibility. Do not grade prompt volume, provider, commit counts, or apparent sophistication, and do not require chat transcripts or use AI-writing detectors. No policy gives paid models an advantage.
11. No real or realistic-looking personal data. Classroom datasets are constructed and deterministic, and are labelled as such in the notebook, the README, and the slides that use them.

4. Lecture authoring pipeline

Work in this order. Do not start LaTeX before the content decisions are made.

1. Plan. Write or update a plan file at ../../plan/YYYY-MM-DD-data-8020-<topic>.md (repository root plan/, which is gitignored). Use the per-lecture template: position in the arc → learning objectives → time budget table → core readings (3–5 anchors plus one survey) → optional/dial-up readings → misconception to target → cut-first list. Record open questions rather than resolving them by guess.
2. Verify the readings. Confirm every citation exists as described before it enters the plan (see §8).
3. Instructor notes — lecture-NN.tex. Full narrative, derivations, and speaker framing. Notes may exceed what is taught; they are the instructor's working document.
4. Slides — lecture-NN-slides.tex. Built from the notes, not the reverse. One idea per frame.
5. Computational companion, when the lecture has one. Write lecture-NN-demo.py in percent-cell format first, generate the notebook from it, and commit the generated figures and CSVs.
6. Build and inspect (§9), then publish links (§7).
7. Consistency sweep (§11), then record in the plan file that the change was implemented and what was deliberately left unchanged.

New-lecture checklist: Makefile targets for both PDFs, index.md link for the slides and any dataset, teaching-page schedule row, references.bib entries, figs/ directory, and dataset labelling.

5. Instructor notes conventions

• \documentclass{article} with \usepackage{../../tex/ee290}.
• Open with \lecturetitle{NN}{Lecture NN: Title---Subtitle}{Jin-Hong Du}{Month D, 2026}. Use --- for the em dash in the title; the macro takes lecture number, title, instructor, and date.
• ee290.sty provides numbered theorem, lemma, proposition, corollary, definition, assumption, example, exercise.
• Callout boxes via tcolorbox: keybox (green, the point to remember), warningbox (orange, the failure mode), technicalbox (purple, the optional technical aside). Keep this mapping stable across lectures.
• Palette, shared with the slides and the figures: hkugreen RGB 0,102,68 · controlblue 48,92,138 · warmorange 205,112,45 · softpurple 115,83,141.
• Shared macros: \E, \Prb, \Var, \Pn, \indep, \norm{}, \given. Reuse them; do not redefine them per file.
• Python listings use the existing \lstset block; do not restyle it.

6. Slide conventions

• \documentclass[10pt,aspectratio=169]{beamer}, metropolis theme with progressbar=frametitle and \metroset{numbering=fraction,block=fill}.
• Slide number stays at the lower right (metropolis default). Do not move or remove it.
• Every normal content slide shows the current part at the lower left as <number> · <short name>, bold, in HKU green. Use 0 for opening slides and number the main parts from 1. Implement with \setfootersection{<number>}{<short name>} placed immediately before each \section; if a deck has no \section commands, place it at each clear topic change — never add a divider slide only to carry a footer.
• Footer names are short and plain (See the problem, Adjustment methods, Diagnose and report). Self-identifying full-page title, section, break, and closing slides may stay footer-free.
• First frame is a [plain,noframenumbering] title page in the established form: lecture title, subtitle, HKU-green rule, course name, author, institute, date.
• Second frame states the lecture's objectives ("By the end, you should be able to…") and closes with a keypoint.
• Emphasis environments: formulahighlight (the centred equation that matters), keypoint (blue), warningpoint (orange), purplepoint (purple). Match the notes' colour semantics.
• Diagrams use the shared tikzset styles: var, arr, flow, method (green), data (blue), danger (orange), purple. Prefer a small three-node flow that shows the mechanism over a decorative graphic.
• Legibility from the back of the room outranks completeness. Move dense derivations to the notes and long lists to the handout.

Side-by-side comparisons

A frame that puts two or more things beside each other to be compared is a table, not a row of column environments. Beamer columns are independent: each one stacks its own content from the top, so if the pictures differ in height — a fork is two rows deep, a chain is one — every line below them lands at a different height, and the reader sees three captions on three baselines instead of one comparison. This has been the single most common layout defect in this course.

Use a tabular with one row per conceptual line — titles, pictures, example, conclusion — so the rows align by construction whatever a cell contains. Two further rules make it reliable:

• Put every picture in a fixed-height cell, \parbox[t][<height>][c]{<width>}{\centering …}, tall enough for the deepest graph. The [c] centres each picture inside its cell, so unequal graphs still occupy equal space. A cell shorter than its picture does not clip it — the picture overflows into the row below, which looks like a collision rather than an overflow, so check the rendered page.
• Wrap wrapping text in \parbox[t]{<width>}{\centering …} rather than relying on the column width, and give each picture the same use as bounding box rectangle when they must look identically sized.

Prefer compacting a diagram — move nodes closer, drop a redundant label — over shrinking its type to make a frame fit. When a frame overflows, the Overfull \vbox figure in the log is the amount to remove, and a frame that overflows badly enough will spill onto a second page rather than clip.

Two related habits: route arrows around rows of nodes rather than across them, and never let a header colour compete with a cell colour in the same table.

7. Publication rule — slides only

Publish lecture slides. Instructor notes stay unpublished; publish them later only if student demand warrants it. This is a standing rule, so when a lecture ships:

• Add the slides PDF to the list in index.md, plus any dataset or results CSV the students need. Do not add lecture-NN.pdf.
• Add the schedule row in _teaching/data-8020-advanced-causal-inference.md with date, topic, slides link, and project milestone. Links from that page are relative (../../courses/data-8020/...).
• Both tables must agree with each other and with the syllabus's weekly topic list. A slides PDF that exists but appears in neither place is not published; a link to a file that does not exist is a broken page.
• Keep the notes PDF committed and buildable even though it is unlinked.

8. References and citation verification

references.bib is the single shared, verified database for every course PDF; notes, slides, syllabus, and handout all cite from it.

Before a reference enters any course file:

• Confirm it exists and that title, authors, year, venue, volume, and pages are correct against the published record — not from recall.
• Prefer the published version over a preprint, and note the preprint's different title when one exists (this has been a real source of error).
• Do not cite a paper for a claim it does not make, and do not attribute a method to the wrong paper in the same line of work.
• Add one BibTeX entry per work with a consistent key; do not create a near-duplicate entry for a work already present.
• Use natbib author–year (\citet, \citep) as the existing files do.
• Slide reading lists must match the notes and the plan file. If a reading is dropped from a lecture, drop it from all three.

External figures need provenance: record source URL, author, year, and licence in the lecture's figs/ATTRIBUTIONS.md, and put an on-slide credit line on any image whose licence requires attribution (for example CC BY-SA). Prefer public-domain or self-drawn TikZ figures.

9. Computational companions and data

• Author lecture-NN-demo.py in percent-cell format (# %%, # %% [markdown]) as the reviewable source of truth; generate the .ipynb from it and keep the two in sync.

• Fix the seed (SEED = 8020 is the established value) and state the true parameter being recovered so the estimate can be judged.

• Match the slide palette in matplotlib: #006644, #305C8A, #CD702D, #73538D. Write figures into figs/ as both .pdf (for LaTeX) and .png.

• Datasets are constructed and deterministic. Say so in the notebook header, the README, and any slide that shows them. They contain no records from real students.

• Keep runtimes short enough for class use — a couple of minutes, not tens. Make simulation size a variable with a small default.

• Dependencies: Python 3.10+, numpy, pandas, matplotlib, scikit-learn, jupyter, nbconvert. Execute from the lecture directory so figure paths resolve:

  cd lectures/lecture-NN
  jupyter nbconvert --to notebook --execute --inplace lecture-NN-demo.ipynb
  

  If a user-level Jupyter configuration loads unavailable extensions, prefix with JUPYTER_CONFIG_DIR=/tmp/data8020-jupyter-config.

• Before the notebook, run the analysis honestly: if a diagnostic shows the method failing, teach that, do not tune the data until it looks good.

10. Build

From this folder:

make          # build every PDF listed in the Makefile
make clean    # remove LaTeX auxiliaries, keep committed PDFs

latexmk -pdf -cd -interaction=nonstopmode -halt-on-error is the underlying command. Every new source file needs its own Makefile target and a matching clean line.

After changing structure, footers, or figures, force-build the affected PDFs and then look at them: the title frame, one representative slide from each part, and the closing or references. Check the log for errors, undefined references and citations, duplicate destinations, and serious overfull boxes. A clean compile is not the same as a correct deck.

LaTeX auxiliaries are gitignored at the repository root, as are *.ipynb and /plan. Commit .tex, the built .pdf, .py, .csv, and figs/. Do not commit stray duplicates such as lecture-NN-slides 2.pdf.

Follow the root file's Git practice: check git status --short --branch before and after edits, keep unrelated local changes intact, and verify git diff --check.

11. Consistency sweep before finishing

Assessment weights, deadlines, page limits, group size, policy language, and weekly topics appear in five places. After any change to one, check the other four:

1. syllabus/data-8020-syllabus.tex
2. project/data-8020-project.tex
3. lectures/lecture-01/lecture-01-slides.tex and lecture-01.tex (the project introduction)
4. _teaching/data-8020-advanced-causal-inference.md
5. index.md

Rules of thumb: a slide must never state a requirement the handout does not contain; a lecture-focused revision should not silently change published weights or dates; if a slide revision introduces a new formal requirement, add the minimum matching wording to the handout in the same change.

12. Definition of done

• Content decisions recorded in a dated plan file, with what was implemented and what was deliberately left alone.
• Every citation verified; every external figure attributed.
• Notes and slides agree; slides carry correct part footers and slide numbers.
• Companion notebook runs from a clean state and reproduces the committed figures and CSVs.
• PDFs build without errors, undefined references, or serious overfull boxes, and were visually inspected.
• index.md and the teaching page updated for published slides only.
• The five-file consistency sweep passed.
• git status shows only intended changes.

13. Source formatting

Applies to every .tex file in this folder and to the Markdown plan files under the repository root plan/. It does not apply to README.md, index.md, or this file.

One sentence per line. A sentence ends its line; the next sentence starts a new one. This keeps git diff readable — an edited sentence shows up as one changed line instead of a reflowed paragraph — and it makes a single sentence easy to move, cut, reorder, or comment out.

A sentence too long for the column wraps onto continuation lines, indented to match the surrounding block. Two rules bound the wrapping:

• Never split inline mathematics across lines. $Y_i(1) \neq Y_i(0)$, \(\E[Y(1)] - \E[Y(0)]\), a \citet{...} call, and any other macro invocation stay whole on one line, even when that line runs long. A broken formula is hard to read in the source and easy to corrupt in a later edit.
• Otherwise wrap at a clause boundary — after a comma or a dash, or before a conjunction — never mid-phrase.

The same principle governs the rest of the source: one \item per line, one table row per line, one TikZ node or edge per line, and display mathematics on its own lines.

Reflowing existing text to this convention is a formatting-only change. Do it in its own commit, so that a real content diff is never buried inside a re-wrap.