Variables, Schemas and Scientific Units
Scientific Python in GX-TXT · Module 4 · Lesson 20
A numerical column is not yet a complete description of a scientific data. To interpret it, it serves at least identity, meaning and unity, in addition to the context necessary to understand origin and quality. In this lesson we will read the diagram of the variables of a Dataset GX-TXT and its public metadata.
Objectives: distinguish ID and name of a variable; read descriptors and units; recognize absent fields; avoid attributing undocumented meanings.
Prerequisites: dictionaries, catalogue and identity Dataset of lectures 5 and 19; Session with the synthetic series of lesson 9.
What describes a pattern
A scheme describes the structure of the data: what variables exist, how they are identified and what properties are available. Depending on the Dataset and the version, a descriptor may contain numerical type, form, unit, label, semantic role and coordinate information.
A variable ID is the reference used in public calls. A name or a label is presentation information and can have different rules. Do not use the column’s position as a substitute for the ID when the API offers a stable identity.
In the Dataset corso_python_serie_sintetica the IDs are time_values and signal. The first variable uses seconds (s), the second millivolt (mV). The four points are synthetic, chosen for the course, and do not have an experimental uncertainty assigned.
Type, Unit and Role
The type, for example float64, describes how numerical values are represented. He doesn’t say alone if a number represents time or tension. The unit specifies the scale of magnitude, while the semantic role can indicate its meaning, such as time or voltage.
A column header such as signal does not guarantee alone units, precision, provenance or uncertainty. If a property is not present, it must be treated as absent: do not invent a unit or a conversion on the basis of the only name. An empty string, an absent field and a None value may require different interpretations according to the API contract.
Public APIs for the scheme
DATASET_VARIABLE_SCHEMA_API_v3/list receives the Dataset ID and returns a list of variable descriptors. get receives the Dataset ID and a variable ID and returns its descriptor. DATASET_METADATA_API_v1/read reads dataset metadata in the current session.
In the example we process variables returned from list, we take variable_id and we ask for details with get. We use .get for optional fields. In the result observed the field questioned as name is not present and therefore is shown None: this does not mean that the variable does not have an ID. For the names and labels actually available, refer to the documented fields of the descriptor in the version in use.
Calls in the cycle are one per variable: on Dataset with many variables or on remote archives can have a cost. Reuse the descriptors already obtained when your job allows it and do not hypothesize about the order of the list.
Full code
from gxtxt import gxtxt_api_call, gxtxt_api_require
gxtxt_api_require("DATASET_VARIABLE_SCHEMA_API_v3@3")
gxtxt_api_require("DATASET_METADATA_API_v1@1")
dataset = "corso_python_serie_sintetica"
variables = gxtxt_api_call("DATASET_VARIABLE_SCHEMA_API_v3", "list", [dataset])
print("Number of variables:", len(variables))
for entry in variables:
identifier = entry["variable_id"]
detail = gxtxt_api_call("DATASET_VARIABLE_SCHEMA_API_v3", "get", [dataset, identifier])
print("ID:", identifier, "nome:", detail.get("name"), "unita:", detail.get("unit"))
print("Type:", detail.get("dtype"), "ruolo:", detail.get("semantic_role"))
metadata = gxtxt_api_call("DATASET_METADATA_API_v1", "read", [dataset])
print("Available metadata:", metadata)
entry["variable_id"] requires an indispensable field for the next call. The other fields are read with get, so an absence remains visible as None. The last metadata law of the Dataset, distinct from the descriptors of the individual variables.

The script questions the list and details of the variables with public APIs.
Execution
- Open the Session containing
corso_python_serie_sinteticaand the Viewer Python Scripts. - Import
variable_schema.py, assigns name and Script ID into thesessionbroom, then saves. - Launch the Runner and press Run Job.
- Check output: There are two variables in the example.
time_valuesreportssandtime;signalreportsmVandvoltagerole. The questionednamefield appears asNonein the response shown.

IDs, units and roles are read by Dataset; a field not present is not invented.
Common error
Seeing a column called time_values and assuming that it is always expressed in seconds can produce wrong conversions. Read the declared unit and verify that it is appropriate for analysis. Similarly, float64 does not indicate experimental accuracy: it describes numerical representation, not measurement uncertainty.
Exercise
A descriptor contains {"variable_id": "temperatura", "unit": "K"} but does not contain the dtype key. What does descrittore.get("dtype") return? Is it correct to conclude that the type is float64?
Worked solution
get returns None when the key is missing and there is no alternative value. It is not correct to invent float64: consult the scheme and the available data or report that the information is not present.
In the next lesson we will read more variables for blocks keeping the alignment.