# MDPI "AI in Medicine" manuscript

## What this project is
Writing a journal article for MDPI's **AI in Medicine** journal (short name
`aimed`, ISSN 3042-6707), on predicting no-reflow / slow-flow complications
after PCI from IVUS images.

## Source material — reference only, not a source of facts
Timeline, oldest first:
1. [Reference/卒業論文_金子_最終.pdf](Reference/卒業論文_金子_最終.pdf) — the
   original graduation thesis (Japanese).
2. [Reference/main.tex](Reference/main.tex) / [main_ja.tex](Reference/main_ja.tex)
   (+ their rendered [main.pdf](Reference/main.pdf) / [main_ja.pdf](Reference/main_ja.pdf))
   — a later MIDL 2026 short paper built on the thesis.

**The dataset and experiments have since changed.** These documents are
useful for prose style, structure, and terminology — they are NOT a source
of current facts. Never cite numbers, case counts, AUC/results, dataset
descriptions, ethics approval numbers, etc. from these files as if they
still hold for the new manuscript. Any such detail needed in the new paper
must come from current data/results the user provides, not by copying it
from these references.

## The manuscript itself
- [main.tex](main.tex) is the actual manuscript and the file to compile —
  edit it (and the files it `\input`s) in place rather than starting new
  files. It was copied from [Template/template.tex](Template/template.tex),
  which is now kept untouched as a pristine copy of the official MDPI
  template for reference (e.g., to check the original
  boilerplate/instructions for a macro) — do not edit it going forward, and
  do not re-derive facts from it, it's just the blank starting point
  main.tex was copied from. It lives in its own `Template/` folder
  (alongside its rendered `template.pdf`) to keep it visually distinct from
  the actual manuscript at the repo root; its `\documentclass`/
  `\includegraphics` calls use `../Definitions/...` to match (still
  resolves to the same [Definitions/](Definitions/) folder).
- The manuscript is split across files rather than written as one block,
  since it's expected to run 10-15 pages (`\input`, not `\include` —
  `\include` forces a `\clearpage` per file, which doesn't suit a short
  continuously-flowing journal article):
  - [sections/](sections/) holds the body, one file per section, numbered
    to match reading order (`1_introduction.tex`, `2_related_work.tex`,
    `3_method.tex`, `4_experiment.tex`, `5_discussion.tex`,
    `6_conclusion.tex`), `\input` from `main.tex` right after each
    `\section{...}` heading. There's no `0_abstract.tex` — see above.
  - [figures/](figures/) holds figure images; subfolder per section if it
    grows large.
  - The **Abstract is the one exception** — it stays written inline inside
    `main.tex`'s `\abstract{...}` call, not split into `sections/`.
    `mdpi.cls` also reuses that same argument verbatim as the PDF's
    `pdfsubject` metadata via hyperref, which requires it to be fully
    expandable; `\input` is not expandable and breaks that (crashes with
    `TeX capacity exceeded`). Confirmed empirically — don't try `\input`
    for the abstract again.
- **Not yet configured for this journal**: the `\documentclass` line
  currently reads `[journal,article,submit,moreauthors]`; before submission
  this must become `[aimed,article,submit,moreauthors]` (or the correct
  article type instead of `article`, if this isn't a standard Article).
  (This applies to `main.tex`; `Template/template.tex` is left as-is.)
- [Definitions/](Definitions/) holds the official MDPI class/style/bst
  files (`mdpi.cls`, `mdpi.bst`, `journalnames.tex`, logos). Don't edit
  these — they're MDPI-supplied.
- `main.tex` references `\bibliography{references}`. [references.bib](references.bib)
  exists but is only a stub (cite keys `babapoor2022`, `wu2011`,
  `nishi2021` carried over from the MIDL paper as a starting point) — real
  bibliographic data still needs to be filled in and verified, and new
  citations added as the manuscript grows.
- [citations/](citations/) holds the PDFs of cited papers (one per
  reference, named after its `.bib` cite key, e.g. `babapoor2022.pdf`).
  Drop a paper's PDF there and Claude Code can read it directly to fill in
  or verify that key's entry in `references.bib` (title, authors, venue,
  year, DOI, etc.) instead of guessing from the key name alone.
- Math/theorem-like environments should use MDPI's names: Theorem, Lemma,
  Corollary, Proposition, Characterization, Property, Problem, Example,
  ExamplesandDefinitions, Hypothesis, Remark, Definition, Notation,
  Assumption (see comments in Template/template.tex, still accurate for
  main.tex).

## Working environment
This repo is edited from more than one machine (Windows/WSL and macOS have
both been used), so don't assume either one — check `uname`/the shell
you're actually in before relying on platform-specific behavior below.

- **Windows/WSL**: the repo lives on the WSL (Ubuntu) filesystem. When it's
  accessed from a Windows-side shell (Git Bash/MSYS, PowerShell) via
  `\\wsl.localhost\...`, WSL's `*:Zone.Identifier` marker files (harmless
  Windows download metadata, no content value) show up with a mangled
  colon character, which makes `git status` report spurious
  deleted/untracked pairs for the same files. These are now covered by
  `.gitignore` — don't try to "fix" them again. Prefer running `git` (and
  anything touching filenames with unusual characters) from inside actual
  WSL, e.g. `wsl.exe -- bash -lc "cd /home/nlab/MDPI && <command>"` from
  PowerShell, rather than Windows Git Bash. Git Bash accessing the repo
  over the UNC path may also need a one-time
  `git config --global --add safe.directory '%(prefix)///wsl.localhost/Ubuntu/home/nlab/MDPI'`
  (dubious-ownership check) — already set on the Windows machine this was
  written from.
- **macOS**: none of the above applies; the repo should behave like a
  normal local git checkout.
- **LaTeX toolchain**: on this WSL machine, TeX Live 2026 is installed at
  `/usr/local/texlive/2026/bin/x86_64-linux/` (a full install — pdflatex,
  latexmk, bibtex, etc.), with `PATH` set in `~/.zshrc` (the default shell
  is zsh). That `PATH` export is only loaded for an *interactive* shell —
  a plain `bash -lc "..."`/`zsh -lc "..."` from Windows (e.g. via
  `wsl.exe --`) won't have it on `PATH` and `which pdflatex` will
  (misleadingly) fail. To compile from outside WSL, use an interactive
  shell explicitly, e.g. from PowerShell:
  `wsl.exe -- zsh -ic "cd /home/nlab/MDPI && pdflatex -interaction=nonstopmode -output-directory=build main.tex"`.
  All generated files (`.pdf`, `.aux`, `.log`, the epstopdf-converted logo,
  etc.) land in [build/](build/) this way, keeping the repo root clean;
  `build/` must exist first (`mkdir -p build`, already done — it's tracked
  as an empty folder via `build/.gitkeep` since its contents are
  gitignored). Verified working: compiling `main.tex` this way produces a
  6-page `build/main.pdf` (only harmless "undefined reference"/rerun
  warnings on the first pass — normal for LaTeX before a second pass
  resolves cross-references). On a machine without this TeX Live install
  (e.g. a fresh macOS checkout), install one (`brew install --cask mactex`
  or the smaller `basictex`, or `sudo apt install texlive-full` on Linux)
  or compile via Overleaf instead (Overleaf manages its own build output
  and ignores this convention).
- **VS Code (LaTeX Workshop)**: [.vscode/settings.json](.vscode/settings.json)
  sets a latexmk recipe that outputs to `build/`. On Windows, VS Code must
  have the folder open *in WSL* (Remote-WSL: "WSL: Reopen Folder in WSL",
  or `code .` from a WSL shell) — opening it via the `\\wsl.localhost\...`
  UNC path runs LaTeX Workshop on the Windows side, where no TeX is
  installed, so building fails.

## Writing conventions
- Manuscript language is English (MDPI submission requirement), even
  though some source material (`main_ja.tex`, the thesis PDF) is Japanese.
- Follow the MIDL paper's terminology (e.g. "attenuated plaque",
  "polar coordinate transformation", "CNN-LSTM") for consistency unless a
  term needs to change for the current data/results or a journal audience.
- Never fill a gap with an unstated inference — don't write claims,
  numbers, or details the user hasn't given. If something needed for the
  manuscript is unclear or unspecified, ask rather than guess.
- When rendering Japanese source material (the thesis, `main_ja.tex`) into
  English, translate faithfully — not a loose paraphrase — while still
  producing natural, idiomatic English rather than a stiff word-for-word
  rendering.
- **Line wrapping (semantic linefeeds + a soft ~80-char cap)**: in prose
  files (`sections/*.tex`, `drafts/ja/*.md`), start a new line at each
  sentence boundary (English `.`/`!`/`?` + space; Japanese `。`/`．`)
  instead of writing a whole paragraph as one unbroken line. That alone
  isn't enough — a single sentence can still run well past a readable
  width — so also keep every line at roughly 80 characters: if a sentence
  (or an enumerated `(1)/(2)/(3)` item within one) is longer than that,
  break it further at a clean clause boundary at or before the ~80-char
  mark (comma, semicolon, or a coordinating/subordinating conjunction
  like "and"/"but"/"because"/"which"/"while"/"however"; Japanese
  `，`/`、`/接続助詞など), continuing flush-left with no extra indent —
  never break mid-phrase just to hit the column exactly. A single newline
  is invisible in the rendered output — both LaTeX and Markdown treat it
  as a space within a paragraph, and only a blank line starts a new
  paragraph — so this is purely a source-readability/diff convention, not
  something that changes the PDF. Applies whenever a prose file is newly
  written or substantively redrafted (including the
  `ja-drafter`/`en-translator` pipeline output); not a mandate to
  mass-reflow untouched files.

## Drafting workflow (subagents)
Sections get written through a fixed pipeline rather than drafted directly
in English in one pass. Each stage is a project subagent under
[.claude/agents/](.claude/agents/); read a stage's `.md` file for its full
brief before invoking it.

1. **Discussion** — no subagent; this is an ordinary conversation between
   the user and the main session to settle what a section should say
   (outline, argument, which facts/numbers apply).
2. **`ja-drafter`** — writes a Japanese prose draft of the section from
   that outline into [drafts/](drafts/)`ja/<N>_<name>.md` (mirroring
   `sections/` numbering). Only uses facts given to it explicitly; never
   pulls numbers from `Reference/`.
3. **Review, in parallel, on the Japanese draft:**
   - **`fact-checker`** — checks every number/statistic against the Notion
     page (below) and flags anything unsupported or copied from `Reference/`.
   - **`content-reviewer`** — checks logical coherence, clinical
     plausibility, and terminology consistency with `Reference/main.tex`.
   Both are read-only; they report findings rather than editing.
4. **`en-translator`** — once review findings are resolved, translates the
   reviewed `drafts/ja/*.md` file into faithful, idiomatic English LaTeX
   and writes it into the matching `sections/*.tex` file. Never changes a
   number during translation.

Re-run the review stage (3) after any substantive re-draft, and again on
the English output of stage 4 if it's not a purely mechanical translation.

## 実験に関するデータの参照場所
https://app.notion.com/p/AI-in-Medicine-3df9efa583a0803eba3ed15f51bf1b2a?source=copy_link

##注意点
上記のNotion以外の数字は基本的に信頼しないこと