gov-uk-dashboards 21.2.2__py3-none-any.whl → 26.26.0__py3-none-any.whl

gov_uk_dashboards/components/plotly/time_series_chart.py

@@ -63,6 +63,9 @@ class TimeSeriesChart:
         hover_data: HoverDataByTrace,
         filtered_df: pl.DataFrame,
         trace_name_list: list[str],
+        dashed_trace_name_list: list[str] = None,
+        trace_colour_groups: list[str, str] = None,
+        initially_hidden_traces: Optional[list[str]] = None,
         hover_data_for_traces_with_different_hover_for_last_point: Optional[
             HoverDataByTrace
         ] = None,
@@ -79,11 +82,15 @@ class TimeSeriesChart:
         x_axis_title: Optional[str] = None,
         download_chart_button_id: Optional[str] = None,
         download_data_button_id: Optional[str] = None,
+        download_all_data_button_id: Optional[str] = None,
+        alternative_data_button_text: Optional[str] = None,
+        alternative_all_data_button_text: Optional[str] = None,
         number_of_traces_colour_shift_dict: Optional[dict] = None,
         additional_line: Optional[dict] = None,
         hover_distance: Optional[int] = 1,
         footnote: Optional[str] = None,
-    ):
+        stacked: Optional[bool] = False,
+    ):  # pylint: disable=duplicate-code
         self.title_data = title_data
         self.y_axis_column = y_axis_column
         self.hover_data = hover_data
@@ -92,6 +99,9 @@ class TimeSeriesChart:
         )
         self.filtered_df = filtered_df
         self.trace_name_list = trace_name_list
+        self.dashed_trace_name_list = dashed_trace_name_list
+        self.trace_colour_groups = trace_colour_groups
+        self.initially_hidden_traces = initially_hidden_traces
         self.legend_dict = legend_dict
         self.trace_name_column = trace_name_column
         self.xaxis_tick_text_format = xaxis_tick_text_format
@@ -107,6 +117,9 @@ class TimeSeriesChart:
         self.x_axis_title = x_axis_title
         self.download_chart_button_id = download_chart_button_id
         self.download_data_button_id = download_data_button_id
+        self.download_all_data_button_id = download_all_data_button_id
+        self.alternative_data_button_text = alternative_data_button_text
+        self.alternative_all_data_button_text = alternative_all_data_button_text
         self.markers = [
             "square",
             "diamond",
@@ -118,6 +131,7 @@ class TimeSeriesChart:
         self.number_of_traces_colour_shift_dict = number_of_traces_colour_shift_dict
         self.additional_line = additional_line
         self.hover_distance = hover_distance
+        self.stacked = stacked
         self.colour_list = self._get_colour_list()
         self.fig = self.create_time_series_chart()
         self.footnote = footnote
@@ -139,7 +153,10 @@ class TimeSeriesChart:
             self.title_data[SUBTITLE],
             self.download_chart_button_id,
             self.download_data_button_id,
-            self.footnote,
+            download_all_data_button_id=self.download_all_data_button_id,
+            alternative_data_button_text=self.alternative_data_button_text,
+            alternative_all_data_button_text=self.alternative_all_data_button_text,
+            footnote=self.footnote,
         )
 
     def is_json_serializable(self, value):
@@ -220,7 +237,12 @@ class TimeSeriesChart:
             )
             fig.add_trace(trace_connector)
         # pylint: disable=unused-variable
-        for i, (df, trace_name, colour, marker,) in enumerate(
+        for i, (
+            df,
+            trace_name,
+            colour,
+            marker,
+        ) in enumerate(
             zip(
                 self._get_df_list_for_time_series(),
                 self.trace_name_list,
@@ -231,15 +253,20 @@ class TimeSeriesChart:
             if REMOVE_INITIAL_MARKER in df.columns and True in df.get_column(
                 REMOVE_INITIAL_MARKER
             ):
-                marker_sizes = [0] + [12] * (len(df.with_row_count()) - 1)
+                marker_sizes = [0] + [12] * (len(df.with_row_index()) - 1)
             else:
-                marker_sizes = [12] * (len(df.with_row_count()))
+                marker_sizes = [12] * (len(df.with_row_index()))
             legendgroup = self._get_legend_group(df)
             fig.add_trace(
                 self.create_time_series_trace(
                     df.sort(self.x_axis_column),
                     trace_name,
-                    line_style={"dash": "solid", "color": colour},
+                    line_style=(
+                        {"dash": "dot", "color": colour}
+                        if self.dashed_trace_name_list is not None
+                        and trace_name in self.dashed_trace_name_list
+                        else {"dash": "solid", "color": colour}
+                    ),
                     marker={"symbol": marker, "size": marker_sizes, "opacity": 1},
                     legendgroup=legendgroup,
                 ),
@@ -401,6 +428,14 @@ class TimeSeriesChart:
             marker (dict[str,str]): Properties for marker parameter.
             legendgroup (str): Name to group by in legend,
         """
+        if (
+            self.initially_hidden_traces is not None
+            and trace_name in self.initially_hidden_traces
+        ):
+            visible = "legendonly"
+        else:
+            visible = True
+
         return go.Scatter(
             x=df[self.x_axis_column],
             y=df[self.y_axis_column],
@@ -414,6 +449,8 @@ class TimeSeriesChart:
                 trace_name in self.legend_dict if self.legend_dict is not None else True
             ),
             legendgroup=legendgroup,
+            stackgroup="one" if self.stacked else None,
+            visible=visible,
         )
 
     def _get_hover_template(self, df, trace_name):
@@ -486,6 +523,7 @@ class TimeSeriesChart:
             return self.legend_dict[trace_name]
         return trace_name
 
+    # pylint: disable=too-many-statements
     def _get_x_axis_content(self):
         """Generates tick text and values for the x-axis based on the unique years calculated from
         the DATE_VALID column in the dataframe.
@@ -585,6 +623,30 @@ class TimeSeriesChart:
             ]
 
             range_x = [0.5, 4.5]
+        elif self.xaxis_tick_text_format == XAxisFormat.WEEK.value:
+            df = self.filtered_df.with_columns(
+                pl.col(self.x_axis_column)
+                .str.strptime(pl.Datetime, "%Y-%m-%d", strict=False)
+                .alias(self.x_axis_column)
+            ).sort(self.x_axis_column)
+
+            start_datetime = df[self.x_axis_column].min() - relativedelta(weeks=1)
+            latest_datetime = df[self.x_axis_column].max() + relativedelta(weeks=1)
+
+            start_of_week = start_datetime - relativedelta(
+                days=start_datetime.weekday()
+            )
+
+            tick_values = []
+            tick_text = []
+
+            current = start_of_week
+            while current <= latest_datetime:
+                tick_values.append(current)
+                tick_text.append(current.strftime("%d %b %Y"))  # e.g. "29 Sep 2025"
+                current += relativedelta(weeks=1)
+
+            range_x = [start_datetime, latest_datetime]
         else:
             raise ValueError(
                 f"Invalid xaxis_tick_text_format: {self.xaxis_tick_text_format}"
@@ -594,9 +656,16 @@ class TimeSeriesChart:
     def _get_y_axis_range_max(self):
         """Get the y axis range maximum value to ensure there is an axis label greater than the
         maximum y value."""
-        largest_number_of_weeks = self.filtered_df[self.y_axis_column].max()
-
-        y_axis_max = largest_number_of_weeks + (0.3 * largest_number_of_weeks)
+        if self.stacked:
+            largest_y_value = (
+                self.filtered_df.group_by(self.x_axis_column)  # group by date
+                .agg(pl.col(self.y_axis_column).sum())  # total per date
+                .select(pl.col(self.y_axis_column).max())  # largest daily total
+                .item()  # extract scalar
+            )
+        else:
+            largest_y_value = self.filtered_df[self.y_axis_column].max()
+        y_axis_max = largest_y_value + (0.3 * largest_y_value)
         return y_axis_max
 
     def _get_df_list_for_time_series(self) -> list[pl.DataFrame]:
@@ -610,27 +679,97 @@ class TimeSeriesChart:
         return df_list
 
     def _get_colour_list(self):
-        """Returns a list of colours."""
+        """Returns a list of colours (one per trace in trace_name_list).
+
+        If `trace_colour_groups` is provided, traces in the same group share a colour.
+        Traces not in any group get their own colour from the palette.
+        """
+        palette = self._get_base_palette()
+        palette = self._apply_colour_shift(palette)
+
+        groups = getattr(self, "trace_colour_groups", None) or []
+        if not groups:
+            return palette[: len(self.trace_name_list)]
+
+        trace_to_group_id = self._build_trace_to_group_id(groups)
+        return self._assign_colours_with_groups(palette, trace_to_group_id)
+
+    def _get_base_palette(self) -> list[str]:
         number_of_traces = len(self.trace_name_list)
         if number_of_traces == 2 and self.filled_traces_dict is None:
-            colour_list = [
+            return [
                 AFAccessibleColours.DARK_BLUE.value,
                 AFAccessibleColours.ORANGE.value,
-            ]  # if 2 lines should use dark blue & orange as have highest contrast ratio
-        else:
-            colour_list = AFAccessibleColours.CATEGORICAL.value.copy()
+            ]
+        return AFAccessibleColours.CATEGORICAL.value.copy()
+
+    def _apply_colour_shift(self, palette: list[str]) -> list[str]:
+        """Apply number_of_traces_colour_shift_dict; may replace palette with explicit list."""
+        number_of_traces = len(self.trace_name_list)
         colour_shift_dict = (
             {"default": 0}
             if self.number_of_traces_colour_shift_dict is None
             else self.number_of_traces_colour_shift_dict
         )
-
         colour_shift_value = colour_shift_dict.get(
             number_of_traces, colour_shift_dict["default"]
         )
+
         if isinstance(colour_shift_value, list):
-            return colour_shift_value  # list of colours
-        while colour_shift_value > 0:
-            colour_list.append(colour_list.pop(0))
-            colour_shift_value -= 1
-        return colour_list
+            return colour_shift_value
+
+        # rotate left by colour_shift_value
+        shift = int(colour_shift_value)
+        if shift <= 0:
+            return palette
+
+        shift = shift % len(palette)
+        return palette[shift:] + palette[:shift]
+
+    def _build_trace_to_group_id(self, groups: list[list[str]]) -> dict[str, int]:
+        """Validate groups and return a mapping of trace -> group_id."""
+        trace_set = set(self.trace_name_list)
+        trace_to_group_id: dict[str, int] = {}
+
+        for group_id, group in enumerate(groups):
+            for trace in group:
+                if trace not in trace_set:
+                    raise ValueError(
+                        f"trace_colour_groups contains '{trace}', but it's not in trace_name_list."
+                    )
+                if trace in trace_to_group_id:
+                    raise ValueError(
+                        f"Trace '{trace}' appears in more than one trace_colour_group."
+                    )
+                trace_to_group_id[trace] = group_id
+
+        return trace_to_group_id
+
+    def _assign_colours_with_groups(
+        self,
+        palette: list[str],
+        trace_to_group_id: dict[str, int],
+    ) -> list[str]:
+        """Assign one colour per group (first-seen), and one per ungrouped trace."""
+        group_colour: dict[int, str] = {}
+        trace_colour: dict[str, str] = {}
+        colour_idx = 0
+
+        # assign colours to groups in order of first appearance in trace_name_list
+        for trace in self.trace_name_list:
+            group_id = trace_to_group_id.get(trace)
+            if group_id is not None and group_id not in group_colour:
+                group_colour[group_id] = palette[colour_idx % len(palette)]
+                colour_idx += 1
+
+        # apply group colours to grouped traces
+        for trace, group_id in trace_to_group_id.items():
+            trace_colour[trace] = group_colour[group_id]
+
+        # assign colours to ungrouped traces
+        for trace in self.trace_name_list:
+            if trace not in trace_colour:
+                trace_colour[trace] = palette[colour_idx % len(palette)]
+                colour_idx += 1
+
+        return [trace_colour[t] for t in self.trace_name_list]

gov_uk_dashboards/constants.py

@@ -17,10 +17,44 @@ YEAR = "Year"
 UNIT_SIZE = "Unit size"
 DEFAULT_COLOURSCALE = "tealgrn"
 
-LEGEND_SPACING = "\u00A0" * 5
+LEGEND_SPACING = "\u00a0" * 5
 
 DOWNLOAD_BUTTON_CLASSES = (
     "govuk-button govuk-button--primary "
     "govuk-!-margin-bottom-0 govuk-!-margin-top-4 "
     "flex w-auto items-center gap-2 print:hidden"
 )
+
+PERCENTAGE_CHANGE_FROM_PREV_YEAR = "Percentage change from prev year"
+PERCENTAGE_CHANGE_FROM_TWO_PREV_YEAR = "Percentage change from two prev year"
+TWENTY_NINETEEN_VALUE = "twenty_nineteen_value"
+
+LARGE_BOLD_FONT_STYLE = {"fontSize": "300%"}
+CHANGED_FROM_GAP_STYLE = {"marginTop": "20px"}
+
+PERIOD_END = "period_end"
+YEAR_END = "year_end"
+METRIC_VALUE = "metric_value"
+LATEST_YEAR = "latest_year"
+PREVIOUS_YEAR = "previous_year"
+PREVIOUS_2YEAR = "previous_2year"
+TWENTY_NINETEEN = "twenty_nineteen"
+
+NOTIFICATION_STYLE_RED = {"borderColor": "#d4351c", "backgroundColor": "#d4351c"}
+NOTIFICATION_STYLE_ORANGE = {"borderColor": "#f47738", "backgroundColor": "#f47738"}
+NOTIFICATION_STYLE_YELLOW = {"borderColor": "#ffdd00", "backgroundColor": "#ffdd00"}
+NOTIFICATION_STYLE_GREEN = {"borderColor": "#00703c", "backgroundColor": "#00703c"}
+
+BANNER_STYLE = {
+    "display": "flex",
+    "visibility": "visible",
+    "margin": "-10px -15px 0px -15px",
+}
+
+ERROR_MESSAGE_BANNER_STYLE = {
+    "width": "100%",
+    "paddingLeft": "30px",
+    "paddingRight": "30px",
+    "justifyContent": "left",
+    "backgroundColor": "#FFDD00",
+}

gov_uk_dashboards/figures/__init__.py

@@ -11,7 +11,9 @@ Contains:
     - LineStyle: Dataclass containing information on how to style a line on a line
         chart.
 """
+
 from . import enums
 from . import styles
-from .chart_data import ChartData
-from .line_chart import line_chart
+
+# from .chart_data import ChartData
+# from .line_chart import line_chart

gov_uk_dashboards/figures/enums/__init__.py

@@ -3,4 +3,5 @@
 Contains:
 - DashPatterns: Sets out valid dash patterns used by plotly/plotly express.
 """
+
 from .dash_patterns import DashPatterns

gov_uk_dashboards/figures/enums/dash_patterns.py

@@ -1,4 +1,5 @@
 """DashPatterns enum"""
+
 from enum import Enum
 
 

gov_uk_dashboards/figures/line_chart.py

@@ -1,80 +1,80 @@
-"""Line chart function"""
-from typing import Optional
-import plotly.express as px
-from gov_uk_dashboards.axes import calc_axis_range
-from gov_uk_dashboards.colours import ONSAccessibleColours
-from .styles import LineStyle
-from .chart_data import ChartData
+# """Line chart function"""
+# from typing import Optional
+# import plotly.express as px
+# from gov_uk_dashboards.axes import calc_axis_range
+# from gov_uk_dashboards.colours import ONSAccessibleColours
+# from .styles import LineStyle
+# from .chart_data import ChartData
 
 
-def line_chart(
-    data: ChartData,
-    title: str,
-    markers: bool = False,
-    line_styles: Optional[dict[str, LineStyle]] = None,
-    **px_line_kwargs,
-):
-    """
-    Create and return a plotly express line chart with standard formatting.
+# def line_chart(
+#     data: ChartData,
+#     title: str,
+#     markers: bool = False,
+#     line_styles: Optional[dict[str, LineStyle]] = None,
+#     **px_line_kwargs,
+# ):
+#     """
+#     Create and return a plotly express line chart with standard formatting.
 
-    Dataframe should be sorted so x axis is in the correct order for plotting.
+#     Dataframe should be sorted so x axis is in the correct order for plotting.
 
-    If no style information provided, lines will be plotted as solid lines
-    using the ONSAcessibleColours enum for their colours.
+#     If no style information provided, lines will be plotted as solid lines
+#     using the ONSAcessibleColours enum for their colours.
 
-    Args:
-        data (ChartData): Data for the chart.
-        title (str): Title to be shown above the chart.
-        markers (bool, optional): Whether markers should be plotted for each point.
-            Defaults to False.
-        line_styles (dict[str, LineStyle], optional): A dictionary with keys that match
-            the categories in the category column (if supplied), and values that are
-            LineStyle data objects to set out the style of the corresponding line.
-            Defaults to None.
-        **px_line_kwargs: Any other keyword arguments to pass to the plotly express
-            line graph function.
+#     Args:
+#         data (ChartData): Data for the chart.
+#         title (str): Title to be shown above the chart.
+#         markers (bool, optional): Whether markers should be plotted for each point.
+#             Defaults to False.
+#         line_styles (dict[str, LineStyle], optional): A dictionary with keys that match
+#             the categories in the category column (if supplied), and values that are
+#             LineStyle data objects to set out the style of the corresponding line.
+#             Defaults to None.
+#         **px_line_kwargs: Any other keyword arguments to pass to the plotly express
+#             line graph function.
 
-    Returns:
-        plotly.Figure: The generated line chart figure object.
-    """
-    color_discrete_map = None
-    line_dash_map = None
-    labels = None
-    if line_styles:
-        color_discrete_map = {
-            category: line_style.color for category, line_style in line_styles.items()
-        }
-        line_dash_map = {
-            category: line_style.dash_pattern
-            for category, line_style in line_styles.items()
-        }
-        # If line dashes are set, plotly express automatically appends the name of the dash style
-        # to the label in the legend/hover data.
-        # As this is normally not desired, labels are set manually to override this.
-        labels = {category: category for category in line_styles}
+#     Returns:
+#         plotly.Figure: The generated line chart figure object.
+#     """
+#     color_discrete_map = None
+#     line_dash_map = None
+#     labels = None
+#     if line_styles:
+#         color_discrete_map = {
+#             category: line_style.color for category, line_style in line_styles.items()
+#         }
+#         line_dash_map = {
+#             category: line_style.dash_pattern
+#             for category, line_style in line_styles.items()
+#         }
+#         # If line dashes are set, plotly express automatically appends the name of the dash style
+#         # to the label in the legend/hover data.
+#         # As this is normally not desired, labels are set manually to override this.
+#         labels = {category: category for category in line_styles}
 
-    linechart = px.line(
-        data.dataframe,
-        x=data.x_column,
-        y=data.y_column,
-        range_y=calc_axis_range(data.dataframe, data.y_column),
-        color_discrete_map=color_discrete_map,
-        line_dash_map=line_dash_map,
-        line_dash=data.category_column,
-        color=data.category_column,
-        labels=labels,
-        markers=markers,
-        color_discrete_sequence=[colour.value for colour in ONSAccessibleColours]
-        if not line_styles
-        else None,
-        **px_line_kwargs,
-    )
+#     linechart = px.line(
+#         data.dataframe,
+#         x=data.x_column,
+#         y=data.y_column,
+#         range_y=calc_axis_range(data.dataframe, data.y_column),
+#         color_discrete_map=color_discrete_map,
+#         line_dash_map=line_dash_map,
+#         line_dash=data.category_column,
+#         color=data.category_column,
+#         labels=labels,
+#         markers=markers,
+#         color_discrete_sequence=[colour.value for colour in ONSAccessibleColours]
+#         if not line_styles
+#         else None,
+#         **px_line_kwargs,
+#     )
 
-    linechart.update_layout(
-        title=title,
-        paper_bgcolor="rgba(0,0,0,0)",
-        plot_bgcolor="rgba(0,0,0,0)",
-        xaxis_type="category",
-    )
+#     linechart.update_layout(
+#         title=title,
+#         paper_bgcolor="rgba(0,0,0,0)",
+#         plot_bgcolor="rgba(0,0,0,0)",
+#         xaxis_type="category",
+#     )
 
-    return linechart
+#     return linechart

gov_uk_dashboards/figures/styles/__init__.py

@@ -4,4 +4,5 @@ Contains:
 - LineStyle: Dataclass containing information on how to style a line on a line
     chart.
 """
+
 from .line_style import LineStyle

gov_uk_dashboards/figures/styles/line_style.py

@@ -1,4 +1,5 @@
 """LineStyle dataclass"""
+
 from dataclasses import dataclass
 from typing import Union
 from ..enums.dash_patterns import DashPatterns

gov_uk_dashboards/formatting/human_readable.py

@@ -1,4 +1,5 @@
 """Functions for converting values to human readable format."""
+
 import math
 from typing import Optional
 

gov_uk_dashboards/formatting/number_formatting.py

@@ -22,3 +22,17 @@ def format_number_into_thousands_or_millions(
     else:
         formatted_number = str(number)
     return formatted_number
+
+
+def add_commas(number: int, remove_decimal_places: bool = False) -> str:
+    """Formats large numbers with a string"""
+    if remove_decimal_places:
+        return f"{number:,.0f}"
+    return f"{number:,}"
+
+
+def format_percentage(percentage):
+    """Formats percentages to remove decimal place on numbers 10 or more"""
+    if abs(percentage) < 10:
+        return percentage
+    return int(percentage)

gov_uk_dashboards/formatting/round_and_add_prefix_and_suffix.py

@@ -2,6 +2,7 @@
 Function to add a prefix and suffix to a number and also show the number of decimal places
 specified.
 """
+
 import math
 import decimal
 

gov_uk_dashboards/formatting/text_functions.py

@@ -0,0 +1,11 @@
+"""Functions to format text"""
+
+import re
+
+
+def create_id_from_string(string):
+    """Function to create an id from a string. Remove non alphanumeric characters and replaces
+    spaces with dashes"""
+    if string is None:
+        return ""
+    return re.sub(r"[^a-z0-9]+", "-", string.lower()).strip("-")

gov_uk_dashboards/lib/dap/dap_deployment.py

@@ -2,6 +2,7 @@
 Scripts for deploying dashboard code to the DLUHC DAP Hosting Area.
 The DAP Hosting area is maintained by the DLUHC DAP Support team.
 """
+
 import subprocess
 import tempfile