flextool 4.0.0__py3-none-any.whl

flextool/plot_outputs/config.py

@@ -0,0 +1,171 @@
+from dataclasses import dataclass, field
+
+# Dimension rule characters come from templates/default_plots.yaml and must remain unchanged.
+# This dict documents their meaning for readability in code (e.g. DIMENSION_RULES['t'] → 'time axis (x)').
+DIMENSION_RULES: dict[str, str] = {
+    't': 'time axis (x, datetime)',
+    'i': 'time-like axis (x, chunk-average)',
+    'b': 'bar/line column stack',
+    'e': 'expand (separate y-axes)',
+    'g': 'group (grouped bars)',
+    's': 'stack (stacked segments)',
+    'u': 'subplot (separate plot panel)',
+    'l': 'line series',
+    'f': 'file (separate file per member)',
+    'm': 'merge (sum and collapse)',
+    'a': 'average and collapse',
+    'y': 'weight by years_represented, then sum and collapse (period row only)',
+    'z': 'years_represented weighted average and collapse (period row only)',
+}
+
+# Field names for plot settings — used by _is_single_config() to detect config dicts.
+PLOT_FIELD_NAMES = {
+    'plot_name', 'map_dimensions_for_plots', 'subplots_per_row', 'legend',
+    'bar_orientation', 'base_length', 'max_subplots_per_file', 'max_items_per_plot',
+    'max_items_per_subplot_column',
+    'time_average_duration', 'xlabel', 'ylabel', 'value_label', 'axis_bounds',
+    'axis_scale_min_max',  # backward compat alias for axis_bounds
+    'axis_tick_format', 'always_include_zero_in_axis', 'skip_data_with_only_zeroes',
+    'multiply_by', 'full_timeline', 'subplots_by_magnitudes',
+    'variant',  # used by plot_config_reader to override variant letter derivation
+    'color_category', 'color_entity_class',  # color-template hints (chunk D)
+    'scenario_rule', 'comparison_overrides',  # comparison-mode add-ons
+}
+
+
+@dataclass
+class PlotConfig:
+    """Typed, default-carrying wrapper for a single plot's settings dict.
+
+    Callers that pass raw dicts (e.g. scenario_results.py) need no change:
+    ``PlotConfig(**raw_dict)`` works as long as the dict only contains known fields.
+    """
+    plot_name: str = ''
+    map_dimensions_for_plots: dict = field(default_factory=dict)
+    subplots_per_row: int = 2
+    legend: str = 'right'  # 'right', 'all', or 'shared'
+    bar_orientation: str = 'horizontal'
+    base_length: float = 4.0
+    max_subplots_per_file: int = 6
+    max_items_per_plot: int = 10
+    max_items_per_subplot_column: int = 40
+    time_average_duration: str | None = None
+    xlabel: str | None = None
+    ylabel: str | None = None
+    value_label: str | None = None
+    axis_bounds: dict | list | str | None = None
+    axis_tick_format: str = 'dynamic'
+    always_include_zero_in_axis: bool = True
+    skip_data_with_only_zeroes: bool = False
+    multiply_by: float | None = None
+    full_timeline: bool = False
+    subplots_by_magnitudes: bool = False
+    # Hints for the color-template resolver (see flextool.plot_outputs.color_template).
+    # Default None means "no hint" — fall back to the tab10/tab20 palette as today.
+    color_category: str | None = None
+    color_entity_class: str | None = None
+
+    # --- Comparison-mode add-ons ---
+    # The unioned plan parquet at comparison-view time has the post-single-rules
+    # shape with `scenario` prepended as the outermost column-MultiIndex level.
+    # `scenario_rule` is the dim-rule character applied to that scenario level
+    # when building the comparison PlotPlan (see
+    # flextool.scenario_comparison.plan_union.compute_comparison_plan_from_single).
+    # Common choices: 'g' (grouped/coloured bars), 'l' (line series), 'u'
+    # (subplot per scenario), 'f' (file per scenario), 's' (stack — rare).
+    # When None, the config has no comparison rendering — comparison view
+    # surfaces "no comparison rule defined" for this plot.
+    scenario_rule: str | None = None
+    # Optional per-mode overrides applied on top of the single-mode values when
+    # rendering the comparison view (e.g. fewer ``max_subplots_per_file``
+    # because each subplot now has scenario-many more bars).  Any field listed
+    # in PLOT_FIELD_NAMES is allowed.  Plain dict so the YAML stays terse.
+    comparison_overrides: dict | None = None
+
+
+def default_ylabel_for(
+    result_key: str, variant_letter: str | None = None
+) -> str | None:
+    """Derive a default y-axis label (the displayed unit) for a plot.
+
+    Single source: the output-metadata catalog
+    (:func:`flextool.process_outputs._output_meta.result_key_summary`).
+    Returns the unit string when one is declared and non-trivial, else
+    ``None`` so callers leave an explicit ylabel untouched.  Imported lazily
+    to keep ``plot_outputs`` free of a ``process_outputs`` import at module
+    load.
+
+    When *variant_letter* is given, the variant-adjusted unit is used
+    (:func:`~flextool.process_outputs._output_meta.result_variant_summary`)
+    so the ``a`` (total → ``/a`` stripped) and ``w`` (weekly, unchanged)
+    plot variants get the correct value-axis unit; otherwise the base
+    output unit is used unchanged.
+    """
+    try:
+        if variant_letter is None:
+            from flextool.process_outputs._output_meta import result_key_summary
+            summary = result_key_summary(result_key)
+        else:
+            from flextool.process_outputs._output_meta import (
+                result_variant_summary,
+            )
+            summary = result_variant_summary(result_key, variant_letter)
+    except Exception:
+        return None
+    if not summary:
+        return None
+    unit = summary[0]
+    if not unit or unit == 'ratio':
+        return None
+    return unit
+
+
+def _is_single_config(d: dict) -> bool:
+    """Return True if *d* is a single-plot config (has known field names), not a named-config dict."""
+    return any(k in PLOT_FIELD_NAMES for k in d)
+
+
+def _is_new_format_entry(d: dict) -> bool:
+    """Return True if *d* is an entry-name-based config (has 'group' and 'order' keys)."""
+    return 'group' in d and 'order' in d
+
+
+def flatten_new_format(plots: dict) -> dict:
+    """Convert entry-name-based format to flat result_key-based format.
+
+    Entries have ``group`` and ``order`` keys; result_keys are nested
+    underneath.  The flattened output maps each result_key directly to
+    its sub-config dict (same shape the orchestrator/plan code expects).
+
+    When the same result_key appears under multiple entry names (e.g.
+    ``costs_dt_p`` under both "Costs" and "Costs lines"), the sub-configs
+    from each entry are merged into a single dict for that result_key.
+
+    Sub-configs that lack an explicit ``plot_name`` get the entry name
+    (e.g. "Node flows") injected as ``_entry_name`` so the orchestrator
+    can use it as a filename fallback instead of the raw result_key.
+
+    Already-flat entries (result_key → config dict without group/order)
+    pass through unchanged for programmatic callers.
+    """
+    flat: dict = {}
+    for key, value in plots.items():
+        if not isinstance(value, dict):
+            continue
+        if _is_new_format_entry(value):
+            for rk, rk_val in value.items():
+                if rk in ('group', 'order') or not isinstance(rk_val, dict):
+                    continue
+                # Inject entry name into sub-configs that lack plot_name
+                enriched = dict(rk_val)
+                for setting_name, setting in enriched.items():
+                    if isinstance(setting, dict) and 'plot_name' not in setting:
+                        setting['_entry_name'] = key
+                if rk in flat:
+                    flat[rk].update(enriched)
+                else:
+                    flat[rk] = enriched
+        else:
+            # Already flat (result_key → config dict) — pass through
+            flat[key] = value
+    return flat

flextool/plot_outputs/format_helpers.py

@@ -0,0 +1,345 @@
+"""Value formatting and filename utilities for plot_outputs."""
+from __future__ import annotations
+
+import logging
+import math
+import os
+
+import numpy as np
+import pandas as pd
+from decimal import Decimal, InvalidOperation
+from matplotlib.ticker import Formatter, FuncFormatter
+
+from flextool.lean_parquet import read_lean_parquet
+
+
+# ── superscript digits for nice exponent display (single source) ──
+_SUPERSCRIPTS = str.maketrans('0123456789-', '⁰¹²³⁴⁵⁶⁷⁸⁹⁻')
+
+
+def _sig_figs_fmt(x, pos, n: int = 5) -> str:
+    """Format x with n significant figures, plain notation, no trailing zeros."""
+    if x == 0:
+        return '0'
+    try:
+        d = Decimal(str(x))
+        rounded = d.quantize(Decimal(10) ** (d.adjusted() - n + 1))
+        result = f'{rounded:f}'
+        if '.' in result:
+            result = result.rstrip('0').rstrip('.')
+        return result
+    except (InvalidOperation, ValueError):
+        return str(x)
+
+
+class DynamicFormatter(Formatter):
+    """Value-axis formatter that adapts to the data range.
+
+    Determines precision from the maximum tick value (2 significant digits):
+    - max >= 1,000: commas, no decimals  (e.g. "1,200,000")
+    - max >= 10:    no decimals           (e.g. "45")
+    - max >= 1:     1 decimal             (e.g. "4.7")
+    - max >= 0.1:   2 decimals            (e.g. "0.46")
+    - smaller:      more decimals as needed
+
+    Switches to engineering notation (exponent multiple of 3) when
+    |max value| > 990,000,000  (e.g. "1.5e9").
+    """
+
+    # ── superscript digits for nice exponent display ──
+    # Alias to the module-level single source so tick formatting and the
+    # value-label formatter share one table.
+    _SUPERSCRIPTS = _SUPERSCRIPTS
+
+    def format_ticks(self, values):
+        if len(values) == 0:
+            return []
+
+        finite = [v for v in values if math.isfinite(v)]
+        if not finite:
+            return [str(v) for v in values]
+
+        max_abs = max(abs(v) for v in finite)
+        if max_abs == 0:
+            return ['0' for _ in values]
+
+        # Engineering notation for very large values
+        if max_abs > 990_000_000:
+            return self._eng_format(values, max_abs)
+
+        # Number of decimals: show ~2 significant digits
+        # decimals = max(0, 1 - floor(log10(max_abs)))
+        log_max = math.floor(math.log10(max_abs))
+        decimals = max(0, 1 - log_max)
+
+        # Commas for thousands and above
+        if max_abs >= 1_000:
+            fmt_spec = f',.{decimals}f'
+        else:
+            fmt_spec = f'.{decimals}f'
+
+        return [format(v, fmt_spec) for v in values]
+
+    def _eng_format(self, values, max_abs):
+        """Format with engineering notation (exponent as multiple of 3)."""
+        exp = 3 * (math.floor(math.log10(max_abs)) // 3)
+        divisor = 10 ** exp
+
+        # Determine decimals for the divided values (2 sig digits)
+        max_divided = max_abs / divisor
+        log_div = math.floor(math.log10(max_divided)) if max_divided > 0 else 0
+        decimals = max(0, 1 - log_div)
+
+        fmt_spec = f',.{decimals}f' if max_divided >= 1_000 else f'.{decimals}f'
+        exp_str = str(exp).translate(self._SUPERSCRIPTS)
+
+        result = []
+        for v in values:
+            if not math.isfinite(v):
+                result.append(str(v))
+            elif v == 0:
+                result.append('0')
+            else:
+                divided = v / divisor
+                formatted = format(divided, fmt_spec)
+                result.append(f'{formatted}×10{exp_str}')
+        return result
+
+    def __call__(self, x, pos=None):
+        """Fallback for individual tick formatting (cursor display, width estimates)."""
+        if not math.isfinite(x):
+            return str(x)
+        if x == 0:
+            return '0'
+        max_abs = abs(x)
+        if max_abs > 990_000_000:
+            exp = 3 * (math.floor(math.log10(max_abs)) // 3)
+            divisor = 10 ** exp
+            divided = x / divisor
+            log_div = math.floor(math.log10(abs(divided))) if divided != 0 else 0
+            dec = max(0, 1 - log_div)
+            exp_str = str(exp).translate(self._SUPERSCRIPTS)
+            return f'{format(divided, f".{dec}f")}×10{exp_str}'
+        log_max = math.floor(math.log10(max_abs))
+        decimals = max(0, 1 - log_max)
+        if max_abs >= 1_000:
+            return format(x, f',.{decimals}f')
+        return format(x, f'.{decimals}f')
+
+
+# Module-level instance reused only to delegate the small-value (< 1e6)
+# comma-formatting path of format_value_label, so small value labels render
+# exactly as the dynamic tick path would. This does NOT affect tick labels.
+_VALUE_LABEL_DELEGATE = DynamicFormatter()
+
+
+def format_value_label(x) -> str:
+    """Format a bar value label (the ``'dynamic'`` value-label path only).
+
+    For ``abs(x) >= 1_000_000`` produce compact engineering notation in the
+    ×10⁶ / ×10⁹ / ×10¹² style with 5 significant figures on the mantissa
+    (trailing zeros and a trailing '.' stripped), e.g. ``16_701_871`` →
+    ``"16.701×10⁶"``. Below 1e6 (and for non-finite / zero values) delegate
+    to the existing dynamic comma formatting so small labels are unchanged.
+
+    Note: this is for *value labels on bars only*. Axis tick labels keep going
+    through DynamicFormatter / _get_value_formatter and must not call this.
+    """
+    if not math.isfinite(x) or x == 0:
+        return _VALUE_LABEL_DELEGATE(x, None)
+    abs_x = abs(x)
+    if abs_x < 1_000_000:
+        return _VALUE_LABEL_DELEGATE(x, None)
+
+    # Engineering exponent (multiple of 3); for abs_x >= 1e6 this is >= 6.
+    exp = 3 * (math.floor(math.log10(abs_x)) // 3)
+    mantissa = x / 10 ** exp
+    # 5 significant figures: |mantissa| lies in [1, 1000).
+    decimals = max(0, 4 - math.floor(math.log10(abs(mantissa))))
+    mantissa_str = format(mantissa, f'.{decimals}f')
+    if '.' in mantissa_str:
+        mantissa_str = mantissa_str.rstrip('0').rstrip('.')
+    exp_str = str(exp).translate(_SUPERSCRIPTS)
+    return f'{mantissa_str}×10{exp_str}'
+
+
+def _get_value_formatter(axis_tick_format, idx: int):
+    """Return a tick formatter for subplot idx.
+
+    axis_tick_format can be:
+      None           → sig-figs FuncFormatter (default, 5 sig figs, plain notation)
+      'dynamic'      → DynamicFormatter (adapts to data range)
+      ',.0f'         → StrMethodFormatter applied to all subplots
+      [',.0f', '.2%'] → per-subplot StrMethodFormatter; sig-figs default beyond list length
+    The format spec is a standard Python format spec (without braces), e.g. ',.0f', '.2%'.
+    """
+    if axis_tick_format is None:
+        return FuncFormatter(_sig_figs_fmt)
+    if isinstance(axis_tick_format, str):
+        spec = axis_tick_format
+    elif isinstance(axis_tick_format, list):
+        entry = axis_tick_format[idx] if idx < len(axis_tick_format) else None
+        if entry is None:
+            return FuncFormatter(_sig_figs_fmt)
+        spec = entry
+    else:
+        return FuncFormatter(_sig_figs_fmt)
+    if spec == 'dynamic':
+        return DynamicFormatter()
+    def _fmt_with_spec(x, pos, _spec=str(spec)):
+        try:
+            return format(x, _spec)
+        except (ValueError, TypeError) as e:
+            logging.error(f"axis_tick_format: cannot format value {x!r} with spec {_spec!r}: {e}")
+            return str(x)
+    return FuncFormatter(_fmt_with_spec)
+
+
+def generate_split_filename(
+    base_name: str,
+    plot_dir: str,
+    extension: str,
+    file_idx: int | None = None,
+    needs_split: bool = False,
+    file_member: str | None = None,
+) -> str:
+    """Generate filename with appropriate suffix based on splitting needs.
+
+    - No splitting: base_name.extension
+    - With file_member only: base_name_member.extension
+    - With splitting: base_name_01.extension, base_name_02.extension, ...
+    - With both: base_name_member_01.extension, base_name_member_02.extension, ...
+
+    File index uses leading zeros for numbers < 10 (e.g., _01, _02, ..., _09, _10).
+    """
+    name = base_name
+    if file_member is not None:
+        name = f'{name}_{file_member}'
+    if not needs_split:
+        return f'{plot_dir}/{name}.{extension}'
+    else:
+        idx_str = f'{file_idx:02d}'
+        return f'{plot_dir}/{name}_{idx_str}.{extension}'
+
+
+def split_into_chunks(items, chunk_size):
+    """Split a list into chunks of specified size."""
+    for i in range(0, len(items), chunk_size):
+        yield items[i:i + chunk_size]
+
+
+def _chunk_average_df(df: pd.DataFrame, chunk_size: int) -> pd.DataFrame:
+    """Chunk-average a DataFrame along its (simple) index.
+
+    Divides the index into consecutive blocks of `chunk_size` rows,
+    averages each block, and labels the result with the first original
+    index label of each chunk.
+    """
+    chunk_ids = np.arange(len(df)) // chunk_size
+    first_labels = df.index[::chunk_size]
+    averaged = df.groupby(chunk_ids).mean()
+    averaged.index = first_labels[:len(averaged)]
+    averaged.index.name = df.index.name
+    return averaged
+
+
+# ---------------------------------------------------------------------------
+#  Timeline breaks
+# ---------------------------------------------------------------------------
+
+def load_timeline_breaks(*parquet_dirs: str | os.PathLike) -> set[str]:
+    """Load timeline break timesteps from one or more parquet directories.
+
+    Reads ``timeline_breaks.parquet`` from each directory and returns the
+    union of all break timestep identifiers (e.g. ``{'t1336', 't2848'}``).
+    Returns an empty set if no files are found.
+    """
+    break_times: set[str] = set()
+    for d in parquet_dirs:
+        path = os.path.join(str(d), 'timeline_breaks.parquet')
+        if os.path.exists(path):
+            try:
+                df = read_lean_parquet(path)
+                if 'time' in df.columns:
+                    break_times.update(df['time'].astype(str))
+            except Exception:
+                pass
+    return break_times
+
+
+def split_at_timeline_breaks(
+    df: pd.DataFrame,
+    break_times: set[str],
+) -> list[pd.DataFrame]:
+    """Split a DataFrame into contiguous segments at timeline discontinuities.
+
+    Returns a list of DataFrames, one per contiguous block.  Plotting each
+    segment separately produces clean gaps (lines/areas stop and restart)
+    rather than plunging to zero at NaN values.
+
+    Works with both simple and MultiIndex row indices.
+    """
+    if not break_times or df.empty:
+        return [df]
+
+    # Find the time level in the index
+    if isinstance(df.index, pd.MultiIndex):
+        time_level = df.index.nlevels - 1  # default: last level
+        for i, name in enumerate(df.index.names):
+            if name and str(name).lower() in ('time', 't'):
+                time_level = i
+                break
+        time_vals = df.index.get_level_values(time_level).astype(str)
+    else:
+        time_vals = df.index.astype(str)
+
+    # Find integer positions where breaks occur
+    break_positions = [i for i, t in enumerate(time_vals) if t in break_times]
+    if not break_positions:
+        return [df]
+
+    # Split into contiguous segments
+    segments: list[pd.DataFrame] = []
+    prev = 0
+    for pos in break_positions:
+        if prev < pos:
+            segments.append(df.iloc[prev:pos])
+        prev = pos
+    if prev < len(df):
+        segments.append(df.iloc[prev:])
+
+    return segments
+
+
+def insert_timeline_breaks(
+    df: pd.DataFrame,
+    break_times: set[str],
+    gap_rows: int = 3,
+) -> pd.DataFrame:
+    """Insert NaN rows before timeline discontinuities for visual gaps.
+
+    Inserts *gap_rows* NaN rows (default 3) between contiguous blocks
+    so the gap is clearly visible in plots.
+    """
+    if not break_times or df.empty:
+        return df
+
+    segments = split_at_timeline_breaks(df, break_times)
+    if len(segments) <= 1:
+        return df
+
+    # Insert NaN rows between segments
+    parts: list[pd.DataFrame] = []
+    for i, seg in enumerate(segments):
+        if i > 0:
+            prev_seg = parts[-1]
+            gap_index = prev_seg.index[-1:].repeat(gap_rows)
+            nan_block = pd.DataFrame(
+                np.nan,
+                index=gap_index,
+                columns=df.columns,
+            )
+            parts.append(nan_block)
+        parts.append(seg)
+
+    return pd.concat(parts)

flextool/plot_outputs/legend_helpers.py

@@ -0,0 +1,143 @@
+"""Legend sizing, positioning, and label formatting utilities."""
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+
+
+def estimate_legend_width(labels, title: str = '', base_width: float = 1.5) -> float:
+    """Estimate the width in inches needed for a legend based on label content.
+
+    Args:
+        labels: List of label strings
+        title: Legend title string
+        base_width: Minimum width in inches (default: 1.5)
+
+    Returns:
+        Estimated width in inches
+    """
+    if not labels:
+        return base_width
+
+    max_label_len = max(len(str(label)) for label in labels)
+    title_len = len(str(title)) if title else 0
+
+    # ~0.09 inches per character + base padding (accounts for typical 8-10pt font)
+    char_width = 0.07
+    label_width = max_label_len * char_width
+    title_width = title_len * char_width
+
+    estimated_width = max(label_width, title_width, base_width) + 0.8
+    return estimated_width
+
+
+def estimate_legend_height(n_entries: int, has_title: bool = True) -> float:
+    """Estimate the height in inches needed for a legend.
+
+    Args:
+        n_entries: Number of legend entries
+        has_title: Whether the legend has a title
+
+    Returns:
+        Estimated height in inches
+    """
+    entry_height = 0.22  # approximate height per entry at 10pt font
+    title_height = 0.25 if has_title else 0.0
+    padding = 0.15  # top + bottom padding
+    return n_entries * entry_height + title_height + padding
+
+
+def _format_legend_labels(items: list) -> list[str]:
+    """Convert legend items (possibly tuples/lists) to display strings.
+
+    Tuples and lists are joined with ' | '; all other items are str()-converted.
+    """
+    result = []
+    for item in items:
+        if isinstance(item, (tuple, list)):
+            result.append(' | '.join(str(v) for v in item))
+        else:
+            result.append(str(item))
+    return result
+
+
+def _should_show_legend(
+    legend_position: str,
+    sub_levels: list,
+    idx: int,
+    n_cols: int,
+    n_subs: int,
+) -> bool:
+    """Return True if the legend should be shown on subplot idx.
+
+    'all'    → show on every subplot.
+    'right'  → show only on the rightmost column or the last subplot.
+    'shared' → never (the caller renders one figure-level legend separately).
+    """
+    if legend_position == 'shared':
+        return False
+    if legend_position == 'all':
+        return True
+    if legend_position == 'right':
+        col = idx % n_cols
+        if col == n_cols - 1 or idx == n_subs - 1:
+            return True
+    return False
+
+
+def build_shared_color_map(
+    labels: list[str],
+    *,
+    color_template: dict | None = None,
+    category: str | None = None,
+    entity_class: str | None = None,
+    scenario: bool = False,
+) -> dict[str, tuple]:
+    """Assign consistent colors to a list of labels.
+
+    Template-matched labels (via ``color_template`` + ``category`` /
+    ``entity_class``) get their explicit color and do **not** consume a
+    palette slot.  Remaining labels get tab10/tab20 colors assigned in
+    input order, so e.g. the first un-templated label always gets
+    ``tab10[0]`` regardless of how many template matches preceded it.
+
+    With no template (the default), this is byte-identical to the
+    previous palette-only behaviour: the palette is picked based on the
+    total label count — tab10 when ≤10, tab20 otherwise — and labels are
+    assigned in input order, cycling if the palette is exhausted.
+    """
+    from flextool.plot_outputs.color_template import resolve_label_color
+
+    n = len(labels)
+
+    # First pass: resolve template colors for each label.  None means
+    # "fall back to palette".
+    template_colors: list[tuple | None] = [None] * n
+    palette_needed = n
+    if color_template and (category or entity_class or scenario):
+        for i, label in enumerate(labels):
+            c = resolve_label_color(
+                label, color_template, category=category,
+                entity_class=entity_class, scenario=scenario,
+            )
+            if c is not None:
+                template_colors[i] = c
+                palette_needed -= 1
+
+    # Pick the palette based on how many palette slots we actually need.
+    # For the zero-template case, palette_needed == n, so the behaviour
+    # matches the pre-refactor code exactly.
+    if palette_needed <= 10:
+        cmap_colors = plt.colormaps['tab10'].colors
+    else:
+        cmap_colors = plt.colormaps['tab20'].colors
+
+    result: dict[str, tuple] = {}
+    palette_idx = 0
+    for i, label in enumerate(labels):
+        tc = template_colors[i]
+        if tc is not None:
+            result[label] = tc
+            continue
+        result[label] = cmap_colors[palette_idx % len(cmap_colors)]
+        palette_idx += 1
+    return result