From 0bcc15def1ae62ea9768f668674073aa79d18456 Mon Sep 17 00:00:00 2001 From: Bob Weigel Date: Mon, 3 Feb 2025 13:00:06 -0500 Subject: [PATCH 1/3] vectorComponents clarification --- hapi-dev/HAPI-data-access-spec-dev.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index 37e37c7..e7ba4d7 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -800,7 +800,7 @@ The focus of the header is to list the parameters in a dataset. The first parame | `label` | string OR array of string | **Optional** A word or very short phrase that could serve as a label for this parameter (as on a plot axis or in a selection list of parameters). It is intended to be less cryptic than the parameter name. If the parameter is a scalar, this label must be a single string. If the parameter is an array, a single string label or an array of string labels are allowed. `null` and the empty string `""` are not allowed. A single label string will be applied to all elements in the array, whereas an array of label strings specifies a different label string for each element in the array parameter. The shape of the array of label strings must match the `size` attribute, and the ordering of multi-dimensional arrays of label strings is as discussed in the `size` attribute definition above. See also the following example responses to an `info` query for examples of a single string and string array labels and additional details in [Units and Label Arrays](#3610-units-and-label-array).| | `stringType` | string or object | **Optional** A string parameter can have a specialized type. Currently, the only supported specialized type is a URI. See [The `stringType` Object](#366-stringtype-object) for more details on syntax and allowed values for `stringType`. | | `coordinateSystemName`| string | **Optional** Some data represent directional or position information, such as look direction, spacecraft location, or a measured vector quantity. This keyword specifies the name of the coordinate system for these vector quantities. If a [`coordinateSystemSchema`](#364-coordinatesystemschema-details) was given for this dataset, then the `coordinateSystemName` must come from the schema. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for more about coordinate systems. | -| `vectorComponents` | string or array of strings| **Optional** The name or list of names of the vector components present in a directional or positional quantity. For a scalar `parameter`, only a single string indicating the component type is allowed. For an array `parameter`, an array of corresponding component names is expected. If not provided, the default value for `vectorComponents` is `["x", "y", "z"]`, which assumes the `parameter` is an array of length 3. There is an enumeration of allowed names for common vector components. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for additional details. | +| `vectorComponents` | string or array of strings| **Optional** The name or list of names of the vector-related elements. For a scalar `parameter`, only a single string indicating its component type is allowed. For an array `parameter`, an array of corresponding component names is expected. If not provided, the default value for `vectorComponents` is `["x", "y", "z"]`, which assumes the `parameter` array has 3 elements. There is an enumeration of allowed names for common vector components. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for additional details. | | `bins` | array of Bins object | **Optional** For array parameters, each object in the `bins` array corresponds to one of the dimensions of the array and describes values associated with each element in the corresponding dimension of the array. The [bins object table](3611-bins-object) below describes all required and optional attributes within each `bins` object. For example, if the parameter represents a 1-D frequency spectrum, the `bins` array will have one object describing the frequency values for each frequency bin; within that object, the `centers` attribute points to an array of values to use for the central frequency of each channel, and the `ranges` attribute specifies a range associated with each channel. | **Example** @@ -986,9 +986,9 @@ The `[1,2,3]` are measurements from the first instrument and the `[4, 5, 6]` are "label": [["V1x","V1y","V1z"],["V2x","V2y","V2z"]] ``` -### 3.6.11 vectorComponents Object +### 3.6.11 `vectorComponents` Object -For a `parameter` that describes a vector quantity (position of spacecraft relative to a body, location of ground station, direction of measured vector quantity, detector look direction), the `vectorComponents` keyword indicates the vector components present in the data. For a scalar `parameter` that is associated with a vector component, this keyword contains a single string describing the component. For non-scalar parameters, this keyword contains an array of strings naming the coordinate values present in the parameter. +For a `parameter` that describes a vector-related quantity (position of spacecraft relative to a body, location of ground station, direction of measured vector quantity, detector look direction), the `vectorComponents` keyword indicates the vector-related components present in the data. For a scalar `parameter` that is associated with a vector component, this keyword contains a single string describing the component. For non-scalar parameters, this keyword contains an array of strings naming the coordinate values present in the parameter. The names represent the mathematical components typically found in vector or positional quantities. @@ -1003,10 +1003,12 @@ Possible component names are constrained to be one of the following: | `rho` | Magnitude of radial component (perpendicular distance from z-axis) in a Cylindrical coordinate representation | | `latitude` | Angle relative to x-y plane from -90° to 90°, or -π to π (90° corresponds to +z axis) | | `colatitude` | Angle relative to +z axis, from 0 to 180°, or 0 to π | -| `longitude` | Angle relative to +x axis of a projection of the vector into the x-y plane, from -180° to 180°, or -π to π (90° corresponds to +y axis; this is also known as "East longitude") | -| `longitude0` | Angle relative to +x axis of a projection of the vector into the x-y plane, from 0° to 360°, or 0 to 2π (270° corresponds to -y axis; this is also known as "East longitude") | -| `altitude` | Altitude above a reference sphere or surface as identified in `coordinateSystemName`. For example, Earth's locations are often described by longitude, latitude, and altitude.| -| `other` | Any parameter component that cannot be described by a name in this list | +| `longitude` | Angle relative to +x axis of a projection of the vector into the x-y plane, from -180° to 180°, or -π to π (90° corresponds to +y axis; this is also known as "East longitude") | +| `longitude0` | Angle relative to +x axis of a projection of the vector into the x-y plane, from 0° to 360°, or 0 to 2π (270° corresponds to -y axis; this is also known as "East longitude") | +| `altitude` | Altitude above a reference sphere or surface as identified in `coordinateSystemName`. For example, Earth's locations are often described by longitude, latitude, and altitude.| +| `other` | Any parameter component that cannot be described by a name in this list | + +Note that `vectorComponents` should be interpreted as describing vector-related elements. In some instances, the `vectorComponents` will describe a proper vector (e.g., if `vectorComponents = ["x", "y", "z"]`). Many angular quantities in datasets have different names than the ones here (azimuth instead of longitude, or elevation or inclination instead of latitude), From bac4afcb26f6329d3f2bc48b72b30d9daf8c91e6 Mon Sep 17 00:00:00 2001 From: Bob Weigel Date: Mon, 10 Feb 2025 12:22:18 -0500 Subject: [PATCH 2/3] Remove assumptions --- hapi-dev/HAPI-data-access-spec-dev.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index e7ba4d7..b7f3018 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -799,8 +799,8 @@ The focus of the header is to list the parameters in a dataset. The first parame | `description` | string | **Optional** A brief, one-sentence description of the parameter. | | `label` | string OR array of string | **Optional** A word or very short phrase that could serve as a label for this parameter (as on a plot axis or in a selection list of parameters). It is intended to be less cryptic than the parameter name. If the parameter is a scalar, this label must be a single string. If the parameter is an array, a single string label or an array of string labels are allowed. `null` and the empty string `""` are not allowed. A single label string will be applied to all elements in the array, whereas an array of label strings specifies a different label string for each element in the array parameter. The shape of the array of label strings must match the `size` attribute, and the ordering of multi-dimensional arrays of label strings is as discussed in the `size` attribute definition above. See also the following example responses to an `info` query for examples of a single string and string array labels and additional details in [Units and Label Arrays](#3610-units-and-label-array).| | `stringType` | string or object | **Optional** A string parameter can have a specialized type. Currently, the only supported specialized type is a URI. See [The `stringType` Object](#366-stringtype-object) for more details on syntax and allowed values for `stringType`. | -| `coordinateSystemName`| string | **Optional** Some data represent directional or position information, such as look direction, spacecraft location, or a measured vector quantity. This keyword specifies the name of the coordinate system for these vector quantities. If a [`coordinateSystemSchema`](#364-coordinatesystemschema-details) was given for this dataset, then the `coordinateSystemName` must come from the schema. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for more about coordinate systems. | -| `vectorComponents` | string or array of strings| **Optional** The name or list of names of the vector-related elements. For a scalar `parameter`, only a single string indicating its component type is allowed. For an array `parameter`, an array of corresponding component names is expected. If not provided, the default value for `vectorComponents` is `["x", "y", "z"]`, which assumes the `parameter` array has 3 elements. There is an enumeration of allowed names for common vector components. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for additional details. | +| `coordinateSystemName`| string | **Optional** Some data represent directional or position information, such as look direction, spacecraft location, or a measured vector quantity. This keyword specifies the name of the coordinate system for these vector quantities. If `coordinateSystemName` is given, `vectorComponents` should be given (but this is not required). If a [`coordinateSystemSchema`](#364-coordinatesystemschema-details) was given for this dataset, then the `coordinateSystemName` must come from the schema. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for more about coordinate systems. | +| `vectorComponents` | string or array of strings| **Optional** The name or list of names of the vector-related elements. For a scalar `parameter`, only a single string indicating its component type is allowed. For an array `parameter`, an array of corresponding component names is expected. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for additional details. | | `bins` | array of Bins object | **Optional** For array parameters, each object in the `bins` array corresponds to one of the dimensions of the array and describes values associated with each element in the corresponding dimension of the array. The [bins object table](3611-bins-object) below describes all required and optional attributes within each `bins` object. For example, if the parameter represents a 1-D frequency spectrum, the `bins` array will have one object describing the frequency values for each frequency bin; within that object, the `centers` attribute points to an array of values to use for the central frequency of each channel, and the `ranges` attribute specifies a range associated with each channel. | **Example** From 757b1e4d884f4675c239c6072a91b993f96eb0a2 Mon Sep 17 00:00:00 2001 From: jvandegriff Date: Mon, 10 Feb 2025 12:58:50 -0500 Subject: [PATCH 3/3] improved wording to deconflict vector concepts --- hapi-dev/HAPI-data-access-spec-dev.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index b7f3018..665ac7f 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -799,8 +799,8 @@ The focus of the header is to list the parameters in a dataset. The first parame | `description` | string | **Optional** A brief, one-sentence description of the parameter. | | `label` | string OR array of string | **Optional** A word or very short phrase that could serve as a label for this parameter (as on a plot axis or in a selection list of parameters). It is intended to be less cryptic than the parameter name. If the parameter is a scalar, this label must be a single string. If the parameter is an array, a single string label or an array of string labels are allowed. `null` and the empty string `""` are not allowed. A single label string will be applied to all elements in the array, whereas an array of label strings specifies a different label string for each element in the array parameter. The shape of the array of label strings must match the `size` attribute, and the ordering of multi-dimensional arrays of label strings is as discussed in the `size` attribute definition above. See also the following example responses to an `info` query for examples of a single string and string array labels and additional details in [Units and Label Arrays](#3610-units-and-label-array).| | `stringType` | string or object | **Optional** A string parameter can have a specialized type. Currently, the only supported specialized type is a URI. See [The `stringType` Object](#366-stringtype-object) for more details on syntax and allowed values for `stringType`. | -| `coordinateSystemName`| string | **Optional** Some data represent directional or position information, such as look direction, spacecraft location, or a measured vector quantity. This keyword specifies the name of the coordinate system for these vector quantities. If `coordinateSystemName` is given, `vectorComponents` should be given (but this is not required). If a [`coordinateSystemSchema`](#364-coordinatesystemschema-details) was given for this dataset, then the `coordinateSystemName` must come from the schema. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for more about coordinate systems. | -| `vectorComponents` | string or array of strings| **Optional** The name or list of names of the vector-related elements. For a scalar `parameter`, only a single string indicating its component type is allowed. For an array `parameter`, an array of corresponding component names is expected. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for additional details. | +| `coordinateSystemName`| string | **Optional** Some parameters contain directional or position information, such as look direction, spacecraft location, or a measured vector quantity. This keyword specifies the name of the coordinate system for these quantities. If `coordinateSystemName` is given, `vectorComponents` should be given (but this is not required). If a [`coordinateSystemSchema`](#364-coordinatesystemschema-details) was given for this dataset, then the `coordinateSystemName` must come from the schema. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for more about coordinate systems. | +| `vectorComponents` | string or array of strings| **Optional** The name or list of names of the vector-related elements. For a scalar `parameter`, only a single string indicating its component type is allowed. For an array `parameter`, an array of corresponding component names is expected. If a parameter has a `coordinateSystemName` and three elements, and they represent Cartesian (x,y,z) values, then as a convenience, you may omit the `vectorComponents`. For any other situation (not three elements, not Cartesian, not ordered as x,y,z), then you must specify the `vectorComponents` explicitly. [See the `vectorComponents` Object](#3611-vectorcomponents-object) for additional details. | | `bins` | array of Bins object | **Optional** For array parameters, each object in the `bins` array corresponds to one of the dimensions of the array and describes values associated with each element in the corresponding dimension of the array. The [bins object table](3611-bins-object) below describes all required and optional attributes within each `bins` object. For example, if the parameter represents a 1-D frequency spectrum, the `bins` array will have one object describing the frequency values for each frequency bin; within that object, the `centers` attribute points to an array of values to use for the central frequency of each channel, and the `ranges` attribute specifies a range associated with each channel. | **Example**