diff --git a/Makefile b/Makefile index 8cdabf2..68cb8c1 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ PY := uv run python evaluate-peptide-hla-rank-sensitivity build-fixed-sensitivities \ evaluate-exact-peptide-sensitivity evaluate-near-sensitivity \ evaluate-length-sensitivity manifest validate-metrics reproduce-results full-reproduce test \ - verify-reproduction validate-literature status + verify-reproduction validate-literature status readme-i18n-status check-readme-i18n install: uv sync --extra dev --extra analysis @@ -252,3 +252,9 @@ validate-literature: status: uv run neorepro status + +readme-i18n-status: + $(PY) scripts/readme_i18n.py status + +check-readme-i18n: + $(PY) scripts/readme_i18n.py check diff --git a/README.de.md b/README.de.md new file mode 100644 index 0000000..98704c7 --- /dev/null +++ b/README.de.md @@ -0,0 +1,51 @@ +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) + +# NeoRepro + +NeoRepro ist eine reproduzierbare, patientenbezogene Benchmark-Ressource für öffentliche MHC-I-Peptid–HLA-Neoantigen-Prädiktoren unter Berücksichtigung von Datenlecks. Sie bündelt festgeschriebene Prädiktor-Artefakte, Provenienz auf Datensatzebene, Prüfungen auf Überschneidungen mit Trainingsdaten, Vergleiche auf einer gemeinsamen Auswertungsmenge, patientenbezogene Unsicherheit, an die Abdeckung angepasste Zufallsreferenzen und maschinell erzeugte Ergebnisse. + +Der Beitrag ist eine Benchmark- und Forschungsressource, kein neuer Prädiktor und keine Behauptung eines universell besten Modells oder klinischen Nutzens. + +## Einstieg + +- **Aktuelles Manuskript:** [als Ressource positioniertes Manuskript](paper/manuscript_resource.md). +- **Evidenz in zwei Minuten:** [zweisprachige Expertenübersicht](output/pdf/neorepro_expert_brief_bilingual.pdf) und [Zusammenfassung der unabhängigen Kohortenerweiterung](reports/extension_summary.md). +- **Festgeschriebene Ergebnisse reproduzieren:** den Befehl im Abschnitt „Reproduktion“ verwenden. +- **Feste Version zitieren:** [CITATION.cff](CITATION.cff) und [v0.1.0 release](https://github.com/stevezkw1998/NeoRepro/releases/tag/v0.1.0). + +Der wissenschaftliche Vertrag und Umfang stehen in [RESEARCH_SPEC.md](RESEARCH_SPEC.md). + +## Status + +- Aktuelle Literaturprüfung: abgeschlossen; Entscheidung `RESCOPE, then GO` +- Reproduzierte Prädiktoren: MHCflurry 2.2.1, BigMHC v1.0, PRIME 2.0, DeepImmuno-CNN und DeepHLApan +- TESLA-Pilot: abgeschlossen; als Positivkontrolle für Trainingsdatenüberschneidung neu eingestuft +- Primärer Benchmark: IMPROVE, 17,475 nach Leakage-Filterung verbleibende Datensätze, 70 Patienten, 3 Kohorten +- Primäre IMPROVE-Inferenz: abgeschlossen; 52,425 Vorhersagen fester Werkzeuge ohne fehlende Datensätze +- Manuskript: [Ressourcenfassung](paper/manuscript_resource.md), aus festgeschriebenen Ergebnisdateien erzeugt; unabhängige statistische und biologische Prüfung abgeschlossen + +## Hauptergebnis + +Die offizielle PRIME2-Ergänzung zeigte, dass alle 520 Datensätze der anfänglichen TESLA-Testmenge exakte Trainingsüberschneidungen waren; sie bleiben daher nur als Leakage-Positivkontrolle erhalten. Im auf exakte Überschneidungen gefilterten und nach Präsentation vorselektierten gemeinsamen IMPROVE-Benchmark erreichte PRIME eine AUROC von 0.597 und einen mittleren patientenbezogenen pMHC-Recall@20 von 0.260; BigMHC erreichte 0.546 beziehungsweise 0.146. In der unabhängigen Zhao-Impfkohorte betrug der patientenbezogene NDCG@5 für BigMHC 0.658 gegenüber einer an die Abdeckung angepassten Zufallsreferenz von 0.578. DeepHLApan erreichte 0.580 gegenüber 0.578, DeepImmuno-CNN bei 43.8% Abdeckung 0.755 gegenüber 0.759. Die Ergebnisse stützen einen prüfbaren, auf Aufgabe und Auswertungsmenge abgestimmten Bewertungsvertrag, keine universelle Rangliste. + +## Reproduktion + +[uv](https://docs.astral.sh/uv/) installieren und anschließend mit dem im Projekt festgeschriebenen CPython 3.11.15 alle Analysen, Abbildungen, Tabellen und Manuskriptartefakte aus den versionierten Benchmark- und Vorhersagedateien neu erzeugen: + +```bash +make -j4 reproduce-results +``` + +Unabhängige bootstrap-Analysen werden von Make parallelisiert. Bei begrenzter CPU oder begrenztem Arbeitsspeicher `make reproduce-results` ohne `-j4` verwenden. `make -j4 full-reproduce` lädt zusätzlich die festgeschriebenen öffentlichen Quelldaten herunter und installiert bzw. startet die Prädiktoren Dritter. Dafür müssen die ausschließlich akademischen Bedingungen von BigMHC und PRIME ausdrücklich akzeptiert werden; außerdem sind mehrere GB Speicherplatz und eine deutlich längere Laufzeit erforderlich. + +## Evidenzkette + +- **Primärer wissenschaftlicher Nachweis:** [aktuelles Manuskript](paper/manuscript_resource.md), [Abschlussbericht](FINAL_REPORT.md) und [Prüfprotokoll](paper/reviewer_response.md). +- **Prüfbare Ausgaben:** [endgültige Ergebnistabelle](results/final_results.csv), [Abbildungen](results/figures/), [Prüfung auf Trainingsüberschneidungen](research/training_overlap_summary_improve.json) und [SHA-256-Manifest](results/manifest.json). +- **Publikationsplanung:** [Strategie für Zielzeitschriften](reports/target_venues_2026-08-20.md). + +Die unabhängige Erweiterung um die Zhao 2026-Impfkohorte lässt sich mit `make -j4 extension` reproduzieren. Die kompakte Evidenzübersicht steht in [reports/extension_summary.md](reports/extension_summary.md), der vor der Inferenz festgeschriebene Studienvertrag in [research/extension_protocol.json](research/extension_protocol.json). Der externe Endpunkt ist ELISPOT nach der Impfung und Verabreichung peptidgepulster dendritischer Zellen; er darf nicht als natürliche Tumorpräsentation oder klinische Wirksamkeit interpretiert werden. + +## Lizenz + +Der ursprüngliche Code und die Dokumentation von NeoRepro stehen unter der MIT License. Für Prädiktoren und Datensätze Dritter gelten weiterhin deren eigene Bedingungen; die Aufnahme in die Studie bedeutet keine Erlaubnis zur Weiterverbreitung. diff --git a/README.es.md b/README.es.md new file mode 100644 index 0000000..009f99f --- /dev/null +++ b/README.es.md @@ -0,0 +1,51 @@ +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) + +# NeoRepro + +NeoRepro es un recurso de evaluación reproducible, sensible a la fuga de datos y a nivel de paciente para predictores públicos de neoantígenos péptido–HLA de MHC-I. Reúne artefactos de predictores fijados, procedencia por registro, auditorías de solapamiento con datos de entrenamiento, comparaciones sobre soporte común, incertidumbre a nivel de paciente, referencias aleatorias ajustadas al soporte y resultados generados automáticamente. + +Es una contribución de referencia y recursos, no un predictor nuevo ni una afirmación de que exista un modelo universalmente ganador o de utilidad clínica. + +## Por dónde empezar + +- **Manuscrito actual:** [manuscrito orientado como recurso](paper/manuscript_resource.md). +- **Resumen de la evidencia en dos minutos:** [informe bilingüe para expertos](output/pdf/neorepro_expert_brief_bilingual.pdf) y [resumen de la extensión con cohorte independiente](reports/extension_summary.md). +- **Reproducir los resultados fijados:** usar el comando de la sección «Reproducción». +- **Citar una versión fija:** [CITATION.cff](CITATION.cff) y [v0.1.0 release](https://github.com/stevezkw1998/NeoRepro/releases/tag/v0.1.0). + +El contrato científico y el alcance están en [RESEARCH_SPEC.md](RESEARCH_SPEC.md). + +## Estado + +- Auditoría de la literatura actual: completa; decisión `RESCOPE, then GO` +- Predictores reproducidos: MHCflurry 2.2.1, BigMHC v1.0, PRIME 2.0, DeepImmuno-CNN y DeepHLApan +- Piloto TESLA: completo; reclasificado como control positivo de solapamiento con entrenamiento +- Evaluación principal: IMPROVE, 17,475 registros tras filtrar fugas, 70 pacientes y 3 cohortes +- Inferencia principal de IMPROVE: completa; 52,425 predicciones de herramientas fijas sin registros ausentes +- Manuscrito: [versión orientada como recurso](paper/manuscript_resource.md), generada a partir de resultados fijados; revisión estadística y biológica independiente completada + +## Resultado principal + +El suplemento oficial de PRIME2 mostró que los 520 registros del conjunto TESLA inicial eran solapamientos exactos con el entrenamiento, por lo que se conservan únicamente como control positivo de fuga. En la evaluación IMPROVE de soporte común, filtrada por solapamiento exacto y preseleccionada por presentación, PRIME obtuvo una AUROC de 0.597 y un Recall@20 medio paciente-pMHC de 0.260; BigMHC obtuvo 0.546 y 0.146. En la cohorte independiente de vacunación de Zhao, el NDCG@5 por paciente de BigMHC fue 0.658 frente a una referencia aleatoria ajustada al soporte de 0.578. DeepHLApan obtuvo 0.580 frente a 0.578, y DeepImmuno-CNN 0.755 frente a 0.759 con una cobertura del 43.8%. Estos resultados respaldan un contrato de evaluación auditable y consciente de la tarea y del soporte, no una clasificación universal. + +## Reproducción + +Instale [uv](https://docs.astral.sh/uv/) y reconstruya todos los análisis, figuras, tablas y artefactos del manuscrito con CPython 3.11.15 fijado por el proyecto y los archivos versionados de evaluación y predicción: + +```bash +make -j4 reproduce-results +``` + +Make paraleliza los análisis bootstrap independientes. Use `make reproduce-results` sin `-j4` si la CPU o la memoria son limitadas. `make -j4 full-reproduce` también descarga los datos públicos fijados e instala y ejecuta predictores de terceros. Requiere aceptar expresamente las condiciones de uso exclusivamente académico de BigMHC y PRIME, varios GB de espacio en disco y un tiempo de ejecución considerablemente mayor. + +## Cadena de evidencia + +- **Registro científico principal:** [manuscrito actual](paper/manuscript_resource.md), [informe final](FINAL_REPORT.md) y [registro de revisión](paper/reviewer_response.md). +- **Resultados auditables:** [tabla final de resultados](results/final_results.csv), [figuras](results/figures/), [auditoría de solapamiento con entrenamiento](research/training_overlap_summary_improve.json) y [manifiesto SHA-256](results/manifest.json). +- **Planificación del envío:** [estrategia de revistas objetivo](reports/target_venues_2026-08-20.md). + +La extensión independiente con la cohorte de vacunación Zhao 2026 se reproduce con `make -j4 extension`. El resumen conciso de la evidencia está en [reports/extension_summary.md](reports/extension_summary.md), y el contrato congelado antes de la inferencia en [research/extension_protocol.json](research/extension_protocol.json). El criterio externo es ELISPOT posterior a la vacunación tras administrar células dendríticas pulsadas con péptidos; no debe interpretarse como presentación tumoral natural ni eficacia clínica. + +## Licencia + +El código y la documentación originales de NeoRepro utilizan la MIT License. Los predictores y conjuntos de datos de terceros conservan sus propias condiciones; su inclusión en el estudio no implica permiso de redistribución. diff --git a/README.fr.md b/README.fr.md new file mode 100644 index 0000000..3a8280e --- /dev/null +++ b/README.fr.md @@ -0,0 +1,51 @@ +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) + +# NeoRepro + +NeoRepro est une ressource d’évaluation reproductible, tenant compte des fuites de données et menée au niveau du patient, pour les prédicteurs publics de néoantigènes peptide–HLA de MHC-I. Elle rassemble des artefacts de prédicteurs épinglés, la provenance de chaque enregistrement, des audits de chevauchement avec les données d’entraînement, des comparaisons sur un support commun, l’incertitude au niveau du patient, des références aléatoires adaptées au support et des résultats générés automatiquement. + +Il s’agit d’une contribution de type ressource et benchmark, et non d’un nouveau prédicteur ni d’une affirmation concernant un modèle universellement gagnant ou une utilité clinique. + +## Pour commencer + +- **Manuscrit actuel :** [manuscrit positionné comme ressource](paper/manuscript_resource.md). +- **Synthèse des preuves en deux minutes :** [note bilingue pour experts](output/pdf/neorepro_expert_brief_bilingual.pdf) et [résumé de l’extension sur une cohorte indépendante](reports/extension_summary.md). +- **Reproduire les résultats figés :** utiliser la commande de la section « Reproduction » ci-dessous. +- **Citer une version figée :** [CITATION.cff](CITATION.cff) et [v0.1.0 release](https://github.com/stevezkw1998/NeoRepro/releases/tag/v0.1.0). + +Le contrat scientifique et le périmètre sont décrits dans [RESEARCH_SPEC.md](RESEARCH_SPEC.md). + +## État + +- Audit de la littérature actuelle : terminé ; décision `RESCOPE, then GO` +- Prédicteurs reproduits : MHCflurry 2.2.1, BigMHC v1.0, PRIME 2.0, DeepImmuno-CNN et DeepHLApan +- Pilote TESLA : terminé ; reclassé comme contrôle positif de chevauchement avec l’entraînement +- Benchmark principal : IMPROVE, 17,475 enregistrements après filtrage des fuites, 70 patients et 3 cohortes +- Inférence IMPROVE principale : terminée ; 52,425 prédictions d’outils fixes sans enregistrement manquant +- Manuscrit : [version positionnée comme ressource](paper/manuscript_resource.md), générée à partir des résultats figés ; revues statistique et biologique indépendantes terminées + +## Résultat principal + +Le supplément officiel de PRIME2 a montré que les 520 enregistrements du jeu TESLA initial correspondaient exactement aux données d’entraînement ; ils ne sont donc conservés que comme contrôle positif de fuite. Sur le benchmark commun IMPROVE, filtré pour exclure les chevauchements exacts et présélectionné selon la présentation, PRIME a obtenu une AUROC de 0.597 et un Recall@20 patient-pMHC moyen de 0.260 ; BigMHC a obtenu respectivement 0.546 et 0.146. Dans la cohorte vaccinale indépendante de Zhao, le NDCG@5 par patient de BigMHC était de 0.658, contre une référence aléatoire adaptée au support de 0.578. DeepHLApan obtenait 0.580 contre 0.578, et DeepImmuno-CNN 0.755 contre 0.759 avec une couverture de 43.8%. Ces résultats soutiennent un contrat d’évaluation auditable, explicite sur la tâche et le support, et non un classement universel. + +## Reproduction + +Installez [uv](https://docs.astral.sh/uv/), puis reconstruisez toutes les analyses, figures, tables et tous les artefacts du manuscrit avec CPython 3.11.15 épinglé par le projet et les fichiers de benchmark et de prédiction versionnés : + +```bash +make -j4 reproduce-results +``` + +Make parallélise les analyses bootstrap indépendantes. Utilisez `make reproduce-results` sans `-j4` si les ressources CPU ou mémoire sont limitées. `make -j4 full-reproduce` télécharge également les données sources publiques épinglées, puis installe et exécute les prédicteurs tiers. Cette commande exige l’acceptation explicite des conditions d’utilisation académique de BigMHC et PRIME, plusieurs GB d’espace disque et une durée d’exécution nettement supérieure. + +## Chaîne de preuves + +- **Dossier scientifique principal :** [manuscrit actuel](paper/manuscript_resource.md), [rapport final](FINAL_REPORT.md) et [dossier de revue](paper/reviewer_response.md). +- **Sorties auditables :** [table finale des résultats](results/final_results.csv), [figures](results/figures/), [audit du chevauchement avec l’entraînement](research/training_overlap_summary_improve.json) et [manifeste SHA-256](results/manifest.json). +- **Planification de la soumission :** [stratégie des revues cibles](reports/target_venues_2026-08-20.md). + +L’extension indépendante sur la cohorte vaccinale Zhao 2026 est reproduite avec `make -j4 extension`. La synthèse concise des preuves se trouve dans [reports/extension_summary.md](reports/extension_summary.md), et le contrat figé avant l’inférence dans [research/extension_protocol.json](research/extension_protocol.json). Le critère externe est un ELISPOT après vaccination et administration de cellules dendritiques chargées en peptides ; il ne doit pas être interprété comme une présentation tumorale naturelle ni comme une efficacité clinique. + +## Licence + +Le code et la documentation d’origine de NeoRepro utilisent la MIT License. Les prédicteurs et jeux de données tiers restent soumis à leurs propres conditions ; leur inclusion dans l’étude n’implique pas une autorisation de redistribution. diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..ee9012c --- /dev/null +++ b/README.ja.md @@ -0,0 +1,51 @@ +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) + +# NeoRepro + +NeoRepro は、公開されている MHC-I ペプチド–HLA ネオアンチゲン予測器を対象とした、リーケージを考慮した患者単位の再現可能なベンチマークリソースです。固定された予測器アーティファクト、レコード単位の来歴、学習データ重複監査、共通評価可能集合での比較、患者単位の不確実性、評価可能範囲を一致させたランダムベースライン、および機械生成結果をまとめています。 + +本プロジェクトはベンチマーク/リソースとしての貢献であり、新しい予測器ではありません。また、普遍的に最良のモデルや臨床的有用性を主張するものでもありません。 + +## はじめに + +- **現行原稿:**[リソースとして位置付けた原稿](paper/manuscript_resource.md)。 +- **短時間で読めるエビデンス概要:**[中英併記の専門家向け概要](output/pdf/neorepro_expert_brief_bilingual.pdf)および[独立コホート拡張の概要](reports/extension_summary.md)。 +- **凍結済み結果の再現:**下記「再現」節のコマンドを使用してください。 +- **固定版の引用:**[CITATION.cff](CITATION.cff) および [v0.1.0 release](https://github.com/stevezkw1998/NeoRepro/releases/tag/v0.1.0)を参照してください。 + +科学的な研究契約と範囲については [RESEARCH_SPEC.md](RESEARCH_SPEC.md) を参照してください。 + +## 状況 + +- 最新文献監査:完了、判断は `RESCOPE, then GO` +- 再現済み予測器:MHCflurry 2.2.1、BigMHC v1.0、PRIME 2.0、DeepImmuno-CNN、DeepHLApan +- TESLA パイロット:完了、学習データ重複の陽性対照として再分類 +- 主要ベンチマーク:IMPROVE、リーケージ除外後 17,475 レコード、70 患者、3 コホート +- 主要 IMPROVE 推論:完了、固定ツールによる 52,425 予測、欠損レコードなし +- 原稿:[リソース位置付け版](paper/manuscript_resource.md)、凍結結果ファイルから生成、独立した統計学・生物学レビュー済み + +## 主な結果 + +PRIME2 の公式補足資料から、初期 TESLA フィクスチャの全 520 レコードが学習データと完全に重複していることが判明したため、リーケージ陽性対照としてのみ保持しました。完全重複を除外し、提示能で事前選択された IMPROVE の共通評価ベンチマークでは、PRIME の AUROC は 0.597、患者-pMHC 平均 Recall@20 は 0.260 であり、BigMHC はそれぞれ 0.546 と 0.146 でした。独立した Zhao ワクチンコホートでは、BigMHC の患者 NDCG@5 は 0.658、評価可能範囲を一致させたランダム参照は 0.578 でした。DeepHLApan は 0.580 対 0.578、DeepImmuno-CNN は 43.8% のカバレッジで 0.755 対 0.759 でした。これらの結果は、普遍的なランキングではなく、監査可能でタスクと評価可能範囲を明示する評価契約を支持します。 + +## 再現 + +[uv](https://docs.astral.sh/uv/) をインストールし、プロジェクトで固定した CPython 3.11.15 とバージョン管理済みのベンチマーク/予測ファイルを使って、すべての解析、図、表、原稿アーティファクトを再構築します。 + +```bash +make -j4 reproduce-results +``` + +独立した bootstrap 解析は Make により並列化されます。CPU またはメモリが限られる場合は、`-j4` を付けずに `make reproduce-results` を使用してください。`make -j4 full-reproduce` は、固定された公開元データのダウンロードと第三者予測器のインストール/実行も行います。BigMHC と PRIME の学術利用限定条件への明示的な同意、数 GB のディスク容量、および大幅に長い実行時間が必要です。 + +## エビデンスチェーン + +- **主要な科学記録:**[現行原稿](paper/manuscript_resource.md)、[最終報告](FINAL_REPORT.md)、[レビュー記録](paper/reviewer_response.md)。 +- **監査可能な出力:**[最終結果表](results/final_results.csv)、[図](results/figures/)、[学習データ重複監査](research/training_overlap_summary_improve.json)、[SHA-256 マニフェスト](results/manifest.json)。 +- **投稿計画:**[投稿先戦略](reports/target_venues_2026-08-20.md)。 + +独立した Zhao 2026 ワクチンコホート拡張は `make -j4 extension` で再現できます。簡潔なエビデンス概要は [reports/extension_summary.md](reports/extension_summary.md)、推論前に凍結した研究契約は [research/extension_protocol.json](research/extension_protocol.json) にあります。外部エンドポイントは、ペプチドをパルスした樹状細胞投与後のワクチン接種後 ELISPOT であり、自然な腫瘍提示や臨床効果を示すものではありません。 + +## ライセンス + +NeoRepro の独自コードと文書には MIT License が適用されます。第三者の予測器とデータセットにはそれぞれの条件が引き続き適用され、本研究への収載は再配布許可を意味しません。 diff --git a/README.ko.md b/README.ko.md new file mode 100644 index 0000000..c6e1f47 --- /dev/null +++ b/README.ko.md @@ -0,0 +1,51 @@ +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) + +# NeoRepro + +NeoRepro는 공개 MHC-I 펩타이드–HLA 신생항원 예측기를 위한 데이터 누출 인지형, 환자 수준, 재현 가능한 벤치마크 리소스입니다. 고정된 예측기 아티팩트, 레코드 수준 출처, 학습 데이터 중복 감사, 공통 평가 가능 집합 비교, 환자 수준 불확실성, 지원 범위를 맞춘 무작위 기준선 및 기계 생성 결과를 제공합니다. + +이 프로젝트는 새로운 예측기가 아니라 벤치마크/리소스 기여이며, 보편적인 최우수 모델이나 임상적 유용성을 주장하지 않습니다. + +## 시작하기 + +- **현재 원고:** [리소스 중심 원고](paper/manuscript_resource.md). +- **간단한 증거 요약:** [중영 이중언어 전문가 요약](output/pdf/neorepro_expert_brief_bilingual.pdf)과 [독립 코호트 확장 요약](reports/extension_summary.md). +- **고정 결과 재현:** 아래 재현 절의 명령을 사용하십시오. +- **고정 버전 인용:** [CITATION.cff](CITATION.cff)와 [v0.1.0 release](https://github.com/stevezkw1998/NeoRepro/releases/tag/v0.1.0)를 참조하십시오. + +과학적 연구 계약과 범위는 [RESEARCH_SPEC.md](RESEARCH_SPEC.md)를 참조하십시오. + +## 상태 + +- 최신 문헌 감사: 완료, 결정은 `RESCOPE, then GO` +- 재현한 예측기: MHCflurry 2.2.1, BigMHC v1.0, PRIME 2.0, DeepImmuno-CNN, DeepHLApan +- TESLA 파일럿: 완료, 학습 데이터 중복 양성 대조군으로 재분류 +- 주요 벤치마크: IMPROVE, 누출 필터링 후 17,475개 레코드, 70명 환자, 3개 코호트 +- 주요 IMPROVE 추론: 완료, 고정 도구 예측 52,425개, 누락 레코드 없음 +- 원고: [리소스 중심 버전](paper/manuscript_resource.md), 고정 결과 파일에서 생성, 독립 통계 및 생물학 검토 완료 + +## 주요 결과 + +PRIME2 공식 보충자료에서 초기 TESLA 픽스처의 520개 레코드 모두가 학습 데이터와 정확히 중복됨을 확인하여 누출 양성 대조군으로만 유지했습니다. 정확한 중복을 제거하고 제시 가능성으로 사전 선별한 IMPROVE 공통 벤치마크에서 PRIME은 AUROC 0.597과 평균 환자-pMHC Recall@20 0.260을, BigMHC는 각각 0.546과 0.146을 기록했습니다. 독립 Zhao 백신 코호트에서 BigMHC 환자 NDCG@5는 0.658, 지원 범위를 맞춘 무작위 참조는 0.578이었습니다. DeepHLApan은 0.580 대 0.578, DeepImmuno-CNN은 43.8% 범위에서 0.755 대 0.759였습니다. 이 결과는 보편적 순위표가 아니라 감사 가능하고 과제와 지원 범위를 명시하는 평가 계약을 지지합니다. + +## 재현 + +[uv](https://docs.astral.sh/uv/)를 설치한 뒤 프로젝트에 고정된 CPython 3.11.15와 버전 관리된 벤치마크 및 예측 파일로 모든 분석, 그림, 표, 원고 아티팩트를 다시 생성합니다. + +```bash +make -j4 reproduce-results +``` + +독립 bootstrap 분석은 Make가 병렬 처리합니다. CPU 또는 메모리가 제한되면 `-j4` 없이 `make reproduce-results`를 사용하십시오. `make -j4 full-reproduce`는 고정된 공개 원천 데이터를 내려받고 외부 예측기도 설치·실행합니다. BigMHC와 PRIME의 학술 전용 조건에 명시적으로 동의해야 하며, 수 GB의 디스크 공간과 훨씬 긴 실행 시간이 필요합니다. + +## 증거 체계 + +- **주요 과학 기록:** [현재 원고](paper/manuscript_resource.md), [최종 보고서](FINAL_REPORT.md), [검토 기록](paper/reviewer_response.md). +- **감사 가능한 출력:** [최종 결과표](results/final_results.csv), [그림](results/figures/), [학습 데이터 중복 감사](research/training_overlap_summary_improve.json), [SHA-256 매니페스트](results/manifest.json). +- **투고 계획:** [대상 저널 전략](reports/target_venues_2026-08-20.md). + +독립 Zhao 2026 백신 코호트 확장은 `make -j4 extension`으로 재현할 수 있습니다. 간결한 증거 요약은 [reports/extension_summary.md](reports/extension_summary.md), 추론 전에 고정한 연구 계약은 [research/extension_protocol.json](research/extension_protocol.json)에 있습니다. 외부 종말점은 펩타이드 펄스 수지상세포 투여 후 백신 접종 뒤 ELISPOT이며, 자연 종양 제시나 임상 효능으로 해석해서는 안 됩니다. + +## 라이선스 + +NeoRepro의 원본 코드와 문서는 MIT License를 사용합니다. 외부 예측기와 데이터셋에는 각자의 조건이 그대로 적용되며, 연구에 포함되었다고 재배포가 허용되는 것은 아닙니다. diff --git a/README.md b/README.md index 859d4a8..2d9cca1 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,28 @@ +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) + # NeoRepro NeoRepro is a leakage-aware, patient-level, reproducible benchmark resource for public MHC-I peptide–HLA neoantigen predictors. It packages pinned predictor artifacts, record-level provenance, training-overlap audits, common-support comparisons, patient-level uncertainty, support-matched random baselines and machine-generated results. This is a benchmark/resource contribution, not a new predictor and not a claim of a universal model winner or clinical utility. -See [RESEARCH_SPEC.md](RESEARCH_SPEC.md) for the scientific contract and [PROJECT_PROMPT.md](PROJECT_PROMPT.md) for the original project brief. +## Start here + +- **Current manuscript:** [resource-positioned manuscript](paper/manuscript_resource.md). +- **Two-minute evidence summary:** [bilingual expert brief](output/pdf/neorepro_expert_brief_bilingual.pdf) and [independent-cohort extension summary](reports/extension_summary.md). +- **Reproduce the frozen results:** use the command in the Reproduce section below. +- **Cite a fixed version:** [CITATION.cff](CITATION.cff) and the [v0.1.0 release](https://github.com/stevezkw1998/NeoRepro/releases/tag/v0.1.0). + +For the scientific contract and scope, see [RESEARCH_SPEC.md](RESEARCH_SPEC.md). ## Status -- Repository initialized: yes - Current-literature audit: complete; decision `RESCOPE, then GO` - Reproduced predictors: MHCflurry 2.2.1, BigMHC v1.0, PRIME 2.0, DeepImmuno-CNN and DeepHLApan - TESLA pilot: complete; reclassified as a training-overlap-positive control - Primary benchmark: IMPROVE, 17,475 leakage-filtered rows, 70 patients, 3 cohorts -- Full inference and analysis: complete; 52,425 fixed-tool predictions with no missing rows +- Primary IMPROVE inference: complete; 52,425 fixed-tool predictions with no missing rows - Manuscript: [resource-positioned version](paper/manuscript_resource.md), generated from frozen result files; independent statistical and biological review complete -- Expert brief: [bilingual one-page PDF](output/pdf/neorepro_expert_brief_bilingual.pdf) ## Main result @@ -31,7 +38,11 @@ make -j4 reproduce-results Independent bootstrap analyses are parallelized by Make. Use `make reproduce-results` without `-j4` when CPU or memory is constrained. `make -j4 full-reproduce` additionally downloads the pinned public source data and installs/runs the third-party predictors. It requires explicit acceptance of the academic-only BigMHC and PRIME terms, several gigabytes of disk space, and substantially more runtime. -Key outputs are the [final report](FINAL_REPORT.md), [resource manuscript](paper/manuscript_resource.md), [review record](paper/reviewer_response.md), [final result table](results/final_results.csv), [figures](results/figures/), [training-overlap audit](research/training_overlap_summary_improve.json), [target-venue strategy](reports/target_venues_2026-08-20.md), and [SHA-256 manifest](results/manifest.json). +## Evidence trail + +- **Primary scientific record:** [current manuscript](paper/manuscript_resource.md), [final report](FINAL_REPORT.md), and [review record](paper/reviewer_response.md). +- **Auditable outputs:** [final result table](results/final_results.csv), [figures](results/figures/), [training-overlap audit](research/training_overlap_summary_improve.json), and [SHA-256 manifest](results/manifest.json). +- **Submission planning:** [target-venue strategy](reports/target_venues_2026-08-20.md). The independent Zhao 2026 vaccine-cohort extension is reproduced with `make -j4 extension`. Its concise evidence summary is in [reports/extension_summary.md](reports/extension_summary.md), with the frozen pre-inference contract in [research/extension_protocol.json](research/extension_protocol.json). The external endpoint is post-vaccination ELISPOT after peptide-pulsed dendritic-cell administration and must not be interpreted as natural tumor presentation or clinical efficacy. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..f66438b --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,51 @@ +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) + +# NeoRepro + +NeoRepro 是面向公开 MHC-I 肽–HLA 新抗原预测器的泄漏感知、患者级、可复现基准资源。它整合了固定版本的预测器工件、逐记录来源、训练数据重叠审计、共同支持集比较、患者级不确定性、支持集匹配的随机基线以及机器生成的结果。 + +本项目贡献的是基准与研究资源,而不是新的预测器,也不宣称存在普适的最佳模型或临床效用。 + +## 从这里开始 + +- **当前论文稿:**[资源定位版论文](paper/manuscript_resource.md)。 +- **两分钟证据摘要:**[中英双语专家简报](output/pdf/neorepro_expert_brief_bilingual.pdf)和[独立队列扩展摘要](reports/extension_summary.md)。 +- **复现冻结结果:**使用下方“复现”部分中的命令。 +- **引用固定版本:**参见 [CITATION.cff](CITATION.cff) 和 [v0.1.0 release](https://github.com/stevezkw1998/NeoRepro/releases/tag/v0.1.0)。 + +科学研究契约与范围见 [RESEARCH_SPEC.md](RESEARCH_SPEC.md)。 + +## 状态 + +- 最新文献审计:已完成;结论为 `RESCOPE, then GO` +- 已复现预测器:MHCflurry 2.2.1、BigMHC v1.0、PRIME 2.0、DeepImmuno-CNN 和 DeepHLApan +- TESLA 试点:已完成;重新归类为训练数据重叠阳性对照 +- 主要基准:IMPROVE,17,475 条经过泄漏过滤的记录、70 名患者、3 个队列 +- 主要 IMPROVE 推理:已完成;52,425 条固定工具预测,无缺失记录 +- 论文稿:[资源定位版](paper/manuscript_resource.md),由冻结结果文件生成;独立统计学与生物学审查均已完成 + +## 主要结果 + +PRIME2 官方补充材料显示,初始 TESLA 数据集的全部 520 条记录都与训练数据完全重叠,因此仅保留为泄漏阳性对照。在经过完全重叠过滤、且预先按呈递能力筛选的 IMPROVE 共同支持基准上,PRIME 的 AUROC 为 0.597,患者-pMHC 平均 Recall@20 为 0.260;BigMHC 分别为 0.546 和 0.146。在独立 Zhao 疫苗队列中,BigMHC 的患者 NDCG@5 为 0.658,而支持集匹配的随机参照为 0.578;DeepHLApan 为 0.580,对应随机参照为 0.578;DeepImmuno-CNN 在 43.8% 覆盖率下为 0.755,对应随机参照为 0.759。这些结果支持一种可审计、区分任务并关注支持集的评估契约,而不是通用排行榜。 + +## 复现 + +安装 [uv](https://docs.astral.sh/uv/),然后使用项目固定的 CPython 3.11.15,从已版本化的基准与预测文件重新生成全部分析、图表、结果表和论文工件: + +```bash +make -j4 reproduce-results +``` + +Make 会并行执行相互独立的 bootstrap 分析。在 CPU 或内存受限时,请使用不带 `-j4` 的 `make reproduce-results`。`make -j4 full-reproduce` 还会下载固定版本的公开源数据,并安装、运行第三方预测器;该命令要求明确接受 BigMHC 和 PRIME 仅限学术使用的条款,需要数 GB 磁盘空间,并且运行时间明显更长。 + +## 证据链 + +- **主要科学记录:**[当前论文稿](paper/manuscript_resource.md)、[最终报告](FINAL_REPORT.md)和[审查记录](paper/reviewer_response.md)。 +- **可审计输出:**[最终结果表](results/final_results.csv)、[图表](results/figures/)、[训练数据重叠审计](research/training_overlap_summary_improve.json)和 [SHA-256 清单](results/manifest.json)。 +- **投稿规划:**[目标期刊策略](reports/target_venues_2026-08-20.md)。 + +独立 Zhao 2026 疫苗队列扩展可通过 `make -j4 extension` 复现。简要证据摘要见 [reports/extension_summary.md](reports/extension_summary.md),推理前冻结的研究契约见 [research/extension_protocol.json](research/extension_protocol.json)。外部终点是在肽脉冲树突状细胞给药后的疫苗接种后 ELISPOT,不应解读为自然肿瘤呈递或临床疗效。 + +## 许可证 + +NeoRepro 原创代码和文档采用 MIT License。第三方预测器和数据集仍受其各自条款约束;纳入本研究不代表获得再分发许可。 diff --git a/README.zh-TW.md b/README.zh-TW.md new file mode 100644 index 0000000..58563db --- /dev/null +++ b/README.zh-TW.md @@ -0,0 +1,51 @@ +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) + +# NeoRepro + +NeoRepro 是一套針對公開 MHC-I 胜肽–HLA 新抗原預測器、考量資料洩漏、病人層級且可重現的基準資源。它整合固定版本的預測器產物、逐筆資料來源、訓練資料重疊稽核、共同可評估集合比較、病人層級不確定性、依支援範圍匹配的隨機基準,以及由機器產生的結果。 + +本專案的貢獻是基準與研究資源,不是新的預測器,也不主張存在普遍適用的最佳模型或臨床效益。 + +## 從這裡開始 + +- **目前論文稿:**[資源定位版論文](paper/manuscript_resource.md)。 +- **兩分鐘證據摘要:**[中英雙語專家簡報](output/pdf/neorepro_expert_brief_bilingual.pdf)與[獨立隊列延伸摘要](reports/extension_summary.md)。 +- **重現凍結結果:**使用下方「重現」章節中的指令。 +- **引用固定版本:**請參閱 [CITATION.cff](CITATION.cff) 與 [v0.1.0 release](https://github.com/stevezkw1998/NeoRepro/releases/tag/v0.1.0)。 + +科學研究契約與範圍請見 [RESEARCH_SPEC.md](RESEARCH_SPEC.md)。 + +## 狀態 + +- 最新文獻稽核:已完成;決策為 `RESCOPE, then GO` +- 已重現的預測器:MHCflurry 2.2.1、BigMHC v1.0、PRIME 2.0、DeepImmuno-CNN 與 DeepHLApan +- TESLA 試驗:已完成;重新歸類為訓練資料重疊陽性對照 +- 主要基準:IMPROVE,17,475 筆經資料洩漏過濾的記錄、70 位病人、3 個隊列 +- 主要 IMPROVE 推論:已完成;52,425 筆固定工具預測,沒有缺漏記錄 +- 論文稿:[資源定位版](paper/manuscript_resource.md),由凍結結果檔案產生;獨立統計與生物學審查皆已完成 + +## 主要結果 + +PRIME2 官方補充資料顯示,初始 TESLA 資料集的全部 520 筆記錄皆與訓練資料完全重疊,因此僅保留為資料洩漏陽性對照。在排除完全重疊、且預先依呈遞能力篩選的 IMPROVE 共同支援基準中,PRIME 的 AUROC 為 0.597,病人-pMHC 平均 Recall@20 為 0.260;BigMHC 分別為 0.546 與 0.146。在獨立 Zhao 疫苗隊列中,BigMHC 的病人 NDCG@5 為 0.658,依支援範圍匹配的隨機參考值為 0.578;DeepHLApan 為 0.580,相對的隨機參考值為 0.578;DeepImmuno-CNN 在 43.8% 覆蓋率下為 0.755,相對的隨機參考值為 0.759。這些結果支持可稽核、區分任務並考量支援範圍的評估契約,而不是通用排行榜。 + +## 重現 + +安裝 [uv](https://docs.astral.sh/uv/),再使用專案固定的 CPython 3.11.15,從已納入版本控制的基準與預測檔案重新產生所有分析、圖表、資料表與論文產物: + +```bash +make -j4 reproduce-results +``` + +Make 會平行執行彼此獨立的 bootstrap 分析。CPU 或記憶體受限時,請使用不含 `-j4` 的 `make reproduce-results`。`make -j4 full-reproduce` 也會下載固定版本的公開來源資料,並安裝、執行第三方預測器;此指令要求明確接受 BigMHC 與 PRIME 僅供學術使用的條款,需要數 GB 磁碟空間,且執行時間明顯更長。 + +## 證據鏈 + +- **主要科學記錄:**[目前論文稿](paper/manuscript_resource.md)、[最終報告](FINAL_REPORT.md)與[審查記錄](paper/reviewer_response.md)。 +- **可稽核輸出:**[最終結果表](results/final_results.csv)、[圖表](results/figures/)、[訓練資料重疊稽核](research/training_overlap_summary_improve.json)與 [SHA-256 清單](results/manifest.json)。 +- **投稿規劃:**[目標期刊策略](reports/target_venues_2026-08-20.md)。 + +獨立 Zhao 2026 疫苗隊列延伸可用 `make -j4 extension` 重現。簡要證據摘要位於 [reports/extension_summary.md](reports/extension_summary.md),推論前凍結的研究契約位於 [research/extension_protocol.json](research/extension_protocol.json)。外部終點是以胜肽脈衝樹突細胞施打後的疫苗接種後 ELISPOT,不應解讀為自然腫瘤呈遞或臨床療效。 + +## 授權條款 + +NeoRepro 原創程式碼與文件採用 MIT License。第三方預測器與資料集仍適用其各自條款;納入本研究不代表取得再散布許可。 diff --git a/i18n/glossary.md b/i18n/glossary.md new file mode 100644 index 0000000..9752ec1 --- /dev/null +++ b/i18n/glossary.md @@ -0,0 +1,16 @@ +# README translation glossary + +English is the only source of truth. Preserve model names, metric names, version strings, +commands, paths, URLs and all numbers exactly. + +| Concept | zh-CN | zh-TW | ja | ko | de | es | fr | +|---|---|---|---|---|---|---|---| +| neoantigen | 新抗原 | 新抗原 | ネオアンチゲン | 신생항원 | Neoantigen | neoantígeno | néoantigène | +| leakage-aware | 泄漏感知 | 資料洩漏感知 | リーケージを考慮した | 데이터 누출을 고려한 | unter Berücksichtigung von Datenlecks | sensible a la fuga de datos | tenant compte des fuites de données | +| patient-level | 患者级 | 病人層級 | 患者単位 | 환자 수준 | patientenbezogen | a nivel de paciente | au niveau du patient | +| training overlap | 训练数据重叠 | 訓練資料重疊 | 学習データの重複 | 학습 데이터 중복 | Überschneidung mit Trainingsdaten | solapamiento con datos de entrenamiento | chevauchement avec les données d’entraînement | +| common support | 共同可评估集合 | 共同可評估集合 | 共通評価可能集合 | 공통 평가 가능 집합 | gemeinsame Auswertungsmenge | soporte común evaluable | support commun évaluable | +| reproducible benchmark resource | 可复现基准资源 | 可重現基準資源 | 再現可能なベンチマークリソース | 재현 가능한 벤치마크 리소스 | reproduzierbare Benchmark-Ressource | recurso de evaluación reproducible | ressource d’évaluation reproductible | + +Use a neutral, concise technical-documentation register. For zh-TW, prefer Taiwan usage such +as “病人層級” and “資料”; do not derive it by mechanical character conversion from zh-CN. diff --git a/i18n/readme_state.json b/i18n/readme_state.json new file mode 100644 index 0000000..a2fd36e --- /dev/null +++ b/i18n/readme_state.json @@ -0,0 +1,91 @@ +{ + "locales": { + "de": { + "file": "README.de.md", + "sections": { + "evidence-trail": "d59dadcd64bcd6fb91d6b2f0e17c2bcbbdda83f5ffb0e706dde0d3254f730f12", + "license": "c8b5a3d845f447f3d200d9eccc802340c77f3d954f86bcdbfa91322a46c89f67", + "main-result": "0f4aa84d0a01bba3302829e11a79635483cbc7ed332a7585666226d663e4536a", + "preamble": "65418799adf89e3fce1e798f934e0d60ec21086d5db6023cf2721d1b841f0835", + "reproduce": "a3378bedac0f19d71a46de7ce86eb0d6c5bce141215fe1564c9ff7ad8b9e38a4", + "start-here": "418af0c8b42d6606208a2d5ef296b960882c4264f3e92795b5e326f2ea13a4d5", + "status": "4247275cd63fe06bb87fd248db4543aca69f00da41fc15df46e492809dfca2d1" + } + }, + "es": { + "file": "README.es.md", + "sections": { + "evidence-trail": "d59dadcd64bcd6fb91d6b2f0e17c2bcbbdda83f5ffb0e706dde0d3254f730f12", + "license": "c8b5a3d845f447f3d200d9eccc802340c77f3d954f86bcdbfa91322a46c89f67", + "main-result": "0f4aa84d0a01bba3302829e11a79635483cbc7ed332a7585666226d663e4536a", + "preamble": "65418799adf89e3fce1e798f934e0d60ec21086d5db6023cf2721d1b841f0835", + "reproduce": "a3378bedac0f19d71a46de7ce86eb0d6c5bce141215fe1564c9ff7ad8b9e38a4", + "start-here": "418af0c8b42d6606208a2d5ef296b960882c4264f3e92795b5e326f2ea13a4d5", + "status": "4247275cd63fe06bb87fd248db4543aca69f00da41fc15df46e492809dfca2d1" + } + }, + "fr": { + "file": "README.fr.md", + "sections": { + "evidence-trail": "d59dadcd64bcd6fb91d6b2f0e17c2bcbbdda83f5ffb0e706dde0d3254f730f12", + "license": "c8b5a3d845f447f3d200d9eccc802340c77f3d954f86bcdbfa91322a46c89f67", + "main-result": "0f4aa84d0a01bba3302829e11a79635483cbc7ed332a7585666226d663e4536a", + "preamble": "65418799adf89e3fce1e798f934e0d60ec21086d5db6023cf2721d1b841f0835", + "reproduce": "a3378bedac0f19d71a46de7ce86eb0d6c5bce141215fe1564c9ff7ad8b9e38a4", + "start-here": "418af0c8b42d6606208a2d5ef296b960882c4264f3e92795b5e326f2ea13a4d5", + "status": "4247275cd63fe06bb87fd248db4543aca69f00da41fc15df46e492809dfca2d1" + } + }, + "ja": { + "file": "README.ja.md", + "sections": { + "evidence-trail": "d59dadcd64bcd6fb91d6b2f0e17c2bcbbdda83f5ffb0e706dde0d3254f730f12", + "license": "c8b5a3d845f447f3d200d9eccc802340c77f3d954f86bcdbfa91322a46c89f67", + "main-result": "0f4aa84d0a01bba3302829e11a79635483cbc7ed332a7585666226d663e4536a", + "preamble": "65418799adf89e3fce1e798f934e0d60ec21086d5db6023cf2721d1b841f0835", + "reproduce": "a3378bedac0f19d71a46de7ce86eb0d6c5bce141215fe1564c9ff7ad8b9e38a4", + "start-here": "418af0c8b42d6606208a2d5ef296b960882c4264f3e92795b5e326f2ea13a4d5", + "status": "4247275cd63fe06bb87fd248db4543aca69f00da41fc15df46e492809dfca2d1" + } + }, + "ko": { + "file": "README.ko.md", + "sections": { + "evidence-trail": "d59dadcd64bcd6fb91d6b2f0e17c2bcbbdda83f5ffb0e706dde0d3254f730f12", + "license": "c8b5a3d845f447f3d200d9eccc802340c77f3d954f86bcdbfa91322a46c89f67", + "main-result": "0f4aa84d0a01bba3302829e11a79635483cbc7ed332a7585666226d663e4536a", + "preamble": "65418799adf89e3fce1e798f934e0d60ec21086d5db6023cf2721d1b841f0835", + "reproduce": "a3378bedac0f19d71a46de7ce86eb0d6c5bce141215fe1564c9ff7ad8b9e38a4", + "start-here": "418af0c8b42d6606208a2d5ef296b960882c4264f3e92795b5e326f2ea13a4d5", + "status": "4247275cd63fe06bb87fd248db4543aca69f00da41fc15df46e492809dfca2d1" + } + }, + "zh-CN": { + "file": "README.zh-CN.md", + "sections": { + "evidence-trail": "d59dadcd64bcd6fb91d6b2f0e17c2bcbbdda83f5ffb0e706dde0d3254f730f12", + "license": "c8b5a3d845f447f3d200d9eccc802340c77f3d954f86bcdbfa91322a46c89f67", + "main-result": "0f4aa84d0a01bba3302829e11a79635483cbc7ed332a7585666226d663e4536a", + "preamble": "65418799adf89e3fce1e798f934e0d60ec21086d5db6023cf2721d1b841f0835", + "reproduce": "a3378bedac0f19d71a46de7ce86eb0d6c5bce141215fe1564c9ff7ad8b9e38a4", + "start-here": "418af0c8b42d6606208a2d5ef296b960882c4264f3e92795b5e326f2ea13a4d5", + "status": "4247275cd63fe06bb87fd248db4543aca69f00da41fc15df46e492809dfca2d1" + } + }, + "zh-TW": { + "file": "README.zh-TW.md", + "sections": { + "evidence-trail": "d59dadcd64bcd6fb91d6b2f0e17c2bcbbdda83f5ffb0e706dde0d3254f730f12", + "license": "c8b5a3d845f447f3d200d9eccc802340c77f3d954f86bcdbfa91322a46c89f67", + "main-result": "0f4aa84d0a01bba3302829e11a79635483cbc7ed332a7585666226d663e4536a", + "preamble": "65418799adf89e3fce1e798f934e0d60ec21086d5db6023cf2721d1b841f0835", + "reproduce": "a3378bedac0f19d71a46de7ce86eb0d6c5bce141215fe1564c9ff7ad8b9e38a4", + "start-here": "418af0c8b42d6606208a2d5ef296b960882c4264f3e92795b5e326f2ea13a4d5", + "status": "4247275cd63fe06bb87fd248db4543aca69f00da41fc15df46e492809dfca2d1" + } + } + }, + "source": "README.md", + "source_sha256": "764f22611b5381d431e8191a5f19fb312f6023049bfbf942ea10e28a63243a12", + "version": 1 +} diff --git a/paper/manuscript.md b/paper/manuscript.md index 1f2b1d1..0991337 100644 --- a/paper/manuscript.md +++ b/paper/manuscript.md @@ -1,5 +1,7 @@ # NeoRepro: leakage-aware reproduction of public MHC-I predictors across patient T-cell recognition and vaccine-response cohorts +> **Archived draft.** This pre-resource-positioning manuscript is retained as a historical record and is not the current submission version. It has not been updated for the final five-predictor resource framing. Read the [current resource-positioned manuscript](manuscript_resource.md) instead. + **Author line:** to be completed before submission ## Abstract diff --git a/scripts/readme_i18n.py b/scripts/readme_i18n.py new file mode 100755 index 0000000..efea309 --- /dev/null +++ b/scripts/readme_i18n.py @@ -0,0 +1,249 @@ +#!/usr/bin/env python3 +"""Track and validate localized README files without calling a translation model.""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import re +import sys +from collections import Counter +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +SOURCE = ROOT / "README.md" +STATE = ROOT / "i18n" / "readme_state.json" + +LOCALES = { + "zh-CN": ROOT / "README.zh-CN.md", + "zh-TW": ROOT / "README.zh-TW.md", + "ja": ROOT / "README.ja.md", + "ko": ROOT / "README.ko.md", + "de": ROOT / "README.de.md", + "es": ROOT / "README.es.md", + "fr": ROOT / "README.fr.md", +} + +NAVIGATION = ( + "[English](README.md) | [简体中文](README.zh-CN.md) | " + "[繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | " + "[한국어](README.ko.md) | [Deutsch](README.de.md) | " + "[Español](README.es.md) | [Français](README.fr.md)" +) + +PROTECTED_TOKENS = ( + "NeoRepro", + "MHC-I", + "MHCflurry", + "BigMHC", + "PRIME", + "DeepImmuno-CNN", + "DeepHLApan", + "TESLA", + "IMPROVE", + "Zhao", + "AUROC", + "NDCG@5", + "Recall@20", + "Top-K", + "SHA-256", + "CITATION.cff", + "CPython", + "Apple Silicon", + "MIT", +) + +LINK_RE = re.compile(r"\[[^\]]*\]\(([^)]+)\)") +CODE_RE = re.compile(r"```[^\n]*\n.*?```", re.DOTALL) +NUMBER_RE = re.compile(r"(? str: + return hashlib.sha256(text.encode("utf-8")).hexdigest() + + +def slug(text: str) -> str: + value = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-") + return value or "section" + + +def split_sections(text: str, *, source: bool) -> list[tuple[str, str]]: + sections: list[tuple[str, str]] = [] + current: list[str] = [] + current_id = "preamble" + section_index = 0 + for line in text.splitlines(keepends=True): + if line.startswith("## "): + sections.append((current_id, "".join(current))) + current = [line] + section_index += 1 + current_id = slug(line[3:].strip()) if source else f"section-{section_index}" + else: + current.append(line) + sections.append((current_id, "".join(current))) + return sections + + +def source_snapshot() -> tuple[str, list[tuple[str, str]], dict[str, str]]: + text = SOURCE.read_text(encoding="utf-8") + sections = split_sections(text, source=True) + hashes = {section_id: digest(body) for section_id, body in sections} + return text, sections, hashes + + +def load_state() -> dict[str, object]: + if not STATE.exists(): + return {"version": 1, "locales": {}} + return json.loads(STATE.read_text(encoding="utf-8")) + + +def link_targets(text: str) -> list[str]: + return LINK_RE.findall(text) + + +def numbers(text: str) -> Counter[str]: + return Counter(NUMBER_RE.findall(text)) + + +def validate_content( + locale: str, source_text: str, source_sections: list[tuple[str, str]] +) -> list[str]: + path = LOCALES[locale] + if not path.exists(): + return [f"missing {path.name}"] + + translated = path.read_text(encoding="utf-8") + errors: list[str] = [] + first_line = translated.splitlines()[0] if translated.splitlines() else "" + if first_line != NAVIGATION: + errors.append("language navigation differs from README.md") + if "# NeoRepro" not in translated: + errors.append("missing '# NeoRepro' title") + + target_sections = split_sections(translated, source=False) + if len(target_sections) != len(source_sections): + errors.append( + f"section count differs: source={len(source_sections)} target={len(target_sections)}" + ) + if link_targets(translated) != link_targets(source_text): + errors.append("Markdown link targets or their order differ") + if CODE_RE.findall(translated) != CODE_RE.findall(source_text): + errors.append("fenced code blocks differ") + if numbers(translated) != numbers(source_text): + errors.append("numeric tokens differ") + + for token in PROTECTED_TOKENS: + if translated.count(token) != source_text.count(token): + errors.append(f"protected token count differs: {token}") + + for target in link_targets(translated): + if target.startswith(("http://", "https://", "#")): + continue + local_target = target.split("#", 1)[0] + if local_target and not (ROOT / local_target).exists(): + errors.append(f"broken relative link: {target}") + return errors + + +def outdated_sections(locale: str, hashes: dict[str, str], state: dict[str, object]) -> list[str]: + locales = state.get("locales", {}) + if not isinstance(locales, dict): + return list(hashes) + locale_state = locales.get(locale, {}) + if not isinstance(locale_state, dict): + return list(hashes) + recorded = locale_state.get("sections", {}) + if not isinstance(recorded, dict): + return list(hashes) + return [section_id for section_id, value in hashes.items() if recorded.get(section_id) != value] + + +def command_status() -> int: + _, _, hashes = source_snapshot() + state = load_state() + for locale, path in LOCALES.items(): + if not path.exists(): + print(f"{locale}: missing {path.name}") + continue + stale = outdated_sections(locale, hashes, state) + print(f"{locale}: {'current' if not stale else 'outdated: ' + ', '.join(stale)}") + return 0 + + +def command_check() -> int: + source_text, source_sections, hashes = source_snapshot() + state = load_state() + failures: list[str] = [] + if source_text.splitlines()[0] != NAVIGATION: + failures.append("README.md: canonical language navigation is missing or changed") + + for locale in LOCALES: + for message in validate_content(locale, source_text, source_sections): + failures.append(f"{locale}: {message}") + stale = outdated_sections(locale, hashes, state) + if stale: + failures.append(f"{locale}: translations are stale for {', '.join(stale)}") + + if failures: + for failure in failures: + print(f"ERROR: {failure}", file=sys.stderr) + return 1 + print(f"README translations are synchronized and valid for {len(LOCALES)} locales.") + return 0 + + +def command_stamp(selected: list[str]) -> int: + source_text, source_sections, hashes = source_snapshot() + locales = list(LOCALES) if selected == ["all"] else selected + unknown = [locale for locale in locales if locale not in LOCALES] + if unknown: + print(f"ERROR: unknown locales: {', '.join(unknown)}", file=sys.stderr) + return 2 + + failures: list[str] = [] + for locale in locales: + for message in validate_content(locale, source_text, source_sections): + failures.append(f"{locale}: {message}") + if failures: + for failure in failures: + print(f"ERROR: {failure}", file=sys.stderr) + return 1 + + state = load_state() + locale_state = state.setdefault("locales", {}) + if not isinstance(locale_state, dict): + print("ERROR: malformed locale state", file=sys.stderr) + return 2 + state["version"] = 1 + state["source"] = SOURCE.name + state["source_sha256"] = digest(source_text) + for locale in locales: + locale_state[locale] = {"file": LOCALES[locale].name, "sections": hashes} + STATE.parent.mkdir(parents=True, exist_ok=True) + STATE.write_text(json.dumps(state, indent=2, sort_keys=True) + "\n", encoding="utf-8") + print(f"Stamped {len(locales)} locale(s) against the current README.md.") + return 0 + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description=__doc__) + subparsers = parser.add_subparsers(dest="command", required=True) + subparsers.add_parser("status", help="show which English sections need translation") + subparsers.add_parser("check", help="validate structure, protected content, and freshness") + stamp = subparsers.add_parser("stamp", help="record reviewed translations as synchronized") + stamp.add_argument("--locale", nargs="+", default=["all"], choices=["all", *LOCALES]) + return parser + + +def main() -> int: + args = build_parser().parse_args() + if args.command == "status": + return command_status() + if args.command == "check": + return command_check() + return command_stamp(args.locale) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_readme_i18n.py b/tests/test_readme_i18n.py new file mode 100644 index 0000000..39c6b0f --- /dev/null +++ b/tests/test_readme_i18n.py @@ -0,0 +1,18 @@ +from __future__ import annotations + +import subprocess +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def test_localized_readmes_are_current_and_structurally_safe() -> None: + completed = subprocess.run( + [sys.executable, "scripts/readme_i18n.py", "check"], + cwd=ROOT, + check=False, + capture_output=True, + text=True, + ) + assert completed.returncode == 0, completed.stdout + completed.stderr