From c5bb0e766da4f9f63820819a4ab6c3d1bb06b092 Mon Sep 17 00:00:00 2001 From: jvandegriff Date: Mon, 27 Jan 2025 11:59:54 -0500 Subject: [PATCH 01/11] initial draft of location attribute --- hapi-dev/HAPI-data-access-spec-dev.md | 77 +++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index 31e5eb6..bf020ef 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -543,6 +543,7 @@ The response is in JSON format [[3](#6-references)] and provides metadata about | `description` | string | **Optional** A detailed description of the dataset content, caveats, relationships to other data, references and links -- the information users need to know for a basic interpretation of the data. Suggested length is a few lines of text, e.g., 1000 characters; extended details can be referenced with links. | | `unitsSchema` | string | **Optional** The name of the units convention that describes how to parse all `units` strings in this dataset. Currently, the only allowed values are: `udunits2`, `astropy3`, and `cdf-cluster`. See [`unitsSchema` Details](#363-unitsschema-details) for additional information about these conventions. The list of allowed unit specifications is expected to grow to include other well-documented unit standards. | | `coordinateSystemSchema` | string | **Optional** The name of the schema or convention that contains a list of coordinate system names and definitions. If this keyword is provided, any `coordinateSystemName` keyword given in a [parameter](#366-parameter-object) definition should follow this schema. See [`coordinateSystemSchema` Details](#364-coordinatesystemschema-details) for additional information. | +| `location` | object | **Optional** A way to specify a location for a dataset. See [`location` Details](#3617-location-and-geoLocation-details) for an explanation of the two kinds of objects can be used, one for a single,fixed location and another for location that varies with time. | `resourceURL` | string | **Optional** URL linking to more detailed information about this dataset. | | `resourceID` | string | **Optional** An identifier by which this data is known in another setting (e.g., DOI) | `creationDate` | string | **Optional** [Restricted ISO 8601](#376-representation-of-time) date/time of the dataset creation. | @@ -1351,6 +1352,82 @@ The approach shown here emphasizes a useful way for HAPI to provide image lists. can only constrain a set of images by time, but if the response contains metadata values in other columns, then clients can restrict the image list further by filtering on values in the metadata columns. +### 3.6.17 `location` and `geoLocation` Details + +Some datasets have measurements associated with a fixed position. Other measurements have postions that change with time. +The `location` and `geoLocation` attributes allow the position of meaurements to be described. + +To indicate a dataset with a single location for all measurements, the `location` object must have four attributes that represent a single vector position value. +``` +"location": { + "point": [value_A, value_B, value_C], + "components": ["vector_component_label_for_A", "vec_comp_for_B", "vec_comp_for_C"], + # these are constsrained to be a valid vectorComponents + # example: "components": ["long", "lat", "altitude"] + "units": ["label_A", "label_B", "label_C"], + # should follow the units schema, if one was provided + # Exmaple: "units": ["deg", "deg", "meters"] + "coordinateSystemName": "name_of_coord_sys" + # Example: "coordinateSystemName": "wgs84" +} +``` +Complete examples: +``` +"location": { + "point": [117.5, 37.1, 0.41], + "components": ["longitude", "latitude", "altitude"], + "units": ["deg", "deg", "km"], + "coordinateSystemName": "wgs84" +} + +"location": { + "point": [-4.1452, 1.2050, 0.10201], + "components": ["x", "y", "z"], + "units": ["Re", "Re", "Re" ], + "coordinateSystemName": "GSE" +} +``` +If the coordinate frame is WGS84, the shorthand `geoLocation` attribute may be used. The values for `geoLocation` must +match those used by the Geo-JASON specification, i.e., one of: +``` + [longitude, latitude, altitude] + -or just- + [longitude, latitude] +``` +Angles in `geoLocation` must be in `deg` and altitude in `km`. + +If the measurement location changes over time, a different object can be gicen for the `location` to +indicate the name of the parameter or parameters that containt the location vector components. Some +datasets may have the location values in more than one coordiante frame, and each coordainte frame +a can be listed. + +``` +"location": { + "parameters": [ ["param_name_for_location_using_coord_sys_A"], ["param_name_for_location_using_coord_sys_B"] ] + # each parameters must be a vector and have in it's attrributes a full set of vectorComponents to describe the vector +} +``` +Example: +``` +"location": { + "parameters": [ ["Location_GEO"], ["Location_GSE"] ] + } +``` +In this example, `Location-GEO` is the name of another parameter in the dataset, and it must contain a set of `vectorComponents` for defining the position. + + +If the vector elements for the position are spread across multiple parameters, each constituent parameter must be listed. +The list of Clients will have a harder time reconstructing This is best shown with an example: +``` +location: { + "parameters": [ ["Location_GEO_X", "Location_GEO_Y", "Location_GEO_Z], + ["Location_J2000_X", "Location_J2000_Y", "Location_J2000_Z"] + ] +} +``` + + + ## 3.7 `data` Provides access to a dataset and allows for selecting time ranges and parameters to return. Data is returned as a CSV [[2](#6-references)], binary, or JSON- stream. The [Data Stream Content](#374-response-formats) section describes the stream structure and layout for each format. From 15f405cf619e0d36af63c369374c3627b12b41c8 Mon Sep 17 00:00:00 2001 From: jvandegriff Date: Mon, 27 Jan 2025 14:18:17 -0500 Subject: [PATCH 02/11] added geoLocation attribute to dataset table --- hapi-dev/HAPI-data-access-spec-dev.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index bf020ef..13e1d91 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -31,6 +31,7 @@       [3.6.14 Time-Varying Bins](#3614-time-varying-bins)
      [3.6.15 Time-Varying size](#3615-time-varying-size)
      [3.6.16 The stringType Object](#3616-the-stringtype-object)
+      [3.6.17 location and geoLocation Details](#3617-location-and-geoLocation-details)
   [3.7 data](#37-data)
      [3.7.1 Request Parameters](#371-request-parameters)
      [3.7.2 Response](#372-response)
@@ -543,7 +544,8 @@ The response is in JSON format [[3](#6-references)] and provides metadata about | `description` | string | **Optional** A detailed description of the dataset content, caveats, relationships to other data, references and links -- the information users need to know for a basic interpretation of the data. Suggested length is a few lines of text, e.g., 1000 characters; extended details can be referenced with links. | | `unitsSchema` | string | **Optional** The name of the units convention that describes how to parse all `units` strings in this dataset. Currently, the only allowed values are: `udunits2`, `astropy3`, and `cdf-cluster`. See [`unitsSchema` Details](#363-unitsschema-details) for additional information about these conventions. The list of allowed unit specifications is expected to grow to include other well-documented unit standards. | | `coordinateSystemSchema` | string | **Optional** The name of the schema or convention that contains a list of coordinate system names and definitions. If this keyword is provided, any `coordinateSystemName` keyword given in a [parameter](#366-parameter-object) definition should follow this schema. See [`coordinateSystemSchema` Details](#364-coordinatesystemschema-details) for additional information. | -| `location` | object | **Optional** A way to specify a location for a dataset. See [`location` Details](#3617-location-and-geoLocation-details) for an explanation of the two kinds of objects can be used, one for a single,fixed location and another for location that varies with time. +| `location` | object | **Optional** A way to specify where a dataset's measurement were made. See [`location` Details](#3617-location-and-geoLocation-details) for an explanation of the two ways to indicate location: one for a fixed location and one for measurements whose location changes with time. +| `geoLocation` | array of double | **Optional** An alternate, shorthand way of indication fixed location for a dataset in Earth-based coordaintes. The values in the array and their units and coordinate frame are meant to match what is used in GeoJSON (geojson.org). See [`location` Details](#3617-location-and-geoLocation-details). | `resourceURL` | string | **Optional** URL linking to more detailed information about this dataset. | | `resourceID` | string | **Optional** An identifier by which this data is known in another setting (e.g., DOI) | `creationDate` | string | **Optional** [Restricted ISO 8601](#376-representation-of-time) date/time of the dataset creation. | From d41f34fc2df195df5de23cadefbe5056ed64132a Mon Sep 17 00:00:00 2001 From: jvandegriff Date: Mon, 27 Jan 2025 14:59:47 -0500 Subject: [PATCH 03/11] cleaned up writeup and examples --- hapi-dev/HAPI-data-access-spec-dev.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index 13e1d91..bc7fb84 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -1357,7 +1357,8 @@ then clients can restrict the image list further by filtering on values in the m ### 3.6.17 `location` and `geoLocation` Details Some datasets have measurements associated with a fixed position. Other measurements have postions that change with time. -The `location` and `geoLocation` attributes allow the position of meaurements to be described. +The `location` attribute allows the position of meaurements to be described. An alternative attribute 'geoLocation" can +be used instead as a compact way of describing an Earth-based fise dposition for a dataset's measurements. To indicate a dataset with a single location for all measurements, the `location` object must have four attributes that represent a single vector position value. ``` @@ -1365,7 +1366,7 @@ To indicate a dataset with a single location for all measurements, the `location "point": [value_A, value_B, value_C], "components": ["vector_component_label_for_A", "vec_comp_for_B", "vec_comp_for_C"], # these are constsrained to be a valid vectorComponents - # example: "components": ["long", "lat", "altitude"] + # example: "components": ["longitude", "latitide", "altitude"] "units": ["label_A", "label_B", "label_C"], # should follow the units schema, if one was provided # Exmaple: "units": ["deg", "deg", "meters"] @@ -1373,7 +1374,10 @@ To indicate a dataset with a single location for all measurements, the `location # Example: "coordinateSystemName": "wgs84" } ``` -Complete examples: +Valid `components` are constrained and must come from the lists of allowed `vectorComponents` +[described here](#3610-specifying-vectorcomponents) + +Some complete examples: ``` "location": { "point": [117.5, 37.1, 0.41], @@ -1383,18 +1387,20 @@ Complete examples: } "location": { - "point": [-4.1452, 1.2050, 0.10201], + "point": [-4.1452e3, 1.2050e3, 0.10201e3], "components": ["x", "y", "z"], - "units": ["Re", "Re", "Re" ], + "units": "km", "coordinateSystemName": "GSE" } ``` +Note that in the second example, the units value of `km` is broadcast to all the elements of the + If the coordinate frame is WGS84, the shorthand `geoLocation` attribute may be used. The values for `geoLocation` must match those used by the Geo-JASON specification, i.e., one of: ``` - [longitude, latitude, altitude] +"location": [longitude, latitude, altitude] -or just- - [longitude, latitude] +"location": [longitude, latitude] ``` Angles in `geoLocation` must be in `deg` and altitude in `km`. From aa574b72843407f483b3551a791ec0787bcd6a52 Mon Sep 17 00:00:00 2001 From: jvandegriff Date: Mon, 27 Jan 2025 15:12:47 -0500 Subject: [PATCH 04/11] improve wording in attribute table --- 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 bc7fb84..9857337 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -544,8 +544,8 @@ The response is in JSON format [[3](#6-references)] and provides metadata about | `description` | string | **Optional** A detailed description of the dataset content, caveats, relationships to other data, references and links -- the information users need to know for a basic interpretation of the data. Suggested length is a few lines of text, e.g., 1000 characters; extended details can be referenced with links. | | `unitsSchema` | string | **Optional** The name of the units convention that describes how to parse all `units` strings in this dataset. Currently, the only allowed values are: `udunits2`, `astropy3`, and `cdf-cluster`. See [`unitsSchema` Details](#363-unitsschema-details) for additional information about these conventions. The list of allowed unit specifications is expected to grow to include other well-documented unit standards. | | `coordinateSystemSchema` | string | **Optional** The name of the schema or convention that contains a list of coordinate system names and definitions. If this keyword is provided, any `coordinateSystemName` keyword given in a [parameter](#366-parameter-object) definition should follow this schema. See [`coordinateSystemSchema` Details](#364-coordinatesystemschema-details) for additional information. | -| `location` | object | **Optional** A way to specify where a dataset's measurement were made. See [`location` Details](#3617-location-and-geoLocation-details) for an explanation of the two ways to indicate location: one for a fixed location and one for measurements whose location changes with time. -| `geoLocation` | array of double | **Optional** An alternate, shorthand way of indication fixed location for a dataset in Earth-based coordaintes. The values in the array and their units and coordinate frame are meant to match what is used in GeoJSON (geojson.org). See [`location` Details](#3617-location-and-geoLocation-details). +| `location` | object | **Optional** A way to specify where a dataset's measurement were made. See [`location` and geoLocation Details](#3617-location-and-geoLocation-details) for an explanation of the two ways to indicate location: one for a fixed location and one for when the measurement location changes with time. +| `geoLocation` | array of double | **Optional** An alternate, shorthand way of indicating a fixed location for a dataset in Earth-based coordinates. The coordinate values used are meant to match what is used in GeoJSON (geojson.org). See [location and geoLocation Details](#3617-location-and-geoLocation-details). | `resourceURL` | string | **Optional** URL linking to more detailed information about this dataset. | | `resourceID` | string | **Optional** An identifier by which this data is known in another setting (e.g., DOI) | `creationDate` | string | **Optional** [Restricted ISO 8601](#376-representation-of-time) date/time of the dataset creation. | From 15a586033a608ab2638fc83090817e83ef1ed6f4 Mon Sep 17 00:00:00 2001 From: jvandegriff Date: Mon, 27 Jan 2025 15:29:57 -0500 Subject: [PATCH 05/11] more tweaks --- hapi-dev/HAPI-data-access-spec-dev.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index 9857337..9c417e3 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -544,8 +544,8 @@ The response is in JSON format [[3](#6-references)] and provides metadata about | `description` | string | **Optional** A detailed description of the dataset content, caveats, relationships to other data, references and links -- the information users need to know for a basic interpretation of the data. Suggested length is a few lines of text, e.g., 1000 characters; extended details can be referenced with links. | | `unitsSchema` | string | **Optional** The name of the units convention that describes how to parse all `units` strings in this dataset. Currently, the only allowed values are: `udunits2`, `astropy3`, and `cdf-cluster`. See [`unitsSchema` Details](#363-unitsschema-details) for additional information about these conventions. The list of allowed unit specifications is expected to grow to include other well-documented unit standards. | | `coordinateSystemSchema` | string | **Optional** The name of the schema or convention that contains a list of coordinate system names and definitions. If this keyword is provided, any `coordinateSystemName` keyword given in a [parameter](#366-parameter-object) definition should follow this schema. See [`coordinateSystemSchema` Details](#364-coordinatesystemschema-details) for additional information. | -| `location` | object | **Optional** A way to specify where a dataset's measurement were made. See [`location` and geoLocation Details](#3617-location-and-geoLocation-details) for an explanation of the two ways to indicate location: one for a fixed location and one for when the measurement location changes with time. -| `geoLocation` | array of double | **Optional** An alternate, shorthand way of indicating a fixed location for a dataset in Earth-based coordinates. The coordinate values used are meant to match what is used in GeoJSON (geojson.org). See [location and geoLocation Details](#3617-location-and-geoLocation-details). +| `location` | object | **Optional** A way to specify where a dataset's measurements were made. See [location and geoLocation Details](#3617-location-and-geoLocation-details) for an explanation of the two ways to indicate location: one for a fixed location and one for when the measurement location changes with time. +| `geoLocation` | array of double | **Optional** An alternate, shorthand way of indicating a fixed location for a dataset in Earth-based coordinates. The coordinates, their order and coordinate frame are meant to match what is used in GeoJSON [geojson.org](https://geojson.org). See [location and geoLocation Details](#3617-location-and-geoLocation-details). | `resourceURL` | string | **Optional** URL linking to more detailed information about this dataset. | | `resourceID` | string | **Optional** An identifier by which this data is known in another setting (e.g., DOI) | `creationDate` | string | **Optional** [Restricted ISO 8601](#376-representation-of-time) date/time of the dataset creation. | @@ -1360,7 +1360,7 @@ Some datasets have measurements associated with a fixed position. Other measurem The `location` attribute allows the position of meaurements to be described. An alternative attribute 'geoLocation" can be used instead as a compact way of describing an Earth-based fise dposition for a dataset's measurements. -To indicate a dataset with a single location for all measurements, the `location` object must have four attributes that represent a single vector position value. +To indicate that there is a single location for all measurements in a dataset, use a `location` object with these four attributes: ``` "location": { "point": [value_A, value_B, value_C], @@ -1374,8 +1374,10 @@ To indicate a dataset with a single location for all measurements, the `location # Example: "coordinateSystemName": "wgs84" } ``` -Valid `components` are constrained and must come from the lists of allowed `vectorComponents` -[described here](#3610-specifying-vectorcomponents) +Valid `components` are constrained and must come from the lists of allowed `vectorComponents` [described here](#3610-specifying-vectorcomponents). + +Strings for the `units` must come from any `unitsSchema` that has been specified for this dataset. +Similary, the `coordinateSystemName` must come from any schema specified by the `coordinateSystemSchema` for this dataset. Some complete examples: ``` @@ -1393,20 +1395,21 @@ Some complete examples: "coordinateSystemName": "GSE" } ``` -Note that in the second example, the units value of `km` is broadcast to all the elements of the +Note that in the second example, the units value of `km` is broadcast to all the elements of the components. -If the coordinate frame is WGS84, the shorthand `geoLocation` attribute may be used. The values for `geoLocation` must -match those used by the Geo-JASON specification, i.e., one of: +If the coordinate frame is WGS84 (see [Geodetic Coordinate Systems](https://en.wikipedia.org/wiki/World_Geodetic_System), +the shorthand `geoLocation` attribute may be used. The values for `geoLocation` must +match those used by the [GeoJASON](https://geojson.org) specification, i.e., one of: ``` -"location": [longitude, latitude, altitude] - -or just- "location": [longitude, latitude] + -OR- +"location": [longitude, latitude, altitude] ``` Angles in `geoLocation` must be in `deg` and altitude in `km`. If the measurement location changes over time, a different object can be gicen for the `location` to indicate the name of the parameter or parameters that containt the location vector components. Some -datasets may have the location values in more than one coordiante frame, and each coordainte frame +datasets may have the location values in more than one coordiante frame, and each coordinate frame a can be listed. ``` From dd2ba15847e7b924641b51d0a525c9883842c5ed Mon Sep 17 00:00:00 2001 From: jvandegriff Date: Mon, 27 Jan 2025 16:57:19 -0500 Subject: [PATCH 06/11] wording tweak --- hapi-dev/HAPI-data-access-spec-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index 9c417e3..c7c122b 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -545,7 +545,7 @@ The response is in JSON format [[3](#6-references)] and provides metadata about | `unitsSchema` | string | **Optional** The name of the units convention that describes how to parse all `units` strings in this dataset. Currently, the only allowed values are: `udunits2`, `astropy3`, and `cdf-cluster`. See [`unitsSchema` Details](#363-unitsschema-details) for additional information about these conventions. The list of allowed unit specifications is expected to grow to include other well-documented unit standards. | | `coordinateSystemSchema` | string | **Optional** The name of the schema or convention that contains a list of coordinate system names and definitions. If this keyword is provided, any `coordinateSystemName` keyword given in a [parameter](#366-parameter-object) definition should follow this schema. See [`coordinateSystemSchema` Details](#364-coordinatesystemschema-details) for additional information. | | `location` | object | **Optional** A way to specify where a dataset's measurements were made. See [location and geoLocation Details](#3617-location-and-geoLocation-details) for an explanation of the two ways to indicate location: one for a fixed location and one for when the measurement location changes with time. -| `geoLocation` | array of double | **Optional** An alternate, shorthand way of indicating a fixed location for a dataset in Earth-based coordinates. The coordinates, their order and coordinate frame are meant to match what is used in GeoJSON [geojson.org](https://geojson.org). See [location and geoLocation Details](#3617-location-and-geoLocation-details). +| `geoLocation` | array of double | **Optional** An alternate, shorthand way of indicating a fixed location for a dataset in Earth-based coordinates. The coordinates, their order and coordinate frame are meant to match what is used in [GeoJSON](https://geojson.org). For information and examples, see [location and geoLocation Details](#3617-location-and-geoLocation-details). | `resourceURL` | string | **Optional** URL linking to more detailed information about this dataset. | | `resourceID` | string | **Optional** An identifier by which this data is known in another setting (e.g., DOI) | `creationDate` | string | **Optional** [Restricted ISO 8601](#376-representation-of-time) date/time of the dataset creation. | From 4541afe3d38c4966a9ef4d98301c8e6a840c51eb Mon Sep 17 00:00:00 2001 From: jvandegriff Date: Mon, 27 Jan 2025 16:59:18 -0500 Subject: [PATCH 07/11] small wording change --- hapi-dev/HAPI-data-access-spec-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index c7c122b..9ac63b9 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -545,7 +545,7 @@ The response is in JSON format [[3](#6-references)] and provides metadata about | `unitsSchema` | string | **Optional** The name of the units convention that describes how to parse all `units` strings in this dataset. Currently, the only allowed values are: `udunits2`, `astropy3`, and `cdf-cluster`. See [`unitsSchema` Details](#363-unitsschema-details) for additional information about these conventions. The list of allowed unit specifications is expected to grow to include other well-documented unit standards. | | `coordinateSystemSchema` | string | **Optional** The name of the schema or convention that contains a list of coordinate system names and definitions. If this keyword is provided, any `coordinateSystemName` keyword given in a [parameter](#366-parameter-object) definition should follow this schema. See [`coordinateSystemSchema` Details](#364-coordinatesystemschema-details) for additional information. | | `location` | object | **Optional** A way to specify where a dataset's measurements were made. See [location and geoLocation Details](#3617-location-and-geoLocation-details) for an explanation of the two ways to indicate location: one for a fixed location and one for when the measurement location changes with time. -| `geoLocation` | array of double | **Optional** An alternate, shorthand way of indicating a fixed location for a dataset in Earth-based coordinates. The coordinates, their order and coordinate frame are meant to match what is used in [GeoJSON](https://geojson.org). For information and examples, see [location and geoLocation Details](#3617-location-and-geoLocation-details). +| `geoLocation` | array of double | **Optional** A simplified, compact way of indicating a fixed location for a dataset in Earth-based coordinates. The coordinates, their order and coordinate frame are meant to match what is used in [GeoJSON](https://geojson.org). For information and examples, see [location and geoLocation Details](#3617-location-and-geoLocation-details). | `resourceURL` | string | **Optional** URL linking to more detailed information about this dataset. | | `resourceID` | string | **Optional** An identifier by which this data is known in another setting (e.g., DOI) | `creationDate` | string | **Optional** [Restricted ISO 8601](#376-representation-of-time) date/time of the dataset creation. | From c25cc75d79975139f8c68e59629fe8abf478836c Mon Sep 17 00:00:00 2001 From: jvandegriff Date: Mon, 27 Jan 2025 17:29:40 -0500 Subject: [PATCH 08/11] wording improvements --- hapi-dev/HAPI-data-access-spec-dev.md | 42 +++++++++++++++------------ 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index 9ac63b9..e4491b7 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -1357,8 +1357,9 @@ then clients can restrict the image list further by filtering on values in the m ### 3.6.17 `location` and `geoLocation` Details Some datasets have measurements associated with a fixed position. Other measurements have postions that change with time. -The `location` attribute allows the position of meaurements to be described. An alternative attribute 'geoLocation" can -be used instead as a compact way of describing an Earth-based fise dposition for a dataset's measurements. +The `location` attribute allows the position of meaurements to be described either as a single, fixed location +for all measurements, or using location values that change with time. An alternative attribute `geoLocation` can +be used instead as a compact way of describing an Earth-based position for a dataset's measurements. To indicate that there is a single location for all measurements in a dataset, use a `location` object with these four attributes: ``` @@ -1382,9 +1383,9 @@ Similary, the `coordinateSystemName` must come from any schema specified by the Some complete examples: ``` "location": { - "point": [117.5, 37.1, 0.41], + "point": [117.5, 37.1, 410.0], "components": ["longitude", "latitude", "altitude"], - "units": ["deg", "deg", "km"], + "units": ["deg", "deg", "m"], "coordinateSystemName": "wgs84" } @@ -1397,47 +1398,50 @@ Some complete examples: ``` Note that in the second example, the units value of `km` is broadcast to all the elements of the components. -If the coordinate frame is WGS84 (see [Geodetic Coordinate Systems](https://en.wikipedia.org/wiki/World_Geodetic_System), -the shorthand `geoLocation` attribute may be used. The values for `geoLocation` must +If the coordinate frame is WGS84 (see [Geodetic Coordinate Systems](https://en.wikipedia.org/wiki/World_Geodetic_System)), +the `geoLocation` attribute may be used to compactly represent a location on Earth. The values for `geoLocation` must match those used by the [GeoJASON](https://geojson.org) specification, i.e., one of: ``` "location": [longitude, latitude] -OR- "location": [longitude, latitude, altitude] ``` -Angles in `geoLocation` must be in `deg` and altitude in `km`. +Angles in `geoLocation` must be in `deg` and altitude in `m`. -If the measurement location changes over time, a different object can be gicen for the `location` to -indicate the name of the parameter or parameters that containt the location vector components. Some -datasets may have the location values in more than one coordiante frame, and each coordinate frame -a can be listed. +Thus the first example above could be compactly represetned as: +``` +"geoLocation": [117.5, 37.1, 410.0] +``` +If the measurement location changes over time, the `location` object can indicate the names of the +parameters in the dataset that contain time-varying positions. If the time-varying position is +present in more than one coordinate system, each can be referenced. Therefore, the `location` +attribute is an array (outer array) consisting of an inner array of string parameter names. +If a parameter has all the `vectorComponents` in it to full represent this position, then the +inner array will have just one element: the name of the fully sufficient parameter. +If the postion info for one coordinate system is spread over multiple parameters, then +each parameter name needs to be in the inner array. ``` "location": { "parameters": [ ["param_name_for_location_using_coord_sys_A"], ["param_name_for_location_using_coord_sys_B"] ] # each parameters must be a vector and have in it's attrributes a full set of vectorComponents to describe the vector } ``` -Example: +Examples help illustrate: ``` "location": { "parameters": [ ["Location_GEO"], ["Location_GSE"] ] } -``` -In this example, `Location-GEO` is the name of another parameter in the dataset, and it must contain a set of `vectorComponents` for defining the position. - -If the vector elements for the position are spread across multiple parameters, each constituent parameter must be listed. -The list of Clients will have a harder time reconstructing This is best shown with an example: -``` location: { "parameters": [ ["Location_GEO_X", "Location_GEO_Y", "Location_GEO_Z], ["Location_J2000_X", "Location_J2000_Y", "Location_J2000_Z"] ] } ``` +In the first example, there are two parameters that provide position info, each in a different coordiante system. Within each parameter definition, there must be a `vectorComponent` description. - +In the second example, there are also two coordinate systems, but each one is expressed in three parameters, one each for the x, y and z values of the position. ## 3.7 `data` From 868b3865610211b18eea8f59d35b3626da352019 Mon Sep 17 00:00:00 2001 From: Bob Weigel Date: Mon, 27 Jan 2025 20:08:06 -0500 Subject: [PATCH 09/11] some typos and add bold for time varying --- hapi-dev/HAPI-data-access-spec-dev.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index e4491b7..6536244 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -1400,7 +1400,7 @@ Note that in the second example, the units value of `km` is broadcast to all the If the coordinate frame is WGS84 (see [Geodetic Coordinate Systems](https://en.wikipedia.org/wiki/World_Geodetic_System)), the `geoLocation` attribute may be used to compactly represent a location on Earth. The values for `geoLocation` must -match those used by the [GeoJASON](https://geojson.org) specification, i.e., one of: +match those used by the [GeoJSON](https://geojson.org) specification, i.e., one of: ``` "location": [longitude, latitude] -OR- @@ -1408,13 +1408,15 @@ match those used by the [GeoJASON](https://geojson.org) specification, i.e., one ``` Angles in `geoLocation` must be in `deg` and altitude in `m`. -Thus the first example above could be compactly represetned as: +Thus the first example above could be compactly represented as: ``` "geoLocation": [117.5, 37.1, 410.0] ``` +**Time-Varying Locations** + If the measurement location changes over time, the `location` object can indicate the names of the -parameters in the dataset that contain time-varying positions. If the time-varying position is +parameters in the dataset that contain time-varying locations. If the time-varying position is present in more than one coordinate system, each can be referenced. Therefore, the `location` attribute is an array (outer array) consisting of an inner array of string parameter names. If a parameter has all the `vectorComponents` in it to full represent this position, then the @@ -1439,9 +1441,9 @@ location: { ] } ``` -In the first example, there are two parameters that provide position info, each in a different coordiante system. Within each parameter definition, there must be a `vectorComponent` description. +In the first example, two parameters provide position info, each in a different coordinate system. Within each parameter definition, there must be a `vectorComponent` description. -In the second example, there are also two coordinate systems, but each one is expressed in three parameters, one each for the x, y and z values of the position. +In the second example, there are also two coordinate systems, but each one is expressed in three parameters, one each for the x, y, and z values of the position. ## 3.7 `data` From 74adaadedbe3b1b29feb30eac074f9dd7fc85cfb Mon Sep 17 00:00:00 2001 From: jvandegriff Date: Mon, 27 Jan 2025 22:11:22 -0500 Subject: [PATCH 10/11] some re-arranging and spelling fixes --- hapi-dev/HAPI-data-access-spec-dev.md | 79 ++++++++++++++++----------- 1 file changed, 46 insertions(+), 33 deletions(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index 6536244..b28a4b7 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -1356,29 +1356,54 @@ then clients can restrict the image list further by filtering on values in the m ### 3.6.17 `location` and `geoLocation` Details -Some datasets have measurements associated with a fixed position. Other measurements have postions that change with time. -The `location` attribute allows the position of meaurements to be described either as a single, fixed location -for all measurements, or using location values that change with time. An alternative attribute `geoLocation` can +Some datasets have parameters whose measurements are associated with a fixed location. Other measurements +are made from locations that change with time. +The `location` attribute can express the location of measurements either as a single, fixed location, +or as location values that change with time. An alternative attribute `geoLocation` can be used instead as a compact way of describing an Earth-based position for a dataset's measurements. -To indicate that there is a single location for all measurements in a dataset, use a `location` object with these four attributes: +For the case of a fixed location on Earth, the `geoLocation` attribute concisely +represents a point location with an array of longitude, latitude, and optionally altitude. +``` + "geoLocation": [longitude, latitude] + -OR- + "geoLocation": [longitude, latitude, altitude] +``` +Angles in `geoLocation` must be in `deg` and altitude in `m` and the coordinate frame is WGS84 (see [Geodetic Coordinate Systems](https://en.wikipedia.org/wiki/World_Geodetic_System)). +This makes `geoLocation` consistent with the [GeoJSON](https://geojson.org) specification for a point location. + +As an example, the location of measurements made by a hypothetical magnetometer at the peak of Sugarloaf Mountain in Maryland, USA, could be represented as: +``` +"geoLocation": [-77.395, 39.269, 391.0] +``` + +For a fixed location expressed in a different coordinate system, or with other vector components for the location, +use a `location` object with these four attributes: + +| location Attribute | Type | Description | +|------------------------|---------|-----------------------------------------------------------------| +| `point` | double array | **Required** values to specify the location | +| `components` | string array | **Required** the kind of [`vectorComponent`](#3610-specifying-vectorcomponents) values in the `point` array | +| `units` | string or string array | **Required** units string or strings for the `vectorComponent` values | +| `coordinateSystemName` | string | **Required** the name of the coordinate system for the `vectorComponent` quantities | + + ``` "location": { "point": [value_A, value_B, value_C], - "components": ["vector_component_label_for_A", "vec_comp_for_B", "vec_comp_for_C"], + "components": ["vector_component_A", "vector_component_B", "vector_component_C"], # these are constsrained to be a valid vectorComponents # example: "components": ["longitude", "latitide", "altitude"] "units": ["label_A", "label_B", "label_C"], # should follow the units schema, if one was provided - # Exmaple: "units": ["deg", "deg", "meters"] + # Example: "units": ["deg", "deg", "meters"] "coordinateSystemName": "name_of_coord_sys" # Example: "coordinateSystemName": "wgs84" } ``` -Valid `components` are constrained and must come from the lists of allowed `vectorComponents` [described here](#3610-specifying-vectorcomponents). -Strings for the `units` must come from any `unitsSchema` that has been specified for this dataset. -Similary, the `coordinateSystemName` must come from any schema specified by the `coordinateSystemSchema` for this dataset. +If a `unitsSchema` has been specified for this dataset, any string given for the `units` must be consistent with that schema. +Similarly, the `coordinateSystemName` must come from a schema, if one is specified by the `coordinateSystemSchema` for this dataset. Some complete examples: ``` @@ -1398,35 +1423,20 @@ Some complete examples: ``` Note that in the second example, the units value of `km` is broadcast to all the elements of the components. -If the coordinate frame is WGS84 (see [Geodetic Coordinate Systems](https://en.wikipedia.org/wiki/World_Geodetic_System)), -the `geoLocation` attribute may be used to compactly represent a location on Earth. The values for `geoLocation` must -match those used by the [GeoJSON](https://geojson.org) specification, i.e., one of: -``` -"location": [longitude, latitude] - -OR- -"location": [longitude, latitude, altitude] -``` -Angles in `geoLocation` must be in `deg` and altitude in `m`. - -Thus the first example above could be compactly represented as: -``` -"geoLocation": [117.5, 37.1, 410.0] -``` - **Time-Varying Locations** -If the measurement location changes over time, the `location` object can indicate the names of the -parameters in the dataset that contain time-varying locations. If the time-varying position is +If a dataset has parameters where the measurement location changes over time, the `location` object can indicate +the names of other parameters in the dataset that contain the corresponding time-varying locations. If the time-varying position is present in more than one coordinate system, each can be referenced. Therefore, the `location` -attribute is an array (outer array) consisting of an inner array of string parameter names. -If a parameter has all the `vectorComponents` in it to full represent this position, then the +attribute is an array (outer array) consisting of a list of inner arrays of string parameter names. +If a parameter containing location info has all the `vectorComponents` in it to fully represent the location, then the inner array will have just one element: the name of the fully sufficient parameter. -If the postion info for one coordinate system is spread over multiple parameters, then +If the position info for one coordinate system is spread over multiple parameters, then each parameter name needs to be in the inner array. ``` "location": { "parameters": [ ["param_name_for_location_using_coord_sys_A"], ["param_name_for_location_using_coord_sys_B"] ] - # each parameters must be a vector and have in it's attrributes a full set of vectorComponents to describe the vector + # each parameter here must be a vector and have in its attributes a full set of `vectorComponents` to describe the vector } ``` Examples help illustrate: @@ -1434,16 +1444,19 @@ Examples help illustrate: "location": { "parameters": [ ["Location_GEO"], ["Location_GSE"] ] } - +``` +In this first example, two parameters provide position info, each in a different coordinate system. +Within the definition of each location parameter, there must be a `vectorComponent` description. +``` location: { "parameters": [ ["Location_GEO_X", "Location_GEO_Y", "Location_GEO_Z], ["Location_J2000_X", "Location_J2000_Y", "Location_J2000_Z"] ] } ``` -In the first example, two parameters provide position info, each in a different coordinate system. Within each parameter definition, there must be a `vectorComponent` description. +In this second example, there are also two coordinate systems, but each one is expressed +across three parameters, one each for the x, y, and z values of the position. -In the second example, there are also two coordinate systems, but each one is expressed in three parameters, one each for the x, y, and z values of the position. ## 3.7 `data` From ff586e0cf141493928a686e3ed0526ae2d58d0b9 Mon Sep 17 00:00:00 2001 From: Bob Weigel Date: Tue, 28 Jan 2025 11:15:09 -0500 Subject: [PATCH 11/11] word smith --- hapi-dev/HAPI-data-access-spec-dev.md | 49 ++++++++++++--------------- 1 file changed, 22 insertions(+), 27 deletions(-) diff --git a/hapi-dev/HAPI-data-access-spec-dev.md b/hapi-dev/HAPI-data-access-spec-dev.md index b28a4b7..39af371 100644 --- a/hapi-dev/HAPI-data-access-spec-dev.md +++ b/hapi-dev/HAPI-data-access-spec-dev.md @@ -545,7 +545,7 @@ The response is in JSON format [[3](#6-references)] and provides metadata about | `unitsSchema` | string | **Optional** The name of the units convention that describes how to parse all `units` strings in this dataset. Currently, the only allowed values are: `udunits2`, `astropy3`, and `cdf-cluster`. See [`unitsSchema` Details](#363-unitsschema-details) for additional information about these conventions. The list of allowed unit specifications is expected to grow to include other well-documented unit standards. | | `coordinateSystemSchema` | string | **Optional** The name of the schema or convention that contains a list of coordinate system names and definitions. If this keyword is provided, any `coordinateSystemName` keyword given in a [parameter](#366-parameter-object) definition should follow this schema. See [`coordinateSystemSchema` Details](#364-coordinatesystemschema-details) for additional information. | | `location` | object | **Optional** A way to specify where a dataset's measurements were made. See [location and geoLocation Details](#3617-location-and-geoLocation-details) for an explanation of the two ways to indicate location: one for a fixed location and one for when the measurement location changes with time. -| `geoLocation` | array of double | **Optional** A simplified, compact way of indicating a fixed location for a dataset in Earth-based coordinates. The coordinates, their order and coordinate frame are meant to match what is used in [GeoJSON](https://geojson.org). For information and examples, see [location and geoLocation Details](#3617-location-and-geoLocation-details). +| `geoLocation` | array of double | **Optional** A simplified, compact way of indicating a fixed location for a dataset in Earth-based coordinates. The array has 2- or 3- elements: [longitude in degrees, latitude in degrees, (optional) altitude in meters]. For information and examples, see [location and geoLocation Details](#3617-location-and-geoLocation-details). | `resourceURL` | string | **Optional** URL linking to more detailed information about this dataset. | | `resourceID` | string | **Optional** An identifier by which this data is known in another setting (e.g., DOI) | `creationDate` | string | **Optional** [Restricted ISO 8601](#376-representation-of-time) date/time of the dataset creation. | @@ -1359,21 +1359,24 @@ then clients can restrict the image list further by filtering on values in the m Some datasets have parameters whose measurements are associated with a fixed location. Other measurements are made from locations that change with time. The `location` attribute can express the location of measurements either as a single, fixed location, -or as location values that change with time. An alternative attribute `geoLocation` can +or as location values that change with time. An alternative attribute, `geoLocation`, can be used instead as a compact way of describing an Earth-based position for a dataset's measurements. For the case of a fixed location on Earth, the `geoLocation` attribute concisely represents a point location with an array of longitude, latitude, and optionally altitude. -``` + +```javascript "geoLocation": [longitude, latitude] -OR- "geoLocation": [longitude, latitude, altitude] ``` -Angles in `geoLocation` must be in `deg` and altitude in `m` and the coordinate frame is WGS84 (see [Geodetic Coordinate Systems](https://en.wikipedia.org/wiki/World_Geodetic_System)). + +Angles in `geoLocation` must be in `deg` and altitude in `m` and the coordinate system is WGS84 (see [Geodetic Coordinate Systems](https://en.wikipedia.org/wiki/World_Geodetic_System)). This makes `geoLocation` consistent with the [GeoJSON](https://geojson.org) specification for a point location. As an example, the location of measurements made by a hypothetical magnetometer at the peak of Sugarloaf Mountain in Maryland, USA, could be represented as: -``` + +```javascript "geoLocation": [-77.395, 39.269, 391.0] ``` @@ -1383,37 +1386,28 @@ use a `location` object with these four attributes: | location Attribute | Type | Description | |------------------------|---------|-----------------------------------------------------------------| | `point` | double array | **Required** values to specify the location | -| `components` | string array | **Required** the kind of [`vectorComponent`](#3610-specifying-vectorcomponents) values in the `point` array | -| `units` | string or string array | **Required** units string or strings for the `vectorComponent` values | -| `coordinateSystemName` | string | **Required** the name of the coordinate system for the `vectorComponent` quantities | +| `components` | string array | **Required** the kind of [`vectorComponents`](#3610-specifying-vectorcomponents) values in the `point` array | +| `units` | string or string array | **Required** units string or strings for the `vectorComponents` values | +| `coordinateSystemName` | string | **Required** the name of the coordinate system for the `vectorComponents` quantities | +If a `unitsSchema` has been specified for this dataset, any string given for the `units` must be consistent with that schema. Similarly, if a `coordinateSystemName` has been specified for this dataset, any string given for the `coordinateSystemName` must be consistent with that schema. -``` -"location": { - "point": [value_A, value_B, value_C], - "components": ["vector_component_A", "vector_component_B", "vector_component_C"], - # these are constsrained to be a valid vectorComponents - # example: "components": ["longitude", "latitide", "altitude"] - "units": ["label_A", "label_B", "label_C"], - # should follow the units schema, if one was provided - # Example: "units": ["deg", "deg", "meters"] - "coordinateSystemName": "name_of_coord_sys" - # Example: "coordinateSystemName": "wgs84" -} -``` +**Examples** -If a `unitsSchema` has been specified for this dataset, any string given for the `units` must be consistent with that schema. -Similarly, the `coordinateSystemName` must come from a schema, if one is specified by the `coordinateSystemSchema` for this dataset. +A verbose version of `"geoLocation": [-77.395, 39.269, 391.0]`: -Some complete examples: -``` +```javascript "location": { - "point": [117.5, 37.1, 410.0], + "point": [-77.395, 39.269, 391.0], "components": ["longitude", "latitude", "altitude"], "units": ["deg", "deg", "m"], "coordinateSystemName": "wgs84" } +``` + +Location in non-WGS84 coordinate system and with cartesian vector components: +```javascript "location": { "point": [-4.1452e3, 1.2050e3, 0.10201e3], "components": ["x", "y", "z"], @@ -1421,7 +1415,8 @@ Some complete examples: "coordinateSystemName": "GSE" } ``` -Note that in the second example, the units value of `km` is broadcast to all the elements of the components. + +Note that in the second example, the units value of `km` [applies to all components elements](#369-unit-and-label-arrays). **Time-Varying Locations**