GX-TXT Python Script Workspace: saving and reloading typed Parameter Datasets

The Parameter Dataset lets you keep in GX-TXT the values of an already verified Python invocation, together with the types, the declarations and the revision of the corresponding Script. Script Runner offers Save parameters as Dataset and Load parameters: these commands prepare and retrieve reproducible configurations, without running Python. The guide shows a set of synthetic parameters and the checks that prevent applying presets that are incomplete, obsolete or tied to another Script.

1. Why save the parameters of a scientific procedure

The same procedure can be repeated changing coefficients, number of replicates or processing mode. Keeping only the source does not document which values were chosen in a particular preparation of the computation. A Parameter Dataset keeps a typed set of values for a specific registered Script, allowing them to be retrieved for a new check before any execution.

2. Parameter Dataset and scientific Dataset are not the same thing

A numeric Dataset can contain observations or measurements, for example a sequence of temperatures. A Parameter Dataset is instead a canonical configuration Dataset, with contract gxtxt.script_parameters.v1. Its variables describe the parameters of the invocation. It must not be confused with a results Dataset or with the Python file that performs the analysis.

3. Three identities to keep distinct

The Script is identified by the registered reference, the revision and the SHA-256 of the source. The Parameter Dataset has its own Dataset ID, revision and content integrity. A possible Job is a third entity, created only by an explicit submission. Saving or loading a preset does not change the revision of the program and does not create a Job.

4. Requirements for using a preset

Open the correct Session and choose an already saved Script in Python Script Workspace. The Script should declare its parameters through gxtxt_parameter_declare() or through the editor’s typed parameters table. Check the reference, version and revision of the source: a preset can be retrieved only when its identity and schema are compatible with those of the current Script.

5. Opening Script Runner and locating Parameter Dataset

Use Run → Open Script Runner… with a saved, unmodified Script. The Runner presents the typed parameters and, below them, the Parameter Dataset section with the Dataset ID and Save label (optional) fields. The Load parameters and Save parameters as Dataset buttons perform different operations. Their presence does not mean that a Job has already been launched.

Original Script Runner with four parameters and the Load parameters and Save parameters as Dataset buttons.
Figure 1. The Runner exposes the typed parameters and the Load parameters and Save parameters as Dataset commands.

6. Preparing a synthetic example

Consider four Script parameters: gain of type double, replicates of type integer, mode of type choice and operator of type string. Their schema was registered together with the source. To illustrate saving, we set values different from some of the defaults:

ParameterTypeChosen value
gaindouble2.25
replicatesinteger5
modechoiceoffset
operatorstringbatch

These are teaching values, not experimental measurements or results of an execution.

7. Filling in the typed fields

Change the values directly in the Runner. The numeric editor applies the type and any limits set by the declaration; a choice field allows only the available alternatives. It is useful to press Validate review before saving: a configuration that does not pass validation should not be treated as a ready-to-use preset.

Script Runner with edited values, the preset Dataset ID and its descriptive label.
Figure 2. The Script values have been set and the Dataset ID chosen before saving.

8. Adding a parameter valid for a single invocation

To also associate a coefficient not present in the registered schema, choose Add parameter… in the Additional parameters for this invocation section. The native dialog lets you specify Name, Type, Value, Required, Description, Choices, Minimum and Maximum. In our example we add an offset of type double, with initial value 0.75 and allowed range from −2.0 to 2.0.

Original Tk Add invocation parameter dialog with name, type, value, Required, Choices and limits.
Figure 3. The original dialog lets you add a further parameter with type, default and limits.

9. An additional schema does not modify the source

After Apply, the new offset appears with the Edit and Remove buttons. It is a manual_invocation parameter, that is, it belongs to the current configuration and not to the Script Registry. Saving the Parameter Dataset also keeps this additional declaration, so that its meaning and limits can be reconstructed during loading.

Script Runner with manual parameter offset double 0.75 and Edit and Remove buttons.
Figure 4. The manual offset appears among the additional parameters before the preset is published.

10. Dataset ID and Save label have different functions

In the Parameter Dataset panel, enter a new, valid Dataset ID. The identifier is the canonical key in the Session; the Save label (optional) is a description for the user, which can convey the role of the preset. Do not enter a file path instead of the ID. A stable, understandable name, different from those already registered, is preferable.

11. Saving with Save parameters as Dataset

Once the values have been checked, press Save parameters as Dataset. If all constraints are satisfied and the Dataset ID is available, GX-TXT publishes the preset as a canonical Dataset. The Runner confirms the commit with a message specifying that no Job was submitted. The procedure does not change the revision of the Python Script.

Runner with the Parameter Dataset committed message, five typed values and no Job.
Figure 5. Saving the Parameter Dataset is confirmed without starting any Job.

12. The canonical format and the saved variables

The Parameter Dataset uses the gxtxt.script_parameters.v1 contract and contains one row of values. Each effective parameter corresponds to a stable variable, with the prefix p_, for example p_gain or p_replicates. The integer type is stored as int64, double as float64, while string and choice use text variables. There is also preset_marker, a boolean marker that preserves a canonical row even for presets with empty values.

13. The preset also keeps the declarations

In addition to the five values, the metadata keep the schema version, the qualified reference of the Script, the SHA-256, the revision and the typed definitions. The parameters coming from the Registry and those added manually remain distinct as registry_declarations and invocation_declarations. This allows loading to reconstruct an effective schema, checking its origin and compatibility.

14. The publication namespace

Saving normally creates the Parameter Dataset in the private namespace of the producer module, for example that of the Python analysis module. The namespace is an organisational property of the Session, not a directory to be entered in the Dataset ID field. Reading can use a compatible preset even when it has been legitimately moved to another namespace of the same Session; this does not grant new write rights.

15. An existing Dataset ID is not overwritten

If you press Save parameters as Dataset again with an identifier already present, GX-TXT refuses the new commit. No implicit replacement takes place: the existing Dataset keeps its revision, values and SHA-256. To save a different configuration, choose a new Dataset ID instead of relying on an automatic update of the previous preset.

Runner with Save parameters as Dataset error: Dataset ID already exists.
Figure 6. A second save with the same Dataset ID is refused without overwriting the preset.

16. Changing the current values before loading

To understand retrieval, temporarily change the displayed values: set gain back to 1.5, replicates to 3, mode to linear, change operator and remove the offset row. These operations affect only the Runner; the already published Parameter Dataset remains unchanged. Loading serves precisely to replace this local configuration with the one saved previously.

Runner with temporary current values and no offset parameter before Load parameters.
Figure 7. The local changes and the removal of offset distinguish the current buffer from the values saved in the preset.

17. Using Load parameters

Enter in the Dataset ID field the identifier of the Parameter Dataset to retrieve and press Load parameters. GX-TXT checks the whole document, including type, constraints, provenance and integrity, before applying any value. If loading succeeds, the Runner reports that the values have been loaded and requires an explicit check before any Run Job.

18. Loading also restores the offset

After Load parameters the values gain=2.25, replicates=5, mode=offset and operator=batch reappear, along with the manual row offset=0.75. Not only the value is restored: the additional declaration needed to interpret and validate it also returns. Validate review can then confirm that the request is consistent, without running the program.

Runner with the five typed values restored and the manual offset back after Load.
Figure 8. Load parameters restores registered values, mode and the manual offset parameter together.

19. The integrity checks of loading

Reading requires a canonical Dataset with the correct contract, a complete row and the expected Variable IDs. It also checks the types, the content fingerprint, the identity of the Script and the compatibility of the declarations. A missing or incompatible value causes a rejection, not a partial load. The original values of the window must remain available when the operation fails.

20. An ordinary numeric Dataset is not a preset

Choosing by mistake the ID of an observations Dataset instead of that of a Parameter Dataset is not enough for loading. The Runner recognises that the contract is not gxtxt.script_parameters.v1 and shows Parameter Dataset load failed, leaving the current values unchanged. You need to locate the real preset and repeat Load parameters.

Runner with the Parameter Dataset load failed warning for an incompatible contract.
Figure 9. Loading an ordinary numeric Dataset is rejected and the current values remain unchanged.

21. A different Script cannot automatically use the same preset

A preset is associated with a specific qualified reference of the Script and with its schema. If the Runner of a different Script is opened and you try to load the same Dataset, an incompatible reference message appears. It is not enough for two programs to have similar parameter names: the identity and the declarations must fully satisfy the compatibility contract.

Runner of another Script with the Parameter Dataset has incompatible reference error.
Figure 10. Another Script cannot load a preset created for a different identity and schema.

22. Why the revision of the preset must be checked

A Parameter Dataset has its own revision, independent of the revision of the Python source. After loading, the Runner keeps a reference to the verified revision and SHA-256. If the Dataset changes or is moved to a different namespace with a change recorded in the metadata, that association can become stale. The Runner must not automatically replace the previously accepted revision.

23. Validate review catches a changed revision

Suppose the Parameter Dataset is reorganised in the Session after being loaded and its revision token changes, while keeping identity and numeric content. When pressing Validate review, the Runner reports Parameter Dataset changed; load it again. The check rejects the old association before a Job and requires a new decision by the user.

Runner with the Parameter Dataset changed; load it again message after a revision change.
Figure 11. Validate review recognises that the Parameter Dataset revision has changed and requires a new load.

24. Reloading the preset from its new location

After checking the current identity of the Dataset, press Load parameters again and repeat Validate review. A compatible preset can also be read from another namespace of the same Session; the Current namespace does not necessarily have to coincide with the one of initial publication. The new revision is verified explicitly, while the scientific values remain those saved.

Runner with the preset reloaded and a valid Validate review after the Dataset namespace change.
Figure 12. The preset is reloaded correctly from base, without altering the Session or the Script.

25. What happens when the Python source changes

The Parameter Dataset also keeps the SHA-256 and the revision of the registered Script at the time of saving. If the Script later changes, loading checks the current source and declarations; a preset that is no longer compatible is rejected. It is preferable to create a new preset for the current revision, instead of manually altering the metadata of the previous one. The verified identity protects against executions with parameters belonging to another version of the program.

26. The loaded values remain editable

After Load parameters, the Runner fields remain available. You can make new corrections, respecting the constraints of the schema; this does not modify the Dataset already saved. If you also want to keep the new configuration, you need a different Dataset ID and a new explicit save. Validate review checks the current preparation, while Run Job is a separate command.

27. Parameters in the execution context

In an actual Python execution, the effective values are available through the public API:

from gxtxt import gxtxt_context

context = gxtxt_context()
parameters = context["parameters"]
gain = parameters["gain"]
replicates = parameters["replicates"]

Any provenance of the Parameter Dataset is kept in the execution context and in the traceability of the Job. This example describes how to read the values when a Job is actually run: there is no need to start one to save, load or validate a preset.

28. Closing the Runner without running Python

At the end, check the identity of the Script, the Dataset ID of the preset, the retrieved parameters and the state of Validate review. Press Close to return to the Python editor, preferably with unneeded panels closed and in High Contrast Dark. Saving, loading and checking the Parameter Dataset are preparation operations: they do not need to start a Script or generate a results Dataset. The next guide will show how to configure the output request, validate and knowingly start a Job.

Original Python Script Workspace in the High Contrast Dark theme after closing the Runner, without Job.
Figure 13. After the check you return to the original Python source in High Contrast Dark.