Sessions, Workspaces and Scientific Notes

by Giux GX-TXT, python-en, scripts-en 3 min read

Scientific Python in GX-TXT · Module 7 · Lesson 38

A Session collects data and results of the work. A Workspace retains a status of work managed by a provider; a note can document an object without becoming the Dataset itself. In this lesson we read the Session and associate a note with a synthetic Dataset.

Objectives

  • Read the summary of the Session and the Workspace list.
  • Publish a didactic series and document it with a well-known Markdown.
  • Reread the note through the Public API.
  • Distinguish identity, numerical content and documentation.

Execution

In the corso_python Session, import session_workspace.py, save it and run it from Run → Open Script Runner → Run Job. The script creates or updates its educational dataset corso_python_note_sintetiche; the note is written for that ID.

Session and notes script in the GX-TXT editor.
Session and notes script in the GX-TXT editor.
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"
request = {"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": "Synthetic series for the lesson on notes"}
gxtxt_api_call("DATASET_PUBLICATION_API_v2", "publish_series", [request])
note = "# Synthetic series Teaching data, not measures. Time in s; signal in mV.\n"
gxtxt_api_call("DATASET_NOTES_API_v1", "write", [dataset, note])
retrieved = gxtxt_api_call("DATASET_NOTES_API_v1", "read", [dataset])
print("Sessione:", info["session_name"])
print("Workspace saved:", len(workspaces))
print("Dateset noted:", dataset)
print("Note:\n", retrieved)

summary returns information about the Current Session. list returns saved Workspaces; in the execution shown the list is empty. An empty list does not mean that the Session does not contain Dataset or graphs: they are resources with distinct roles.

The script publishes three synthetic points, with time in seconds and signal in millivolt. Then DATASET_NOTES_API_v1/write associates a Markdown note to the Dataset and read reread. The note says that the data is didactic and explicit the units.

Job output showing the Session, the Workspace count and the retrieved note.
Job output showing the Session, the Workspace count and the retrieved note.

A note on a Dataset and a note on a Workspace belong to different objects. When a managed Workspace exists, SESSION_WORKSPACE_API_v1 also exposes note_read and note_write using its ID; here we do not write a Workspace note because there is no saved example. Use the APIs of the respective owners, instead of directly modifying the internal files of the Session.

Documentation in a useful way

A note can describe the origin of data, method, unity, hypotheses and limits. It does not replace the variable scheme nor warrants on its own that a result is correct. It retains the identity of the Dataset to which it refers and does not attribute to synthetic data the status of measures.

Exercise

  1. Does the zero number of Workspace imply that there are no Datasets in the Session?
  2. Which ID identifies the annotated dataset?
  3. Why reread the note after writing?

Worked solution

  1. No: Workspace and Dataset are distinct resources.
  2. corso_python_note_sintetiche.
  3. It allows you to control the content returned by the API for that object, instead of assuming that a string prepared in memory has been saved.

In the next lesson, we will describe a transformation before applying it.

Download the Module 7 scripts (ZIP)

#GX-TXT #Python #Reproducibility

Other steps of this project

Leave a Reply

Your email address will not be published. Required fields are marked *