Per-board participation guide with a ready-to-paste prompt and a runnable skeleton

A generic guide makes each entrant adapt it to their board, and most drop out at that step. The guide tab now fills in this board target, split year, experimental error and baselines, so the prompt and the starter script can be copied as they are.

i18n.js

@@ -171,7 +171,31 @@ ko: {
 
   secOpen: "개설 예정",
   openLead: "각 부문은 홀드아웃과 실험 오차가 확보된 뒤에 엽니다. 확보되지 않은 부문은 열지 않습니다.",
-  learnMore: "자세히"
+  learnMore: "자세히",
+
+  tabGuide: "참여 가이드",
+  gdIntro: "예측 도구를 처음 만드신다면 아래 순서대로 하시면 됩니다. " +
+           "직접 코딩하셔도 되고, 아래 프롬프트를 언어모델에 그대로 붙여 넣으셔도 됩니다.",
+  gdWhat: "무엇을 만드는가",
+  gdWhatD: "화합물 구조(SMILES)를 받아 <b>값 하나</b>를 내놓는 함수입니다. " +
+           "그 값이 실측과 얼마나 가까운지로 채점합니다.",
+  gdPrompt: "언어모델용 프롬프트",
+  gdPromptD: "아래를 통째로 복사해 Claude · GPT · Gemini 등에 붙여 넣으십시오. " +
+             "이 부문의 값이 이미 채워져 있습니다.",
+  gdCopy: "복사", gdCopied: "복사됨",
+  gdStarter: "바로 돌려볼 수 있는 뼈대",
+  gdStarterD: "직접 짜시려면 이 뼈대에서 시작하십시오. 훈련 자료를 받아 지문을 만들고 " +
+              "모델을 학습해 제출 파일까지 씁니다.",
+  gdRules: "지켜야 할 것",
+  gdR1: "기준일 이후 최초 보고된 화합물은 학습에 쓰지 마십시오. 그것이 테스트셋입니다.",
+  gdR2: "같은 화합물이 여러 논문에 있으면 InChIKey 로 접어 중앙값을 쓰십시오. " +
+        "문자열로 접으면 같은 분자가 여러 번 들어갑니다.",
+  gdR3: "정답을 조회해 채우지 마십시오. 예측값이 실측과 소수 자리까지 일치하는 밀도를 " +
+        "검사해 순위표에 함께 표시합니다.",
+  gdR4: "방법에는 제한이 없습니다. 지문+트리 · 그래프 신경망 · 사전학습 모델 · 물리 계산 " +
+        "무엇이든 좋습니다.",
+  gdTarget: "넘어야 할 선",
+  gdTargetD: "기준선을 넘지 못하면 순위표에서 그 아래에 표시됩니다.",
 },
 
 en: {
@@ -355,6 +379,30 @@ en: {
   secOpen: "Opening next",
   openLead: "A board opens only once its holdout and experimental error are established. " +
             "Boards without them are not opened.",
-  learnMore: "Detail"
+  learnMore: "Detail",
+
+  tabGuide: "Guide",
+  gdIntro: "If this is your first predictor, follow the steps below. Write it yourself, " +
+           "or paste the prompt into a language model as it is.",
+  gdWhat: "What you are building",
+  gdWhatD: "A function that takes a structure (SMILES) and returns <b>one number</b>. " +
+           "We score how close that number is to the measured value.",
+  gdPrompt: "Prompt for a language model",
+  gdPromptD: "Copy the whole block into Claude, GPT, Gemini or similar. " +
+             "The values for this board are already filled in.",
+  gdCopy: "Copy", gdCopied: "Copied",
+  gdStarter: "A skeleton you can run",
+  gdStarterD: "If you would rather write it yourself, start here. It pulls the training data, " +
+              "builds fingerprints, fits a model and writes the submission file.",
+  gdRules: "Rules to observe",
+  gdR1: "Do not train on compounds first reported on or after the split year. That is the test set.",
+  gdR2: "Fold duplicate measurements by InChIKey and take the median. Folding by SMILES string " +
+        "leaves the same molecule in several times.",
+  gdR3: "Do not fill predictions by looking up the answer. We measure how many predictions match " +
+        "the measured value to the decimal and show it on the leaderboard.",
+  gdR4: "There is no restriction on method. Fingerprints and trees, graph networks, pretrained " +
+        "models, physics-based calculation — all are fine.",
+  gdTarget: "Lines to cross",
+  gdTargetD: "A submission that does not clear a baseline is shown below it on the leaderboard.",
 }
 };

index.html

@@ -469,7 +469,7 @@ async function board(name,tab){
   const b=BOARDS[name]||await j("/api/board/"+encodeURIComponent(name));
   const cat=CATS.categories.find(c=>(c.boards||[]).includes(name));
   const cn=cat?(L==="ko"?cat.name:cat.en):"";
-  const TT=[["rank",t.tabRank],["submit",t.tabSubmit],["info",t.tabInfo]];
+  const TT=[["rank",t.tabRank],["submit",t.tabSubmit],["guide",t.tabGuide],["info",t.tabInfo]];
   app.innerHTML=W(`
     <div class="crumb"><a href="#/">${t.all}</a> › <a href="#/c/${cat?cat.id:""}">${esc(cn)}</a> › ${esc(b.board)}</div>
     <h1 class="ttl">${esc(b.board)}<span class="chip">${b.split_grade}/${b.answer_grade}</span></h1>
@@ -480,6 +480,7 @@ async function board(name,tab){
     <div id="pane"><div class="skel" style="margin-top:20px"></div></div>`);
   if(tab==="rank")return paneRank(b);
   if(tab==="submit")return paneSubmit(b);
+  if(tab==="guide")return paneGuide(b);
   paneInfo(b);
 }
 
@@ -511,6 +512,123 @@ async function paneRank(b){
       : t.noEntries}</p>`;
 }
 
+/* 부문 값이 채워진 참여 가이드. 일반문으로 두면 참가자가 자기 부문에 맞게 고쳐야 하고,
+   대부분 그 단계에서 떨어진다. */
+function promptFor(b){
+  const nf=(b.noise_floor||{}).sd_single;
+  const bl=Object.entries(b.baselines||{})
+    .map(([k,v])=>`  ${k}: ${v.mae!=null?("MAE "+f(v.mae)):("AUROC "+f(v.auroc))}`).join("\n");
+  const unit = b.type && b.type.indexOf("logS")>=0
+    ? "logS = log10(용해도 in mol/L)"
+    : b.threshold==null ? "부문 정의값" : "p 스케일 = -log10(농도 in M)";
+  return [
+`나는 신약 예측 도구 시험대 LEADBOARD 의 "${b.board}" 부문에 참가한다.`,
+`아래 조건대로 예측 파일을 만드는 Python 스크립트를 작성해 달라.`,
+``,
+`[과제]`,
+`  입력   ${b.board.toLowerCase()}_test.json  — compound_id 와 SMILES 만 들어 있다 (${b.n_test}개)`,
+`  출력   predictions.csv — 두 열: compound_id,prediction`,
+`  예측값  ${unit}`,
+b.target && b.target!=="—" ? `  대상   ${b.target} · ${b.type}` : `  대상   ${b.type}`,
+``,
+`[학습 자료]`,
+b.cut ? `  ChEMBL 에서 ${b.target} 의 ${b.type} 활성을 받아 쓴다.` : `  공개 자료를 직접 큐레이션해 쓴다.`,
+b.cut ? `  ★ ${b.cut}년 이후 처음 보고된 화합물은 학습에 넣지 말 것 — 그것이 테스트셋이다.` : ``,
+`  같은 화합물이 여러 논문에 있으면 InChIKey 로 접어 중앙값을 쓸 것.`,
+``,
+`[제약]`,
+`  방법에 제한은 없다. 지문+트리, 그래프 신경망, 사전학습 모델, 물리 계산 모두 가능.`,
+`  정답을 조회해 채우지 말 것. 예측값이 실측과 소수 자리까지 일치하는 밀도를 검사한다.`,
+``,
+`[평가]`,
+`  주지표 ${b.metric==="auroc"?"AUROC (높을수록 좋음)":"MAE (낮을수록 좋음)"}`,
+nf ? `  이 부문의 실험 재현 오차는 ${f(nf)} 이다. 그보다 작은 차이는 순위로 인정되지 않는다.` : ``,
+`  넘어야 할 기준선:`,
+bl,
+``,
+`스크립트는 자료 수집 → 정제 → 특징 → 학습 → 예측 → CSV 저장까지 한 파일로 작성해 달라.`
+].filter(x=>x!==``||true).join("\n");
+}
+
+function starterFor(b){
+  return [
+`# ${b.board} 제출 뼈대`,
+`import json, math, requests, numpy as np`,
+`from rdkit import Chem`,
+`from rdkit.Chem import rdFingerprintGenerator`,
+`import lightgbm as lgb`,
+``,
+`# 1) 훈련 자료  (ChEMBL 에서 받는다)`,
+`API = "https://www.ebi.ac.uk/chembl/api/data/activity.json"`,
+`rows, off = [], 0`,
+`while True:`,
+`    q = {"target_chembl_id": "${b.target}", "standard_type": "${b.type}",`,
+`         "standard_relation": "=", "limit": 1000, "offset": off}`,
+`    d = requests.get(API, params=q, timeout=120).json()`,
+`    rows += d["activities"]; off += 1000`,
+`    if off >= d["page_meta"]["total_count"]: break`,
+``,
+`# 2) 정제 — InChIKey 로 접고, 기준일 이후는 버린다`,
+`rec = {}`,
+`for r in rows:`,
+`    s, v, u, y = r["canonical_smiles"], r["standard_value"], r["standard_units"], r["document_year"]`,
+`    if not (s and v and u == "nM" and y): continue`,
+`    m = Chem.MolFromSmiles(s)`,
+`    if m is None or float(v) <= 0: continue`,
+`    k = Chem.MolToInchiKey(m)`,
+`    rec.setdefault(k, {"y": [], "p": [], "m": m})`,
+`    rec[k]["y"].append(int(y)); rec[k]["p"].append(9.0 - math.log10(float(v)))`,
+`train = {k: v for k, v in rec.items() if min(v["y"]) < ${b.cut||2022}}   # ★ 테스트셋 제외`,
+``,
+`# 3) 특징 · 학습`,
+`gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)`,
+`X = np.array([gen.GetFingerprintAsNumPy(v["m"]) for v in train.values()])`,
+`Y = np.array([float(np.median(v["p"])) for v in train.values()])`,
+`model = lgb.LGBMRegressor(n_estimators=500, learning_rate=0.05).fit(X, Y)`,
+``,
+`# 4) 예측 · 저장`,
+`test = json.load(open("${b.board.toLowerCase()}_test.json", encoding="utf-8"))`,
+`Xt = np.array([gen.GetFingerprintAsNumPy(Chem.MolFromSmiles(c["smiles"]))`,
+`               for c in test["compounds"]])`,
+`p = model.predict(Xt)`,
+`with open("predictions.csv", "w") as f:`,
+`    f.write("compound_id,prediction\n")`,
+`    for c, v in zip(test["compounds"], p):`,
+`        f.write("%s,%.4f\n" % (c["compound_id"], v))`
+].join("\n");
+}
+
+function paneGuide(b){
+  const pr=promptFor(b), sk=starterFor(b);
+  const bl=Object.entries(b.baselines||{}).sort((x,y)=>
+    (x[1].mae!=null?x[1].mae:-x[1].auroc)-(y[1].mae!=null?y[1].mae:-y[1].auroc));
+  $("#pane").innerHTML=`
+    <p class="lede" style="margin:6px 0 18px">${t.gdIntro}</p>
+    <h3>${t.gdWhat}</h3><p class="dim" style="font-size:14.5px">${t.gdWhatD}</p>
+    <h3>${t.gdPrompt}</h3><p class="dim" style="font-size:14px">${t.gdPromptD}</p>
+    <div style="position:relative">
+      <button class="btn" id="cp1" style="position:absolute;right:12px;top:12px;padding:6px 13px;font-size:12px">${t.gdCopy}</button>
+      <pre class="fig" style="white-space:pre-wrap;margin:0">${esc(pr)}</pre></div>
+    <h3>${t.gdStarter}</h3><p class="dim" style="font-size:14px">${t.gdStarterD}</p>
+    <div style="position:relative">
+      <button class="btn" id="cp2" style="position:absolute;right:12px;top:12px;padding:6px 13px;font-size:12px">${t.gdCopy}</button>
+      <pre class="fig" style="white-space:pre;overflow-x:auto;margin:0;font-size:12px">${esc(sk)}</pre></div>
+    <h3>${t.gdTarget}</h3><p class="dim" style="font-size:14px">${t.gdTargetD}</p>
+    <div class="tw"><table><thead><tr><th style="text-align:left;width:auto">${t.baseH}</th>
+      <th>MAE</th><th>AUROC</th></tr></thead><tbody>
+      ${bl.map(([k,v])=>`<tr><td style="text-align:left">${esc(k)}</td>
+        <td>${v.mae!=null?f(v.mae):"—"}</td><td>${v.auroc!=null?f(v.auroc):"—"}</td></tr>`).join("")}
+      </tbody></table></div>
+    <h3>${t.gdRules}</h3>
+    <ol class="cl" style="grid-template-columns:1fr">
+      ${[t.gdR1,t.gdR2,t.gdR3,t.gdR4].map(x=>`<li><span>${x}</span></li>`).join("")}
+    </ol>`;
+  const wireCopy=(id,txt)=>{const el=$("#"+id); if(!el)return;
+    el.onclick=async()=>{try{await navigator.clipboard.writeText(txt);
+      el.textContent=t.gdCopied; setTimeout(()=>el.textContent=t.gdCopy,1600);}catch(e){}};};
+  wireCopy("cp1",pr); wireCopy("cp2",sk);
+}
+
 function paneInfo(b){
   const nf=b.noise_floor, bl=b.baselines;
   $("#pane").innerHTML=`