Zum Inhalt springen
RepoReady
Registrieren
Menü
Menü der Dokumentation

Dokumentation: ein nachvollziehbarer Arbeitsablauf

L2 Arbeitsablauf dokumentiert ergänzt einen Weg, dem andere folgen können: Versionen und Kennungen, die Aufbereitung der Eingaben, welches Skript welches Ergebnis erzeugt und eine Anleitung, die zum Repository passt.

Zuletzt aktualisiert

L2 wartet, bis die Lücke behoben und die offene Frage beantwortet ist.
Bezug zur StufeErforderlich für L2

Dokumentation macht aus verfügbaren Materialien einen Arbeitsablauf. Kleine Lücken stoppen ihn: eine ungenannte Version, ein umbenanntes Skript, ein Pfad, den es nur auf einem Laptop gibt. Von über 9.000 R-Dateien aus Harvard Dataverse liefen 74 % nicht fehlerfrei durch (Trisovic et al., 2022). Eine Materials and workflow-Prüfung bewertet diesen Bereich; Warnungen blockieren hier keine Stufe.

Dependencies and versions are listed

Was zählt
Eine Standarddatei listet jedes Paket, das der Code importiert, mit Version oder Versionsbereich: requirements.txt, environment.yml, pyproject.toml, renv.lock oder DESCRIPTION.
Häufige Lücken
Gar keine Abhängigkeitsdatei, Importe, die in keiner Datei stehen, oder ein gelistetes Paket ohne jede Version.
So beheben Sie es
Erzeugen Sie die Liste aus einer sauberen Umgebung mit Ihrer Analyse, geben Sie jedem Paket eine Version und ändern Sie sie im selben Commit wie den Code.

The exact code version is identified

Was zählt
Das Paper zitiert eine unveränderliche Version, die den Code hinter jedem Ergebnis enthält: Release, Tag, Commit-Hash oder Versions-DOI.
Häufige Lücken
Nur ein Branch oder eine Concept-DOI, ein zitierter Tag, den es nicht gibt, oder Ergebniscode, der erst nach der zitierten Version hinzukam.
So beheben Sie es
Taggen Sie die eingereichte Version, archivieren Sie sie für eine eigene Versions-DOI und nennen Sie diese DOI im Paper:
bash
git tag -a v1.0-paper -m "Code as submitted with the manuscript"
git push origin v1.0-paper

Versionen von Werkzeugen und Modellen

Was zählt
Forks, andere Repositorys und Modelle, die der Code nutzt, haben einen festen Tag, Commit oder eine Modellrevision, und jede im Paper genannte Version passt zu Pins und Logs.
Häufige Lücken
Ein Fork nur auf einem Branch, ein Modell ohne Revision, eine Methodenversion, der die Lock-Datei widerspricht. Ergebnisdateien nach dem zitierten Release geändert: eine Warnung.
So beheben Sie es
Fixieren Sie jeden Fork und jedes Modell auf Commit oder Revision, übernehmen Sie Versionen aus der Lock-Datei in den Methodenteil und zitieren Sie nach Änderungen ein neues Release.

Data sources have stable identifiers

Was zählt
Jeder Datensatz hat eine Accession, DOI, versionierte Ablage oder Release-URL; Live-Dienste nennen Release oder Abfragedatum; kontrollierte Daten sagen, wo und wie man Zugang beantragt.
Häufige Lücken
Ein nur im Text genannter Datensatz, ein Cloud-Laufwerk-Link, eine Platzhalter-DOI, ein Link auf die falsche Datei oder kontrollierte Daten ohne Verfahren.
So beheben Sie es
Nennen Sie jeden Datensatz mit Quelle, Kennung, Version und Zugang im README, fixieren Sie Modelle auf eine Revision, ersetzen Sie private Links. Die Tabelle im Leitfaden Materialien hilft.

Data preparation steps are documented

Was zählt
Jede Eingabe, die kein geteilter Code erzeugt, auch hinterlegte verarbeitete Daten, kommt mit ihren Schritten: Werkzeug, Version, abweichende Parameter und jede manuelle Kuratierung.
Häufige Lücken
Eine von Hand bearbeitete Tabelle, eine Datei, die nur auskommentierter Code schreibt, oder ein Modell ohne Trainingscode. Auskommentierte Schritte anderswo: eine Warnung.
So beheben Sie es
Machen Sie jeden Schritt zu einem Skript oder einer Workflow-Regel, aktivieren oder entfernen Sie auskommentierte Schritte und beschreiben Sie manuelle Schritte genau:
Snakefile
rule filter_cells:
    input:  "data/raw/counts.h5ad"
    output: "data/processed/filtered.h5ad"
    params: min_genes=200
    shell:  "python -m pipeline.filter {input} {output} --min-genes {params.min_genes}"

rule train_model:
    input:  "data/processed/filtered.h5ad"
    output: "models/classifier.pt"
    shell:  "python -m pipeline.train {input} {output} --seed 0"

Code is linked to the paper’s results

Was zählt
Eine Tabelle oder ein Eintrag verbindet jede zentrale Abbildung, jedes Panel, jede Tabelle und berichtete Zahl mit dem einen Skript, Notebook-Abschnitt oder Befehl, der sie erzeugt.
Häufige Lücken
Gar keine Zuordnung, eine Zuordnung mit Lücken oder analysis_v2.py neben analysis_final.py. Skripte, die nirgends genannt sind: eine Warnung.
So beheben Sie es
Legen Sie im README eine Ergebnistabelle an, eine Zeile pro Element im Paper, behalten Sie eine Kopie je Skript und nennen Sie den Zweck aller anderen Skripte:
README.md
## Ergebnisse

| Im Paper  | Befehl                             | Ausgabe                          |
|-----------|------------------------------------|----------------------------------|
| Abb. 2    | Rscript analysis/figure2.R         | results/figure2/figure2.csv      |
| Abb. 3B   | python -m analysis.fig3 --panel b  | results/figure3/panel_b.csv      |
| Tabelle 2 | python -m analysis.evaluate_cohort | results/claims/table2_auroc.json |

Instructions explain how to run the analysis

Was zählt
README, Paper oder verlinkte Dokumente nennen Einrichtung, Ablageort oder Bezug der Eingaben, die Reihenfolge und jeden manuellen Schritt, oder dass es keinen gibt.
Häufige Lücken
Kein README, Daten aus einem Ordner außerhalb des Repositorys, den kein Dokument nennt, oder ein versprochener automatischer Download, den es nicht gibt.
So beheben Sie es
Schreiben Sie einen kurzen Abschnitt „Reproduzieren“: Einrichtung, Ablageort jeder Eingabe, dann jeden Schritt mit Befehl und den Ausgaben, die er erzeugt, der Reihe nach.

Documented commands agree with the code

Was zählt
Jeder Befehl, jede Datei, Option, Variable, jeder Ordner und Paketname aus der Dokumentation passt genau zum Repository, und Ergebnis-Notebooks sind ohne Fehler gespeichert.
Häufige Lücken
Ein umbenanntes Skript, data.csv statt Data.csv.gz, ein Paketname, der einem anderen Paket gehört, oder übrig gebliebenes <your-path>. Ein TODO-Link im Fließtext: eine Warnung.
So beheben Sie es
Prüfen Sie in einem frischen Klon jeden Namen aus dem README, legen Sie die Ordner an, in die er schreibt, ersetzen Sie Platzhalter und speichern Sie Notebooks fehlerfrei.

Machine assumptions documented

Was zählt
Ergebniscode bildet Pfade vom Projektordner oder einer Einstellung aus, prüft nicht unerklärt auf Rechner oder System, und das README nennt GPU, Speicher und Laufzeit.
Häufige Lücken
Pfade wie /Users/you/data, ein Skript, das Ihr eigenes Shell-Profil lädt oder andere Systeme ablehnt. Ungenannter GPU- oder Speicherbedarf: eine Warnung.
So beheben Sie es
Bilden Sie Pfade vom Projektordner aus, lassen Sie Datenorte überschreiben und nennen Sie Hardwarebedarf und Laufzeit im README:
python
from pathlib import Path
import os

ROOT = Path(__file__).resolve().parents[1]   # repository root, from src/pipeline.py
DATA = Path(os.environ.get("DATA_DIR", ROOT / "data"))
counts = DATA / "raw" / "counts.h5ad"

Ein aufgeräumtes Repository

Was zählt
Nur, was die Analyse braucht: kein System- oder Editor-Ballast, keine Arbeitskopien, Duplikate, großen Binärdateien, von Ihrer .gitignore ausgeschlossenen Dateien, ungenutzten Funktionen oder eingecheckten Schlüssel.
Häufige Lücken
Funktionen, die nichts aufruft, Dateien, die die Analyse nie liest (eine Warnung je Repository), oder ein API-Schlüssel im Code, den nur Sie sehen.
So beheben Sie es
Warnungen hier ändern die Stufe nie. Ergänzen Sie eine .gitignore, entfernen Sie Überflüssiges, widerrufen Sie eingecheckte Schlüssel und tilgen Sie sie aus der Historie.

Sehen Sie, wo Ihr Projekt steht

Starten Sie die Analyse für Ihr Paper oder Repository. Jeder Befund nennt seinen Bereich und verweist hierher.

Jetzt starten