Manuskript und Code: Versionen, Seeds und Statistik

Warum das wichtig ist

Gutachtende wünschen einen einseitigen Test, und der Text ändert sich, das Skript aber nicht. Die Daten werden neu heruntergeladen, und ein neueres Release einer Referenzdatenbank rutscht hinein. Im Manuskript steht „gemittelt über fünf Seeds“, das finale Skript läuft über drei.

Jede Änderung ist klein, und jede macht es schwerer, die veröffentlichten Zahlen nachzuvollziehen.

So sieht gute Praxis aus

• Ein Befehl, etwa make paper, erzeugt alle Abbildungen und Tabellen neu, auch die im Supplement.
• Text und Code werden gemeinsam überarbeitet: Eine Änderung im Methodenteil kommt mit dem Commit, der sie umsetzt.
• Das Manuskript nennt die exakte Code-Version (Tag oder Commit, idealerweise mit Archiv-DOI) und Datenversion (Accession, Release oder Abrufdatum).
• Parameter, Splits, Ausschlussregeln, Zahl der Seeds und statistische Tests im Text entsprechen den Skripten.
• Bekannte Abweichungen, etwa ein nach der Einreichung behobener Fehler, sind im README dokumentiert.

So beheben Sie es

Legen Sie eine Zuordnungsdatei für Abbildungen und Tabellen im Wurzelverzeichnis an:

figure_2:
  command: snakemake --cores 4 results/figures/figure2.pdf
  script: workflow/scripts/plot_figure2.R
  inputs: [data/processed/counts.tsv, data/processed/metadata.tsv]
table_1:
  command: python -m analysis.table1 --config configs/table1.yaml
  output: results/tables/table1.csv
supplementary_figure_4:
  command: quarto render reports/supplement.qmd

Testen Sie berichtete Werte. In Python mit pytest; in R leistet testthat::expect_equal() mit tolerance dasselbe:

import json

def test_table2_auroc_matches_paper():
    with open("results/claims/table2_auroc.json") as fh:
        result = json.load(fh)
    assert 0.90 <= result["mean"] <= 0.92  # the paper reports 0.91

Nennen Sie Versionen im Manuskript, zum Beispiel:

Alle Analysen nutzten das Code-Release v1.2.0 (Commit <hash>,
archiviert unter <DOI>). Die Expressionsdaten stammen aus
<Repository> (Accession <accession>), abgerufen am <Datum>,
verarbeitet mit workflow/ im selben Release.

Verwandte Themen

• Zahlen und Abbildungen zum Code zurückverfolgen⁠
• Lizenz, Zitation und Paper-Version⁠
• Vorlage für das Code Availability Statement⁠