VSPlotter

VSPlotter is a lightweight, high-performance plotting extension for Visual Studio Code. It allows you to quickly create and visualize plots from CSV files directly within your VS Code environment.

Features

• ✅ Supported file types: CSV, TSV, JSON (with custom delimiter support)
• ✅ Create plots from CSV files within VS Code
• ✅ Create AG Grid Tables from CSV files
• ✅ Lightweight and high-performance plotting using uPlot
• ✅ Interactive selection of x-axis and y-axis columns
• ✅ Support for multiple y-axis columns against a single x-axis
• ✅ Automatic row numbering for default x-axis
• ✅ Automatic handling of non-numeric data with enum label generation
• ✅ Saved plot settings to easily recreate plots for multiple CSV files
• ✅ Auto-plot configuration support with JSON file import/export
• ✅ File Explorer integration with automatic file discovery
• ✅ Chart Export: Copy charts to clipboard or save as PNG
• ✅ Plot settings dialog: Edit X/Y columns (including Select all / Unselect all for Y and per subplot group), layout, uPlot series/axes/scales, legend/cursor, and raw opts JSON from the chart toolbar (Settings, gear icon); Save updates the plot tree like Edit Plot Settings and refreshes the open chart. Charts created with Plot from a grid stay linked to that grid: the Data tab uses displayed grid columns (not CSV-only names), chart-side Computed columns are hidden (use grid columns instead), and Save replots from the live grid so row filters and valueGetter columns stay in sync.
• ✅ Plot computed columns (synthetic ids): Default prefix is __vp: (VS Code setting vsplotter.plotComputedColumnPrefix, non-empty; per-plot JSON may set plotComputedColumnPrefix). The chart legend, default axis labels, auto title, and tab title show the id without that prefix (full ids stay in JSON, settings UI, and quick picks). In the chart Settings dialog, Add / Edit opens a dedicated modal (shared with the grid’s Insert Custom Column… flow) for expression vs source, optional dependsOn, and post-transform presets. Expressions are compile-checked (extension host); dependsOn is filled from detected references in params.data["col"], getValue("…"), and params.getValue("…") (bracket form — dot access like params.data.A is not auto-detected). The modal offers Ctrl+Space (Windows/Linux), Cmd+Space (macOS), and @ filtering for column/snippet insertions. Edit Plot Settings → Computed columns & transforms uses the same Expression vs Source split with validation and an editable comma-separated dependsOn step prefilled from those references. Each entry is either a row expr (same idea as grid formulas: params.data, params.getValue, params.prev = previous file row raw fields) or a source column/id copy, plus optional built-in transform: delta / alias diff (same behavior), unary log, log10, log1p, sqrt, abs, exp, sin, cos, tan (radians), min / max / mean (average) / std (population standard deviation over finite values, same as NumPy std default) — each fills every row with that scalar (all null if no finite values). Use dependsOn for raw headers and other synthetic ids so evaluation order is defined; cycles are rejected. Later columns see post-transform values when using params.getValue on earlier synthetics (e.g. mean / std then an expr for μ±kσ bands). Delta/diff on Y: first point is 0 (synthetic anchor for stable uPlot Y scaling), then differences. X delta/diff drops the first chart row so the first plotted X is the first real step and stays numeric for uPlot. Plot transforms use file row order; the grid’s Formula preset (column editor) and context-menu transform actions use the same ids, with delta/diff on AG Grid display order (sort/filter) and min/max/mean/std as constants over filtered visible rows.
• ✅ Overlay Plots: Compare data from multiple files on one chart
• ✅ Summary Statistics: View min/max/mean/median/std dev per column in grids
• ✅ Custom Delimiters: Auto-detect or manually select CSV delimiters (comma, tab, semicolon, pipe)
• ✅ Seamless integration with VS Code's interface

Quick Start

1. Open a .csv file in VS Code
2. Run the command VSPlotter: Create plot from file
3. Select your x-axis and y-axis column(s)
4. View your plot in a new VS Code tab

Commands

• VSPlotter: Show Sample Grid Table: Displays a sample grid to show the extension's capabilities
• VSPlotter: Show Sample Plot: Opens media/data/sampledata.csv with Sin(x) + Cos(x) in one subplot group, EnumTest (enumerated strings) in another, vertical layout, and saved opts so the plot-settings dialog demonstrates subgroups, enums, and the Series / Legend / Cursor tabs
• VSPlotter: Create Plot from file: Creates a plot from the selected CSV file
• VSPlotter: Create Grid Table from file: Creates a grid table from the selected CSV file
• VSPlotter: Overlay Plot from Multiple Files: Select multiple files and overlay their data on a single chart for comparison
• VSPlotter: Save Auto-Plot Configuration - Export current configurations to a JSON file
• VSPlotter: Load Auto-Plot Configuration - Import configurations from a JSON file
• VSPlotter: Open Settings - Quick access to VSPlotter configuration

Keyboard Shortcuts

All shortcuts use Ctrl+Alt (⌃⌥ on Mac) to avoid conflicts with VS Code defaults.

Performance

VSPlotter is built on top of the uPlot charting library, known for its exceptional performance and small footprint. This ensures that VSPlotter can handle large datasets with ease, providing a smooth and responsive plotting experience even for complex visualizations.

For data grid visualizations, AG Grid is used for a full-featured, high-performance spreadsheet-like viewer for CSV files.

Large File Optimizations

• Progressive loading: Datasets above 50K rows load in chunks in the webview; pagination and page size always follow your VS Code settings (vsplotter.gridOptions.*) and optional grid JSON — they are not forced by row count.
• Streaming parser: CSV files larger than 5MB use an incremental streaming parser to reduce peak memory usage.
• Debounced filters: Row and column filter inputs are debounced (200ms) to avoid excessive re-rendering while typing.
• Cached cell rules: Cell class rule functions are pre-compiled once rather than re-created on every cell render.
• Row buffer: 20 rows are pre-rendered above/below the viewport for smoother scrolling.

Requirements

• Visual Studio Code v1.60.0 or higher

Usage Examples

Create a plot from a file

1. Open a .csv file or left-click the file from the Explorer window.
2. Select the VSPlotter: Create Plot from file from the command palette.
3. Select your desired X-Axis (default is the row number).
4. Select 1 or more columns for the Y-Axis.
5. Click OK to create the plot.

• Hover over the graph to see point values.
• Click, hold, and drag to zoom.
• Double click to reset zoom.

Create a plot from a grid table

1. Open a .csv file or left-click the file from the Explorer window.
2. Select the VSPlotter: Create Grid Table from file from the command palette.
3. Select your desired X-Axis in the dropdown menu (default is the row number).
4. Select one or more Y-axis columns by clicking column headers or the name labels next to the sidebar visibility checkboxes (click again to deselect). Shift+click a second header or label to add every visible column between that column and the previous non-Shift click to the selection (order follows the grid’s displayed columns).
5. Optional: right-click the grid and use the context menu — Hide Selected Columns hides the current selection; Hide Other Columns hides everything that is not selected so only those columns remain visible (restore columns with the sidebar checkboxes or Show / Hide All).
6. Click the Plot Selected button to generate the plot.

Plot enumerated (string) data

String data is automatically detected and enumerated for plotting

Reusing Saved Plot Settings

Each unique X and Y-Axis combination is saved under the Saved Plot Settings section of the VSPlotter Plots Tree View within the Explorer tab. These settings can be re-used for separate files with similar column data (e.g. stock data, time series data, etc.).

1. Click on the desired settings under Saved Plot Settings
2. Select a file with the same column data used in the saved settings.

Selecting Saved Plots

Each time a plot is created, it is saved under both File Explorer and Saved Plots section of the VSPlotter Plots Tree View within the Explorer tab.

• Click on the ✚ symbol to create a new plot from the same file
• Click on the 🗂️ symbol to open the file in a Grid Table.
• Click on the 📈 symbol to restore a previously created plot.
• Click on the 🗑️ symbol to delete a saved plot.

Auto-Plot Configuration

VSPlotter now supports auto-plot configurations that can be saved and loaded from JSON files. This allows you to:

1. Create plot configurations once and reuse them across multiple files
2. Save configurations to .vscode/vsplotter.json for workspace-specific settings
3. Export configurations to share with team members
4. Import configurations from other projects
5. Multi-file overlays: use the reserved top-level key "__overlays__" with an array of plot objects that include "overlayFiles" (two or more absolute paths), plus "x", "y", and optional "opts". On load, entries appear under Saved Plots → Overlays and Saved Plot Settings → Overlays (templates without concrete paths).

Subplot Groups

When using subplot layouts (vertical, horizontal, or grid) on a single-file plot or a multi-file overlay (with two or more Y columns), you can group Y-axis columns so that each group shares a single subplot panel:

{
  "x": "Time",
  "y": ["Temp", "Pressure", "Voltage", "Current"],
  "subplots": "vertical",
  "subplotGroups": [
    ["Temp", "Pressure"],
    ["Voltage", "Current"]
  ]
}

This produces 2 subplots instead of 4 — each panel renders its columns overlaid like a subplots: "none" plot. Colors are assigned continuously across all groups. Columns not assigned to any group automatically go into a catch-all panel.

You can also configure groups interactively via Edit Plot Settings → Subplot Groups.

Chart Export

Charts can be exported directly from the plot panel:

1. Open any plot (from a file, saved plot, or overlay).
2. Use the toolbar buttons at the top of the chart panel:
   • Copy to Clipboard – Copies the chart as a PNG image to the system clipboard.
   • Save as PNG – Opens a file dialog to save the chart as a .png file.

This works for both single plots and subplot layouts.

Plot settings (chart webview)

From any chart panel, click Settings (gear icon) in the toolbar to open a modal editor (VS Code–style tabs and Codicons, similar to the grid column settings UI).

• Data – X column and Y columns (populated from CSV headers; for overlay plots, headers come from the first overlay file until you change the file list). For overlays, Overlay files lists the combined paths (Add files… opens a file picker; Remove keeps at least two files). Overlay alignment chooses interpolate (default) vs row index (first file’s X). Use Select all / Unselect all next to Y-axis columns when you want every column on or off the plot quickly.
• Layout – Title, width/height (leave empty for automatic sizing). Subplot layout and optional subplot groups (each group row has Select all / Unselect all) apply to single-file plots and to multi-file overlays when you have two or more Y columns (each subplot stacks the same metrics across overlay files; groups use the same rules as single-file plots). On overlays, the default title (Overlay: … vs …, or Overlay: … when X is the built-in <Row> column) is recomputed when you change X or Y only if the title was still that default for the previous columns; a customized title is kept.
• Series – Per–Y-series line options (label, stroke, fill, width, visibility, gaps, points).
• Axes – Labels, axis side (dropdown: top/right/bottom/left → uPlot 0–3), scale key, stroke, grid; add extra axes if needed.
• Scales – Time/auto flags, direction, numeric min/max range; add custom scale keys.
• Legend / Cursor – Legend and cursor visibility options.
• Advanced – Full opts object as JSON (functions and hooks cannot be round-tripped from the webview).

Save applies changes to saved plot settings (same tree update as the command VSPlotter: Edit Plot Settings) and reloads the chart in the same panel (no second tab). Cancel closes without saving. If the Advanced tab is active when you save, its JSON replaces the structured opts built from the other tabs for that save.

The command VSPlotter: Edit Plot Settings adds Overlay files and Overlay alignment when the item is a multi-file overlay, and Subplots layout / Subplot groups when the overlay has at least two Y columns, so you can change which workspace files are combined (each file must include the current X and Y columns) and how metrics are split across panels.

Overlay Plot from Multiple Files

Compare data from different files side-by-side on a single chart:

1. Run the command VSPlotter: Overlay Plot from Multiple Files from the Command Palette.
2. Select 2 or more files from your workspace.
3. Choose the X-axis column and one or more Y-axis columns.
4. Choose overlay X alignment for this plot: the quick pick reflects vsplotter.defaultOverlayAlignMode when overlayAlignMode would be omitted from saved JSON, explains interpolate vs row index, and stores a per-plot choice (you can change it later in chart Settings → Data or Edit Plot Settings).
5. Each file's data is plotted as a separate series, with the filename prefix in the legend for easy identification.

Overlay alignment (chart Settings → Data, Edit Plot Settings, or JSON overlayAlignMode):

• Workspace default when omitted: set vsplotter.defaultOverlayAlignMode in VS Code Settings to interpolate or index. If a saved overlay omits overlayAlignMode, that setting is used. Per-plot overlayAlignMode in JSON always overrides.
• Interpolate to common numeric X: sorted union of all files’ numeric X values; each Y series is linearly interpolated onto that grid (null outside that series’ X range; no extrapolation). Suited to different sample rates or timestamps on a shared numeric axis.
• Row index (first file’s X) ("overlayAlignMode": "index"): only the first file’s X; Y values align by row index (legacy). Best when rows match across files or X is <Row>. Mismatched row lengths are padded/truncated (with a console warning); sampled X mismatch across files logs a hint to try interpolate.

If interpolation is not possible (no finite numeric X/Y pairs), VSPlotter falls back to row-index mode and shows a warning.

The overlay is saved automatically under Saved Plots → Overlays and Saved Plot Settings → Overlays, and is included when you use Save Auto-Plot Configuration (under the "__overlays__" key). In .vscode/vsplotter.json, use the "__overlays__" key or the empty pattern "" for overlay entries; regex file patterns skip overlay objects when applying config per file (by design). Click an overlay entry or run VSPlotter: Open Saved Overlay Plot to reopen it. Edit, duplicate, delete, and copy JSON work like other saved plots.

Summary Statistics

When opening a grid table, a Summary Statistics panel appears above the data grid:

• Click the Summary Statistics header to expand/collapse the panel.
• Shows per-column statistics for numeric columns: Count, Nulls, Min, Max, Mean, Median, and Std Dev.
• Text columns show count and null count.

Custom Delimiter Support

VSPlotter supports CSV files with different delimiters:

• Auto-detect (default): Automatically detects comma, tab, semicolon, or pipe delimiters by analyzing the first few lines.
• Manual override: Set vsplotter.csvDelimiter in settings to force a specific delimiter:
  • , (comma – standard CSV)
  • \t (tab – TSV files)
  • ; (semicolon – common in European locales)
  • | (pipe)

Known Issues

• When opening large files (> 50 MB), the grid table may sometimes fail to render certain columns. This should not affect plotting.

Release Notes

See the CHANGELOG for details on each release.

Acknowledgements

VSPlotter is powered by uPlot and AG Grid.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Enjoy plotting with VSPlotter!