Merge branch 'dev' into fr/plotly-annotations

Author: rodriguesfred

release-please-config.json

@@ -4,16 +4,27 @@
 # Py-af-colours source: https://github.com/best-practice-and-impact/py-af-colours
 
 from pathlib import Path
+from typing import List, Literal
 
 import yaml
 
+ColourFormat = Literal["hex", "rgb"]
+PaletteName = Literal["duo", "focus", "categorical", "sequential"]
 
-def get_af_colours(palette: str, colour_format="hex", number_of_colours=6, config_path=None):
+
+def get_af_colours(
+    palette: PaletteName,
+    colour_format: ColourFormat = "hex",
+    number_of_colours: int | None = None,
+    config_path: str | Path | None = None,
+    include_grey: bool = False,
+) -> List:
     """
     get_af_colours() is the top level function in af_colours. This returns
     the chosen Analysis Function colour palette in hex or rgb format.
     For the categorical palette, this can be a chosen number of colours
-    up to 6.
+    up to 6. For the sequential palette, this can be a chosen number of colours of 3,
+    4, or 5.
 
     Parameters
     ----------
@@ -25,12 +36,17 @@ def get_af_colours(palette: str, colour_format="hex", number_of_colours=6, confi
         Colour format required, with accepted values of "hex" or "rgb".
 
     number_of_colours : int, optional
-        Number of colours required (categorical palette only). Takes
-        values between 2 and 6. Returns 2 colours by default. If a
-        palette other than categorical is chosen, any value passed
-        is ignored.
+        Number of colours required. For the sequential palette, takes
+        values 3, 4, or 5 (applying guidance-informed subsets). For categorical
+        palette, takes values between 2 and 6. The default is None, which uses the
+        default value for the chosen colour palette.
+        If palette is another type, this argument is ignored.
+
+    include_grey : bool, optional
+        Whether to include the grey colour in the sequential palette. Can be used to show
+        null values in charts. The default is False, which excludes the grey colour.
 
-    config_path : NoneType, optional
+    config_path : str | Path | None, optional
         Takes the default value None, inside the function this is
         mapped to the relative path independent of operating system.
         Should not require changing.
@@ -54,35 +70,44 @@ def get_af_colours(palette: str, colour_format="hex", number_of_colours=6, confi
     with open(config_path) as file:
         config = yaml.load(file, Loader=yaml.BaseLoader)
 
-    categorical_hex_list = config["categorical_hex_list"]
-    duo_hex_list = config["duo_hex_list"]
-    sequential_hex_list = config["sequential_hex_list"]
-    focus_hex_list = config["focus_hex_list"]
+    categorical_hex_list: List[str] = config["categorical_hex_list"]
+    duo_hex_list: List[str] = config["duo_hex_list"]
+    sequential_hex_list: List[str] = config["sequential_hex_list"]
+    focus_hex_list: List[str] = config["focus_hex_list"]
 
     if palette not in ["categorical", "duo", "sequential", "focus"]:
         raise ValueError("palette must be one of 'categorical', 'duo', 'sequential' " + f"or 'focus', not {palette}.")
+
     if colour_format not in ["hex", "rgb"]:
         raise ValueError(f"colour_format must be 'hex' or 'rgb', not {colour_format}.")
 
-    if number_of_colours < 1:
+    if number_of_colours is not None and number_of_colours < 1:
         raise ValueError("number_of_colours must be greater than 0.")
 
-    elif palette == "sequential":
-        chosen_colours_list = sequential_colours(sequential_hex_list, colour_format)
+    if palette == "sequential":
+        return sequential_colours(
+            sequential_hex_list,
+            colour_format=colour_format,
+            number_of_colours=number_of_colours or 5,
+            include_grey=include_grey,
+        )
 
-    elif palette == "focus":
-        chosen_colours_list = focus_colours(focus_hex_list, colour_format)
+    if palette == "focus":
+        return focus_colours(focus_hex_list, colour_format)
 
-    elif palette == "duo":
-        chosen_colours_list = duo_colours(duo_hex_list, colour_format)
+    if palette == "duo":
+        return duo_colours(duo_hex_list, colour_format)
 
-    elif palette == "categorical":
-        chosen_colours_list = categorical_colours(categorical_hex_list, duo_hex_list, colour_format, number_of_colours)
+    # palette == "categorical"
+    return categorical_colours(categorical_hex_list, duo_hex_list, colour_format, number_of_colours)
 
-    return chosen_colours_list
 
-
-def categorical_colours(categorical_hex_list, duo_hex_list, colour_format="hex", number_of_colours=2):
+def categorical_colours(
+    categorical_hex_list: List[str],
+    duo_hex_list: List[str],
+    colour_format: ColourFormat = "hex",
+    number_of_colours: int | None = 6,
+) -> List:
     """
     Return the Analysis Function categorical colour palette as a list
     in hex or rgb format for up to 6 colours. If number_of_colours is
@@ -102,7 +127,7 @@ def categorical_colours(categorical_hex_list, duo_hex_list, colour_format="hex",
 
     number_of_colours : int
         Number of colours required, with accepted values between 2 and 6
-        inclusive. Returns 2 colours if no value given.
+        inclusive. Returns 6 colours if no value given.
 
     Raises
     ------
@@ -115,15 +140,17 @@ def categorical_colours(categorical_hex_list, duo_hex_list, colour_format="hex",
         categorical_colours_list
 
     """
+    n = 6 if number_of_colours is None else number_of_colours
 
-    if number_of_colours > 6:
+    if n > 6:
         raise ValueError("number_of_colours must not be more than 6 for the categorical palette.")
+    if n < 2:
+        raise ValueError("number_of_colours must be at least 2 for the categorical palette.")
 
-    if number_of_colours == 2:
-        categorical_colours_list = duo_colours(duo_hex_list, colour_format)
-        return categorical_colours_list
+    if n == 2:
+        return duo_colours(duo_hex_list, colour_format)
 
-    elif colour_format == "hex":
+    if colour_format == "hex":
         full_categorical_colours_list = categorical_hex_list
 
     elif colour_format == "rgb":
@@ -132,16 +159,13 @@ def categorical_colours(categorical_hex_list, duo_hex_list, colour_format="hex",
     else:
         raise ValueError(f"colour_format must be 'hex' or 'rgb', not {colour_format}.")
 
-    categorical_colours_list = full_categorical_colours_list[0:number_of_colours]
+    return full_categorical_colours_list[0:n]
 
-    return categorical_colours_list
 
-
-def duo_colours(duo_hex_list, colour_format="hex"):
+def duo_colours(duo_hex_list: List[str], colour_format: ColourFormat = "hex") -> List:
     """
     Return the Analysis Function duo colour palette as a list of 2
-    colours in hex or rgb format. This function is also called by
-    sequential_colours() if number_of_colours is equal to 2.
+    colours in hex or rgb format.
 
     Parameters
     ----------
@@ -158,21 +182,24 @@ def duo_colours(duo_hex_list, colour_format="hex"):
         duo_colours_list
 
     """
-
     if colour_format == "hex":
-        duo_colours_list = duo_hex_list
+        return duo_hex_list
     elif colour_format == "rgb":
-        duo_colours_list = hex_to_rgb(duo_hex_list)
+        return hex_to_rgb(duo_hex_list)
     else:
         raise ValueError(f"colour_format must be 'hex' or 'rgb', not {colour_format}.")
 
-    return duo_colours_list
-
 
-def sequential_colours(sequential_hex_list, colour_format="hex"):
+def sequential_colours(
+    sequential_hex_list: List[str],
+    colour_format: ColourFormat = "hex",
+    number_of_colours: int = 5,
+    include_grey: bool = False,
+) -> List:
     """
     Return the Analysis Function sequential colour palette as a list
-    of 3 colours in hex or rgb format.
+    in hex or rgb format. Supports combinations of 3, 4, or 5 colours
+    based on Analysis Function guidance.
 
     Parameters
     ----------
@@ -182,24 +209,43 @@ def sequential_colours(sequential_hex_list, colour_format="hex"):
     colour_format : string
         Colour format required, with accepted values of "hex" or "rgb".
 
+    number_of_colours: int
+        Number of sequential colours required, with accepted values of 3,
+        4, or 5. Defaults to 5.
+
+    include_grey : bool, optional
+        Whether to include the grey colour in the palette. Can be used to show
+        null values in charts. The default is False, which excludes the grey colour.
+
     Returns
     -------
     list
         sequential_colours_list
 
     """
+    SEQUENTIAL_COMBOS = {
+        3: [sequential_hex_list[1], sequential_hex_list[2], sequential_hex_list[3]],
+        4: [sequential_hex_list[0], sequential_hex_list[1], sequential_hex_list[2], sequential_hex_list[3]],
+        5: sequential_hex_list[:5],
+    }
+
+    if number_of_colours not in [3, 4, 5]:
+        raise ValueError("number_of_colours must be 3, 4, or 5 for the sequential palette.")
+
+    if include_grey:
+        colours = SEQUENTIAL_COMBOS[number_of_colours] + [sequential_hex_list[-1]]
+    else:
+        colours = SEQUENTIAL_COMBOS[number_of_colours]
 
     if colour_format == "hex":
-        sequential_colours_list = sequential_hex_list
+        return colours
     elif colour_format == "rgb":
-        sequential_colours_list = hex_to_rgb(sequential_hex_list)
+        return hex_to_rgb(colours)
     else:
         raise ValueError(f"colour_format must be 'hex' or 'rgb', not {colour_format}.")
 
-    return sequential_colours_list
-
 
-def focus_colours(focus_hex_list, colour_format="hex"):
+def focus_colours(focus_hex_list: List[str], colour_format: ColourFormat = "hex") -> List:
     """
     Return the Analysis Function focus colour palette as a list of 2
     colours in hex or rgb format.
@@ -220,16 +266,14 @@ def focus_colours(focus_hex_list, colour_format="hex"):
     """
 
     if colour_format == "hex":
-        focus_colours_list = focus_hex_list
+        return focus_hex_list
     elif colour_format == "rgb":
-        focus_colours_list = hex_to_rgb(focus_hex_list)
+        return hex_to_rgb(focus_hex_list)
     else:
         raise ValueError(f"colour_format must be 'hex' or 'rgb', not {colour_format}.")
 
-    return focus_colours_list
 
-
-def hex_to_rgb(hex_colours):
+def hex_to_rgb(hex_colours: List[str]) -> List:
     """
     Convert a list of hex codes to a list of rgb colours.
 
@@ -247,13 +291,17 @@ def hex_to_rgb(hex_colours):
     Returns
     -------
     list
-        converted_list
+        rgb_list
 
     """
     if type(hex_colours) is not list:
         raise TypeError("hex_colours must be a list.")
 
+    for value in hex_colours:
+        if not isinstance(value, str):
+            raise TypeError("hex_colours must be a list of hex strings.")
+
     hex_colours_new = [i.lstrip("#") for i in hex_colours]
 
-    converted_list = [(tuple(int(value[i : i + 2], 16) for i in (0, 2, 4))) for value in hex_colours_new]
-    return converted_list
+    rgb_list = [(tuple(int(value[i : i + 2], 16) for i in (0, 2, 4))) for value in hex_colours_new]
+    return rgb_list

src/afcharts/af_colours.py

@@ -38,5 +38,3 @@ ytick.direction : out
 # LEGEND
 legend.frameon : False
 
-# FIGURE OUTPUT 
-figure.figsize : 6.4, 4.8

src/afcharts/afcharts.mplstyle

@@ -1,4 +1,4 @@
 categorical_hex_list: ["#12436D","#28A197","#801650", "#F46A25","#3D3D3D","#A285D1"]
 duo_hex_list: ["#12436D","#F46A25"]
-sequential_hex_list: ["#12436D", "#2073BC", "#6BACE6"]
+sequential_hex_list: ["#092135", "#12436D", "#2073BC", "#6BACE6", "#ADD1F1", "#F2F2F2"]
 focus_hex_list: ["#12436D","#BFBFBF"]

src/afcharts/config/af_colours.yaml

@@ -748,6 +748,12 @@ fig
 This line chart uses the afcharts theme. There are pale grey grid lines extending from the y axis, and there is a thicker dark blue line representing the data. A dotted horizontal line has been added at 70 years of age, with an annotation to label it.
 </div>
 
+### Saving figures
+
+The afcharts style uses a larger base font size (14pt vs Matplotlib's default 10pt) for accessibility. The `figure.figsize` parameter is intentionally not set in the style sheet — the default canvas remains 6.4 × 4.8 inches.
+
+By default, `savefig` saves at exactly `figure.figsize`. If you pass `bbox_inches='tight'`, the output is cropped to the bounding box of all content, so dimensions will vary between charts. Avoid this if you need a consistent, fixed output size.
+
 ### Wrapping text
 
 If text is too long, it may be cut off or distort the dimensions of the chart. To avoid this, text can be wrapped to multiple lines using the `textwrap` module. The width argument controls how many characters are allowed on each line before wrapping. See the figure title below for an example.

src/afcharts/cookbook/01-matplotlib-usage.qmd

@@ -24,7 +24,7 @@ get_af_colours("duo")
 
 ### Number of colours
 
-By default, `get_af_colours()` will return all colours in the given palette. For the categorical palette, the number of colours returned can be set with the `number_of_colours` argument.
+By default, `get_af_colours()` will return all core colours in the given palette with grey as an optional addition. For the categorical and sequential palettes, the number of colours returned can be set with the `number_of_colours` argument.
 
 For example, to return four colours from the categorical palette as hex codes:
 ```{python}
@@ -40,7 +40,7 @@ For example, to return the sequential colour palette as a list of rgb code tuple
 ```{python}
 #| eval: false
 get_af_colours("sequential", colour_format="rgb")                      
-# [(18, 67, 109), (32, 115, 188), (107, 172, 230)]
+# [(9, 33, 53), (18, 67, 109), (32, 115, 188), (107, 172, 230), (173, 209, 241)]
 ```
 
 
@@ -57,7 +57,7 @@ from afcharts.af_colours import get_af_colours
 
 cat = get_af_colours("categorical")
 duo = get_af_colours("duo")
-sequential = get_af_colours("sequential")
+sequential = get_af_colours("sequential", include_grey=True)
 focus = get_af_colours("focus")
 ```
 
@@ -103,6 +103,8 @@ display(HTML(df.to_html(escape=False, index=False)))
 ### Sequential palette
 The `sequential` colour palette should be used for data where the order has some meaning, such as age groups.
 
+The pale grey colour should be used for cases when, for example, you have no data or have suppressed the value. By default, the sequential palette returned by `get_af_colours()` does not include the pale grey. To include it, set `include_grey=True`.
+
 ```{python}
 #| echo: false
 

src/afcharts/cookbook/04-colour-palettes.qmd

@@ -18,8 +18,7 @@
 @pytest.mark.parametrize(
     "palette, colour_format, number_of_colours",
     [
-        # Test categorical palette for length boundaries (1–6 supported values)
-        ("categorical", "hex", 1),
+        # Test categorical palette for length boundaries (2–6 supported values)
         ("categorical", "hex", 2),
         ("categorical", "hex", 3),
         ("categorical", "hex", 4),
@@ -38,3 +37,11 @@ def test_categorical_list_length(palette, colour_format, number_of_colours):
     assert len(result) == number_of_colours, (
         f"Expected {number_of_colours} colours but got {len(result)} for palette='{palette}', format='{colour_format}'"
     )
+
+
+def test_categorical_minimum_colours_value():
+    """
+    Verify requesting 1 colour from the categorical palette triggers a ValueError.
+    """
+    with pytest.raises(ValueError):
+        get_af_colours("categorical", "hex", 1)