API

Plot publisher for Live Data Server

plot_publisher.extract_data(plot_div: str) → List[List[List]] | List[List][source]

Extract data from a Plotly HTML div produced by plot1d() or plot_heatmap() and return it in the original input format.

The plot type is detected automatically by inspecting the first trace:

  • Heatmap / surface (first trace contains a z key) – delegates to extract_heatmap_data() and returns [x, y, z] where

    • x – plain Python list of X-axis values

    • y – plain Python list of Y-axis values

    • z – list of rows, each row a plain Python list of Z values

  • 1-D scatter (no z key) – delegates to extract_plot1d_data() and returns a list of traces [[x, y, ...], ...] where each trace is

    • [x, y] – no error bars

    • [x, y, dy] – Y error bars only

    • [x, y, dy, dx] – both Y and X error bars

All arrays are plain Python lists. Error bar arrays in 1D plots are always returned regardless of their visible flag.

The original inputs to plot1d() or plot_heatmap() may have been plain Python lists or NumPy arrays. Regardless of the original type, all returned values are plain Python lists.

@param plot_div: HTML div string produced by plot1d() or

plot_heatmap() with publish=False.

@return: [x, y, z] for heatmap / surface plots, or

[[x, y, ...], ...] for 1-D scatter plots.

@raises ValueError: If plot_div is not a string, contains no recognisable

Plotly data, cannot be JSON-parsed, or has no traces.

plot_publisher.inject_plotlyjs_version(html_content: str, version: str | None = None) → str[source]

Add a plotlyjs-version="<version>" attribute to the first Plotly <div> found in html_content.

@param html_content: HTML string that potentially contains Plotly div elements. @param version: The plotly.js version to inject. If None, auto-detects from get_plotlyjs_version(). @return: The (possibly) modified HTML string with the version attribute injected. @raises ValueError: If html_content is not a str.

plot_publisher.plot1d(run_number: int | str, data_list: List[float] | List[List[float]], data_names: List[str] | None = None, x_title: str = '', y_title: str = '', x_log: bool = False, y_log: bool = False, instrument: str = '', show_dx: bool = True, title: str = '', publish: bool = True) → Response | str[source]

Generate a 1-D Plotly figure (scatter/error) and optionally publish it.

@param run_number: Run identifier. @param data_list: See function body for accepted shapes – either a single

trace [x, y] or a list of traces.

@param data_names: Optional legend labels. @param x_title: X-axis label. @param y_title: Y-axis label. @param x_log: Use log scale on X-axis. @param y_log: Use log scale on Y-axis. @param instrument: Instrument name (used if publish is True). @param show_dx: Show X error bars when present. @param title: Plot title. @param publish: If True the plot is sent to the server via

publish_plot; otherwise the HTML div is returned.

@return: requests.Response when publish is True, otherwise the HTML div. @raises RuntimeError: If data_list is malformed.

plot_publisher.plot_heatmap(run_number, x, y, z, x_title='', y_title='', surface=False, x_log=False, y_log=False, instrument='', title='', publish=True, colorscale='Jet')[source]

Generate a 2-D heat-map (or surface plot) and optionally publish it.

@param run_number: Run identifier. @param x,y,z: Grid data for the heat-map/surface. @param x_title: X-axis label. @param y_title: Y-axis label. @param surface: When True render as 3-D surface. @param x_log: Log scale for X. @param y_log: Log scale for Y. @param instrument: Instrument name (used if publish is True). @param title: Plot title. @param publish: If True the plot is sent to the server; otherwise the

HTML div is returned.

@param colorscale: Colorscale for the heatmap. Default is “Jet”. @return: requests.Response when publish is True, otherwise the HTML div.

plot_publisher.publish_plot(instrument: str, run_number: int | str, files: Dict[str, str], config: Configuration | None = None) → Response[source]

Publish one or more files to the plot server.

@param instrument: Instrument name. @param run_number: Run number associated with the data. @param files: dict of {filename: content}. HTML strings that look

like Plotly divs will have the Plotly version injected.

@param config: Optional configuration object or path; if None the default

configuration is loaded with read_configuration().

@return: requests.Response object from the POST request. @raises requests.HTTPError: If the server responds with a non-OK status code. @raises ValueError: If input parameters are invalid.