kitsUI：KIT 量尺建構工具

kitsUI 是 kits 的 Shiny 介面。 計算全部交給 kits，kitsUI 只負責畫面、檢查和下載。

四個頁面依序做：

1. ① 資料：上傳長格式資料（可以一次好幾個檔，也收 .csv.gz），勾這一回合的世代與波次。
2. ② 題目校準：沒有題庫時自由校準；有固定檔時，舊題固定在題庫的值，只估新題，並檢查偏移。 「固定了哪些題」列出每一題的狀態，並核對固定的值和題庫完全相同。
3. ③ 連結：內部連結（其他世代 → 參照世代，KIT 是 M36 → M03）與外部連結（參照世代 → D，KIT 是 M03 → D）； 每條連結只做一次，做好就凍結。參照世代在第一回合 ① 選；沒有 D 分數的錨題時，外部連結不適用。 垂直連結圖會接上之前回合的點。
4. ④ 受試者評分：這一回合的分數、分數對照表、題目表，並下載新的固定檔（zip）。 題目表可以設定通過步驟（得分至少幾分算通過）。

下一回合上傳新的波次和上一回合的固定檔，從 ① 再做一次。 最後一頁「使用手冊」有完整的操作步驟與截圖（原稿在 tools/manual/）。 舊的參數不動，早先的分數也不重算。

一個回合可以一次勾好幾個波次。同一個量尺的各波合在一起做一次固定校準，偏移也合起來判斷。 已經收完的好幾波，建議一次勾；以後每次新收一波，再只勾那一波。 兩種做法的對照與 kitsUI 的處理流程，見使用手冊「任務二 → 一次加好幾波」。

每一版的改變

見 NEWS.md。

0.4.0 的新功能

這一版讓 KIT 以外的資料（例如世代不叫 M03、M36，或不是發展量表）也能從頭做到尾。 KIT 的資料照舊：示範資料 M03 + M36 兩回合的題庫、連結、分數和 0.3.12 完全相同（只有偏移紀錄的說明文字改了，見下面）。

• ① 參照世代可以選：第一回合在「這一回合的世代與波次」下面選，資料有 M03 時預設 M03，沒有時是第一個世代。 參照世代寫進固定檔，之後的回合沿用，不能再改。③ ④ 的標題與說明都用實際的世代名稱； 好幾個世代時，每個世代、每個領域各有一條到參照世代的內部連結，③ 有一覽表。
• 外部連結（到 D）只在參照世代有 D 分數的錨題（kits::kits_anchors()，lan、motor、cog）時做。 沒有錨題時 ③ 寫「不適用」，這不是錯誤；④ 分數表的最後分數是參照世代量尺上的 ref_score（取代空白的 d_score）。
• 固定檔的 VERSION 多了每個檔案的 SHA-256（Checksums）。上傳時核對；被改過的固定檔先擋下來， 可以按「仍然使用這個固定檔（我知道它被改過）」。0.3.12 以前的固定檔照樣讀，固定檔資訊寫「沒有核對碼」。 zip 只讀根目錄（或唯一一層資料夾）的檔案，子資料夾裡同名的檔案（例如 old/bank.csv）不會再蓋掉真的檔案。
• ① 波次（wave_m）的單位：月（施測月齡，預設）、年、波次序號，第一回合選，寫進固定檔（VERSION 的 WaveUnit）。 單位不是月時，不照月齡借另一世代的題庫，題目表也不算 age50。之前的固定檔當成月。
• ② 一個量尺停下來時，可以只把它設成「這一回合不做」，其他量尺照樣完成、產生固定檔； 不做的量尺不校準，題庫、連結都不動，checks.csv 記一列 excluded。停下來的紅框裡有一鍵的「這一回合不做…，再校準一次」。
• ② 這一回合的資訊不足、無法估計時（例如每個列次只剩一題可以估計、可以估計的步驟不到 2 個）， 紅字直接說「tsupport B82 這一回合資訊不足，無法估計（…）。按「這一回合不做」跳過這個量尺；題庫與連結不會改變。」， kits 的原文收在下面。kitsUI 不強迫估計，也不把偏移的題或新題改用題庫的值；要使用者按了才跳過。 按了以後，checks.csv 的 excluded 那一列寫「insufficient information to estimate: …」， ② 的摘要與量尺一覽、④ 的固定檔說明都寫出這個量尺是因為資訊不足而跳過。其他原因停下來（資料有問題）時照舊。
• ② 這一回合的資料不能判斷偏移時（能自由校準的題不到 2 題，或上下人數夠的步驟不到 3 個）， 題庫的題固定在題庫的值並 flag，不再停下來（checks.csv 記為 drift not judged, kept fixed）。
• ② 「可固定的題少於幾題」預設依量尺的題數：min(5, 題數的一半)。KIT 的長量表仍是 5；4、5 題的短量表不會每回合都被 flag。
• ② kits 常見的英文錯誤改成白話中文，kits 的原文收在可以打開的「kits 的原文」裡。
• ② 偏移把關的表說清楚兩條線：判斷用的線（全部判斷的步驟畫的）與最後的線（拿掉偏移的步驟以後畫的）。 多了 steps、steps_judged（有判斷的步驟數）、steps_dropped（被拿掉的步驟）、 max_dist_judging（判斷的步驟離判斷用的線最遠的距離，就是判斷用的數字）； kits 的 max_abs_resid 改叫 max_dist_final，它包括沒有判斷的步驟、對最後的線算，只供參考。 表下面寫這個量尺的界線（2 × 殘差標準差）；紀錄的說明改成「第 3 步離判斷用的線 0.40 logit，超過界線 0.31 logit」。 判斷本身沒有改。
• 世代名稱可以有空白（例如「C 1」），領域名稱可以有逗號。
• ① 讀檔：
  • 不是 UTF-8、也不是 Big5 的 CSV（例如 Latin-1）不再讓 R 當掉，改成說明怎麼在 Excel 另存成「CSV UTF-8」。
  • 資料約定以外的欄自動拿掉，並列出拿掉了哪些。
  • wave_m 空白的列不放進來，並提醒有幾列。
  • 像遺漏碼的分數（例如 0–3 分的題有 95–99）會提醒，指到 kitJoin 的「遺漏值處理」。
  • 空檔、只有欄名的檔、分號或 Tab 分隔、欄名大寫都有清楚的訊息。
• 固定檔的建立日期用台灣的日期。
• 0.4.0 寫出的固定檔，0.3.12 也讀得進來（實際用 0.3.12 讀過）： KIT 的固定檔（參照世代 M03、單位是月、世代名稱沒有空白）讀到的題庫、連結、紀錄和 0.4.0 讀到的相同， 接著做的下一回合分數也相同；但 0.3.12 不核對 Checksums。 用到 0.4.0 新功能的固定檔不要給舊版用：0.3.12 讀得進來，但不管 WaveUnit（一律當成月，下一個固定檔也不再有這一行）、 內部與外部連結仍然只認 M03，世代名稱有空白的量尺在下一回合會停下來。請大家都換成 0.4.0。
• 程式碼字型改用 JetBrains Mono（原本是 M PLUS Code Latin），app 與使用手冊都一樣。

0.3.8 的新功能

• ② 每個量尺的結果最上面多了「固定了哪些題」。 每一題一個狀態：固定（沿用題庫）、固定（不判斷偏移，沿用題庫）、偏移 → 新版本、 新題（這一回合估計）、這一回合拿掉、自由校準。 上方有一句核對，例如「固定的 N 題、M 個步驟，參數和題庫完全相同（最大差 0）」。 有任何固定的步驟和題庫不同時，這一句變成紅框。 固定的題收在「看全部固定的題」裡（第一回合是自由校準，寫「看全部自由校準的題」）；整張表可以下載成 CSV。
• ② 的「圖」多了「偏移把關圖」。 橫軸是這一回合自由試算的門檻（固定前），縱軸是題庫的門檻（固定的值）。 虛線是判斷用的線，灰色帶子是容許範圍；實線是拿掉偏移的步驟之後的線。 藍色是固定，灰色菱形是固定但不判斷偏移的題，橘色叉叉是偏移 → 新版本，灰色空心圓是沒有判斷的步驟。
• 校準的順序：先不固定任何題、只用這一波自由試算； 試算的門檻和題庫的門檻比，離 mean/sigma 線太遠的是偏移； 沒有偏移的題固定成題庫的 beta，所以固定之後門檻和題庫相同； 偏移的題換成新版本（例如 lanc09_rR2），用這一波重新估；最後做固定校準。 所以偏移是在固定之前判斷的，固定之後的題不會偏移。
• 比的是門檻，不是 beta。同一題的幾個步驟 beta 會一起移動，也可能順序顛倒； Thurstonian 門檻比較穩定，也好讀。
• ④ 題目表多了「通過步驟」：得分至少幾分算通過，預設每題是 1。 0.3.9 起是收起來的區塊：選題目、填通過步驟、按「套用到選的題」；有題目不是 1 時自動打開。 題目很多時，可以在「用檔案設定」上傳 CSV（item_id、step）或先下載範本；「全部改回 1」回到預設。 題目表多一欄 step，三種門檻與 age50 照它算。 紅字是設定沒有套用；橘字是這一回合沒有的題，設定照樣存著給之後的回合。 校準、連結與分數都用全部的分數，不受影響。① 作答設計圖的通過比例也照它算。 例如之後的認知題是 0–4 分、3 分以上才算通過時用它。
• age50 只從這一回合的資料算：至少兩個波次、通過比例跨過 50%，且在資料的月齡範圍內。 只有一個波次時是空的，不往外推。
• ③ 垂直連結圖：只有一個世代的回合（例如 M03 84 個月借用 M36 題庫）也畫得出來。 之前回合的點來自固定檔的各波次摘要，用現在的連結換算；圖上分得出這一回合與之前的回合。 0.3.8 以前的固定檔沒有摘要，下一回合起或用這一版重跑之前的回合後才有。
• 固定檔多了兩個檔：wave_summary.csv、pass_steps.csv（見下面「固定檔」）。
• 0.3.6–0.3.7：① 上傳失敗時有「開啟 kitJoin」按鈕；程式碼字型改用 M PLUS Code Latin； ③ 內部連結的獨立檢核（kits_link_check()）預設收起來。

固定檔

④ 頁下載的 kitsui_fixed_R1.zip、kitsui_fixed_R2.zip… 是同一把尺。 下一回合一定要上傳它。請不要解壓縮後修改再壓縮：VERSION 記下每個檔案的 SHA-256，改過的檔案上傳時會被擋下來。

檔案	內容
VERSION	版本、建立日期、各回合名稱、參照世代（第一回合選的）、量尺、各回合的資料檔（md5）、波次的單位（WaveUnit，0.4.0 起；沒有這一行是月）、每個檔案的 SHA-256（Checksums，0.4.0 起）
bank.csv	題庫：每個量尺每一題每一步的 beta 與標準誤
versions.csv	題目版本：偏移的題原來的題號與新的題號
waves.csv	每個題庫校準過的波次
wave_summary.csv	各量尺、世代、波次的人數、能力值的 P25、中位數、P75（校準的量尺上）與實際月齡的中位數（0.3.11 起）；只有摘要，沒有個人資料
pass_steps.csv	通過步驟；沒列的題用 1。下一回合沿用；新版本用原來那一題的設定
links.csv	連結的點與設定
checks.csv	每一回合的檢查紀錄（0.4.0 起多了 excluded：這一回合不做的量尺；drift not judged, kept fixed：不能判斷偏移、固定在題庫的值）
README.txt	固定檔的說明

• 固定檔會累積：R2 的固定檔已經包含 R1 的題庫、連結、波次。做 R3 時只上傳 R2 的固定檔。
• 固定檔裡的內容和 README.txt 都是英文，打開不會是亂碼。 要放中文的 CSV（例如自己的中文題號或領域名稱）用 UTF-8 BOM 寫出，Excel 打開也正常。 app 的畫面仍然是中文。

安裝與執行

install.packages("pak")
# pak::pkg_install("jiewenTsai/kitsUI")
install.packages("kitsUI", repos = c('https://jiewentsai.r-universe.dev', 'https://cloud.r-project.org'))   # 會一起裝 kits、kitDesign，並把太舊的套件更新到需要的版本
kitsUI::run_kitsui()

pak 安裝失敗時，可以改用 remotes（upgrade = "always" 才會更新太舊的套件）：

install.packages("remotes")
remotes::install_github("jiewenTsai/kitsUI", upgrade = "always")

Windows 也可以雙擊 run.bat：第一次會自動安裝需要的套件，之後每次打開都會檢查版本， 太舊的會自動更新（照 DESCRIPTION 寫的最低版本）。 打開時說「bslib 版本太舊」：在 R 執行 install.packages("bslib")，再重新開啟。 下載圖檔（HTML）需要 pandoc；裝了 RStudio 或 Quarto 就有。

資料格式

長格式，一列是一個列次（一個孩子的一個波次）的一題作答。

手上的資料是寬格式（一題一欄）、欄名不一樣，或分數不是從 0 開始時， 先用 kitJoin 的「kits 作答檔」轉好再上傳（本機版：在 R 執行 kitJoin::run_kitjoin()，資料不會離開這台電腦）。 ① 資料頁的上傳說明和紅字裡也有「開啟 kitJoin」按鈕。

欄位	必填	意思
visit_id	是	列次編號，每個孩子的每個波次不同
subj_id	否	孩子編號
cohort	是	世代，例如 M03、M36；名稱可以有空白
sex	否	性別
wave_m	是	波次。KIT 是施測月齡；也可以是年或波次序號（在 ① 第一回合選單位）
age_m	否	實際月齡
item_id	是	題號
item_score	是	得分，從 0 開始的整數
domain	是	領域，例如 lan、motor、cog

① 頁可以下載欄位範例檔。 外部連結用 kits::kits_anchors() 的錨題，領域名稱要和它一致（lan、motor、cog）。 參照世代沒有錨題時（例如不是發展量表），外部連結不適用，分數停在參照世代的量尺上（ref_score）。

雲端部署

app.R 是 Posit Connect Cloud 的主檔，manifest.json 記錄套件版本。 新增或移除 R/ 的檔案、或更新套件後，請重新產生 manifest.json：

rsconnect::writeManifest(appPrimaryDoc = "app.R")

雲端版只能上傳已去識別化的資料。

授權

GPL-3。