Scientific calibration with the GX-TXT public APIs

With Octave Script Workspace a GNU Octave script can use scientific data already registered in the Session and publish a new Dataset without directly accessing the storage files. In this example we will read five synthetic voltages, apply a double gain chosen in the Runner and keep the corrected values through the GX-TXT public APIs.

The procedures refer to GX-TXT DEV112-P005, module Octave Script Workspace 1.8.3. The GUI labels are given in English and the code contains English comments. The editor uses the actual High Contrast Dark theme; the other controls keep the native Tk/ttk look.

1. The Scientific Problem and the Five Starting Data

Suppose we have five voltage readings, in volts, acquired at successive times. The chosen gain is dimensionless and equal to 1.6. The relation used is:

V_corrected = gain × V_input

The input Dataset must have been previously published in the Session with the table.generic contract and with the stable variable IDs time_s and voltage_V. To prepare it you can follow the guide «Publishing numerical results and text output», adapting values and identifiers.

Time (s)Initial voltage (V)
00.120
10.185
20.250
30.315
40.380

These data are entirely synthetic and do not come from an instrument.

The five rows of the canonical input Dataset, with time columns and voltages in volts.
Figure 1 — The five rows of the canonical input Dataset, with time columns and voltages in volts.

2. Creating a Session Script and Declaring the Required APIs

Open Octave Script Workspace, choose File → New Script and keep Scope: session. Assign an identifier, for example w02_gain_corrected_voltage, a name and a description; then save with File → Save.

In the Required APIs field enter exactly the two public APIs, separated by a semicolon:

CANONICAL_DATASET_API_v2;DATASET_PUBLICATION_API_v2

The first provides canonical access to the data, the second handles numerical publication. Declaring them lets the Runner check their availability before the computation.

Registering the Octave source with the two required public APIs.
Figure 2 — Registering the Octave source with the two required public APIs.

3. Complete GNU Octave Script

The program uses the GX-TXT public Bridge, without opening local files or using private framework commands. Copy the code into the editor; the comments are in English.

% Five-point voltage calibration using only public GX-TXT Script Bridge APIs.
% The input Dataset is selected by the user in Script Runner; no file paths.
gxtxt_parameter_declare('gain', 'double', 'default', 1.0, ...
                        'min', 0.5, 'max', 2.5, ...
                        'description', 'Dimensionless voltage calibration gain');
ctx = gxtxt_context();
gxtxt_api_require('CANONICAL_DATASET_API_v2');
gxtxt_api_require('DATASET_PUBLICATION_API_v2');
if (!isfield(ctx.inputs, 'measured'))
  error('Select the canonical Dataset using Runner input alias measured');
endif
source_id = ctx.inputs.measured.dataset_id;
if (!strcmp(source_id, 'w02_raw_voltage'))
  error('The reviewed input Dataset is not the expected synthetic measurement');
endif
if (!gxtxt_api_has_operation('CANONICAL_DATASET_API_v2', 'read_range') || ...
    !gxtxt_api_has_operation('DATASET_PUBLICATION_API_v2', 'publish_series'))
  error('The installed public Script Bridge lacks the required operations');
endif
source_metadata = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'describe', {source_id});
blocks = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'read_range', ...
                        {source_id, {'time_s', 'voltage_V'}, 0, 5});
time_s = double(blocks.time_s.values(:));
voltage_V = double(blocks.voltage_V.values(:));
if (numel(time_s) != 5 || numel(voltage_V) != 5 || ...
    any(!isfinite(time_s)) || any(!isfinite(voltage_V)))
  error('Input must contain exactly five finite time/voltage samples');
endif
assert(all(abs(time_s - [0; 1; 2; 3; 4]) < 1e-10));
assert(all(abs(voltage_V - [0.12; 0.185; 0.25; 0.315; 0.38]) < 1e-10));
gain = ctx.parameters.gain;
corrected_V = gain .* voltage_V;
assert(all(isfinite(corrected_V)));
request = struct('dataset_id', 'w02_gain_corrected_voltage', ...
                 'contract', 'table.generic', 'storage', 'csv', ...
                 'x_values', time_s, 'y_values', corrected_V, ...
                 'x_variable', struct('variable_id', 'time_s', ...
                                      'name', 'Elapsed time', 'unit', 's', ...
                                      'semantic_role', 'time'), ...
                 'y_variable', struct('variable_id', 'corrected_V', ...
                                      'name', 'Corrected voltage', 'unit', 'V', ...
                                      'semantic_role', 'voltage'), ...
                 'notes', 'Five synthetic input voltages scaled by a reviewed gain');
request.source_dataset_ids = {source_id};
request.source_variable_ids = {'time_s', 'voltage_V'};
request.source = source_id;
request.provenance = 'Gain-adjusted synthetic voltage from verified canonical input';
published = gxtxt_api_call('DATASET_PUBLICATION_API_v2', 'publish_series', {request});
fprintf('W02_INPUT_DATASET=%s\n', source_id);
fprintf('W02_GAIN=%.2f\n', gain);
fprintf('W02_POINT_COUNT=%d\n', numel(time_s));
for k = 1:numel(time_s)
  fprintf('W02_ROW=%d t=%.1f raw=%.3f corrected=%.3f\n', ...
          k, time_s(k), voltage_V(k), corrected_V(k));
endfor
disp('W02_PUBLICATION_COMPLETE');
disp(published);

In the first part the script checks the selected Dataset, the availability of the APIs and the numerical content. In the second part it computes the result, publishes it and prints a five-line summary. The identifiers used in the code must match those actually registered in the Session.

4. The Declared Parameter and the Execution Context

gxtxt_parameter_declare declares a parameter called gain, of type double, with default value 1.0, minimum 0.5 and maximum 2.5. The declaration is recognized when the source is registered; it does not start a Job.

gxtxt_context() returns the context of the specific execution. From ctx.parameters.gain you get the value validated by the user; from ctx.inputs.measured.dataset_id you get the identifier of the Dataset bound to the semantic alias measured.

The script must not build the physical path of the Dataset: the Runner provides a logical reference, checked in the current Session.

5. Discovering the Public Operations and Reading the Data

gxtxt_api_require requires the two APIs before proceeding. With gxtxt_api_has_operation you check that precisely the read_range and publish_series operations are available. A missing operation produces a recognizable error, not an empty result to be interpreted arbitrarily.

The general function gxtxt_api_call(api_id, operation, args) sends a call to a registered public service. The arguments of each operation are passed in an Octave cell array; the target API determines the accepted types and the structure of the result.

The describe command returns the metadata of the selected Dataset. To read the five values you use:

blocks = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'read_range', ...
                        {source_id, {'time_s', 'voltage_V'}, 0, 5});
time_s = double(blocks.time_s.values(:));
voltage_V = double(blocks.voltage_V.values(:));

The range starts from row 0 (zero-based index) and requests 5 samples. The answer is a structure indexed by the stable variable IDs; the individual blocks contain typed values and read metadata. The .values(:) operation turns the numerical data into the column vectors used by Octave.

The code uses read_range to retrieve the two numeric variables of the selected Dataset.
Figure 3 — The code uses read_range to retrieve the two numeric variables of the selected Dataset.

The assert statements check the five values of this exercise: for real experimental measurements, the criteria must be adapted to the actual Dataset.

6. Opening Script Runner and Choosing the Gain

After saving the source, use Run → Open Script Runner…. The Runner shows the script, the required APIs and the typed parameter gain (double) with initial value 1.0.

Script Runner shows the gain parameter detected from the source.
Figure 4 — Script Runner shows the gain parameter detected from the source.

Set gain = 1.6. This change concerns the single scientific invocation and does not alter the source revision in the Registry.

7. Binding the measured Input and Identifying the Output

Open Inputs and output and choose Add input Dataset. Configure the three controls:

  • Semantic alias: measured
  • Namespace: module/analysis.octave_script
  • Dataset ID: w02_raw_voltage

The Namespace is not a decorative detail. The Dataset used in the example belongs to the space of the producer module, so it might not appear if you choose base.

In the Output request (optional) section enter Dataset ID: w02_gain_corrected_voltage, add a descriptive label and leave Replace owned output unchecked. Filling in the field alone does not publish any result.

The measured input bound to the Dataset and the numeric output declared before the computation.
Figure 5 — The measured input bound to the Dataset and the numeric output declared before the computation.

8. Validating the Request Without Running It

Press Validate review. With alias, input revision, APIs and parameter consistent, the Runner answers:

Review valid. No Job submitted; Run Job performs fresh admission checks.
Validation completes successfully and does not create a Job yet.
Figure 6 — Validation completes successfully and does not create a Job yet.

The revision of the input Dataset is recorded in the request. The check serves to prevent an unexpected replacement of the input from going unnoticed between the choice of data and the execution.

9. Starting GNU Octave and Examining the Job State

Press Run Job only once. GX-TXT runs the registered revision of the script, providing it with the measured alias and gain = 1.6.

In Run → Script Jobs Manager… the Job becomes COMPLETED after the computation. In case of FAILED, consult the Job details before attempting a new execution.

Script Jobs Manager shows the scientific Job finished with status COMPLETED.
Figure 7 — Script Jobs Manager shows the scientific Job finished with status COMPLETED.

A Job keeps the executed revision, its own state and the output streams: it must not be confused with a published Dataset.

10. Reading the Results from Program Output

Choose Jobs → Open execution details, then Program output. The main lines actually produced by the script are:

W02_INPUT_DATASET=w02_raw_voltage
W02_GAIN=1.60
W02_POINT_COUNT=5
W02_ROW=1 t=0.0 raw=0.120 corrected=0.192
W02_ROW=2 t=1.0 raw=0.185 corrected=0.296
W02_ROW=3 t=2.0 raw=0.250 corrected=0.400
W02_ROW=4 t=3.0 raw=0.315 corrected=0.504
W02_ROW=5 t=4.0 raw=0.380 corrected=0.608
W02_PUBLICATION_COMPLETE
Program output contains the gain value and the five computed results.
Figure 8 — Program output contains the gain value and the five computed results.

This text is an account of the execution. Numerical publication requires a separate call to the APIs: writing numbers to stdout is not enough to create a canonical Dataset.

11. Publishing a New Numerical Series

The script prepares a request structure containing dataset_id, contract: table.generic, storage: csv, the x_values and y_values vectors and the variable descriptors.

The actual publication operation is:

published = gxtxt_api_call('DATASET_PUBLICATION_API_v2', ...
                           'publish_series', {request});

Two output variables are declared: time_s with unit s and corrected_V with unit V. The request also records source_dataset_ids and source_variable_ids, so that the new Dataset keeps an explicit relationship with the original values.

The code builds the scientific request and calls publish_series through the public Bridge.
Figure 9 — The code builds the scientific request and calls publish_series through the public Bridge.

The new Dataset is distinct from the input. The initial values are not modified, and no files or internal Registry entries are written by hand.

12. Comparing the Canonical Output Table with the Input

The published Dataset w02_gain_corrected_voltage uses table.generic and the CSV format. The Canonical table view tab shows five rows with time and corrected voltage.

Canonical table of the result with five corrected_V values.
Figure 10 — Canonical table of the result with five corrected_V values.
Time (s)Input (V)GainOutput (V)
00.1201.60.192
10.1851.60.296
20.2501.60.400
30.3151.60.504
40.3801.60.608

When displaying float64 numbers, representations such as 0.29599999999999999 may appear instead of 0.296. These are differences in binary representation, not new measurements: comparisons are made with an appropriate tolerance.

13. Checking Schema and Scientific Provenance

The Schema and provenance tab describes the published variables, including type, unit of measurement and semantic role. For this example time_s is a coordinate in seconds and corrected_V represents voltage data in volts.

Schema of the two float64 variables, with units and roles recorded in the canonical Dataset.
Figure 11 — Schema of the two float64 variables, with units and roles recorded in the canonical Dataset.

The provenance records w02_raw_voltage as source Dataset, time_s and voltage_V as starting variables and analysis.octave_script as producer of the new result. This information documents the link between two Datasets without falsely attributing an instrumental origin to the synthetic data.

14. Common Problems and Summary

If the Dataset does not appear in Add input Dataset, check the Namespace, the active Session and the identifier. If the script reports a missing input, check that the Semantic alias is exactly measured. If Validate review rejects the gain, check the double type and the declaration limits.

In case of an error during execution consult Program stderr and Diagnostic log. If the identifier of the output Dataset already exists, do not assume that the new invocation is allowed to overwrite it: a new result must be published with an available identity or with an explicitly authorized replacement procedure.

The complete workflow links canonical Dataset → Runner input → typed parameter → read_range → Octave computation → publish_series → new canonical Dataset. Using the public APIs separates the scientific computation from the physical details of storage and lets you check identity, revisions and provenance of the results.