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, adictsubclass holding all of its state as items and none as instance attributes. That is what makes a source free to serialize (_to_jsonablealready turns any mapping into a plain dict), free tocopy/deepcopy/pickle, and free to compare – the same reasoning that governs the series classes, applied one level down.kindis 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 anInlineDatafor any series that has nodata_sourcekey, 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 sametable_idshare one.datsidecar holding the union of the columns they mention.
- class gleplot.GridRef(table_id, columns)[source]
Gridded data pulled from a provider table.
Two shapes, matching the two
HeatmapSeries/ContourSeriesgrid modes (the series’ ownsourcefield, which predates this module and is unrelated todata_source):source='grid':GridRef('t1', {'z': ['c0', 'c1', 'c2']})– the listed columns are stacked left-to-right into the 2-Dzgrid, 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’sfitz.
Grid series write their own raw
.z/points sidecar per series (that is what GLE’scolormap/fitzread), so unlikeColumnRefthey never share a sidecar.
Providers
- class gleplot.DataProvider(*args, **kwargs)[source]
Supplies the tables that
ColumnRef/GridRefname.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 maketo_dict()either lossy or impossible, and would stop the same figure being rendered against different tables (preview vs export, or a what-if dataset).
- class gleplot.TableData(keys, names, columns)[source]
A concrete, in-memory
ProviderTable.Keeps the three parallel lists a table needs: stable
keys, displaynames, and the columncolumnsthemselves. Renaming a column means changingnamesand leaves every reference to it intact – which is the property the whole reference model rests on, made testable here.- 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.
- classmethod from_data_table(table)[source]
Adapt a
gleplot.dataio.DataTable(a loaded.datfile).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.
- class gleplot.DictDataProvider(tables=None)[source]
A
DataProviderover 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.
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:
- label
The series’ label, when it has one – the only user-facing name a series has.
- Type:
str or None
- table_id
The
table_idthe reference names (''for a source whose kind this build does not understand).- Type:
- missing_columns
The column keys that could not be resolved. Empty when the whole table is missing.
- reason
One of
'no-provider','unknown-table','missing-column','unknown-kind','unusable-data'.- Type:
- 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
reasoncan 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” – seegleplot.writer.resolve_figure().
- class gleplot.DanglingSourceWarning(ref)[source]
Warning category for a series skipped because its source is dangling.
Carries the structured record on
.refso a caller that installs awarningsfilter still gets the inspectable object rather than only the rendered message.- Parameters:
ref (DanglingSourceRef)