02viz

Geospatial Visualization Studio — multi-engine chart, diagram, and label studio • v0.14.2

1. Overview

02viz transforms the QGIS environment into a comprehensive data visualisation studio. It provides a single dock with three tabs—Charts, Map Diagrams, and Labels—all sharing a common layer and data selector. Four rendering engines (two zero-dependency offline JavaScript engines plus an optional Python engine) produce interactive, publishable charts from QGIS vector layers or external tabular data (CSV, XLSX, ODS, GPKG, DBF). The plugin runs entirely offline with no accounts, no network, and no mandatory external Python dependencies.

The plugin ships with bundled, vendored copies of Apache ECharts, Plotly.js, Vega, and Vega-Lite in web/. The chart-to-map selection bridge uses the browser's document.title as a click-event transport channel—a design driven by the observation that addToJavaScriptWindowObject causes access violations in WebCore during page commit on Qt 5.15's QtWebKit fork. QWebChannel exists only on QtWebEngine, making titleChanged the single cross-platform signal for chart-to-map interaction.

2. Theoretical Foundations

2.1 The Grammar of Graphics

The plugin's architecture follows Wilkinson's (2005) Grammar of Graphics, which decomposes statistical graphics into independent components: data, aesthetic mappings, geometric objects, scales, statistical transformations, coordinate systems, and facets. The spec assembly layer (core/transform.py and dock.py) produces a data dictionary with typed rows and metadata, which each engine reinterprets through its own rendering primitives. This separation of data shaping from rendering is the central architectural principle—every engine exposes only build_html(spec) → str, consuming the same data structure and producing a fully self-contained HTML document.

Vega-Lite (Satyanarayan et al., 2017), one of the four engines, is a direct realisation of the Grammar of Graphics as a declarative JSON specification language. Its compiler maps visual encoding channels to lower-level Vega rendering directives, providing theoretical continuity from Wilkinson's abstract framework to an executable visualisation. The plugin exposes a custom Vega-Lite spec editor, allowing users to directly manipulate the declarative specification.

2.2 Exploratory Data Analysis

The Smart Assistant and Explore Dashboard operationalise Tukey's (1977) framework for exploratory data analysis (EDA). Fields are classified into numeric, categorical, and identifier categories; visualisations are selected based on the data type combination. This follows Tukey's principle that visual summaries should precede formal modelling. The Explore Dashboard produces KPI cards, histograms, box plots, correlation matrices, and scatter plots in a single operation, enabling rapid assessment of distribution shape, central tendency, spread, association, and outliers.

2.3 Perceptual Principles

The plugin follows Cleveland and McGill's (1984) ranking of graphical perception accuracy. Position along a common scale (bar charts, line charts) is used for the most critical comparisons. Angle (pie charts) occupies a lower perceptual tier and is recommended only for part-to-whole comparisons with few categories. Area (bubble charts) uses square-root scaling via transform.bubble_sizes(): radii follow \(r \propto \sqrt{v}\) so that perceived area—not radius—is proportional to the data value, correcting the systematic underestimation that occurs with linear radius scaling.

3. Rendering Engines

3.1 Apache ECharts Engine

ECharts (Li et al., 2018) is a declarative framework optimised for interactive web exploration. The plugin's ECharts engine (engines/echarts.py, 568 lines) produces self-contained HTML with the library inlined. It uses the timeline component for animation, markLine and markArea for reference overlays, and custom renderItem functions for violin plots (polygon rendering) and error-bar whiskers. As the only engine with full ES5 compatibility, it is the default on QGIS builds using Qt 5.15's QtWebKit fork.

3.2 Plotly.js Engine

The Plotly engine (engines/plotly.py, 466 lines) uses Plotly.js's frames-and-slider animation with play/pause updatemenus. Overlays are rendered as layout.shapes (lines and rectangles) with layout.annotations. Cross-filter highlighting uses Plotly.restyle() with per-trace selected.marker.opacity and unselected.marker.opacity attributes. On WebKit-only QGIS builds, a styled "explainer" fallback page informs the user why the panel is blank and offers the options of switching to ECharts, exporting to HTML, or opening in the system browser.

3.3 Vega-Lite Engine

The Vega-Lite engine (engines/vegalite.py, 573 lines) compiles declarative JSON specifications to Vega at runtime via vegaLite.compile(). It supports 14 of 17 chart types; treemap, sunburst, and radar are excluded because these hierarchical and radial layouts are not part of the Vega-Lite grammar. Users can edit the generated JSON specification directly with validation before rendering. Data rows carrying feature IDs are injected as a named dataset o2viz. The violin chart workaround avoids the order channel, using a ranged-area mark with re-paired polygon half-points to prevent the facets from collapsing to zero width.

3.4 Matplotlib / Seaborn Engine

The Matplotlib engine (engines/mpl.py, 276 lines) is the only engine with optional Python dependencies. It imports matplotlib and seaborn lazily, uses matplotlib.use("Agg") for headless rendering, and applies seaborn's set_theme(style="whitegrid") when available. Output is an 8.2" x 5.0" figure at 150 DPI, base64-encoded as PNG. Eleven chart types are supported. Optional dependency status is detected at startup via core/requirements.py without any pip invocation.

4. Chart Types (17)

4.1 Bar and Scatter Charts

Bar charts encode numeric values using position along a common scale, the highest-accuracy channel in Cleveland and McGill's hierarchy. Grouped bars use the Group field for multi-series display; stacked bars use the stacked checkbox for additive composition. The Top-N control collapses categories beyond N into "Other".

Scatter plots display bivariate numeric relationships with optional group-colouring and least-squares trend line: \(\beta = S_{xy} / S_{xx}\), \(\alpha = \bar{y} - \beta\bar{x}\). Bubble charts add a third numeric dimension with square-root-scaled radii: \(r = r_{\min} + (r_{\max} - r_{\min}) \sqrt{(v - v_{\min})/(v_{\max} - v_{\min})}\). During animation, bubble radii are scaled globally so the same value maps to the same size across all frames.

4.2 Histograms and Kernel Density Estimation

Histograms use equal-width binning via stats.histogram(): bin width \(w = (x_{\max} - x_{\min}) / k\), index \(i = \min(\lfloor (v - x_{\min}) / w \rfloor, k-1)\).

Kernel density estimation uses a Gaussian kernel with Silverman's (1986) rule-of-thumb bandwidth:

The grid extends one bandwidth past the data range so the density tapers to approximately zero at boundaries. All computation is pure Python—no numpy, scipy, or pandas dependency.

4.3 Box Plots and Violin Plots

Box plots display the five-number summary (min, Q1, median, Q3, max) via linear-interpolation quantiles: for position \(p = q(n-1)\), integer index \(i = \lfloor p \rfloor\), fraction \(d = p - i\), the quantile is \(x_{[i]}(1-d) + x_{[i+1]}d\). Outlier detection uses Tukey fences: values outside \([Q_1 - 1.5 \times \mathrm{IQR}, Q_3 + 1.5 \times \mathrm{IQR}]\).

Violin plots build on KDE: transform.violin_rows() computes per-group density, then constructs a closed polygon—the left half at [midpoint - half_width * d/peak, y], right half mirrored. The resulting shape reveals multimodality, skewness, and tail behaviour invisible in a box plot.

4.4 Pareto and Other Charts

Pareto charts operationalise Juran's (1954) principle: categories are sorted descending by value, cumulative share \(s_i = \sum v_j / \sum v \times 100\) is overlaid as a line. Treemap and sunburst charts use two-level nested hierarchies built by transform.tree_rows(), rendering as ECharts or Plotly hierarchical layouts. Radar charts compute per-axis maxima padded by 5% via transform.radar_axis_maxes().

5. Charts Tab

5.1 Data Specification

The shared data card provides: a QgsMapLayerComboBox filtered to vector layers, an external file loader (CSV, XLSX, ODS, GPKG, DBF), a "selected features only" checkbox (auto-refreshes on selectionChanged), and a "live refresh" checkbox (re-renders on layer edit, capped at 100,000 rows). The last I/O directory persists via QSettings("zero2viz/last_io_dir").

5.2 Field Classification

The field classifier (core/fields.py) assigns each attribute: numeric (≥60% numeric with >8 distinct values), categorical (≤30 distinct values, unless all unique with >6 rows), or skip (identifiers matching fid, id, gid, uuid, objectid, *_id, *_key). The "Suggest a chart" button triggers assistant.suggest_chart() with priority heuristics: two numeric fields with \(|r| \ge 0.4 \rightarrow\) scatter+trend; categorical+numeric \(\rightarrow\) mean bar; categorical only \(\rightarrow\) count bar; numeric only \(\rightarrow\) histogram.

5.3 Themes and Palettes

5.4 Chart-to-Map Selection Bridge

6. Statistical Methods

6.1 Aggregation and Correlation

All aggregation is pure Python in transform.py: Count, Sum, Mean (\(\bar{x} = \frac{1}{n}\sum x_i\)), Median (linear interpolation), Min, Max. The Pearson correlation by stats.pearson() uses the standard formula with zero-variance degeneracy checks:

6.2 Skewness and Outliers

Adjusted Fisher-Pearson sample skewness:

The Explore Dashboard reports skewness with a log-transform hint when \(|g_1| \ge 0.5\). Outlier counts use Tukey's inner fences.

7. Map Diagrams Tab

8. Labels Tab

9. One-Click Explore Dashboard

10. Animation (Play Axis)

11. Reference Overlays

12. Smart Chart Assistant

13. Chart Presets

14. Controls Summary

Shared Data Card

Charts Tab Controls

Map Diagrams Tab Controls

Labels Tab Controls

15. Workflow Guide

1. Click the 02viz toolbar icon to toggle the dock.
2. Data: Select a vector layer or load external file. Optionally enable "selected features only" or "live refresh".
3. Charts: Choose engine (ECharts recommended). Select chart type and bind fields. Click Suggest a chart for automatic recommendations. Set aggregation, bins, Top-N. Click Render chart. Click elements to select features. Export as HTML/SVG/PNG/PDF.
4. Diagrams: Switch to Diagrams tab. Check fields, choose type/size/normalisation. Click Apply to layer.
5. Labels: Switch to Labels tab. Choose fields, configure formatting, verify in preview. Click Apply to layer.
6. Explore: Click "Explore layer" for full statistical dashboard. Use Tile Picker to toggle tiles.
7. Animation: Select an "Animate by" field. Chart renders with timeline controls. Optionally set speed.
8. Presets: Save/load chart configurations. Fields remap by name across layers.

16. Technical Notes

• Pure-Python statistics: All aggregation, histogram, Pearson r, KDE (Silverman bandwidth), boxplot (linear-interpolation quantiles), skewness (adjusted Fisher-Pearson), outlier detection (Tukey 1.5×IQR), and min-max normalisation. Only the Matplotlib engine has optional Python dependencies.
• Data shaping: Group-by, pivot (category × series), heatmap matrix, treemap/sunburst hierarchies, Top-N with "Other" collapse, per-frame slicing for animation, bubble sqrt-scaling, least-squares trend line.
• Engine isolation: Every engine exposes only build_html(spec) → str. Never touch Qt. Testable in pure Python. Usable for batch export.
• WebView fallback: QtWebEngine → QtWebKit → system browser. Plotly/Vega-Lite on WebKit shows styled explainer page.
• Dock styling: Explicitly locked light theme for Qt5/Qt6 consistency.
• SmartModeler bridge: v0.14.0 adds smartmodeler_suggest_chart(layer_id) for integration. Narrow, reviewed interface: no file paths, URLs, exports, or feature values exposed.
• Accessibility: All buttons have accessibleName/accessibleDescription; TabFocus policy.
• QGIS compatibility: 3.28–4.99. Zero external Python dependencies. Bundled JS libraries inlined for fully offline operation.

17. Literature

1. Wilkinson, L. (2005). The Grammar of Graphics (2nd ed.). Springer. DOI: 10.1007/0-387-28695-0
2. Tufte, E. R. (1983). The Visual Display of Quantitative Information. Graphics Press.
3. Tukey, J. W. (1977). Exploratory Data Analysis. Addison-Wesley.
4. Cleveland, W. S. & McGill, R. (1984). Graphical perception: Theory, experimentation, and application to the development of graphical methods. Journal of the American Statistical Association, 79(387), 531–554. DOI: 10.1080/01621459.1984.10478080
5. Satyanarayan, A., Moritz, D., Wongsuphasawat, K., & Heer, J. (2017). Vega-Lite: A grammar of interactive graphics. IEEE Transactions on Visualization and Computer Graphics, 23(1), 341–350. DOI: 10.1109/TVCG.2016.2599030
6. Hunter, J. D. (2007). Matplotlib: A 2D graphics environment. Computing in Science & Engineering, 9(3), 90–95. DOI: 10.1109/MCSE.2007.55
7. Li, D., Mei, H., Shen, Y., Su, S., Zhang, W., Wang, J., Zu, M., & Chen, W. (2018). ECharts: A declarative framework for rapid construction of web-based visualization. Visual Informatics, 2(2), 136–146. DOI: 10.1016/j.visinf.2018.04.011
8. Silverman, B. W. (1986). Density Estimation for Statistics and Data Analysis. Chapman & Hall. DOI: 10.1007/978-1-4899-3324-9
9. Wong, B. (2011). Points of view: Color blindness. Nature Methods, 8(6), 441. DOI: 10.1038/nmeth.1618
10. Juran, J. M. (1954). Universals in management planning and controlling. Management Review, 43(11), 748–761.