Add SWC and LST quality flags scripts and docs (#332)

* Initial setup SWC quality flags scripts and docs

* Fix invalid date in example

* Add initial setup LST quality flags scripts

* Add documentation on SWC quality flags scripts

* Add documentation on LST quality flags scripts

* Auto-formatting scripts

---------

Co-authored-by: Amber Mulder <amber.mulder@planet.com>
Co-authored-by: Jonas Viehweger <jonas.viehweger@planet.com>

planetary-variables/land-surface-temperature/index.md

@@ -13,3 +13,4 @@ Planet's LST product provides near real-time measurements twice a day at 1:30 an
 
 -   [Land Surface Temperature Visualization]({% link planetary-variables/land-surface-temperature/land-surface-temperature-visualization/index.md %})
 -   [Land Surface Temperature Anomaly]({% link planetary-variables/land-surface-temperature/land-surface-temperature-anomaly/index.md %})
+-   [Land Surface Temperature Quality Flags]({% link planetary-variables/land-surface-temperature/land-surface-temperature-quality-flags/index.md %})

planetary-variables/land-surface-temperature/land-surface-temperature-quality-flags/index.md

@@ -0,0 +1,47 @@
+---
+title: Land Surface Temperature Quality Flags
+grand_parent: Planetary Variables
+parent: Land Surface Temperature
+layout: script
+nav_exclude: false
+scripts:
+    - [Visualization, script.js]
+    - [Raw Values, raw.js]
+examples:
+- zoom: '11'
+  lat: '44.8398'
+  lng: '-0.5294'
+  datasetId: '8d977093-cf9e-4351-8159-90f2522c29c1'
+  fromTime: '2022-04-26T00:00:00.000Z'
+  toTime: '2022-04-26T23:59:59.999Z'
+  platform:
+  - EOB
+  evalscripturl: https://custom-scripts.sentinel-hub.com/custom-scripts/planetary-variables/land-surface-temperature/land-surface-temperature-quality-flags/script.js
+  additionalQueryParams: 
+  - - themeId
+    - PLANET_SANDBOX
+---
+## General description
+Land Surface Temperature (LST) products include [quality flag assets](https://developers.planet.com/docs/planetary-variables/land-surface-temperature-technical-specification/#quality-flags) that provide quality metadata for each pixel using a bitwise flag system. These flags help identify the reliability of the LST values for each pixel. Here we show how these quality flags can be easily displayed using custom scripts. For a complete list of all possible quality flags and their corresponding bits, please refer to [these tables](https://developers.planet.com/docs/planetary-variables/land-surface-temperature-technical-specification/#quality-flags).
+
+## Notes on usage
+Users can customize the script by adding the bit numbers corresponding to the quality flag(s) of interest to the `bits_to_check` list within the script. By default, the provided scripts are set to check all critical flags (indicating unreliable data, with corresponding LST pixels set to the no data value), but this can be updated to include or exclude specific flags as needed.
+
+Planet’s LST product provides near real-time measurements twice a day at 1:30 and 13:30 solar local time. The `sensing_time` variable in the scripts can be used to select the sensing time of interest
+
+The provided Visualization script highlights pixels for which specific quality flags of interest are set. This allows users to visually inspect areas of concern or interest.
+
+The Raw Values script retrieves a binary raster where:
+
+- `1` indicates pixels for which the quality flag(s) of interest are set  
+- `0` indicates pixels where the quality flag(s) of interest are not set
+
+## Description of representative images
+The 'Open water' (bit 15\) quality flag in Flevoland, The Netherlands, on 2022-12-31.
+
+![The water quality flag](fig/qf_lst_100m_water_netherlands_2022-12-31.png)
+
+## Useful links
+-   [Product specifications](https://planet.widen.net/s/tltwk6hnps)
+-   [Data sheet](https://planet.widen.net/s/ttvp2rvwzd)
+-   [Sentinel Hub documentation about Land Surface Temperature](https://docs.sentinel-hub.com/api/latest/data/planetary-variables/land-surface-temp/)

planetary-variables/land-surface-temperature/land-surface-temperature-quality-flags/raw.js

@@ -0,0 +1,47 @@
+//VERSION=3
+
+const bits_to_check = [8, 9, 11, 13, 14, 15]; // Bits to check if they are set
+const sensing_time = "0130"; // "0130" or "1330" or ""
+
+function setup() {
+  return {
+    input: ["QF", "dataMask"],
+    output: { bands: 1, sampleType: "UINT8" },
+    mosaicking: "TILE",
+  };
+}
+
+//Select files based on sensing time (0130 or 1330)
+function preProcessScenes(collections) {
+  collections.scenes.tiles = collections.scenes.tiles.filter(function (tile) {
+    return tile.dataPath.includes("T" + sensing_time);
+  });
+  collections.scenes.tiles.sort((a, b) => new Date(b.date) - new Date(a.date));
+  return collections;
+}
+
+function areBitsSet(qf) {
+  // Check if the bits are set
+  for (let idx in bits_to_check) {
+    const bit = 1 << (bits_to_check[idx] - 1);
+    if ((qf & bit) !== 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function evaluatePixel(sample) {
+  // When there are no dates, return no data
+  if (sample.length == 0) return [NaN];
+
+  // Return NaN for no data pixels
+  if (sample[0].dataMask == 0) {
+    return [NaN];
+  }
+
+  // Check if the bits are set
+  const bit_set = areBitsSet(sample[0].QF);
+
+  return [bit_set ? 1 : 0];
+}

planetary-variables/land-surface-temperature/land-surface-temperature-quality-flags/script.js

@@ -0,0 +1,54 @@
+//VERSION=3
+
+const bits_to_check = [8, 9, 11, 13, 14, 15]; // Bits to check if they are set
+const sensing_time = "0130"; // "0130" or "1330" or ""
+
+function setup() {
+  return {
+    input: ["QF", "dataMask"],
+    output: { id: "default", bands: 4 },
+    mosaicking: "TILE",
+  };
+}
+
+//Select files based on sensing time (0130 or 1330)
+function preProcessScenes(collections) {
+  collections.scenes.tiles = collections.scenes.tiles.filter(function (tile) {
+    return tile.dataPath.includes("T" + sensing_time);
+  });
+  collections.scenes.tiles.sort((a, b) => new Date(b.date) - new Date(a.date));
+  return collections;
+}
+
+function areBitsSet(qf) {
+  // Check if the bits are set
+  for (let idx in bits_to_check) {
+    const bit = 1 << (bits_to_check[idx] - 1);
+    if ((qf & bit) !== 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function evaluatePixel(sample) {
+  // When there are no dates, return no data
+  if (sample.length == 0) return [NaN, NaN, NaN, 0];
+
+  // Return NaN for no data pixels
+  if (sample[0].dataMask == 0) {
+    return [NaN, NaN, NaN, 0];
+  }
+
+  // Check if the bits are set
+  const bit_set = areBitsSet(sample[0].QF);
+
+  // Ensure only flagged pixels are displayed
+  let opacity = 0;
+  let imgVals = [1, 0, 0];
+  if (bit_set) {
+    opacity = 0.5;
+  }
+
+  return [...imgVals, opacity];
+}

planetary-variables/soil-water-content/index.md

@@ -14,4 +14,5 @@ Planet's SWC product provides near-daily measurements at spatial resolutions of
 -   [Soil Water Content Visualization]({% link planetary-variables/soil-water-content/soil-water-content-visualization/index.md %})
 -   [Soil Water Content Anomaly]({% link planetary-variables/soil-water-content/soil-water-content-anomaly/index.md %})
 -   [Derived Root-Zone Soil Water Content]({% link planetary-variables/soil-water-content/derived-root-zone-soil-water-content/index.md %})
--   [Soil Water Content Backward Average]({% link planetary-variables/soil-water-content/soil-water-content-backward-average/index.md %})
+-   [Soil Water Content Backward Average]({% link planetary-variables/soil-water-content/soil-water-content-backward-average/index.md %})
+-   [Soil Water Content Quality Flags]({% link planetary-variables/soil-water-content/soil-water-content-quality-flags/index.md %})

planetary-variables/soil-water-content/soil-water-content-quality-flags/index.md

@@ -0,0 +1,51 @@
+---
+title: Soil Water Content Quality Flags
+grand_parent: Planetary Variables
+parent: Soil Water Content
+layout: script
+nav_exclude: false
+scripts:
+    - [Visualization, script.js]
+    - [Raw Values, raw.js]
+examples:
+- zoom: '11'
+  lat: '44.8398'
+  lng: '-0.5294'
+  datasetId: '65f7e4fb-a27a-4fae-8d79-06a59d7e6ede'
+  fromTime: '2022-04-26T00:00:00.000Z'
+  toTime: '2022-04-26T23:59:59.999Z'
+  platform:
+  - EOB
+  evalscripturl: https://custom-scripts.sentinel-hub.com/custom-scripts/planetary-variables/soil-water-content/soil-water-content-quality-flags/script.js
+  additionalQueryParams: 
+  - - themeId
+    - PLANET_SANDBOX
+---
+## General description
+Soil Water Content (SWC) products include [quality flag assets](https://developers.planet.com/docs/planetary-variables/soil-water-content-technical-specification/#quality-flags) that provide quality metadata for each pixel using a bitwise flag system. These flags help identify the reliability of the SWC values for each pixel. Here we show how these quality flags can be easily displayed using custom scripts. For a complete list of all possible quality flags and their corresponding bits, please refer to [these tables](https://developers.planet.com/docs/planetary-variables/soil-water-content-technical-specification/#quality-flags).
+
+## Notes on usage
+Users can customize the script by adding the bit numbers corresponding to the quality flag(s) of interest to the `bits_to_check` list within the script. By default, the provided scripts are set to check all critical flags (indicating unreliable data, with corresponding SWC pixels set to the no data value), but this can be updated to include or exclude specific flags as needed.
+
+The provided Visualization script highlights pixels for which specific quality flags of interest are set. This allows users to visually inspect areas of concern or interest.
+
+The Raw Values script retrieves a binary raster where:
+
+- `1` indicates pixels for which the quality flag(s) of interest are set  
+- `0` indicates pixels where the quality flag(s) of interest are not set
+
+## Description of representative images
+The 'Open water' (bit 15\) quality flag in Bordeaux, France, on 2022-04-26.
+
+![The water quality flag](fig/qf_swc_100m_water_bordeaux_2022-04-26.png)
+
+
+The 'Possible frozen soil' (bit 7) and 'Frozen soil' (bit 8) quality flags in Alberta, Canada, on 2022-12-23.
+
+![Possibly (frozen) quality flags](fig/qf_swc_100m_frozen_and_possibly_frozen_alberta_2022-12-23.png)
+
+
+## Useful links
+-   [SWC Technical specifications](https://developers.planet.com/docs/planetary-variables/soil-water-content-technical-specification/)
+-   [SWC Data sheet](https://planet.widen.net/s/cv7bfjhhd5)
+-   [Sentinel Hub documentation about Soil Water Content](https://docs.sentinel-hub.com/api/latest/data/planetary-variables/soil-water-content/)

planetary-variables/soil-water-content/soil-water-content-quality-flags/raw.js

@@ -0,0 +1,33 @@
+//VERSION=3
+
+const bits_to_check = [6, 8, 9, 10, 11, 12, 13, 14, 15, 16]; // Bits to check if they are set
+
+function setup() {
+  return {
+    input: ["QF", "dataMask"],
+    output: { bands: 1, sampleType: "UINT8" },
+  };
+}
+
+function areBitsSet(qf) {
+  // Check if the bits are set
+  for (let idx in bits_to_check) {
+    const bit = 1 << (bits_to_check[idx] - 1);
+    if ((qf & bit) !== 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function evaluatePixel(sample) {
+  // Return NaN for no data pixels
+  if (sample.dataMask == 0) {
+    return [NaN];
+  }
+
+  // Check if the bits are set
+  const bit_set = areBitsSet(sample.QF);
+
+  return [bit_set ? 1 : 0];
+}

planetary-variables/soil-water-content/soil-water-content-quality-flags/script.js

@@ -0,0 +1,40 @@
+//VERSION=3
+
+const bits_to_check = [6, 8, 9, 10, 11, 12, 13, 14, 15, 16]; // Bits to check if they are set
+
+function setup() {
+  return {
+    input: ["QF", "dataMask"],
+    output: { id: "default", bands: 4 },
+  };
+}
+
+function areBitsSet(qf) {
+  // Check if the bits are set
+  for (let idx in bits_to_check) {
+    const bit = 1 << (bits_to_check[idx] - 1);
+    if ((qf & bit) !== 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function evaluatePixel(sample) {
+  // Return NaN for no data pixels
+  if (sample.dataMask == 0) {
+    return [NaN, NaN, NaN, 0];
+  }
+
+  // Check if the bits are set
+  const bit_set = areBitsSet(sample.QF);
+
+  // Ensure only flagged pixels are displayed
+  let opacity = 0;
+  let imgVals = [1, 0, 0];
+  if (bit_set) {
+    opacity = 0.5;
+  }
+
+  return [...imgVals, opacity];
+}