Croissant-Semantik

Semantik zu einem Croissant hinzufügen

Eine RoboCroissant-Datei gibt an, welche Dateien eine Wissensdatenbank hat und welche Spalten diese enthalten. Dieser Skill fügt die Bedeutung der Daten hinzu: welche Spalten gemeinsam ein Gen oder eine Krankheit beschreiben, was eine Zeile aussagt, welches Identifier-Präfix die IDs einer Spalte verwenden, wofür Codes stehen. Er schreibt dies in ein neues Croissant unter Verwendung von Croissant 1.1 Konstrukten und zeichnet auf, warum jede Aussage getroffen wurde.

Sie erstellen einen Plan (JSON, nach Layout), die Skripte wenden ihn an und prüfen ihn. Sie bearbeiten das Croissant nicht von Hand.

Ein- und Ausgaben

• Eingabe: ein Croissant (croissant.json oder croissant.json.gz) und ein Ausgabeverzeichnis, plus die semantics_answers.json der Betreuer neben dem Croissant, falls vorhanden.
• Ausgabe, im Ausgabeverzeichnis:
  • semantics_plan.json — der Plan (Format: reference/plan-format.md)
  • croissant.semantic.json (oder .json.gz, wenn die Eingabe gzip-komprimiert war) — das Ergebnis
  • check_report.md — Ausgabe von check.py (und check_report.load_errors.txt, vollständige mlcroissant-Fehler, wenn Datensätze nicht geladen werden konnten)
  • notes.md — Entscheidungen, nicht berücksichtigte Layouts und warum, sowie Fragen an die Betreuer der Wissensdatenbank

Das eingegebene Croissant wird niemals modifiziert. Legen Sie Downloads, Hilfsskripte und andere temporäre Dateien in OUT/work/ ab, nicht woanders.

Skripte

Alle in scripts/, direkt ausführbar (es sind uv run --script-Dateien und installieren ihre eigenen Abhängigkeiten). Verwenden Sie --help bei jedem von ihnen.

Skript	Verwendung
inventory.py CROISSANT [--layout ID] [--json F] [--common-columns]	Layouts (unterschiedliche Spaltensets) auflisten, größte zuerst; die Spalten eines Layouts, Datensatzmengen und Dateien beschreiben; die von den meisten Datensatzmengen gemeinsam genutzten Spalten auflisten
sample.py CROISSANT --layout ID	Echte Zeilen aus drei der Dateien des Layouts lesen; Beispielwerte jeder Spalte und deren Form anzeigen (CURIEs und deren Präfixe, nackte IDs, Listen, Codes)
dialects.py list/show/detect/read	Bekannte Dateiformate (VCF, GAF, MITAB, CTD, ...) als berechenbare Dialekte; welcher die Dateien eines Layouts liest; Datensätze nur mit dem lesen, was ein Croissant über die Datei sagt
vocab.py class/slot/search/associations/prefix/identify/term/ols/infores	Biolink-Klassen und -Slots (mit Vorschlägen für ähnliche Begriffe), Assoziationsklassen für ein Subjekt/Objekt-Paar, Identifier-Präfixe (Biolink + Bioregistry), welche Präfixe zu nackten IDs passen, Ontologiebegriffe nach ID oder Text und Infores-IDs für Quellnamen nachschlagen
apply_plan.py CROISSANT PLAN OUT	Den Plan in ein neues Croissant schreiben
check.py CROISSANT PLAN OUT --report R --load-records	--plan-only zuerst: Begriffe, Präfixe, Dialekte und Einheiten in Sekunden. Dann die vollständige Prüfung: überprüft Begriffe, Präfixe, Codes und Dialekte gegen Biolink und Stichprobendaten, führt den MLCommons-Validator aus, liest einige Datensätze über mlcroissant (aus den ersten Zeilen jeder Datei, nicht aus vollständigen Downloads) und meldet die Abdeckung

Arbeitsablauf

1. Untersuchung. Wenn neben dem Croissant eine semantics_answers.json existiert, lesen Sie diese zuerst: sie enthält die Antworten der Betreuer der Wissensdatenbank auf frühere Fragen (siehe "Betreuer-Antworten" unten). Stellen Sie diese Fragen nicht erneut; apply_plan.py und check.py wenden die Antworten automatisch auf Ihren Plan an. Führen Sie dann inventory.py CROISSANT aus. Notieren Sie die Wissensdatenbank (Name, Beschreibung, URL im Croissant) und wie sich die Datensatzmengen auf die Layouts verteilen. Große Wissensdatenbanken haben hunderte von Layouts; arbeiten Sie von oben nach unten.

Finden Sie jetzt die eigene Infores-ID der Wissensdatenbank (vocab.py infores NAME; versuchen Sie den vollständigen Namen, das Akronym und die URL) und setzen Sie sie als infores des Plans. Sie benennt die Ressource, deren Dateien dies sind, und Graph-Builder zitieren sie als Quelle für alles, was daraus gelesen wird: ohne sie wird die Transformationsstufe die Wissensdatenbank überhaupt nicht aufbauen. Wenn mehrere Einträge passen, wählen Sie den für die Ressource, die diese Dateien veröffentlicht, nicht einen Dienst, der sie weiterbereitstellt (infores:reactome, nicht infores:automat-reactome). check.py vergleicht sie mit dem, was der Rest Ihres Plans sagt: ein einzelner Aggregator oder provided_by-Konstante benennt ebenfalls die Wissensdatenbank (HCOP-Orthologe werden von infores:hgnc aggregiert), und eine Nichtübereinstimmung ist eine Warnung, die es zu klären gilt.

Wenn keiner passt, schlagen Sie eine vor: infores: und den Kurznamen der Wissensdatenbank in Kleinbuchstaben, durch Bindestriche getrennt (infores:bioplex, infores:expression-atlas), mit "infores_proposed": true im Plan. Schreiben Sie dann ihren Katalogeintrag mit vocab.py infores-entry CROISSANT --id infores:NAME, fügen Sie --knowledge-level und --agent-type hinzu, wenn die Dokumentation diese klar macht, und setzen Sie ihn in notes.md unter eine Überschrift Zu registrierende Infores-ID, ganz oben. Sagen Sie dort, dass der Benutzer sie mit einem Pull-Request im Infores-Registrierungssystem registrieren sollte (der Befehl gibt aus, wo), und dass sich die ID während der Überprüfung ändern kann. check.py behält eine Warnung für eine vorgeschlagene ID, bis sie registriert ist; erklären Sie sie nicht weg.

2. Wählen Sie die zu bearbeitenden Layouts aus. Zielen Sie auf die Layouts, die die meisten Datensatzmengen und die Kerninhalte abdecken (Assoziationen und die Hauptentitätstabellen) – typischerweise die Top 5–15, oder bis die verbleibenden Layouts nebensächlich sind (README-ähnliche Dateien, Protokolle, anzahlbezogene Dateien pro Version). Wenn es viele kleine Layouts gibt (inventory.py wird das sagen), teilen die Datensatzmengen wahrscheinlich Kernspalten: verwenden Sie inventory.py --common-columns und planen Sie diese Spalten einmal mit match.has_columns. Alles, was Sie auslassen, kommt in die skipped-Liste des Plans mit einem Grund. Wenige Layouts gut zu bearbeiten ist besser als viele schlecht.

3. Betrachten Sie für jedes Layout die Daten, bevor Sie etwas entscheiden.

   • inventory.py CROISSANT --layout ID für Spalten, Beschreibungen und Dateinamen. Eine Spalte mit der Markierung MIXED hat in verschiedenen Datensatzmengen unterschiedliche atomare Typen (die Pipeline leitet sie pro Datei ab); entscheiden Sie ihren Typ aus den Daten und setzen Sie atomic.
   • Für Tabellen: dialects.py detect CROISSANT --layout ID findet heraus, wie die Dateien geschrieben sind (Kommentarzeilen, Kopfzeile oder keine, Trennzeichen) unter den bekannten Formaten. Bekannte Formate (VCF, GAF, MITAB) haben veröffentlichte Spezifikationen; verlassen Sie sich auf diese, anstatt das Format neu zu entdecken. Wenn nichts passt, beschreiben Sie den Dialekt inline (reference/dialects.md). Ziehen Sie dann eine Stichprobe mit --dialect NAME, damit die Zeilen so gelesen werden, wie das Format es vorschreibt, und nicht geraten.
   • sample.py CROISSANT --layout ID für echte Werte. Es liest drei Dateien des Layouts (die am neuesten aussehende nach Namen, die größte, die kleinste), weil eine einzige Datei – oft ein alter Snapshot oder eine gefilterte Teilmenge – Werte verbergen kann (N/A-Platzhalter, zusätzliche Code-Werte, andere ID-Typen). --files N zieht mehr davon als Stichprobe; --record-set ID bezieht eine bestimmte Datei als Stichprobe. Wenn die Stichprobenziehung fehlschlägt (eine riesige Datei, ein Archiv, eine Dateigruppe), sagen Sie dies im basis des Plans und senken Sie die Konfidenz.
   • Für Code-Spalten (Typen, Evidenz, Beziehungen, Quellen) übersieht eine Stichprobe seltene Werte. sample.py CROISSANT --record-set ID --profile COL1,COL2 liest die gesamte Datei und zählt jeden unterschiedlichen Wert; wiederholen Sie --record-set, um mehrere Dateien zu addieren. Planen Sie anhand des Profils, nicht der Stichprobe.
   • Gehen Sie schonend mit den Servern der Wissensdatenbank um. Führen Sie jeweils nur einen Stichproben- oder Prüfbefehl pro Wissensdatenbank aus, niemals viele parallel: Hosts blockieren Bursts mit einer Bot-Herausforderung, und dann schlagen alle späteren Anfragen fehl. Die Skripte steuern ihre eigenen Anfragen und cachen Downloads (in ~/.cache/croissant-semantics/downloads; --refresh lädt erneut herunter), sodass ein erneutes Ausführen günstig ist (eine unter einem größeren --max-mb gecachte Kopie bedient eine kleinere). Wenn ein Skript eine Bot-Herausforderung oder einen HTTP 403 meldet, stoppen Sie die Stichprobenziehung für diesen Host, versuchen Sie nicht, sie zu umgehen, und sagen Sie in notes.md, welche Prüfungen nicht ausgeführt werden konnten. Die Skripte lehnen diesen Host dann für eine Stunde ab, über mehrere Läufe hinweg, und arbeiten mit gecachten Dateien.
   • Spreadsheets (xlsx und älteres xls), SQLite-Datenbanken und Parquet-Dateien werden ebenfalls als Stichproben gezogen und profiliert: das Blatt oder die Tabelle ist dasjenige, mit dem der Name der Datensatzmenge endet ("file.xlsx — Sheet1", "file.xlsx: Sheet1"), und die Stichprobenziehung schlägt fehl, anstatt zu raten, wenn sie es nicht sagen kann. Sie werden vollständig gelesen, erhöhen Sie also --max-mb falls nötig (auch bei check.py). mlcroissant kann keine Spreadsheets oder Datenbanken lesen, daher werden ihre Datensätze nicht geladen.
   • XML, RDF (Turtle, RDF/XML, OWL), FASTA und andere Dateien, die keine Tabellen sind, können nicht als Stichproben gezogen werden: die Skripte sagen dies. Wenn ein Layout wichtig ist, überprüfen Sie seine IDs mit einem kleinen Skript in OUT/work/ (uv run --with rdflib für RDF; streamen Sie XML mit xml.etree.ElementTree.iterparse) und sagen Sie, wie in notes.md. Ihre Felder haben normalerweise kein extract, daher kann kein Werkzeug sie lesen: ein Generatorproblem, das gemeldet werden muss.
   • --profile mit --layout profiliert --files Datensatzmengen des Layouts (Standard 3, oder all), anstatt jede mit --record-set zu benennen. --prefixes zählt das Präfix oder Tag jedes Werts, für alle profilierten Spalten oder nur für die aufgelisteten (--prefixes COL1,COL2); --by COL kreuztabelliert gegen eine andere Spalte (welche Objekttypen bei welchem Code vorkommen); --split SEP zählt die Elemente von Listen-Zellen; --per-file profiliert jede Datensatzmenge einzeln (um zu prüfen, ob IDs pro Datei eindeutig sind); --stop-mb N stoppt jede Datei nach N MB, für Dateien mit vielen GB (die Zählungen decken dann nur den Anfang ab; in einer nach Spezies oder ID sortierten Datei kann das nur eine Gruppe sein, sagen Sie es also).
   • Profilieren Sie ID-Spalten der Hauptlayouts (--profile COL --shapes), bevor Sie ihnen vertrauen: die Datenprüfung liest die ersten Zeilen einiger Dateien, daher besteht eine Spalte, deren spätere Zeilen keine IDs haben oder eine andere ID-Familie enthalten, sie. Mehrere Wissensdatenbanken hatten 20–30 % der Zeilen ohne ID nach Hunderten von Zeilen, die alle eine hatten.
   • Ein match.has_columns-Eintrag, der viele Layouts abdeckt, wird von check.py nur auf wenigen seiner Dateien als Stichprobe geprüft. Ziehen Sie die Layouts, die er umfasst, nach Stichproben, die sich unterscheiden (--record-set-name, --files), bevor Sie ihm vertrauen.
   • Die Skripte verwenden den Zertifikatsspeicher des Betriebssystems. Wenn Downloads dennoch mit einem Zertifikatsfehler fehlschlagen, melden Sie dies mit der Ausgabe; schalten Sie die Überprüfung nicht aus.
   • Wenn die Dokumentation hinter einer Bot-Prüfung steckt ("Bestätigen Sie, dass Sie ein Mensch sind", eine Cloudflare- oder ALTCHA Herausforderung), versuchen Sie nicht, diese zu umgehen; planen Sie anhand von Daten und Namen und begrenzen Sie die Konfidenz auf medium für Bedeutungen, die nur die Dokumentation bestätigen könnte. Die Herkunft des Croissants kann auf Seiten verweisen, die seitdem hinter eine Prüfung gestellt wurden: zitieren Sie nur, was Sie lesen konnten.
   • In einer riesigen Datei können die ersten Zeilen nicht repräsentativ sein (CTDs 3 GB genes_diseases beginnt mit Tausenden von abgeleiteten Zeilen). Profilieren Sie eine kleinere Datei desselben Layouts (die kuratierte Teilmenge), anstatt das Ganze zu streamen.
   • Verwenden Sie --record-set-name REGEX (anstelle von --layout), um Datensatzmengen nach Namen auszuwählen, anstatt eine Liste von --record-set-Argumenten in der Shell zu erstellen (zsh teilt Variablen nicht in Wörter auf). --per-file zeigt jede beprobte Datei einzeln an, für Layouts, deren Dateien sich unterscheiden (eine ID-Art pro Datei).
   • Die Datenprüfung liest die ersten Zeilen einiger Dateien. Die späteren Zeilen einer Spalte können abweichen (leere Knoten nach 200 IRIs, ein seltener Code): bestätigen Sie ID-Formulare und Codes mit --profile, das ganze Dateien liest.
   • inventory.py listet Dokumentationsdateien, die mit den Daten ausgeliefert werden (README.pdf in einem Zip, ein Datenwörterbuch), nach den Layouts auf. Lesen Sie die relevanten: sample.py CROISSANT --dump FILE gibt eine Datei als Text aus, --member NAME ein Mitglied eines Archivs (ein Zip wird vollständig gelesen, erhöhen Sie also --max-mb für ein großes) (es listet die Mitglieder eines Zip auf, wenn der Name falsch ist), --sheet NAME ein Blatt einer Tabelle.
   • sample.py markiert Spalten, deren deklarierter Typ nicht zu den Werten passt (eine sc:Integer-Spalte, die 27152464|29518214 enthält) und Dateien, deren Zeilen breiter oder schmaler als die Kopfzeile sind. Beides sind in der Regel Pipeline-Probleme: beheben Sie Typen mit atomic und melden Sie sie.
   • Wenn die Skripte eine Quelle nicht lesen können, holen Sie die Dateien selbst (eine nach der anderen, in OUT/work/) und weisen Sie die Skripte mit --url-map OLD=file:///abs/path/ darauf hin, damit ihre Prüfungen dennoch laufen, anstatt eigene Profiler zu schreiben. Downloads werden gecacht, und ~/.cache/croissant-semantics/downloads/index.tsv ordnet jede gecachte Datei ihrer URL zu.
   • Wenn die "Spaltennamen" eines Layouts eigentlich Daten sind (keine Kopfzeile, daher hat die Pipeline die erste Datenzeile als Namen genommen, und jede Datei wurde zu einem eigenen Layout), überspringen Sie es und melden Sie es in notes.md als Pipeline-Problem.
   • Wenn die Daten-URLs verschwunden sind (HTTP 404), ist die Wissensdatenbank wahrscheinlich zu einer neueren Version übergegangen. Finden Sie die aktuellen URLs auf ihrer Download-Seite und übergeben Sie --url-map OLD=NEW an sample.py und check.py (z.B. --url-map 202607=202610). Wenn mehr als die Version geändert hat (ein anderer Pfad oder Dateiname), mappen Sie ganze URLs, eine --url-map OLD_URL=NEW_URL pro Datei. Wenn die URLs selbst = enthalten (Abfragezeichenfolgen), schreiben Sie OLD=>NEW. Sagen Sie dies in notes.md; es ist ebenfalls ein Pipeline-Problem. Eine SPARQL-Endpunkt-URL, die JSON zurückgibt, wo das Croissant eine Tabelle beschreibt, benötigt normalerweise ein gemapptes &format=csv (oder text/csv).
   • Archive: Mitglieder von Zip- und Tar-Archiven werden als Stichproben gezogen. Ein Zip wird vollständig heruntergeladen (bis zu --max-mb); ein Tar wird gestreamt, bis das Mitglied gefunden wird, daher kann ein tief in einem riesigen Tar liegendes Mitglied --max-mb überschreiten. Ein Archiv, das einmal fehlschlägt, wird nicht erneut versucht, und die Stichprobenziehung stoppt nach wiederholten Fehlschlägen. Wenn Sie müssen, extrahieren Sie ein Mitglied selbst in OUT/work/ und notieren Sie, was Sie geprüft haben und wie in notes.md.
   • Wenn die Daten einen Login oder API-Key benötigen (HTTP 401/403, oder das Croissants conditionsOfAccess sagt dies), suchen Sie nicht nach Anmeldeinformationen. Planen Sie nur anhand der Dokumentation und der Spaltennamen: source ist documentation oder agent, confidence maximal medium, und notes.md sagt, dass nichts gegen Daten geprüft wurde.
   • **Suchen Sie nach einer mitgelieferten Da…

…