Data sources

A series normally owns its numbers. It can instead carry a data_source that names columns in a table held elsewhere; the numbers are then looked up when the figure is saved, through the data_provider passed to gleplot.Figure.savefig().

Sources

class gleplot.DataSource(**fields)[source]

Base class for the three source kinds.

Like gleplot.series.Series, a dict subclass holding all of its state as items and none as instance attributes. That is what makes a source free to serialize (_to_jsonable already turns any mapping into a plain dict), free to copy/deepcopy/pickle, and free to compare – the same reasoning that governs the series classes, applied one level down.

kind is always the first item, so the serialized key order is stable.

Parameters:

fields (Any)

class gleplot.InlineData(**fields)[source]

The arrays are baked into the series itself.

Carries no state beyond its discriminator: everything it “holds” is already on the series. Constructing one is therefore optional – source_of() returns an InlineData for any series that has no data_source key, which is what keeps the scripting API’s output (and its serialized form) unchanged.

Parameters:

fields (Any)

class gleplot.ColumnRef(table_id, columns)[source]

Columnar data pulled from a provider table.

ColumnRef('t1', {'x': 'time', 'y': 'signal'}) says: my x column is the table column whose stable key is 'time', my y column is 'signal'. Two series referencing the same table_id share one .dat sidecar holding the union of the columns they mention.

Parameters:
class gleplot.GridRef(table_id, columns)[source]

Gridded data pulled from a provider table.

Two shapes, matching the two HeatmapSeries/ContourSeries grid modes (the series’ own source field, which predates this module and is unrelated to data_source):

  • source='grid': GridRef('t1', {'z': ['c0', 'c1', 'c2']}) – the listed columns are stacked left-to-right into the 2-D z grid, so a table laid out like a spreadsheet resolves to the grid it looks like.

  • source='points': GridRef('t1', {'x': ..., 'y': ..., 'zpts': ...}) – scattered samples, one key per role, gridded by GLE’s fitz.

Grid series write their own raw .z/points sidecar per series (that is what GLE’s colormap/fitz read), so unlike ColumnRef they never share a sidecar.

Parameters:

Providers

class gleplot.DataProvider(*args, **kwargs)[source]

Supplies the tables that ColumnRef/GridRef name.

One method. A provider is passed at write time (Figure.savefig(..., data_provider=...)) and is never stored on the figure: the figure is a serializable document and the provider is a live application object, so binding them would make to_dict() either lossy or impossible, and would stop the same figure being rendered against different tables (preview vs export, or a what-if dataset).

get_table(table_id)[source]

The table with this id, or None if there is no such table.

Parameters:

table_id (str)

Return type:

ProviderTable | None

class gleplot.TableData(keys, names, columns)[source]

A concrete, in-memory ProviderTable.

Keeps the three parallel lists a table needs: stable keys, display names, and the column columns themselves. Renaming a column means changing names and leaves every reference to it intact – which is the property the whole reference model rests on, made testable here.

Parameters:
classmethod from_mapping(mapping)[source]

Build a table whose column keys are their display names.

The convenient form for scripts and tests, where there is no rename story to model.

Parameters:

mapping (Mapping[str, Sequence[float]])

Return type:

TableData

classmethod from_data_table(table)[source]

Adapt a gleplot.dataio.DataTable (a loaded .dat file).

Column keys are positional (c0, c1, …) because a loaded file’s header names are display text that an edit may change, while position is what the file itself is keyed by. Non-numeric columns are dropped: they cannot be plotted, and offering them as referenceable would only produce dangling references later.

Parameters:

table (Any)

Return type:

TableData

class gleplot.DictDataProvider(tables=None)[source]

A DataProvider over a plain {table_id: table} mapping.

Enough for scripts, tests and simple embedders; GLEstudio supplies its own provider backed by the project’s live tables.

Parameters:

tables (Mapping[str, ProviderTable] | None)

Unresolved references

class gleplot.DanglingSourceRef(axes_index, series_attr, series_index, label, table_id, reason, missing_columns=())[source]

A reference that could not be resolved, and the series it belonged to.

Deliberately an object rather than a formatted string: GLEstudio shows these in the structure tree with retarget/remove actions, so it needs the identity of the series (which axes, which list, which index) and of the missing thing (which table, which columns) separately from any wording. str() renders the human-readable form for CLI use.

Parameters:
axes_index

Index of the axes in figure.axes_list.

Type:

int

series_attr

The axes list the series lives in ('lines', 'heatmaps', …).

Type:

str

series_index

Index within that list.

Type:

int

label

The series’ label, when it has one – the only user-facing name a series has.

Type:

str or None

table_id

The table_id the reference names ('' for a source whose kind this build does not understand).

Type:

str

missing_columns

The column keys that could not be resolved. Empty when the whole table is missing.

Type:

tuple of str

reason

One of 'no-provider', 'unknown-table', 'missing-column', 'unknown-kind', 'unusable-data'.

Type:

str

REASONS = {'missing-column': 'column(s) not found in the table', 'no-provider': 'no data provider was supplied for this write', 'unknown-kind': 'unrecognized data-source kind', 'unknown-table': 'no table with that id', 'unusable-data': 'the resolved data cannot be plotted (empty or degenerate)'}

Every value reason can take, with its wording.

'unusable-data' is the one reason where the reference resolved fine and the numbers behind it did not: a grid series whose extent (or auto colorbar range) is computed at write time from the resolved arrays (SPEC 14.5) cannot be drawn when those arrays are empty or degenerate. It is reported like any other skip rather than raised, because “nothing about a write raises” – see gleplot.writer.resolve_figure().

property series_id: str

axes[0].lines[2].

Type:

A stable, printable identifier

property message: str

The rendered, human-readable form (also what str() returns).

class gleplot.DanglingSourceWarning(ref)[source]

Warning category for a series skipped because its source is dangling.

Carries the structured record on .ref so a caller that installs a warnings filter still gets the inspectable object rather than only the rendered message.

Parameters:

ref (DanglingSourceRef)