Publishing Independent Curves and Numerical Families

A single image can contain several traces. The GX-TXT Curve Digitalizer lets you acquire them as independent scientific curves, each with its own identity, or as a numerical family, in which each curve is associated with a physical condition.

The two modes do not require the points to be digitized again. What changes is the structure of the published Dataset: independent curves use table.generic, a family uses curve_family.table. In both cases the grouping of points depends on the curve key, not on its visible label.

The example is a synthetic teaching raster, not an instrument experiment. The guide concerns a single accepted calibration and the separate publication layout. Handling several calibrations, the combined layout and advanced naming rules is covered separately.

1. A Source with Five Traces

The original image shows five colored lines on a grid, with a legend that associates each line with a Grid bias condition between −2 and +2 V.

Synthetic graph with five colored curves and a Grid bias legend from −2 to +2 V.
Figure 1. The image contains five non-intersecting curves with Grid bias values stated in the legend.

The file measures 1280 × 900 pixels. The presence of five lines in the figure does not automatically produce five numerical curves: association with the source, calibration and acquisition of the points are required.

2. Defining the Common Scientific Calibration

In the Calibration tab, set the quantities Elapsed time and Detector response, with units s and mV respectively. The limits are X = 0–10 s and Y = −20–80 mV.

Graph with four calibration markers and Calibration ready.
Figure 2. A single transformation converts the source pixels into seconds and millivolts for all traces.
Calibration axis settings with X 0–10 s and Y −20–80 mV.
Figure 3. The X axis ranges from zero to ten seconds, the Y axis from minus twenty to eighty millivolts.

Select the four corners of the original rectangle and accept the measurement. The same transformation is valid for all five curves because they share the same image and the same axes.

3. The Difference Between a Curve and a Dataset

A curve is a series of scientific points with its own identifier. A Dataset is the canonical object published by GX-TXT, which can contain several curves.

In independent mode, five curves can therefore be collected in a single tabular Dataset. The Dataset must keep both the coordinates of the points and a field stating which curve each row belongs to.

4. Creating the First Independent Curve

In the Curves tab, keep This configuration is a numerical curve family disabled. Press New curve and give the first line a name.

New curve dialog creating the first curve.
Figure 4. The identity of the series is defined by the New curve command, not by the color of the ink.

The name is descriptive. The scientific identifier of the curve is assigned internally by the framework and must not be reconstructed from the text of the name.

5. Adding a Second Curve

Repeat New curve for the second trace.

Curves table with two curves.
Figure 5. The new series has a distinct identity and will receive its own numerical points.

Each new curve appears in a separate row and can be selected to acquire, correct or display only its own points.

6. Adding the Other Three Curves

Create the following curves as well, keeping the relationship with the respective traces in the figure.

Curves table with three curves.
Figure 6. The series can have a different number of points without losing the grouping.
Curves table with four curves.
Figure 7. The data are acquired with the same calibration but belong to different curves.
Curves table with five curves.
Figure 8. The tab keeps the identity and point count of each curve.

The five names report the conditions shown in the legend, but in this first mode there is not yet a real numerical family_value parameter: the values in the name are only text.

7. Acquiring the Manual Points

Select one curve at a time, use the Add mode and click on the corresponding stroke in the raster.

Graph with manual points placed on all five traces.
Figure 9. The five series contain eight, nine, ten, eleven and twelve points respectively.
Curves table with point counts 8 to 12.
Figure 10. Each row represents a standalone series; the name is descriptive, while the internal identity is stable.

In the example the five traces have 8, 9, 10, 11 and 12 points respectively, for a total of 50 scientific points. The different number of points does not prevent representing them as standalone curves.

8. Identifying and Ordering the Points

The series has its own curve_key. Each point has a point_order, which in this configuration starts from zero within the series.

Teaching curvePointsInternal indices
Bias −2 V80–7
Bias −1 V90–8
Bias 0 V100–9
Bias +1 V110–10
Bias +2 V120–11

Do not assume that curve_name is a unique key: it is an editable label. Do not assume either that point_order always matches an ordering by X: the behavior depends on the policy chosen in Digitizing.

9. Preparing the Independent Publication

Open the Publish tab. Select the only accepted calibration and set a Publication base Dataset ID distinct from that of the source.

Publish tab with the accepted calibration and the base Dataset ID.
Figure 11. The intended output is a single numerical Dataset in separate layout, with no multiple-calibration key.
Detail of the Publication layout set to separate.
Figure 12. This lesson does not change the naming template and does not combine several calibrations.

For this workflow we use the separate layout and a single calibration realization. We are not comparing several calibrations or creating a Dataset Group.

10. Publishing the Table.generic Dataset

Press Publish selected calibrations. GX-TXT checks the source, the calibration and the structure of the rows, then registers the canonical output.

Publish confirmation for the table.generic Dataset.
Figure 13. The CORE registers fifty rows containing the five series with their identifiers.
Successful publication message for the independent Dataset.
Figure 14. The scientific table was published as a canonical Dataset separate from the raster image.

The result contains 50 numerical rows in the table.generic contract, even though there are five curves.

11. Opening the Result from the Dataset Catalog

In the Session Dataset browser the new numerical Dataset is available. Select it and open it with the native command.

Dataset browser listing the new numerical Dataset.
Figure 15. The new Dataset is available to the CORE tools of the same Session.

The result stays independent of the Curve Digitalizer Interactive Document. To view the rows there is no need to keep open the window in which they were created.

12. The Plot Tab of the CORE Scientific Viewer

The CORE Scientific Dataset Viewer offers a Plot tab and a canonical table.

Plot tab of the CORE Scientific Dataset Viewer.
Figure 16. The generic Plot tab does not replace scientific grouping by curve_key.

The generic plot does not replace the semantics of the curves: a consumer must recognize curve_key and distinguish the series, instead of indiscriminately connecting all the X/Y points of the table.

13. The Long Format of Independent Data

Open Canonical table.

Canonical table of the independent Dataset.
Figure 17. The curve_id, point_index and point_id fields make explicit which trace each row belongs to.

In the implementation examined, the publication includes the technical variables x, y, curve_id, curve_label, point_index, point_id, pixel_x and pixel_y. Each row represents one point.

These technical names are useful for reading the example, but future tools should resolve the columns through the public semantic roles.

14. The Independent Semantic Contract

The publication keeps metadata identifying the independent mode, the table.generic contract, the original image and the calibration.

Schema and provenance of the independent Dataset.
Figure 18. The metadata declare the independent mode, the source and the calibration identity.

The main roles are:

Stable roleMeaning
x, yCalibrated scientific coordinates
curve_keyOpaque identity of the curve
curve_nameVisible label of the curve
point_orderOrder of the point in the curve
raster_x, raster_yPixel coordinates of the original image

The opaque key is the basis of the grouping. The title of the curve can change without necessarily changing its identity.

15. Variable Schema v3 of the Independent Dataset

The CORE Variables section lists eight variables, including the raster coordinates.

Variables tab of the independent Dataset with eight variables.
Figure 19. There is no family_value in the independent table; the raster and order columns remain.

Selecting the curve identifier field you can check its text type.

Detail of the curve identifier variable.
Figure 20. The opaque curve_key identifier must be used to group the points.

This publication has no numerical family_value column. A label containing “−2 V” is not enough to turn the structure into a family.

16. Enabling Numerical Curve Family

Go back to the Digitalizer Curves tab and enable This configuration is a numerical curve family.

Curves tab with the numerical curve family checkbox enabled.
Figure 21. The change of mode defines the structure of the future output, without reacquiring the fifty points.
Curve family frame with Grid bias, V and family.
Figure 22. The family defines a quantity, the unit V and the semantic role family.

The example uses Grid bias as the quantity name, V as the unit and family as the scientific role. Enabling it changes the type of output intended, but neither deletes nor recreates the fifty points already accepted.

17. A Family Requires Real Numerical Parameters

Trying to publish right away, when the curves have no numerical value, the Viewer shows an error.

Error message for a missing family parameter value.
Figure 23. GX-TXT blocks publication if a series lacks its numerical value: it does not derive it from the label.

The parameter cannot be inferred from the title “Bias −2 V”. The title is free text: the value must be recorded in the dedicated field, with its unit.

18. Opening Edit Curve to Assign the Parameter

Select the first curve and press Edit.

Edit curve dialog for the first curve.
Figure 24. The parameter is recorded on the existing curve, without creating a new curve.

In the dialog, enter the value of the parameter for the curve.

Edit curve dialog with family value −2 and unit V.
Figure 25. Family values are numerical conditions of the series, distinct from the X/Y samples.
Curves table with the first family value assigned.
Figure 26. The parameter is repeated for every point of the series in the family Dataset.

The first condition is −2 V. The parameter belongs to the series and will be repeated in the rows of that series when the family is published.

19. Assigning the Other Values

Repeat the procedure for the remaining traces: −1 V, 0 V, +1 V, +2 V.

Curves table with family values −2 V and −1 V.
Figure 27. The first two curves have minus two and minus one volt as their condition respectively.

The values are not new measurements of the Y variable: they describe an external condition associated with each curve.

20. Checking the Units of the Curves

In the example, a deliberately wrong test assigns the last curve the value 2 with the unit mA, while the family is defined in V.

Edit curve dialog with the unit mA on the fifth curve.
Figure 28. An inconsistent unit must be corrected before producing a scientific family Dataset.

The GUI blocks the publication.

Error message for an incompatible family unit.
Figure 29. Publication is blocked because one curve uses mA while Grid bias is defined in V.

The check prevents conditions expressed in incompatible declared units from being combined in a common numerical column.

21. Correcting the Unit of the Fifth Curve

Open Edit curve again and correct its unit to V.

Edit curve dialog correcting the unit to V.
Figure 30. The correction concerns the unit of the parameter, not the twelve points of the fifth curve.

There is no need to move or digitize again the twelve points of the fifth series: the change concerns only the description of the parameter.

22. Checking the Ready Family

The Curves table now shows all five numerical conditions correctly expressed in volts.

Curves table with five family values in volts.
Figure 31. All five series keep their previous point counts and the same UUIDs.
Detail of the curve table with family values and point counts.
Figure 32. The family parameter does not replace the opaque identifier of the curve.

The counts stay 8, 9, 10, 11 and 12. The grouping is still associated with the identities of the five curves.

23. Preparing a Second Output ID

Open Publish, keep the same accepted calibration and choose a new base ID intended for the family Dataset.

Publish tab with a new base Dataset ID for the family.
Figure 33. The output plan uses an ID distinct from the previous independent Dataset.

Using a different ID avoids confusing the independent result with the new numerical_family result.

24. Publishing Curve_family.table

Press Publish selected calibrations.

Publish confirmation for the curve_family.table Dataset.
Figure 34. The family Dataset still contains fifty points, now with the family_value column.
Successful publication message for the family Dataset.
Figure 35. Registration takes place in the GX-TXT canonical archive, not in a temporary CSV.

The result now has the curve_family.table contract, with 50 rows and a numerical column for the Grid bias condition. The X/Y scientific samples are those already digitized.

25. Viewing the Family from the Browser

The Dataset browser shows both outputs, identified separately.

Dataset browser listing both published Datasets.
Figure 36. The family result has a Dataset identity different from the independent output.

Opening the family Dataset brings up the CORE Scientific Dataset Viewer.

CORE Scientific Dataset Viewer opened on the family Dataset.
Figure 37. The Plot tab is a view of the Dataset, while the scientific contract is defined in the Schema.

The correct scientific interpretation does not depend on the window name or on the generic plot, but on the curve_family.table contract and on the semantic roles.

26. The Canonical Table of the Family

The canonical table now shows the family_value column.

Canonical table of the family Dataset with the family_value column.
Figure 38. The parameter values are associated with each row without creating new original points.

For every point of a given curve the parameter value is repeated: for example, the Bias −2 V curve keeps family_value = -2 in all eight of its rows.

27. A New Column, Not New Points

Comparing the two Datasets row by row shows that the common fields are identical: scientific X/Y, raster coordinates, label, curve identifier, point identifier and order.

PropertyIndependent curvesNumerical family
Contracttable.genericcurve_family.table
Modeindependentnumerical_family
Rows5050
Curves55
Canonical variables89
Numerical parameterAbsentfamily_value
Grouping keycurve_keycurve_key

The new column changes the meaning of the rows; it is not a second experimental acquisition.

28. The Structured Provenance of the Dataset

Open Schema and provenance to read the contract of the family result.

Schema and provenance of the family Dataset.
Figure 39. The curve_family.table contract keeps the original source and the accepted calibration.

The metadata identify the source image, its SHA-256 fingerprint, the calibration transformation and the roles of the variables. The provenance must be read together with the data, not reconstructed from the colors of the plot.

29. Nine Variables in the Family

The Variables tab shows nine variables, compared with the eight of the independent publication.

Variables tab of the family Dataset with nine variables.
Figure 40. The family_value variable is of type float64, unit V and role family.
Detail of the family_value variable description.
Figure 41. Consumers must read the public roles and not guess the meaning from the column title.

The additional variable is of type float64, has unit V and role family. The X and Y coordinates keep the units s and mV respectively, with no change of axis.

30. Checking the Source Ancestry

The Source ancestry tab lets you check the link between the result and its original data.

Source ancestry tab of the family Dataset.
Figure 42. Provenance makes it possible to verify that the two outputs derive from the same raster image.
Detail of the source ancestry chain.
Figure 43. The identification chain includes the source Dataset and the accepted transformation.

In the example both publications keep the same fingerprint of the original image and the same SHA-256 of the calibration. No two different images were generated and the calibration was not repeated.

31. The Family_parameter Role in the Variable Schema

Selecting the family_value variable in the CORE shows its description.

Variable description showing the family_parameter role.
Figure 44. The Grid bias parameter is numerical and not a text label used to group rows.

Its stable semantic role is family_parameter. The numerical parameter describes the condition of the series, not the X time and not the measured Y response.

32. Why Curve_key Cannot Be Replaced by the Parameter

The family Dataset still contains a text variable identifying the curve.

Curve key variable in the family Dataset.
Figure 45. In the family too, the primary grouping remains curve_key, not family_value.
Detail of curve_key next to curve_label and family_value.
Figure 46. The opaque identity stays distinct from the visible name and from the numerical Grid bias value.

curve_key serves to separate the series. family_parameter describes a numerical condition and is not a primary key: in other experiments two curves might share the same parameter value and still be two different curves.

33. The Point Order Is Internal to the Curve

The point_order field is a zero-based integer.

Point order variable described as a zero-based integer.
Figure 47. The order must be rebuilt within each curve_key, not through a global sort by X.

In the example the sequences are 0–7, 0–8, 0–9, 0–10 and 0–11, each within its own curve. Sorting the records globally by X or by the parameter is not equivalent to rebuilding the sequence defined by the operator.

34. The Raster Coordinates Remain Available

Both published Datasets keep the coordinates of the original pixels, in addition to the calibrated X/Y.

These references are essential for scientific checking: they make it possible to compare a numerical point with the original trace without having to approximately reconstruct the geometry from the displayed plot.

The source used is a synthetic image; the agreement of the clicks with its mathematical formulas does not measure the accuracy of an instrument.

35. Temporarily Going Back to Independent

The This configuration is a numerical curve family control can be disabled in the current configuration.

Curves tab with the numerical family checkbox disabled.
Figure 48. The document returns to independent mode without deleting the Datasets already published.

The five traces and their points stay available. Datasets already published are not deleted or reinterpreted by a change of mode in the still-editable document.

36. Re-enabling the Family

Re-enabling the checkbox, the five numerical conditions are found again.

In the example the sequence of points, the identifiers and the coordinates stayed unchanged, both in the document and in the outputs already consolidated.

37. Saving, Closing and Reopening

Use Configuration → Save configuration, close the Viewer normally and reopen it from the same Session.

Reopened Curves tab with the five family values.
Figure 49. The original identity of the curves and the five numerical parameters stayed saved.
Reopened Viewer with the five curves and their points.
Figure 50. The reopened series keep the original calibration and the number of points.

The five curves, the values −2, −1, 0, +1 and +2 V and the fifty original points come back.

38. Persistence of the Outputs and the Source

The Publish tab shows the family publication plan, still associated with the accepted calibration.

Reopened Publish tab with the family publication plan.
Figure 51. The canonical publications remain readable even when the Viewer is closed.

The Source tab confirms that the source Dataset is still the original one.

Source tab showing the original source Dataset.
Figure 52. The source Dataset was not replaced, cropped or modified by the publication.

The public APIs keep reading the two Datasets already published, with unchanged identity and SHA-256. This persistence is distinct from the save operation of the current configuration.

39. Reading the Columns Through the Public APIs

Programs that consume the result should not infer scientific roles from technical names such as curve_id, curve_label or family_value, because they might evolve. The versioned Curve Digitalizer API resolves the associations from the metadata and from Variable Schema v3.

A Tcl example in the GX-TXT environment, with the appropriate Session open:

# Activate the public Curve Digitalizer Dataset Schema API.
::GX::modulePublicApiActivate viewer.curve_digitizer CURVE_DIGITIZER_DATASET_SCHEMA_API_v1

set dataset_id "example.family.curves"
set manifest [::GX::CurveDigitizerDataset::read $dataset_id]

# Resolve semantic roles rather than assuming CSV header positions.
set curve_key_variable [dict get $manifest columns curve_key]
set point_order_variable [dict get $manifest columns point_order]
set x_variable [dict get $manifest columns x]
set y_variable [dict get $manifest columns y]

# A numerical family also declares a repeated numeric parameter.
if {[dict get $manifest mode] eq "numerical_family"} {
    set parameter_variable [dict get $manifest columns family_parameter]
}

# Read the original raster positions through the bounded public API.
set batch [::GX::CurveDigitizerDataset::rasterPoints $dataset_id "" 0 100]

# Group rows by curve_key, then order within each group by point_order.

The rasterPoints function returns the source coordinates in a bounded read. The roles returned by the API are linked to the canonical variables actually published.

40. Independent Curves and Families Are Not Synonyms

The independent mode is appropriate when the curves must be considered distinct series, with no declared common numerical parameter.

The numerical_family mode is appropriate when the variation of a quantity, such as Grid bias in volts, has an explicit scientific meaning for each series.

Do not convert to a family just because the curve names contain numbers: consistent units and a real parameter are required. Conversely, do not consider two Datasets as new independent measurements if they come from the very same acquisition of points.

41. Recommended Operating Procedure

  1. Import the original raster and accept the scientific calibration.
  2. Create a curve for each trace, assigning clear names and acquiring the points in the correct series.
  3. Check the counts and the grouping by curve, without using the name as an identifier.
  4. For independent curves, keep the family disabled and publish the table.generic Dataset.
  5. For a family, enable This configuration is a numerical curve family and enter the quantity, the unit and the numerical value of each curve.
  6. Correct missing values or incompatible units before publishing.
  7. Publish the curve_family.table Dataset with a distinct identity.
  8. Open the two results in the CORE and compare the canonical rows and the Variable Schema.
  9. Use CURVE_DIGITIZER_DATASET_SCHEMA_API_v1 to resolve the columns, curve_key for grouping and point_order for the sequence.
  10. Save, close and reopen; check the source, the number of points, the family parameter and the persistence of the Datasets.

Conclusion: converting from independent curves to a numerical family changes the semantics of the published table, not the pixels or the original coordinates. Correctly distinguishing curve identity, point order and family parameter lets later analysis tools use the data without confusing traces or experimental conditions.