dea-tools 0.3.6.dev1__tar.gz → 0.3.6.dev31__tar.gz

{dea_tools-0.3.6.dev1/dea_tools.egg-info → dea_tools-0.3.6.dev31}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: dea-tools
-Version: 0.3.6.dev1
+Version: 0.3.6.dev31
 Summary: Functions and algorithms for analysing Digital Earth Australia data.
 Home-page: https://github.com/GeoscienceAustralia/dea-notebooks
 Author: Geoscience Australia
@@ -44,7 +44,7 @@ Requires-Dist: pyproj
 Requires-Dist: pystac-client
 Requires-Dist: planetary-computer
 Requires-Dist: python-dateutil
-Requires-Dist: pyTMD<=2.1.6
+Requires-Dist: pyTMD!=2.1.7
 Requires-Dist: pytz
 Requires-Dist: rasterio
 Requires-Dist: rasterstats
@@ -65,6 +65,17 @@ Provides-Extra: dask-gateway
 Requires-Dist: dask_gateway; extra == "dask-gateway"
 Provides-Extra: otps
 Requires-Dist: otps; extra == "otps"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 
 dea-tools package

{dea_tools-0.3.6.dev1 → dea_tools-0.3.6.dev31}/dea_tools/datahandling.py

@@ -17,7 +17,7 @@ here: https://gis.stackexchange.com/questions/tagged/open-data-cube).
 If you would like to report an issue with this script, you can file one
 on GitHub (https://github.com/GeoscienceAustralia/dea-notebooks/issues/new).
 
-Last modified: Feb 2024
+Last modified: February 2025
 """
 
 import datetime
@@ -112,7 +112,7 @@ def load_ard(
 ):
     """
     Load multiple Geoscience Australia Landsat or Sentinel 2
-    Collection 3 products (e.g. Landsat 5, 7, 8, 9; Sentinel 2A and 2B),
+    Collection 3  Analysis Ready Data products (e.g. Landsat 5, 7, 8, 9; Sentinel 2A, 2B, 2C),
     optionally apply pixel quality/cloud masking and contiguity masks,
     and drop time steps that contain greater than a minimum proportion
     of good quality (e.g. non-cloudy or shadowed) pixels.
@@ -126,13 +126,14 @@ def load_ard(
     And Sentinel-2 products:
         * ga_s2am_ard_3
         * ga_s2bm_ard_3
+        * ga_s2cm_ard_3
 
     Cloud masking can be performed using the Fmask (Function of Mask)
     cloud mask for Landsat and Sentinel-2, and the s2cloudless
     (Sentinel Hub cloud detector for Sentinel-2 imagery) cloud mask for
     Sentinel-2.
 
-    Last modified: June 2023
+    Last modified: February 2025
 
     Parameters
     ----------
@@ -142,7 +143,8 @@ def load_ard(
     products : list
         A list of product names to load. Valid options are
         ['ga_ls5t_ard_3', 'ga_ls7e_ard_3', 'ga_ls8c_ard_3', 'ga_ls9c_ard_3']
-        for Landsat, ['ga_s2am_ard_3', 'ga_s2bm_ard_3'] for Sentinel 2.
+        for Landsat, ['ga_s2am_ard_3', 'ga_s2bm_ard_3', 'ga_s2cm_ard_3']
+        for Sentinel 2.
     cloud_mask : string, optional
         The cloud mask used by the function. This is used for both
         masking out poor quality pixels (e.g. clouds) if
@@ -256,21 +258,27 @@ def load_ard(
     # Setup #
     #########
 
+    # Convert products to a list if it is passed as a string
+    products = [products] if isinstance(products, str) else products
+
+    # Valid Landsat products
+    valid_ls = ["ga_ls5t_ard_3", "ga_ls7e_ard_3", "ga_ls8c_ard_3", "ga_ls9c_ard_3"]
+    valid_s2 = ["ga_s2am_ard_3", "ga_s2bm_ard_3", "ga_s2cm_ard_3"]
+
     # Verify that products were provided
     if not products:
         raise ValueError(
-            "Please provide a list of product names to load data from. "
-            "Valid options are: ['ga_ls5t_ard_3', 'ga_ls7e_ard_3', "
-            "'ga_ls8c_ard_3', 'ga_ls9c_ard_3'] for Landsat, and "
-            "['ga_s2am_ard_3', 'ga_s2bm_ard_3'] for Sentinel 2."
+            f"Please provide a list of Landsat or Sentinel-2 Analysis Ready Data "
+            f"product names to load data from. Valid options are: "
+            f"{valid_ls + valid_s2}."
         )
 
     # Determine whether products are all Landsat, all S2, or mixed
-    elif all(["ls" in product for product in products]):
+    elif all([product in valid_ls for product in products]):
         product_type = "ls"
-    elif all(["s2" in product for product in products]):
+    elif all([product in valid_s2 for product in products]):
         product_type = "s2"
-    else:
+    elif all([product in valid_s2 + valid_ls for product in products]):
         product_type = "mixed"
 
         warnings.warn(
@@ -280,6 +288,16 @@ def load_ard(
             "(e.g. Landsat and Sentinel-2's 'nbart_swir_2'); use with "
             "caution."
         )
+    else:
+        # If an invalid product is passed, raise error
+        invalid_products = [
+            product for product in products if product not in valid_s2 + valid_ls
+        ]
+        raise ValueError(
+            f"The `load_ard` function only supports Landsat and "
+            f"Sentinel-2 Analysis Ready Data products; {invalid_products} is not supported. "
+            f"Valid options are: {valid_ls + valid_s2}."
+        )
 
     # Set contiguity band depending on `mask_contiguity`;
     # "oa_nbart_contiguity" if True, False or "nbart",

{dea_tools-0.3.6.dev1 → dea_tools-0.3.6.dev31}/dea_tools/landcover.py

@@ -34,13 +34,13 @@ from matplotlib.animation import FuncAnimation
 
 # Define colour schemes for each land cover measurement
 lc_colours = {
-    'level3': {0: (255, 255, 255, 255, "No Data"),
-               111: (172, 188, 45, 255, "Cultivated Terrestrial\n Vegetation"),
+    'level3': {111: (172, 188, 45, 255, "Cultivated Terrestrial\n Vegetation"),
                112: (14, 121, 18, 255, "Natural Terrestrial\n Vegetation"),
                124: (30, 191, 121, 255, "Natural Aquatic\n Vegetation"),
                215: (218, 92, 105, 255, "Artificial Surface"),
                216: (243, 171, 105, 255, "Natural Bare\n Surface"),
-               220: (77, 159, 220, 255, "Water")},
+               220: (77, 159, 220, 255, "Water"),
+               255: (255, 255, 255, 255, "No Data")},
 
     'level3_change_colour_scheme': {0: (255, 255, 255, 255, "No Change"),
                                     111112: (14, 121, 18, 255, "CTV -> NTV"),
@@ -61,49 +61,51 @@ lc_colours = {
                                     216215: (218, 92, 105, 255, "BS -> AS"),
                                     216220: (77, 159, 220, 255, "BS -> Water"),
                                     220112: (14, 121, 18, 255, "Water -> NTV"),
-                                    220216: (243, 171, 105, 255, "Water -> BS")},
+                                    220216: (243, 171, 105, 255, "Water -> BS"),
+                                    },
 
-    'level3_change_colour_bar': {0: (255, 255, 255, 255, "No change"),
-                                 111: (172, 188, 45, 255, "Changed to Cultivated\n Terrestrial Vegetation"),
+    'level3_change_colour_bar': {111: (172, 188, 45, 255, "Changed to Cultivated\n Terrestrial Vegetation"),
                                  112: (14, 121, 18, 255, "Changed to Natural\n Terrestrial Vegetation"),
                                  124: (30, 191, 121, 255, "Changed to Natural\n Aquatic Vegetation"),
                                  215: (218, 92, 105, 255, "Changed to Artificial\n Surface"),
                                  216: (243, 171, 105, 255, "Changed to Natural\n Bare Surface"),
-                                 220: (77, 159, 220, 255, "Changed to Water")},
+                                 220: (77, 159, 220, 255, "Changed to Water"),
+                                 0: (255, 255, 255, 255, "No Change")},
 
-    'lifeform_veg_cat_l4a': {0: (255, 255, 255, 255, "No Data /\n Not vegetated"),
-                             1: (14, 121, 18, 255, "Woody Vegetation"),
-                             2: (172, 188, 45, 255, "Herbaceous\n Vegetation")},
+     'lifeform_veg_cat_l4a': {1: (14, 121, 18, 255, "Woody Vegetation"),
+                              2: (172, 188, 45, 255, "Herbaceous\n Vegetation"),
+                              255: (255, 255, 255, 255, "No Data /\n Not vegetated")},
 
-    'canopyco_veg_cat_l4d': {0: (255, 255, 255, 255, "No Data /\n Not vegetated"),
-                             10: (14,  121, 18,  255, "> 65 % cover"),
+
+    'canopyco_veg_cat_l4d': {10: (14,  121, 18,  255, "> 65 % cover"),
                              12: (45,  141, 47,  255, "40 to 65 % cover"),
                              13: (80,  160, 82,  255, "15 to 40 % cover"),
                              15: (117, 180, 118, 255, "4 to 15 % cover"),
-                             16: (154, 199, 156, 255, "1 to 4 % cover")},
+                             16: (154, 199, 156, 255, "1 to 4 % cover"),
+                             255: (255, 255, 255, 255, "No Data /\n Not vegetated")},
 
-    'waterstt_wat_cat_l4a': {0: (255, 255, 255, 255, "No Data /\n Not water"),
-                             1: (77, 159, 220, 255, "Water")},
+    'waterstt_wat_cat_l4a': {1: (77, 159, 220, 255, "Water"),
+                             255: (255, 255, 255, 255, "No Data /\n Not water")},
 
-    'watersea_veg_cat_l4a_au': {0: (255, 255, 255, 255, "No data /\n Not aquatic vegetation"),
-                                1: (25,  173, 109, 255, "> 3 months"),
-                                2: (176, 218, 201, 255, "< 3 months")},
+    'watersea_veg_cat_l4a_au': {1: (25,  173, 109, 255, "> 3 months"),
+                                2: (176, 218, 201, 255, "< 3 months"),
+                                255: (255, 255, 255, 255, "No data /\n Not aquatic vegetation")},
 
-    'inttidal_wat_cat_l4a': {0: (255, 255, 255, 255, "No data /\n Not intertidal"),
-                             3: (77, 159, 220, 255, "Intertidal")},
+    'inttidal_wat_cat_l4a': {3: (77, 159, 220, 255, "Intertidal"),
+                             255: (255, 255, 255, 255, "No data /\n Not intertidal")},
 
-    'waterper_wat_cat_l4d_au': {0: (255, 255, 255, 255, "No data /\n Not water"),
-                                1: (27,  85,  186, 255, "> 9 months"),
+    'waterper_wat_cat_l4d_au': {1: (27,  85,  186, 255, "> 9 months"),
                                 7: (52,  121, 201, 255, "7 to 9 months"),
                                 8: (79,  157, 217, 255, "4 to 6 months"),
-                                9: (113, 202, 253, 255, "1 to 3 months")},
+                                9: (113, 202, 253, 255, "1 to 3 months"),
+                                255: (255, 255, 255, 255, "No data /\n Not water")},
 
-    'baregrad_phy_cat_l4d_au': {0: (255, 255, 255, 255, "No data /\n Not bare"),
-                                10: (255, 230, 140, 255, "Sparsely vegetated\n (< 20% bare)"),
+    'baregrad_phy_cat_l4d_au': {10: (255, 230, 140, 255, "Sparsely vegetated\n (< 20% bare)"),
                                 12: (250, 210, 110, 255, "Very sparsely\n vegetated (20 to 60% bare)"),
-                                15: (243, 171, 105, 255, "Bare areas,\n unvegetated (> 60% bare)")},
+                                15: (243, 171, 105, 255, "Bare areas,\n unvegetated (> 60% bare)"),
+                                255: (255, 255, 255, 255, "No data /\n Not bare")},
 
-    'level4': {0: (255, 255, 255, 255, "No Data"),
+    'level4': {
                1: (151, 187, 26, 255, 'Cultivated Terrestrial\n Vegetated:'),
                2: (151, 187, 26, 255, 'Cultivated Terrestrial\n Vegetated: Woody'),
                3: (209, 224, 51, 255, 'Cultivated Terrestrial\n Vegetated: Herbaceous'),
@@ -112,11 +114,11 @@ lc_colours = {
                6: (213, 193, 79, 255, 'Cultivated Terrestrial\n Vegetated: Open\n (15 to 40 %)'),
                7: (228, 210, 108, 255, 'Cultivated Terrestrial\n Vegetated: Sparse\n (4 to 15 %)'),
                8: (242, 227, 138, 255, 'Cultivated Terrestrial\n Vegetated: Scattered\n (1 to 4 %)'),
-               # 9: (197, 168, 71, 255, 'Cultivated Terrestrial\n Vegetated: Woody Closed\n (> 65 %)'),
-               # 10: (205, 181, 75, 255, 'Cultivated Terrestrial\n Vegetated: Woody Open\n (40 to 65 %)'),
-               # 11: (213, 193, 79, 255, 'Cultivated Terrestrial\n Vegetated: Woody Open\n (15 to 40 %)'),
-               # 12: (228, 210, 108, 255, 'Cultivated Terrestrial\n Vegetated: Woody Sparse\n (4 to 15 %)'),
-               # 13: (242, 227, 138, 255, 'Cultivated Terrestrial\n Vegetated: Woody Scattered\n (1 to 4 %)'),
+               9: (197, 168, 71, 255, 'Cultivated Terrestrial\n Vegetated: Woody Closed\n (> 65 %)'),
+               10: (205, 181, 75, 255, 'Cultivated Terrestrial\n Vegetated: Woody Open\n (40 to 65 %)'),
+               11: (213, 193, 79, 255, 'Cultivated Terrestrial\n Vegetated: Woody Open\n (15 to 40 %)'),
+               12: (228, 210, 108, 255, 'Cultivated Terrestrial\n Vegetated: Woody Sparse\n (4 to 15 %)'),
+               13: (242, 227, 138, 255, 'Cultivated Terrestrial\n Vegetated: Woody Scattered\n (1 to 4 %)'),
                14: (228, 224, 52, 255, 'Cultivated Terrestrial\n Vegetated: Herbaceous Closed\n (> 65 %)'),
                15: (235, 232, 84, 255, 'Cultivated Terrestrial\n Vegetated: Herbaceous Open\n (40 to 65 %)'),
                16: (242, 240, 127, 255, 'Cultivated Terrestrial\n Vegetated: Herbaceous Open\n (15 to 40 %)'),
@@ -140,24 +142,24 @@ lc_colours = {
                34: (153, 196, 80, 255, 'Natural Terrestrial Vegetated: Herbaceous Open (15 to 40 %)'),
                35: (170, 212, 113, 255, 'Natural Terrestrial Vegetated: Herbaceous Sparse (4 to 15 %)'),
                36: (186, 226, 146, 255, 'Natural Terrestrial Vegetated: Herbaceous Scattered (1 to 4 %)'),
-               # 37: (86, 236, 231, 255, 'Cultivated Aquatic Vegetated:'),
-               # 38: (61, 170, 140, 255, 'Cultivated Aquatic Vegetated: Woody'),
-               # 39: (82, 231, 172, 255, 'Cultivated Aquatic Vegetated: Herbaceous'),
-               # 40: (43, 210, 203, 255, 'Cultivated Aquatic Vegetated: Closed (> 65 %)'),
-               # 41: (73, 222, 216, 255, 'Cultivated Aquatic Vegetated: Open (40 to 65 %)'),
-               # 42: (110, 233, 228, 255, 'Cultivated Aquatic Vegetated: Open (15 to 40 %)'),
-               # 43: (149, 244, 240, 255, 'Cultivated Aquatic Vegetated: Sparse (4 to 15 %)'),
-               # 44: (187, 255, 252, 255, 'Cultivated Aquatic Vegetated: Scattered (1 to 4 %)'),
+               37: (86, 236, 231, 255, 'Cultivated Aquatic Vegetated:'),
+               38: (61, 170, 140, 255, 'Cultivated Aquatic Vegetated: Woody'),
+               39: (82, 231, 172, 255, 'Cultivated Aquatic Vegetated: Herbaceous'),
+               40: (43, 210, 203, 255, 'Cultivated Aquatic Vegetated: Closed (> 65 %)'),
+               41: (73, 222, 216, 255, 'Cultivated Aquatic Vegetated: Open (40 to 65 %)'),
+               42: (110, 233, 228, 255, 'Cultivated Aquatic Vegetated: Open (15 to 40 %)'),
+               43: (149, 244, 240, 255, 'Cultivated Aquatic Vegetated: Sparse (4 to 15 %)'),
+               44: (187, 255, 252, 255, 'Cultivated Aquatic Vegetated: Scattered (1 to 4 %)'),
                # 45: (43, 210, 203, 255, 'Cultivated Aquatic Vegetated: Woody Closed (> 65 %)'),
                # 46: (73, 222, 216, 255, 'Cultivated Aquatic Vegetated: Woody Open (40 to 65 %)'),
                # 47: (110, 233, 228, 255, 'Cultivated Aquatic Vegetated: Woody Open (15 to 40 %)'),
                # 48: (149, 244, 240, 255, 'Cultivated Aquatic Vegetated: Woody Sparse (4 to 15 %)'),
                # 49: (187, 255, 252, 255, 'Cultivated Aquatic Vegetated: Woody Scattered (1 to 4 %)'),
-               # 50: (82, 231, 196, 255, 'Cultivated Aquatic Vegetated: Herbaceous Closed (> 65 %)'),
-               # 51: (113, 237, 208, 255, 'Cultivated Aquatic Vegetated: Herbaceous Open (40 to 65 %)'),
-               # 52: (144, 243, 220, 255, 'Cultivated Aquatic Vegetated: Herbaceous Open (15 to 40 %)'),
-               # 53: (175, 249, 232, 255, 'Cultivated Aquatic Vegetated: Herbaceous Sparse (4 to 15 %)'),
-               # 54: (207, 255, 244, 255, 'Cultivated Aquatic Vegetated: Herbaceous Scattered (1 to 4 %)'),
+               50: (82, 231, 196, 255, 'Cultivated Aquatic Vegetated: Herbaceous Closed (> 65 %)'),
+               51: (113, 237, 208, 255, 'Cultivated Aquatic Vegetated: Herbaceous Open (40 to 65 %)'),
+               52: (144, 243, 220, 255, 'Cultivated Aquatic Vegetated: Herbaceous Open (15 to 40 %)'),
+               53: (175, 249, 232, 255, 'Cultivated Aquatic Vegetated: Herbaceous Sparse (4 to 15 %)'),
+               54: (207, 255, 244, 255, 'Cultivated Aquatic Vegetated: Herbaceous Scattered (1 to 4 %)'),
                55: (30, 191, 121, 255, 'Natural Aquatic Vegetated:'),
                56: (18, 142, 148, 255, 'Natural Aquatic Vegetated: Woody'),
                57: (112, 234, 134, 255, 'Natural Aquatic Vegetated: Herbaceous'),
@@ -209,9 +211,14 @@ lc_colours = {
                103: (79, 157, 217, 255, 'Water: (Water) Non-perennial (4 to 6 months)'),
                104: (133, 202, 253, 255, 'Water: (Water) Non-perennial (1 to 3 months)'),
                # 105: (250, 250, 250, 255, 'Water: (Snow)')
+               255: (255, 255, 255, 255, "No Data")
                },
 
-    'level4_colourbar_labels': {0: (255, 255, 255, 255, "No Data"),
+    'level4_colourbar_labels': {9: (197, 168, 71, 255, 'Cultivated Terrestrial Vegetated: Woody Closed (> 65 %)'),
+                                10: (205, 181, 75, 255, 'Cultivated Terrestrial Vegetated: Woody Open (40 to 65 %)'),
+                                11: (213, 193, 79, 255, 'Cultivated Terrestrial Vegetated: Woody Open (15 to 40 %)'),
+                                12: (228, 210, 108, 255, 'Cultivated Terrestrial Vegetated: Woody Sparse (4 to 15 %)'),
+                                13: (242, 227, 138, 255, 'Cultivated Terrestrial Vegetated: Woody Scattered (1 to 4 %)'),
                                 14: (228, 224, 52, 255, 'Cultivated Terrestrial Vegetated: Herbaceous Closed (> 65 %)'),
                                 15: (235, 232, 84, 255, 'Cultivated Terrestrial Vegetated: Herbaceous Open (40 to 65 %)'),
                                 16: (242, 240, 127, 255, 'Cultivated Terrestrial Vegetated: Herbaceous Open (15 to 40 %)'),
@@ -245,10 +252,41 @@ lc_colours = {
                                 101: (27, 85, 186, 255, 'Water: (Water) Perennial (> 9 months)'),
                                 102: (52, 121, 201, 255, 'Water: (Water) Non-perennial (7 to 9 months)'),
                                 103: (79, 157, 217, 255, 'Water: (Water) Non-perennial (4 to 6 months)'),
-                                104: (133, 202, 253, 255, 'Water: (Water) Non-perennial (1 to 3 months)')},
+                                104: (133, 202, 253, 255, 'Water: (Water) Non-perennial (1 to 3 months)'),
+                                255: (255, 255, 255, 255, "No Data")
+                               },
+}
+
+# dictionary needed to generate colour schemes of descriptors from the level 4 colour scheme. The structure is as follow:
+# long_descriptor_name[string]: {keyword_for_finding_classes_in_level4_colourscheme[string] : (RGB_colourscheme[4 integers], label_of_descriptor[string])}
+lc_colours_mapping = {
+        'lifeform_veg_cat_l4a': {'Woody': (14, 121,18, 255, 'Woody Vegetation'),
+                                'Herbaceous': (172, 188, 45, 255, 'Herbaceous\n Vegetation')},
+        'canopyco_veg_cat_l4d': {'> 65 %': (14,  121, 18,  255, '> 65 % cover'),
+                                '40 to 65 %': (45,  141, 47,  255, '40 to 65 % cover'),
+                                '15 to 40 %': (80,  160, 82,  255, '15 to 40 % cover'),
+                                '4 to 15 %': (117, 180, 118, 255, '4 to 15 % cover'),
+                                '1 to 4 %': (154, 199, 156, 255, '1 to 4 % cover')},
+        'watersea_veg_cat_l4a_au': {'(semi-) permenant': (25,  173, 109, 255, '> 3 months'),
+                                   '(temporary or seasonal)': (176, 218, 201, 255, '< 3 months')},
+        'waterstt_wat_cat_l4a': {'Water: (Water)': (77, 159, 220, 255, 'Water')},
+        'inttidal_wat_cat_l4a': {'Tidal area': (77, 159, 220, 255, 'Water: (Water) Tidal area')},
+        'waterper_wat_cat_l4d_au': {'> 9 months': (27,  85,  186, 255, '> 9 months'),
+                                   '7 to 9 months': (52,  121, 201, 255, '7 to 9 months'),
+                                   '4 to 6 months': (79,  157, 217, 255, '4 to 6 months'),
+                                   '1 to 3 months': (113, 202, 253, 255, '1 to 3 months')},
+        'baregrad_phy_cat_l4d_au': {'Sparsely vegetated': (255, 230, 140, 255, 'Sparsely vegetated\n (< 20% bare)'),
+                                   'Very sparesely': (250, 210, 110, 255, 'Very sparsely\n vegetated (20 to 60% bare)'),
+                                   'Bare areas': (243, 171, 105, 255, 'Bare areas,\n unvegetated (> 60% bare)')},
+
 }
 
 
+
+
+
+
+
 def get_layer_name(measurement, da):
     aliases = {
         'lifeform': 'lifeform_veg_cat_l4a',
@@ -287,6 +325,7 @@ def make_colorbar(fig, ax, measurement, horizontal=False, animation=False):
         Land cover measurement to use for colour map and labels. 
     
     """
+
     # Create new axis object for colorbar
     # parameters for add_axes are [left, bottom, width, height], in
     # fractions of total plot
@@ -298,12 +337,12 @@ def make_colorbar(fig, ax, measurement, horizontal=False, animation=False):
         orient = 'vertical'
         
             # get level 4 colour bar colour map ect
-        cb_cmap, cb_norm, cb_labels, cb_ticks = lc_colourmap('level4_colourbar_labels',
+        cb_cmap, cb_norm, cb_labels, cb_ticks = lc_colourmap_colourbar('level4_colourbar_labels',
                                                          colour_bar=True)
     elif measurement == 'level4' and animation == False:
         
         # get level 4 colour bar colour map ect
-        cb_cmap, cb_norm, cb_labels, cb_ticks = lc_colourmap('level4_colourbar_labels',
+        cb_cmap, cb_norm, cb_labels, cb_ticks = lc_colourmap_colourbar('level4_colourbar_labels',
                                                          colour_bar=True)
         #move plot over to make room for colourbar
         fig.subplots_adjust(right=0.825)
@@ -327,7 +366,7 @@ def make_colorbar(fig, ax, measurement, horizontal=False, animation=False):
             orient = 'vertical'
             
         # get measurement colour bar colour map ect
-        cb_cmap, cb_norm, cb_labels, cb_ticks = lc_colourmap(measurement,
+        cb_cmap, cb_norm, cb_labels, cb_ticks = lc_colourmap_colourbar(measurement,
                                                          colour_bar=True)
 
     img = ax.imshow([cb_ticks], cmap=cb_cmap, norm=cb_norm)
@@ -339,6 +378,59 @@ def make_colorbar(fig, ax, measurement, horizontal=False, animation=False):
 
 
 
+
+def descriptors_colours(lc_colours, lc_colours_mapping, descriptor):
+    """
+    Generates a sorted dictionary of colours based on a given descriptor.
+
+    This function takes in a dictionary of Land Cover classes, a mapping of descriptors to colours, 
+    and a specific descriptor. It returns a dictionary where the keys are sorted and the values are 
+    the corresponding colours and labels from the descriptor mapping.
+    
+    Parameters
+    ----------
+    lc_colours : dict
+        Dictionary containing colour schemes for all Land Cover classes. 
+        
+    lc_colours_mapping : dict
+        Dictionary mapping descriptors (e.g., lifeform) to their corresponding colours and labels.
+        
+    descriptor : str
+        The descriptor to be used for mapping colours.
+
+    Returns
+    -------
+    sorted_colours_dict : dict
+        Sorted dictionary with class values as keys and colour tuples as values.
+    """
+    
+    # get the level 4 colour scheme from the lc_colours dictionary
+    level4_colours = lc_colours['level4']
+
+    # get the descriptor dictionary from the lc_colours_mapping
+    descriptor_dict = lc_colours_mapping[descriptor]
+
+    # create a new colours dictionary with all level 4 values set to white colour
+    # based on the descriptor, the values of interest will be filled with the pre-defined colours (all the rest will stay white)
+    colours_dict = level4_colours.copy()
+    for key in colours_dict:
+       colours_dict[key] = (255, 255, 255, 255, "No Data")
+
+    # update the colours dictionary with the descriptor-specific colours
+    for class_keyword, colour_n_label in descriptor_dict.items():
+        
+        for class_value, lvl4_scheme in level4_colours.items(): 
+            label_lvl4 = lvl4_scheme[4]
+            
+            if class_keyword in label_lvl4:
+                colours_dict[class_value] = colour_n_label
+                
+    # sort the colours dictionary by keys
+    sorted_colours_dict = {key: colours_dict[key] for key in sorted(colours_dict.keys())}
+
+    return sorted_colours_dict
+               
+
 def lc_colourmap(colour_scheme, colour_bar=False):
     """
     Returns colour map and normalisation for the provided DEA Land Cover
@@ -371,6 +463,85 @@ def lc_colourmap(colour_scheme, colour_bar=False):
         in the chosen DEA Land Cover measurement.
     """
 
+
+    colour_scheme = colour_scheme.lower()
+
+    # if a descriptor colour scheme is required, use the descriptors_colours function
+    if colour_scheme in lc_colours_mapping:
+        lc_colour_scheme=descriptors_colours(lc_colours,lc_colours_mapping, colour_scheme)
+
+    else: # standard colours scheme
+        lc_colour_scheme = lc_colours[colour_scheme] 
+        # Ensure a valid colour scheme was requested
+        assert (colour_scheme in lc_colours.keys(
+                )), f'colour scheme must be one of [{lc_colours.keys()}] (got "{colour_scheme}")'
+
+
+    # Create colour map
+    colour_arr = []
+    for key, value in lc_colour_scheme.items():  
+        colour_arr.append(np.array(value[:-2]) / 255)
+        
+    cmap = mcolours.ListedColormap(colour_arr)
+    bounds = list(lc_colour_scheme)
+    
+    if colour_bar == True:
+        if colour_scheme == 'level4':
+            # Set colour labels to shortened level 4 list
+            lc_colour_scheme = lc_colours['level4_colourbar_labels']
+        cb_ticks = list(lc_colour_scheme)
+        #print(f'CB_TICKS {cb_ticks}')
+        cb_labels = []
+        for x in cb_ticks:
+            cb_labels.append(lc_colour_scheme[x][4])
+
+    bounds.append(bounds[-1]+1)
+
+    # shift all back by 0.5 to make sure level4 values are within bounds and not mathcing exactly one bound
+    bounds = [i-0.5 for i in bounds]
+    
+    norm = mcolours.BoundaryNorm(np.array(bounds), cmap.N)
+
+    if colour_bar == False:
+        return (cmap, norm)
+    else:
+        return (cmap, norm, cb_labels, cb_ticks)
+
+
+
+def lc_colourmap_colourbar(colour_scheme, colour_bar=False):
+    """
+    Returns colour map and normalisation for the provided DEA Land Cover
+    measurement, for use in plotting with Matplotlib library
+    
+    Parameters
+    ----------
+    colour_scheme : string
+        Name of land cover colour scheme to use
+        Valid options: 'level3', 'level4', 'lifeform_veg_cat_l4a', 
+        'canopyco_veg_cat_l4d', 'watersea_veg_cat_l4a_au',
+        'waterstt_wat_cat_l4a', 'inttidal_wat_cat_l4a', 
+        'waterper_wat_cat_l4d_au', 'baregrad_phy_cat_l4d_au'.
+    colour_bar : bool, optional
+        Controls if colour bar labels are returned as a list for 
+        plotting a colour bar. Default: False.
+        
+    Returns
+    ---------
+    cmap : matplotlib colormap
+        Matplotlib colormap containing the colour scheme for the
+        specified DEA Land Cover measurement.
+    norm : matplotlib colormap index
+        Matplotlib colormap index based on the discrete intervals of the
+        classes in the specified DEA Land Cover measurement. Ensures the
+        colormap maps the colours to the class numbers correctly.
+    cblables : array
+        A two dimentional array containing the numerical class values
+        (first dim) and string labels (second dim) of the classes found
+        in the chosen DEA Land Cover measurement.
+    """
+
+
     colour_scheme = colour_scheme.lower()
     # Ensure a valid colour scheme was requested
 #     try:
@@ -380,9 +551,9 @@ def lc_colourmap(colour_scheme, colour_bar=False):
 #     ('The dataset provided does not have a valid '
 #     'name. Please specify which DEA Landcover measurement is being plotted '
 #     'by providing the name using the "measurement" variable. For example (measurement = "full_classification")')
-
+        
     # Get colour definitions
-    lc_colour_scheme = lc_colours[colour_scheme]
+    lc_colour_scheme = lc_colours[colour_scheme]  
 
     # Create colour map
     colour_arr = []
@@ -397,6 +568,7 @@ def lc_colourmap(colour_scheme, colour_bar=False):
             # Set colour labels to shortened level 4 list
             lc_colour_scheme = lc_colours['level4_colourbar_labels']
         cb_ticks = list(lc_colour_scheme)
+        #print(f'CB_TICKS {cb_ticks}')
         cb_labels = []
         for x in cb_ticks:
             cb_labels.append(lc_colour_scheme[x][4])
@@ -410,6 +582,7 @@ def lc_colourmap(colour_scheme, colour_bar=False):
         return (cmap, norm, cb_labels, cb_ticks)
 
 
+
 def plot_land_cover(data, year=None, measurement=None, out_width=15, cols=4,):
     """
     Plot a single land cover measurement with appropriate colour scheme.
@@ -437,30 +610,33 @@ def plot_land_cover(data, year=None, measurement=None, out_width=15, cols=4,):
                        f'DataArray name {measurement}. Please specify which '
                        'DEA Landcover measurement is being plotted by providing'
                        'the name using the "measurement" variable For example'
-                       '(measurement = "full_classification")')
+                       '(measurement = "level4")')
 
     height, width = data.geobox.shape
     scale = out_width / width
 
     if year:
-        #plotting protocall if 'year' variable is passed
-        year_string = f"{year}-01-01"
-        data = data.sel(time=year_string, method="nearest")
+        #plotting protocol if 'year' variable is passed
+        if int(year) not in pd.to_datetime(data.time.values).year: # check if year selecte is in the datacube
+            raise ValueError(f'Year {year} is not in the data array.')
+        
+        year_string = f"{year}-07-01" # LC collection 3 dates are in July
+        data = data.sel(time=year_string, method='nearest')
         
         fig, ax = plt.subplots()
         fig.set_size_inches(width * scale, height * scale)
         make_colorbar(fig, ax, measurement)
-        im = ax.imshow(data, cmap=cmap, norm=norm, interpolation="nearest")
+        im = ax.imshow(data.values, cmap=cmap, norm=norm, interpolation="nearest")
 
     
     elif len(data.time) == 1:
-        #plotting protocall if only one timestep is passed and not a year variable
+        #plotting protocol if only one timestep is passed and not a year variable
         fig, ax = plt.subplots()
         fig.set_size_inches(width * scale, height * scale)
         make_colorbar(fig, ax, measurement)
         im = ax.imshow(data.isel(time=0), cmap=cmap, norm=norm, interpolation="nearest")
     else:
-        #plotting protocall if multible time steps are passed to plot
+        #plotting protocol if multible time steps are passed to plot
         if cols > len(data.time):
             cols = len(data.time)
         rows = int((len(data.time) + cols-1)/cols)
@@ -489,7 +665,8 @@ def lc_animation(
         width_pixels=10,
         dpi=150,
         font_size=15,
-        label_ax=True):
+        label_ax=True,
+):
     """
     Creates an animation of DEA Landcover though time beside 
     corresponding stacked plots of the landcover classes. Saves the
@@ -531,19 +708,21 @@ def lc_animation(
     label_ax : boolean, optional
         Determines if animation plot should have tick marks and numbers
         on axes. Also removes white space around plot. default: True
+
         
     Returns
     -------
     A GIF (.gif) animation file.
     """
 
-    def calc_class_ratio(da):
+    def calc_class_ratio(da, measurement):
         """
         Creates a table listing year by year what percentage of the
         total area is taken up by each class.
         Parameters
         ----------
         da : xarray.DataArray with time dimension
+        measurement: string with name of descriptor/measurement
         Returns
         -------
         Pandas Dataframe : containing class percentages per year
@@ -551,13 +730,24 @@ def lc_animation(
 
         # list all class codes in dataset
         list_classes = (np.unique(da, return_counts=False)).tolist()
-
+        
+        # if a descriptor colour scheme is required, list_classes need to be chnaged to contain only classes of that descriptor
+        # the following code uses the descriptors_colours function to get the colours scheme and then the values of the descriptor of interest
+        if measurement in lc_colours_mapping:
+            lc_colour_scheme=descriptors_colours(lc_colours,lc_colours_mapping, measurement)
+            # sort based on first RGB colour, so stack plot will show same colours next to each other
+            lc_colour_scheme= dict(sorted(lc_colour_scheme.items(), key=lambda item: item[1][0]))
+            # create list of values
+            all_classes_descriptor = list(lc_colour_scheme.keys())
+            # out of all possible classes of that descriptor, keep only the ones actually in the data array
+            list_classes = [i for i in all_classes_descriptor if i in list_classes] # the order of all_classes_descriptor and list_classes is important: the correct sorting order is the one of all_classes_descriptor
+            
         # create empty dataframe & dictionary
         ratio_table = pd.DataFrame(data=None, columns=list_classes)
         date_line = {}
 
         # count all pixels, should be consistent
-        total_pix = int(np.sum(da.isel(time=1)))
+        total_pix = da.isel(time=1).size
 
         # iterate through each year in dataset
         for i in range(0, len(da.time)):
@@ -572,7 +762,6 @@ def lc_animation(
 
             # add each year's counts to dataframe
             ratio_table.loc[date] = date_line
-
         return ratio_table
 
     def rgb_to_hex(r, g, b):
@@ -596,7 +785,7 @@ def lc_animation(
                    f'DataArray name {measurement}. Please specify which '
                    'DEA Landcover measurement is being plotted by providing '
                    'the name using the "measurement" variable For example '
-                   '(measurement = "full_classification")')
+                   '(measurement = "level4")')
     
     # Prepare variables needed
     # Get info on dataset dimensions
@@ -626,14 +815,16 @@ def lc_animation(
 
     if stacked_plot == True:
         
-
-
         # Create table for stacked plot
-        stacked_plot_table = calc_class_ratio(da)
+        stacked_plot_table = calc_class_ratio(da, measurement)
 
         # Build colour list of hex vals for stacked plot
         hex_colour_list = []
-        colour_def = lc_colours[measurement]
+
+        if measurement in lc_colours_mapping: # if descriptor
+            colour_def=descriptors_colours(lc_colours,lc_colours_mapping, measurement)
+        else:  # if level 3 or 4
+            colour_def = lc_colours[measurement]
 
         # Custom error message to help if user puts incorrect measurement name
         for val in list(stacked_plot_table):

{dea_tools-0.3.6.dev1 → dea_tools-0.3.6.dev31/dea_tools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: dea-tools
-Version: 0.3.6.dev1
+Version: 0.3.6.dev31
 Summary: Functions and algorithms for analysing Digital Earth Australia data.
 Home-page: https://github.com/GeoscienceAustralia/dea-notebooks
 Author: Geoscience Australia
@@ -44,7 +44,7 @@ Requires-Dist: pyproj
 Requires-Dist: pystac-client
 Requires-Dist: planetary-computer
 Requires-Dist: python-dateutil
-Requires-Dist: pyTMD<=2.1.6
+Requires-Dist: pyTMD!=2.1.7
 Requires-Dist: pytz
 Requires-Dist: rasterio
 Requires-Dist: rasterstats
@@ -65,6 +65,17 @@ Provides-Extra: dask-gateway
 Requires-Dist: dask_gateway; extra == "dask-gateway"
 Provides-Extra: otps
 Requires-Dist: otps; extra == "otps"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 
 dea-tools package

{dea_tools-0.3.6.dev1 → dea_tools-0.3.6.dev31}/dea_tools.egg-info/requires.txt

@@ -26,7 +26,7 @@ pyproj
 pystac-client
 planetary-computer
 python-dateutil
-pyTMD<=2.1.6
+pyTMD!=2.1.7
 pytz
 rasterio
 rasterstats

{dea_tools-0.3.6.dev1 → dea_tools-0.3.6.dev31}/setup.py

@@ -56,7 +56,7 @@ REQUIRED = [
     'pystac-client',
     'planetary-computer',
     'python-dateutil',
-    'pyTMD<=2.1.6',    
+    'pyTMD!=2.1.7',    
     'pytz',
     'rasterio',
     'rasterstats',