Session, Workspace e note scientifiche

di Giux GX-TXT, python-it, scripts-it 3 min di lettura

Corso Python scientifico in GX-TXT · Modulo 7 · Lezione 38

Una Sessione raccoglie dati e risultati del lavoro. Un Workspace conserva uno stato di lavoro gestito da un provider; una nota può documentare un oggetto senza diventare essa stessa il Dataset. In questa lezione leggiamo la Sessione e associamo una nota a un Dataset sintetico.

Obiettivi

  • Leggere il riepilogo della Sessione e l’elenco dei Workspace.
  • Pubblicare una serie didattica e documentarla con una nota Markdown.
  • Rileggere la nota attraverso l’API pubblica.
  • Distinguere identità, contenuto numerico e documentazione.

Esecuzione

Nella Sessione corso_python, importa session_workspace.py, salvalo e avvialo da Run → Open Script Runner → Run Job. Lo script crea o aggiorna il proprio Dataset didattico corso_python_note_sintetiche; la nota viene scritta per quell’ID.

Script di Sessione e note nell'editor GX-TXT.
Script di Sessione e note nell'editor GX-TXT.
import numpy as np
from gxtxt import gxtxt_api_call, gxtxt_api_require

for api in ("SESSION_INSPECTION_API_v1@1", "SESSION_WORKSPACE_API_v1@1", "DATASET_PUBLICATION_API_v2@2", "DATASET_NOTES_API_v1@1"):
    gxtxt_api_require(api)
info = gxtxt_api_call("SESSION_INSPECTION_API_v1", "summary", [])
workspaces = gxtxt_api_call("SESSION_WORKSPACE_API_v1", "list", [])
dataset = "corso_python_note_sintetiche"
richiesta = {"dataset_id": dataset, "contract": "table.generic", "storage": "csv", "replace_owned": True,
    "x_values": np.array([0., 1., 2.]), "y_values": np.array([1., 1.2, 1.1]),
    "x_variable": {"variable_id": "tempo", "name": "tempo", "unit": "s"},
    "y_variable": {"variable_id": "segnale", "name": "segnale", "unit": "mV"},
    "provenance": "Serie sintetica per la lezione sulle note"}
gxtxt_api_call("DATASET_PUBLICATION_API_v2", "publish_series", [richiesta])
nota = "# Serie sintetica\n\nDati didattici, non misure. Tempo in s; segnale in mV.\n"
gxtxt_api_call("DATASET_NOTES_API_v1", "write", [dataset, nota])
letta = gxtxt_api_call("DATASET_NOTES_API_v1", "read", [dataset])
print("Sessione:", info["session_name"])
print("Workspace salvati:", len(workspaces))
print("Dataset annotato:", dataset)
print("Nota riletta:\n", letta)

summary restituisce informazioni sulla Sessione corrente. list restituisce i Workspace salvati; nell’esecuzione mostrata la lista è vuota. Un elenco vuoto non significa che la Sessione non contenga Dataset o grafici: sono risorse con ruoli distinti.

Lo script pubblica tre punti sintetici, con tempo in secondi e segnale in millivolt. Poi DATASET_NOTES_API_v1/write associa una nota Markdown al Dataset e read la rilegge. La nota dice che i dati sono didattici e ne esplicita le unità.

Output del Job: Sessione, numero di Workspace e nota riletta.
Output del Job: Sessione, numero di Workspace e nota riletta.

Una nota su un Dataset e una nota su un Workspace appartengono a oggetti diversi. Quando esiste un Workspace gestito, SESSION_WORKSPACE_API_v1 espone anche note_read e note_write usando il suo ID; qui non scriviamo una nota di Workspace perché nell’esempio non ce n’è uno salvato. Usa le API dei rispettivi proprietari, anziché modificare direttamente file interni della Sessione.

Documentare in modo utile

Una nota può descrivere origine dei dati, metodo, unità, ipotesi e limiti. Non sostituisce lo schema delle variabili né garantisce da sola che un risultato sia corretto. Conserva l’identità del Dataset a cui si riferisce e non attribuire a dati sintetici lo stato di misure.

Esercizio

  1. Il numero zero di Workspace implica che non ci siano Dataset nella Sessione?
  2. Quale ID identifica il Dataset annotato?
  3. Perché rileggere la nota dopo la scrittura?

Soluzione ragionata

  1. No: Workspace e Dataset sono risorse distinte.
  2. corso_python_note_sintetiche.
  3. Permette di controllare il contenuto restituito dall’API per quell’oggetto, anziché assumere che una stringa preparata in memoria sia stata salvata.

Nella prossima lezione descriveremo una trasformazione prima di applicarla.

Scarica gli script del Modulo 07 (ZIP)

#GX-TXT #Python #Riproducibilità

Altre tappe del progetto

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *