Scientific Python in GX-TXT · Module 4 · Lesson 24

The publication of structured data may take multiple steps: declare dimensions and variables, write values and conclude the operation. In this lesson we use the public writer of GX-TXT to create a Synthetic Dataset with two variables and observe the cancellation of a second incomplete publication.

Objectives: to include begin, schema statement, write_variable, finalize and abort; to distinguish a complete Dataset from an undone attempt; to reread the published values.

Prerequisites: Dataset and variables of lessons 19–23, exceptions and Python functions.

A multi-step publication

A writer is the managed object used to prepare and write a Dataset. With DATASET_PUBLICATION_API_v2 the example path is:

  1. begin: prepares the writer for a definition of Dataset.
  2. declare_dimension: declares a size and its length.
  3. declare_variable: associates with each variable type, rank, size and unit.
  4. write_variable: writes the values of declared variables.
  5. finalize: concludes the publication.
  6. abort: undoes a writer that should not be concluded.

These operations work through the public provider: the script does not directly change the Session log. A transaction is used to prevent an incomplete sequence being presented as a complete publication. Exact guarantees and error conditions depend on the contract and the transaction documented.

Example Data and Scheme

We create corso_python_writer_sintetico with three samples. The time_values variable contains [0.0, 0.5, 1.0] s; signal contains [1.2, 1.5, 1.3] mV. Both are float64, rank 1, associated with the sample size of length 3. The data are synthetic, not experimental measures and have no uncertainty assigned.

The coordinate role signals the time variable; data signals the signal content. Type, form, unity and role must be consistent with values and scientific meaning. The form passed to the writing is [3] for each variable.

Managing the Writer

The try block contains statements, scripts and finalize. If one of these operations raises an exception, the manager asks abort and then uses raise to propagate the error. It doesn’t turn a failure into a successful message. In real applications it is also necessary to consider the case when cleaning itself fails, keeping the message of the original error.

After full publication, we open a second writer for corso_python_writer_annullato, we declare a dimension and call intentionally abort without writing or finalizing. Then we ask for the catalogue: in the execution shown the unsubscribed ID is not present. This is a controlled example of cancellation, not proof of all possible faults or interruptions.

The replace_owned=True option on the full definition allows replacement only when authorized by the provider rules for the manufacturer. Do not replace Dataset of different properties: use a dedicated session and free ID if necessary.

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")
api = "DATASET_PUBLICATION_API_v2"
dataset = "corso_python_writer_sintetico"
definition = {"dataset_id": dataset, "contract": "table.generic", "storage": "hdf5", "replace_owned": True, "provenance": "Teaching Synthetic Data"}
writer = gxtxt_api_call(api, "begin", [definition])
try:
    gxtxt_api_call(api, "declare_dimension", [writer, "campione", 3, {"extendible": 0}])
    schema_t = {"dtype": "float64", "rank": 1, "dimension_ids": "campione", "unit": "s", "coordinate_role": "coordinate"}
    schema_y = {"dtype": "float64", "rank": 1, "dimension_ids": "campione", "unit": "mV", "coordinate_role": "data"}
    gxtxt_api_call(api, "declare_variable", [writer, "tempo", schema_t])
    gxtxt_api_call(api, "declare_variable", [writer, "segnale", schema_y])
    gxtxt_api_call(api, "write_variable", [writer, "tempo", np.array([0.0, 0.5, 1.0]), [3]])
    gxtxt_api_call(api, "write_variable", [writer, "segnale", np.array([1.2, 1.5, 1.3]), [3]])
    result = gxtxt_api_call(api, "finalize", [writer])
except Exception:
    gxtxt_api_call(api, "abort", [writer])
    raise
print("Full dataset:", result.get("dataset_id"))
trial_value = "corso_python_writer_annullato"
temporary = gxtxt_api_call(api, "begin", [{"dataset_id": trial_value, "contract": "table.generic", "storage": "hdf5"}])
gxtxt_api_call(api, "declare_dimension", [temporary, "campione", 3, {"extendible": 0}])
gxtxt_api_call(api, "abort", [temporary])
catalog = gxtxt_api_call("CANONICAL_DATASET_API_v2", "list", [])
print("Dateset cancelled present:", trial_value in catalog)
read_result_value = gxtxt_api_call("CANONICAL_DATASET_API_v2", "read_range", [dataset, ["tempo", "segnale"], 0, 3])
print("Tempo (s):", read_result_value["tempo"]["values"].reshape(-1))
print("Segnale (mV):", read_result_value["segnale"]["values"].reshape(-1))

The rereading uses CANONICAL_DATASET_API_v2/read_range: so we compare the published values with the written ones. The reshape(-1) transformation is appropriate for these two single-dimensional variables read as columns; do not apply it without verifying the meaning of the shape in a multi-dimensional Dataset.

Structured-writer script in the GX-TXT Python editor.
Structured-writer script in the GX-TXT Python editor.

The writer declares scheme and values before the publication is completed.

Execution and control

  1. Open a dedicated session and the Viewer Python Scripts.
  2. Import structured_writer.py, assigns name and Script ID into the session broom, then saves.
  3. Open the Runner and press Run Job.
  4. Check that the output indicates the full Dataset, Dataset annullato present: False and the two sets of three expected values.
Results of publication and controlled cancellation.
Results of publication and controlled cancellation.

The complete Dataset is readable; the canceled attempt does not appear in the catalog shown.

Common error

Declaring a dimension of three elements and writing a different number is not a simple label difference: the scheme and the data would be inconsistent. Check form, type and unit before writing and do not declare publication completed when one of the necessary operations has failed.

Exercise

To publish four samples instead of three, what parts of the example should they change? What control would you use after publication?

Worked solution

It is necessary to declare the sample size with length 4, to provide four consistent values for each variable and to indicate the [4] shape to the scripts. After finalize, reread four rows with the canonical API and compare values, units and schemas with those provided. The data must be clearly identified as synthetic if invented.

In the next module we will use numerical APIs for transformations and models.

Download the Module 4 scripts (ZIP)

#Datasets #GX-TXT #Python

Other steps of this project

Leave a Reply

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