Where should parameter definitions be placed in the GGXF structure?

[ccrook]

The GGXF specification currently proposes an attribute "uncertaintyMeasure" which is used to describe the statistical characteristics of this parameter, eg 1SE, 2CEP. Because some types include both horizontal and vertical parameters with different uncertainty measures it has been proposed that this would have to be structured, something like

uncertaintyMeasure:
   horizontal: 2CEP
   vertical: 2SE

This adds some complexity to software which needs to have table relating parameters to uncertainty measures. For example a deformation model may have parameters displacementEastUncertainty, displacementNorthUncertainty, and displacementUpUncertainty. The software needs to identify which uncertaintyMeasure applies to which parameter. This is intuitive to a human reader but must be defined programmatically for software, and defined for each type of GGXF file.

In the 31 Jan 2022 GGXF meeting it was proposed that instead the uncertainty measure is included in the parameter definition in the GGXF group. This would be a conditional attribute of a parameter that would apply if the parameter defines uncertainty. For example:

    parameters:
      - parameterName: latitudeOffset
        angleUnit: arc-second
        unitSiRatio: 4.84813681109536E-06
      - parameterName: longitudeOffset
        angleUnit: arc-second
        unitSiRatio: 4.84813681109536E-06
      - parameterName: latitudeOffsetUncertainty
        lengthUnit: metre
        unitSiRatio: 1.0
        uncertaintyMeasure: 2CEP
      - parameterName: longitudeOffsetUncertainty
        lengthUnit: metre
        unitSiRatio: 1.0
        uncertaintyMeasure: 2CEP

This removes any ambiguity in associating the uncertaintyMeasure(s) with the corresponding parameters.

Note 1: Perhaps GGXF specification should also add a requirement that within a single GGXF file the uncertainty measure for a specific parameter is the same for every group. In fact possibly this should apply to all parameter attributes - ie if the unit of displacementEast is metre in one group, then it must be metre in all groups which have that parameter.

Note 2: It has been proposed that the GGXF group/file header also include an optional defaultUncertainty attribute that would be used to record the uncertainty of a parameter if it is not explicitly defined in the grid data. In order to be consistent with this approach I suggest this would be formatted as:

    uncertaintyDefault:
      - parameterName: latitudeOffsetUncertainty
        lengthUnit: metre
        unitSiRatio: 1.0
        uncertaintyMeasure: 2CEP
        value: 0.05
      - parameterName: longitudeOffsetUncertainty
        lengthUnit: metre
        unitSiRatio: 1.0
        uncertaintyMeasure: 2CEP
        value: 0.05

Note 3

As an even larger change, the list of parameters in a GGXF file could be included in the file header as:

    parameters:
      - parameterName: latitudeOffset
        angleUnit: arc-second
        unitSiRatio: 4.84813681109536E-06
      - parameterName: longitudeOffset
        angleUnit: arc-second
        unitSiRatio: 4.84813681109536E-06
      - parameterName: latitudeOffsetUncertainty
        lengthUnit: metre
        unitSiRatio: 1.0
        uncertaintyMeasure: 2CEP
        defaultValue: 0.05
      - parameterName: longitudeOffsetUncertainty
        lengthUnit: metre
        unitSiRatio: 1.0
        uncertaintyMeasure: 2CEP
        defaultValue: 0.05

Then in the group header the parameters element simply be a list of parameter names, ie:

yaml

   groupName: some_group
   groupParameters: latitudeOffset, longitudeOffset, latitudeOffsetUncertainty, longitudeOffsetUncertainty

This would avoid duplication and remove the possibility of using inconsistent definitions in a single GGXF file.

[ccrook]

https://github.com/opengeospatial/CRS-Gridded-Geodetic-data-eXchange-Format/wiki/DataStructure

[ccrook]

Because this impacts on the same GGXF attributes as issue #28 I am closing this discussion here so that it can be combined in one place.

[ccrook]

@RogerLott This is the issue I was referring to at the end of the last meeting. In retrospect I erred in closing it - better to keep questions separate even if they relate to similar attributes in GGXF.

This is also illustrated in the wiki (Layout option 3)

[ccrook]

Agreed in meeting 6 June 2022 that parameter definitions should go in file header. So file header contains parameters, and each group contains group parameters listing which parameters it is actually using. groupParameters is optional - default is all parameters are defined in each grid of the group in the order defined in the file header parameters array.

[RogerLott]

An extension of moving parameters to the file header is to also move other global attributes currently (v0.91 draft) in the ggxfGroup header, specifically the no data flag, uncertainty measure, interpolation method and permanant tide. The consequence of this is that for most use cases the ggxfGroup header will contain nothing other than the group name, which makes it redundant. The logical extension of this is in general to do away with ggxfGroup headers, retaining them only for files with multiple groups where the group header is used to modify global attributes (e.g. by subsetting the parameters in each ggxfGroup). Removing the requirement for a group header simplifies the structure for most use cases - file header followed by one or more grids (nested or hierarchical, but all containing the same parameters). The v0.92 draft assumes this.

[RogerLott]

Uncertainty measure added as a parameter attribute (optional) in v0.92 draft.

[ccrook]

Parameter definitions have been implemented in the GGXF header. The handling of default values will be created as a separate issue.