Publishing a Derived Series
Scientific Python in GX-TXT · Module 4 · Lesson 23
A scientific transformation should produce a distinguishable result from the starting data and accompanied by information about its origin. In this lesson we convert a synthetic series from millivolt to volts, we publish it as a new canonical dataset and read it through the public API.
Objectives: to distinguish given source and derived; to apply a declared conversion; to publish a series with own identity and units; to compare the values chosen with the expected ones.
Prerequisites: conversions of lesson 16, Dataset identity and reading of lessons 19–21.
Why create a new Dataset
A memory result exists only during the execution of the script; a disk file is not automatically a recorded Dataset in the Session. The publication through a GX-TXT API creates an identity and a pattern that other Session tools can use.
Keeping the Source Dataset and publishing a separate derivative makes the relationship between input and output clearer. It is also necessary to describe the transformation: a different label does not show that the values have been converted correctly.
Proposed transformation
We start from the corso_python_serie_sintetica synthetic series: [0.0, 0.5, 1.0, 1.5] s times and [1.2, 1.5, 1.3, 1.6] mV signals. They are invented values, not experimental measures, without uncertainty assigned. The proportional conversion is:
segnale in V = segnale in mV / 1000
The expected values are [0.0012, 0.0015, 0.0013, 0.0016] V. The time remains expressed in seconds and associated with the same line. In lesson 16 we compared the conversion with the unit register; here we focus on the publication of the result.
publish_series and provenance
DATASET_PUBLICATION_API_v2/publish_series receives a request with ID of the new Dataset, contract, X and Y values and variable descriptors. In the example the ascissa is time_values in s, the order is signal_v in V and the source_dataset_ids field indicates the source dataset. The provenance string describes the division for 1000 and the synthetic nature of the data.
The request uses replace_owned=True: a new execution can replace the derived Dataset only if the provider rules authorize that manufacturer. Do not use this option to overwrite a different property dataset; in case of conflict choose a free ID. The publication does not intentionally change the source dataset.
Full code
import numpy as np
from gxtxt import gxtxt_api_call, gxtxt_api_require
gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
gxtxt_api_require("DATASET_PUBLICATION_API_v2@2")
source = "corso_python_serie_sintetica"
derived = "corso_python_serie_volt"
b = gxtxt_api_call("CANONICAL_DATASET_API_v2", "read_range", [source, ["tempo", "segnale"], 0, 4])
time_values = np.asarray(b["tempo"]["values"]).reshape(-1)
signal_mv = np.asarray(b["segnale"]["values"]).reshape(-1)
signal_v = signal_mv / 1000.0
request = {"dataset_id": derived, "contract": "table.generic", "storage": "csv", "replace_owned": True,
"x_values": time_values, "y_values": signal_v,
"x_variable": {"variable_id": "tempo", "name": "tempo", "unit": "s", "semantic_role": "time"},
"y_variable": {"variable_id": "segnale_v", "name": "segnale_v", "unit": "V", "semantic_role": "voltage"},
"source_dataset_ids": [source], "provenance": "Synthetic series: conversion from mV to V, division by 1000"}
gxtxt_api_call("DATASET_PUBLICATION_API_v2", "publish_series", [request])
readback = gxtxt_api_call("CANONICAL_DATASET_API_v2", "read_range", [derived, ["segnale_v"], 0, 4])
values = np.asarray(readback["segnale_v"]["values"]).reshape(-1)
print("Sorgente (mV):", signal_mv)
print("Series published (V):", values)
print("Comparison with conversion:", np.allclose(values, signal_v, rtol=1e-12, atol=1e-15))
The script knows the column shape and the number of rows of the starting series; a generic program must check schema, length and drive before turning the data. np.allclose compares the values with explicit tolerances, here chosen for the small numerical example: they are not an experimental uncertainty.
The rereading of the derivative uses the canonical API, so check what GX-TXT has published instead of limiting itself to the array in memory. For a real case, it also checks metadata, selection, units and completeness of the whole.

The script reads the source, converts and publishes a new series.
Execution
- Open Session with
corso_python_serie_sinteticaand Viewer Python Scripts. - Import
derived_series.py, assigns name and Script ID into thesessionbroom, then saves. - Open the Runner and press Run Job.
- Compare the values of the series published with those expected in volts and check that the printed comparison is
True. The derived dataset has IDcorso_python_serie_volt.

The inlet series contains the converted values and agrees with the calculation for the selected tolerances.
Common error
Publish the same numbers by changing only the unit from mV to V would multiply the physical value for a thousand. A conversion requires both the transformation of values and consistent metadata. A correct conversion function should also be applied to the right variables and axes.
Exercise
A synthetic reading of 2.5 mV is converted into volts. What is the numerical value? What information should you keep together with the derived series?
Worked solution
2.5 / 1000 = 0.0025 V. It maintains at least the identity of the source, the operation and the units of departure and arrival; for real measures it also retains uncertainty, method and other information necessary for their interpretation.
In the next lesson we will deepen the structured writer and the annulment of an incomplete publication.