ploteries.writer

Provides a higher-level interface to ploteries that exposes a Writer class with add_*() methods similar to Tensorboard’s API.

Classes

Writer(path)

All add_*() methods build a list of trace dictionaries by combining corresponding dictionaries derived from the argument iterable values and the list of dictionaries in the argument traces_kwargs. The values iterable is expected to change from one time index to the next and its contents are stored for each time index in the data records table using a name tag derived from the add_*() methods's name or specified using argument data_name. The traces_kwargs, however, will be saved along with layout_kwargs in a figure template that is stored in the figure definitions table. Note that this figure template is only built the first time the add_* method is called, and that arguments traces_kwargs and layout_kwargs are ignored in subsequent calls.
class ploteries.writer.Writer(path)

All add_*() methods build a list of trace dictionaries by combining corresponding dictionaries derived from the argument iterable values and the list of dictionaries in the argument traces_kwargs. The values iterable is expected to change from one time index to the next and its contents are stored for each time index in the data records table using a name tag derived from the add_*() methods’s name or specified using argument data_name. The traces_kwargs, however, will be saved along with layout_kwargs in a figure template that is stored in the figure definitions table. Note that this figure template is only built the first time the add_* method is called, and that arguments traces_kwargs and layout_kwargs are ignored in subsequent calls.

` .. todo:: We need to 1) check that figure-definition values are compatible with the existing figure; 2) add mode=”overwrite” functionality. It might be best to make each add_* function a class deriving from a BaseAdder class.

Parameters:

path – Data store directory or file path. If a directory is specified, 'data_store.pltr' will be appended.

add_scalar(*arg, **kwargs)

Alias for add_scalars().

add_scalars(figure_name: str, values: _SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], global_step: int, traces_kwargs: List[Dict] | None = None, layout_kwargs=None, data_name: str | None = None, smoothing: bool = True)
Parameters:

  • figure_name – The figure name. If specified in format ‘<tab>/<group>/…’ , the tab and group entries will determine the position of the figure in the page.

  • values – The values for each scalar trace as an array-like.

  • names – The legend name to use for each trace.

  • traces – None or list of dictionaries of length equal to that of values containing keyword arguments for the trace. The default value for each trace is {'type':'scatter', 'mode':'lines'} and will be updated with the specified values.

  • data_name – The name of the data series when stored in the data table. If None, the name __add_scalars__.<figure_name> will be used.

  • smoothing – Whether to enable smoothing.

Example:

``` writer.add_scalars(

‘three_plots’, [0.1, 0.4, 0.5], 10, [{‘type’: ‘scatter’, ‘name’: ‘trace 0’},

{‘name’: ‘trace 1’}, {‘type’: ‘bar’, ‘name’: ‘trace 2’}])

```

add_plots(figure_name: str, values: _SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], global_step: int, traces_kwargs: List[Dict] | None = None, layout_kwargs=None, data_name: str | None = None)
Parameters:

  • figure_name – (See add_scalars()).

  • values – The values for each scalar trace as a dictionary, e.g., [{'x': [0,2,4], 'y': [0,2,4]}, {'x': [0,2,4], 'y': [0,4,16]}]. Dictionaries can contain lists, strings numpy ndarrays and generally anything compatible with Serializer. These dictionaries will be udpated with the corresponding value of traces_kwargs, if any. Note that the content of values will change with the global step and is saved in the data records table, but the content of traces_kwargs will remain constant and stored with the figure definition.

  • data_name – (See add_scalars()).

  • traces_kwargs – (See add_scalars()).

  • layout_kwargs – (See add_scalars()).

Example:

``` writer.add_plots(

‘three_plots’, [{‘x’: [0,2,4], ‘y’: [0,2,4]}, {‘x’: [0,2,4], ‘y’: [0,4,16]}], 10, [{‘type’: ‘scatter’, ‘name’: ‘trace 0’},

{‘name’: ‘trace 1’}, {‘type’: ‘bar’, ‘name’: ‘trace 2’}])

```

add_histograms(figure_name: str, values: List[_SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]], global_step: int, traces_kwargs: List[Dict] | None = None, layout_kwargs=None, data_name: str | None = None, compute_histogram: bool = True, histogram_kwargs: dict | None = None)
Parameters:

  • figure_name – (See add_scalars()).

  • values – A list of 1-row array-like entries. * When compute_histogram is True (the default), bin centers will be computed from all entries together, taking param histogram_kwargs into account. * When compute_histogram is False (requires an entry ‘bin_centers’ in param histogram_kwargs), each entry will be assumed to be a pre-computed histogram.

  • data_name – (See add_scalars()).

  • traces_kwargs – (See add_scalars()).

  • <layout_kwargs – (See add_scalars()).

  • compute_histogram – (See param values.). Note that this param can change between different calls with the same figure_name.

  • histogram_kwargs – When compute_histogram is True, these kwargs will be passed to compute_histogram(). Note that this param can change between different calls with the same figure_name.

Example:

```

static compute_histogram(dat, bins=20, bin_centers=None, normalize=True)
Parameters:

  • dat – Array-like from which the histogram will be computed.

  • bins – Num bins or bin edges (passed to numpy.histogram to create a histogram).

  • bin_centers – Overrides ‘bins’ and specifies the bin centers instead of the edges. The first and last bin centers are assumed to extend to +/- infinity.

  • normalize – Normalize the histogram so that it adds up to one.

add_table(figure_name: str, values: dict, global_step: int, data_name: str | None = None, **kwargs)
Parameters:

  • figure_name – (See add_scalars()).

  • values – A dictionary of values. Each key in the dictionary will define a column (row, if transposed=True) in the table, and the corresponding value will contain the row (resp., column) values for the specified global_step.

  • data_name – (See add_scalars()).

  • **kwargs –

    Extra arguments for class : class: ploteries.figure_handlers.TableHandler.

Example:

``` writer.add_table(

‘my_table’, {‘col1’: 1.0, ‘col2’: 2.0}, 10)

```