add color, locale, plotly theme, timestamp ticks

docs/_sources/first_steps.rst.txt

@@ -65,8 +65,9 @@ Our component code might look like this to plot the timeseries accordingly:
 
 .. code-block:: python
 
-    from hdhelpers.plotting import get_and_pad_start_and_end_timestamp, get_y_axis_label, plotly_fig_to_json_dict
-    from hdhelpers.helpers import modify_timezone
+    from hdhelpers.plotting import set_agnostic_theme, set_dt_ticks, resolve_color
+    from hdhelpers.helpers import get_locale, modify_timezone
+    from hdhelpers.metadata import get_queried_interval, get_series_name
     import plotly.graph_objects as go
 
     def main(*, series):
@@ -75,26 +76,16 @@ Our component code might look like this to plot the timeseries accordingly:
 
         series = modify_timezone(series)
 
-        colors = get_colors_from_plot_target_settings()
-        fig = go.Figure([go.Scatter(x=series.index, y=series.values, marker={"color": colors.status_colors.warn_color})])
+        fig = go.Figure([go.Scatter(x=series.index, y=series.values, marker={"color": resolve_color("ki.vision")})])
 
-        start, end = get_and_pad_start_and_end_timestamp(series=series, start_padding='5s')
+        start, end = get_queried_interval(series=series)
         fig.update_xaxes(range=(start, end))
 
-        full_title = get_y_axis_label(series=series, default_title="Level")
+        full_title = get_series_name(series=series, default_title="Level")
         fig.update_layout(yaxis_title=full_title)
 
-        return {"plot": plotly_fig_to_json_dict(fig=fig)}
+        set_dt_ticks(fig)
+        set_agnostic_theme(fig)
 
-Explanation
------------
+        return {"plot": fig}
 
-- *modify_timezone*: We use `modify_timezone` function to set the timezone. Since our goal is just to make sure that the timestamps are timezone aware, not to convert it to a specific timezone, we do not pass a value for the `timezone` parameter. That way, if there is a `plot_target_timezone` set in the hetida designer's `plot_target_settings` context variable, that timezone will be used. Otherwise, the timestamps keep their current timezone or are converted to UTC if they are timezone naive.
-
-- *get_colors_from_plot_target_settings*: To use a (global) standard color, we use `get_colors_from_plot_target_settings`, which returns the `plot_target_style` property of the `plot_target_settings` context variable. It contains a set of colors with specific purposes, such as `background_color`, and the `status_colors` object, which in turn contains the four status colors: `success_color`, `error_color`, `warn_color`, and `info_color`. The status colors have no hardwired use in a plot, but are intended to convey a message. In our example, we want to communicate that the order of magnitude of our data is potentially dangerous, so we use the `warn_color` for `fig`'s `marker["color"]` property, which determines the plot's marker and line color.
-
-- *get_and_pad_start_and_end_timestamp*: We use `get_and_pad_start_and_end_timestamp` for precise control over the x-axis range. We do not set `start` and `end` explicitly because we want to parse them from the metadata, which reflects the chosen interval for which the data was requested. This way, we can see that there is missing data from 8:18 to 8:20. In the default behaviour of plotly this time range would not have been included possibly hiding missing data. Note: (1) We do not pass a `timezone` for the same reasons as with `modify_timezone`. (2) We also set a `start_padding`, so the markers of the first data point is not cut in half by the edge of the plot.
-
-- *get_y_axis_label*: We use `get_y_axis_label` so our y-axis can be labeled by using information from the metadata. With the above input series, title and unit will be parsed from the metadata. In case the metadata does not contain the mentioned information, we provide a `default_title`, and `default_unit` to configure the axis label in such cases.
-
-- *plotly_fig_to_json_dict*: We use `plotly_fig_to_json_dict` to apply standardized stylings and serialize the plotly figure into a json dict. All the standardized styling options are active by default, as detailed in [Styling Flags](#flags), so we do not have to set any for this example.

docs/_sources/index.rst.txt

@@ -48,6 +48,17 @@ helpers
    :members:
    :show-inheritance:
 
+
+
+plotting
+------------------
+
+.. automodule:: hdhelpers.plotting
+   :members:
+   :show-inheritance:
+
+
+
 exceptions
 -------------------
 

docs/first_steps.html

@@ -94,8 +94,9 @@ <h2>How to use hdhelpers for plotting? (tbd)<a class="headerlink" href="#how-to-
 - define the label of the y-axis corresponding to the metadata,
 - and use standard colors for plotting.</p>
 <p>Our component code might look like this to plot the timeseries accordingly:</p>
-<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">hdhelpers.plotting</span><span class="w"> </span><span class="kn">import</span> <span class="n">get_and_pad_start_and_end_timestamp</span><span class="p">,</span> <span class="n">get_y_axis_label</span><span class="p">,</span> <span class="n">plotly_fig_to_json_dict</span>
-<span class="kn">from</span><span class="w"> </span><span class="nn">hdhelpers.helpers</span><span class="w"> </span><span class="kn">import</span> <span class="n">modify_timezone</span>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">hdhelpers.plotting</span><span class="w"> </span><span class="kn">import</span> <span class="n">set_agnostic_theme</span><span class="p">,</span> <span class="n">set_dt_ticks</span><span class="p">,</span> <span class="n">resolve_color</span>
+<span class="kn">from</span><span class="w"> </span><span class="nn">hdhelpers.helpers</span><span class="w"> </span><span class="kn">import</span> <span class="n">get_locale</span><span class="p">,</span> <span class="n">modify_timezone</span>
+<span class="kn">from</span><span class="w"> </span><span class="nn">hdhelpers.metadata</span><span class="w"> </span><span class="kn">import</span> <span class="n">get_queried_interval</span><span class="p">,</span> <span class="n">get_series_name</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">plotly.graph_objects</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">go</span>
 
 <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">(</span><span class="o">*</span><span class="p">,</span> <span class="n">series</span><span class="p">):</span>
@@ -104,28 +105,20 @@ <h2>How to use hdhelpers for plotting? (tbd)<a class="headerlink" href="#how-to-
 
     <span class="n">series</span> <span class="o">=</span> <span class="n">modify_timezone</span><span class="p">(</span><span class="n">series</span><span class="p">)</span>
 
-    <span class="n">colors</span> <span class="o">=</span> <span class="n">get_colors_from_plot_target_settings</span><span class="p">()</span>
-    <span class="n">fig</span> <span class="o">=</span> <span class="n">go</span><span class="o">.</span><span class="n">Figure</span><span class="p">([</span><span class="n">go</span><span class="o">.</span><span class="n">Scatter</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="n">series</span><span class="o">.</span><span class="n">index</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="n">series</span><span class="o">.</span><span class="n">values</span><span class="p">,</span> <span class="n">marker</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;color&quot;</span><span class="p">:</span> <span class="n">colors</span><span class="o">.</span><span class="n">status_colors</span><span class="o">.</span><span class="n">warn_color</span><span class="p">})])</span>
+    <span class="n">fig</span> <span class="o">=</span> <span class="n">go</span><span class="o">.</span><span class="n">Figure</span><span class="p">([</span><span class="n">go</span><span class="o">.</span><span class="n">Scatter</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="n">series</span><span class="o">.</span><span class="n">index</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="n">series</span><span class="o">.</span><span class="n">values</span><span class="p">,</span> <span class="n">marker</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;color&quot;</span><span class="p">:</span> <span class="n">resolve_color</span><span class="p">(</span><span class="s2">&quot;ki.vision&quot;</span><span class="p">)})])</span>
 
-    <span class="n">start</span><span class="p">,</span> <span class="n">end</span> <span class="o">=</span> <span class="n">get_and_pad_start_and_end_timestamp</span><span class="p">(</span><span class="n">series</span><span class="o">=</span><span class="n">series</span><span class="p">,</span> <span class="n">start_padding</span><span class="o">=</span><span class="s1">&#39;5s&#39;</span><span class="p">)</span>
+    <span class="n">start</span><span class="p">,</span> <span class="n">end</span> <span class="o">=</span> <span class="n">get_queried_interval</span><span class="p">(</span><span class="n">series</span><span class="o">=</span><span class="n">series</span><span class="p">)</span>
     <span class="n">fig</span><span class="o">.</span><span class="n">update_xaxes</span><span class="p">(</span><span class="nb">range</span><span class="o">=</span><span class="p">(</span><span class="n">start</span><span class="p">,</span> <span class="n">end</span><span class="p">))</span>
 
-    <span class="n">full_title</span> <span class="o">=</span> <span class="n">get_y_axis_label</span><span class="p">(</span><span class="n">series</span><span class="o">=</span><span class="n">series</span><span class="p">,</span> <span class="n">default_title</span><span class="o">=</span><span class="s2">&quot;Level&quot;</span><span class="p">)</span>
+    <span class="n">full_title</span> <span class="o">=</span> <span class="n">get_series_name</span><span class="p">(</span><span class="n">series</span><span class="o">=</span><span class="n">series</span><span class="p">,</span> <span class="n">default_title</span><span class="o">=</span><span class="s2">&quot;Level&quot;</span><span class="p">)</span>
     <span class="n">fig</span><span class="o">.</span><span class="n">update_layout</span><span class="p">(</span><span class="n">yaxis_title</span><span class="o">=</span><span class="n">full_title</span><span class="p">)</span>
 
-    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;plot&quot;</span><span class="p">:</span> <span class="n">plotly_fig_to_json_dict</span><span class="p">(</span><span class="n">fig</span><span class="o">=</span><span class="n">fig</span><span class="p">)}</span>
+    <span class="n">set_dt_ticks</span><span class="p">(</span><span class="n">fig</span><span class="p">)</span>
+    <span class="n">set_agnostic_theme</span><span class="p">(</span><span class="n">fig</span><span class="p">)</span>
+
+    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;plot&quot;</span><span class="p">:</span> <span class="n">fig</span><span class="p">}</span>
 </pre></div>
 </div>
-<section id="explanation">
-<h3>Explanation<a class="headerlink" href="#explanation" title="Link to this heading">¶</a></h3>
-<ul class="simple">
-<li><p><em>modify_timezone</em>: We use <cite>modify_timezone</cite> function to set the timezone. Since our goal is just to make sure that the timestamps are timezone aware, not to convert it to a specific timezone, we do not pass a value for the <cite>timezone</cite> parameter. That way, if there is a <cite>plot_target_timezone</cite> set in the hetida designer’s <cite>plot_target_settings</cite> context variable, that timezone will be used. Otherwise, the timestamps keep their current timezone or are converted to UTC if they are timezone naive.</p></li>
-<li><p><em>get_colors_from_plot_target_settings</em>: To use a (global) standard color, we use <cite>get_colors_from_plot_target_settings</cite>, which returns the <cite>plot_target_style</cite> property of the <cite>plot_target_settings</cite> context variable. It contains a set of colors with specific purposes, such as <cite>background_color</cite>, and the <cite>status_colors</cite> object, which in turn contains the four status colors: <cite>success_color</cite>, <cite>error_color</cite>, <cite>warn_color</cite>, and <cite>info_color</cite>. The status colors have no hardwired use in a plot, but are intended to convey a message. In our example, we want to communicate that the order of magnitude of our data is potentially dangerous, so we use the <cite>warn_color</cite> for <cite>fig</cite>’s <cite>marker[“color”]</cite> property, which determines the plot’s marker and line color.</p></li>
-<li><p><em>get_and_pad_start_and_end_timestamp</em>: We use <cite>get_and_pad_start_and_end_timestamp</cite> for precise control over the x-axis range. We do not set <cite>start</cite> and <cite>end</cite> explicitly because we want to parse them from the metadata, which reflects the chosen interval for which the data was requested. This way, we can see that there is missing data from 8:18 to 8:20. In the default behaviour of plotly this time range would not have been included possibly hiding missing data. Note: (1) We do not pass a <cite>timezone</cite> for the same reasons as with <cite>modify_timezone</cite>. (2) We also set a <cite>start_padding</cite>, so the markers of the first data point is not cut in half by the edge of the plot.</p></li>
-<li><p><em>get_y_axis_label</em>: We use <cite>get_y_axis_label</cite> so our y-axis can be labeled by using information from the metadata. With the above input series, title and unit will be parsed from the metadata. In case the metadata does not contain the mentioned information, we provide a <cite>default_title</cite>, and <cite>default_unit</cite> to configure the axis label in such cases.</p></li>
-<li><p><em>plotly_fig_to_json_dict</em>: We use <cite>plotly_fig_to_json_dict</cite> to apply standardized stylings and serialize the plotly figure into a json dict. All the standardized styling options are active by default, as detailed in [Styling Flags](#flags), so we do not have to set any for this example.</p></li>
-</ul>
-</section>
 </section>
 </section>
 
@@ -141,10 +134,7 @@ <h3><a href="index.html">Table of Contents</a></h3>
     <ul>
 <li><a class="reference internal" href="#">First steps</a><ul>
 <li><a class="reference internal" href="#how-to-get-metadata-with-hdhelpers">How to get metadata with hdhelpers?</a></li>
-<li><a class="reference internal" href="#how-to-use-hdhelpers-for-plotting-tbd">How to use hdhelpers for plotting? (tbd)</a><ul>
-<li><a class="reference internal" href="#explanation">Explanation</a></li>
-</ul>
-</li>
+<li><a class="reference internal" href="#how-to-use-hdhelpers-for-plotting-tbd">How to use hdhelpers for plotting? (tbd)</a></li>
 </ul>
 </li>
 </ul>
@@ -193,7 +183,7 @@ <h3>Navigation</h3>
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-    &#169; Copyright 2026, Steffen Wittkamp, Jenny Kupzig, Christoph Dingel.
+    &#169; Copyright 2026, Steffen Wittkamp, Jenny Kupzig.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 9.1.0.
     </div>
   </body>

docs/genindex.html

@@ -43,12 +43,16 @@ <h1 id="index">Index</h1>
  | <a href="#H"><strong>H</strong></a>
  | <a href="#I"><strong>I</strong></a>
  | <a href="#M"><strong>M</strong></a>
+ | <a href="#R"><strong>R</strong></a>
+ | <a href="#S"><strong>S</strong></a>
 
 </div>
 <h2 id="G">G</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="index.html#hdhelpers.metadata.get_display_names">get_display_names() (in module hdhelpers.metadata)</a>
+</li>
+      <li><a href="index.html#hdhelpers.helpers.get_locale">get_locale() (in module hdhelpers.helpers)</a>
 </li>
       <li><a href="index.html#hdhelpers.metadata.get_measurements">get_measurements() (in module hdhelpers.metadata)</a>
 </li>
@@ -103,6 +107,13 @@ <h2 id="H">H</h2>
 
       <ul>
         <li><a href="index.html#module-hdhelpers.metadata">module</a>
+</li>
+      </ul></li>
+      <li>
+    hdhelpers.plotting
+
+      <ul>
+        <li><a href="index.html#module-hdhelpers.plotting">module</a>
 </li>
       </ul></li>
       <li><a href="index.html#hdhelpers.exceptions.HelperException">HelperException</a>
@@ -132,11 +143,33 @@ <h2 id="M">M</h2>
         <li><a href="index.html#module-hdhelpers.helpers">hdhelpers.helpers</a>
 </li>
         <li><a href="index.html#module-hdhelpers.metadata">hdhelpers.metadata</a>
+</li>
+        <li><a href="index.html#module-hdhelpers.plotting">hdhelpers.plotting</a>
 </li>
       </ul></li>
   </ul></td>
 </tr></table>
 
+<h2 id="R">R</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="index.html#hdhelpers.plotting.resolve_color">resolve_color() (in module hdhelpers.plotting)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="S">S</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="index.html#hdhelpers.plotting.set_agnostic_theme">set_agnostic_theme() (in module hdhelpers.plotting)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="index.html#hdhelpers.plotting.set_dt_ticks">set_dt_ticks() (in module hdhelpers.plotting)</a>
+</li>
+  </ul></td>
+</tr></table>
+
 
 
             <div class="clearer"></div>
@@ -173,7 +206,7 @@ <h3>Navigation</h3>
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-    &#169; Copyright 2026, Steffen Wittkamp, Jenny Kupzig, Christoph Dingel.
+    &#169; Copyright 2026, Steffen Wittkamp, Jenny Kupzig.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 9.1.0.
     </div>
   </body>