Deprecate percentages in favor of statistics

stac-extensions · Aug 27, 2024 · 32f144b · 32f144b
1 parent 1f27ab9
commit 32f144b
Show file tree

Hide file tree

Showing 5 changed files with 58 additions and 49 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `s2:snow_ice_percentage` in favor of `eo:snow_cover`
 - `s2:generation_time` in favor of `processing:datetime`
 - `s2:processing_baseline` in favor of `processing:version`
+- `s2:water_percentage` in favor of an entry in `statistics`
+- `s2:vegetation_percentage` in favor of an entry in `statistics`
+- `s2:thin_cirrus_percentage` in favor of an entry in `statistics`
+- `s2:cloud_shadow_percentage` in favor of an entry in `statistics`
+- `s2:nodata_pixel_percentage` in favor of an entry in `statistics`
+- `s2:unclassified_percentage` in favor of an entry in `statistics`
+- `s2:dark_features_percentage` in favor of an entry in `statistics`
+- `s2:not_vegetated_percentage` in favor of an entry in `statistics`
+- `s2:degraded_msi_data_percentage` in favor of an entry in `statistics`
+- `s2:high_proba_clouds_percentage` in favor of an entry in `statistics`
+- `s2:medium_proba_clouds_percentage` in favor of an entry in `statistics`
+- `s2:saturated_defective_pixel_percentage` in favor of an entry in `statistics`
 
 ### Removed
 

diff --git a/README.md b/README.md
@@ -39,18 +39,18 @@ The fields in the table below can be used in these parts of STAC documents:
 | s2:datastrip_id                         | string   | Datastrip Identifier                                         |
 | s2:datatake_type                        | string   | Datatake Type                                                |
 | s2:reflectance_conversion_factor        | number   | Reflectance Conversion Factor                                |
-| s2:water_percentage                     | number   | Water Percentage                                             |
-| s2:vegetation_percentage                | number   | Vegetation Percentage                                        |
-| s2:thin_cirrus_percentage               | number   | Thin Cirrus Percentage                                       |
-| s2:cloud_shadow_percentage              | number   | Cloud Shadow Percentage                                      |
-| s2:nodata_pixel_percentage              | number   | No Data Pixel Percentage                                     |
-| s2:unclassified_percentage              | number   | Unclassified Percentage                                      |
-| s2:dark_features_percentage             | number   | Dark Features Percentage                                     |
-| s2:not_vegetated_percentage             | number   | Not Vegetated Percentage                                     |
-| s2:degraded_msi_data_percentage         | number   | Degraded MSI Data Percentage                                 |
-| s2:high_proba_clouds_percentage         | number   | High Probability Clouds Percentage                           |
-| s2:medium_proba_clouds_percentage       | number   | Medium Probability Clouds Percentage                         |
-| s2:saturated_defective_pixel_percentage | number   | Saturated Defective Pixel Percentage                         |
+| s2:water_percentage                     | number   | **DEPRECATED** in favor of `statistics`. Water Percentage    |
+| s2:vegetation_percentage                | number   | **DEPRECATED** in favor of `statistics`. Vegetation Percentage |
+| s2:thin_cirrus_percentage               | number   | **DEPRECATED** in favor of `statistics`. Thin Cirrus Percentage |
+| s2:cloud_shadow_percentage              | number   | **DEPRECATED** in favor of `statistics`. Cloud Shadow Percentage |
+| s2:nodata_pixel_percentage              | number   | **DEPRECATED** in favor of `statistics`. No Data Pixel Percentage |
+| s2:unclassified_percentage              | number   | **DEPRECATED** in favor of `statistics`. Unclassified Percentage |
+| s2:dark_features_percentage             | number   | **DEPRECATED** in favor of `statistics`. Dark Features Percentage |
+| s2:not_vegetated_percentage             | number   | **DEPRECATED** in favor of `statistics`. Not Vegetated Percentage |
+| s2:degraded_msi_data_percentage         | number   | **DEPRECATED** in favor of `statistics`. Degraded MSI Data Percentage |
+| s2:high_proba_clouds_percentage         | number   | **DEPRECATED** in favor of `statistics`. High Probability Clouds Percentage |
+| s2:medium_proba_clouds_percentage       | number   | **DEPRECATED** in favor of `statistics`. Medium Probability Clouds Percentage |
+| s2:saturated_defective_pixel_percentage | number   | **DEPRECATED** in favor of `statistics`. Saturated Defective Pixel Percentage |
 | s2:product_type                         | string   | **DEPRECATED** in favor of `product:type`. Product Type      |
 | s2:snow_ice_percentage                  | number   | **DEPRECATED** in favor of `eo:snow_cover`. Snow and Ice Percentage |
 | s2:generation_time                      | datetime | **DEPRECATED** in favor of `processing:datetime`. Generation Time |
@@ -60,6 +60,11 @@ The fields in the table below can be used in these parts of STAC documents:
 | s2:mean_solar_zenith                    | number   | **DEPRECATED** in favor of `view:sun_elevation`. Mean Solar Zenith |
 | s2:mean_solar_azimuth                   | number   | **DEPRECATED** in favor of `view:sun_azimuth`. Mean Solar Azimuth |
 
+The fields with the `_percentage` suffix should be provided in the `statistics` field as defined in
+[common metadata](https://github.com/radiantearth/stac-spec/blob/dev/commons/common-metadata.md#statistics-object).
+Ideally remove the `s2:` prefix and the `_percentage` suffix and use the remainders as the key name in the Statistics Object,
+so for example `high_proba_clouds` instead of `s2:high_proba_clouds_percentage`.
+
 ## Relation types
 
 None

diff --git a/examples/item.json b/examples/item.json
@@ -714,21 +714,23 @@
     "s2:datatake_type": "INS-NOBS",
     "processing:datetime": "2023-11-07T18:21:59.14490Z",
     "sat:relative_orbit": 139,
-    "s2:water_percentage": 95.782292,
     "eo:snow_cover": 0,
     "processing:version": "05.09",
-    "s2:vegetation_percentage": 0,
-    "s2:thin_cirrus_percentage": 0.774645,
-    "s2:cloud_shadow_percentage": 0,
-    "s2:nodata_pixel_percentage": 99.062872,
-    "s2:unclassified_percentage": 0,
-    "s2:dark_features_percentage": 0,
-    "s2:not_vegetated_percentage": 0.000708,
-    "s2:degraded_msi_data_percentage": 0,
-    "s2:high_proba_clouds_percentage": 0.699942,
-    "s2:reflectance_conversion_factor": 1.01678413954947,
-    "s2:medium_proba_clouds_percentage": 2.742413,
-    "s2:saturated_defective_pixel_percentage": 0
+    "statistics": {
+      "water": 95.782292,
+      "vegetation": 0,
+      "thin_cirrus": 0.774645,
+      "cloud_shadow": 0,
+      "nodata_pixel": 99.062872,
+      "unclassified": 0,
+      "dark_features": 0,
+      "not_vegetated": 0.000708,
+      "degraded_msi_data": 0,
+      "high_proba_clouds": 0.699942,
+      "reflectance_conversion_factor": 1.01678413954947,
+      "medium_proba_clouds": 2.742413,
+      "saturated_defective_pixel": 0
+    }
   },
   "stac_extensions": [
     "https://stac-extensions.github.io/sentinel-2/v1.0.0/schema.json",

diff --git a/examples/item2.json b/examples/item2.json
@@ -44,18 +44,20 @@
     "s2:datastrip_id": "S2A_OPER_MSI_L2A_DS_ESRI_20201007T160858_S20190212T192646_N02.12",
     "s2:tile_id": "S2A_OPER_MSI_L2A_TL_ESRI_20201007T160858_A019029_T07HFE_N02.12",
     "s2:reflectance_conversion_factor": 1.02763689829235,
-    "s2:degraded_msi_data_percentage": 0,
-    "s2:nodata_pixel_percentage": 96.769553,
-    "s2:saturated_defective_pixel_percentage": 0,
-    "s2:dark_features_percentage": 0,
-    "s2:cloud_shadow_percentage": 0,
-    "s2:vegetation_percentage": 0.000308,
-    "s2:not_vegetated_percentage": 0.069531,
-    "s2:water_percentage": 48.349833,
-    "s2:unclassified_percentage": 0,
-    "s2:medium_proba_clouds_percentage": 14.61311,
-    "s2:high_proba_clouds_percentage": 24.183494,
-    "s2:thin_cirrus_percentage": 12.783723,
+    "statistics": {
+      "degraded_msi_data": 0,
+      "nodata_pixel": 96.769553,
+      "saturated_defective_pixel": 0,
+      "dark_features": 0,
+      "cloud_shadow": 0,
+      "vegetation": 0.000308,
+      "not_vegetated": 0.069531,
+      "water": 48.349833,
+      "unclassified": 0,
+      "medium_proba_clouds": 14.61311,
+      "high_proba_clouds": 24.183494,
+      "thin_cirrus": 12.783723
+    },
     "datetime": "2019-02-12T19:26:51.024000Z"
   },
   "geometry": {

diff --git a/json-schema/schema.json b/json-schema/schema.json
@@ -57,18 +57,6 @@
         { "required": ["s2:product_uri"] },
         { "required": ["s2:datastrip_id"] },
         { "required": ["s2:datatake_type"] },
-        { "required": ["s2:water_percentage"] },
-        { "required": ["s2:vegetation_percentage"] },
-        { "required": ["s2:thin_cirrus_percentage"] },
-        { "required": ["s2:cloud_shadow_percentage"] },
-        { "required": ["s2:nodata_pixel_percentage"] },
-        { "required": ["s2:unclassified_percentage"] },
-        { "required": ["s2:dark_features_percentage"] },
-        { "required": ["s2:not_vegetated_percentage"] },
-        { "required": ["s2:degraded_msi_data_percentage"] },
-        { "required": ["s2:high_proba_clouds_percentage"] },
-        { "required": ["s2:medium_proba_clouds_percentage"] },
-        { "required": ["s2:saturated_defective_pixel_percentage"] },
         { "required": ["s2:reflectance_conversion_factor"] }
       ]
     },