Quickstart

This guide will walk you through your first VectorScope session.

Starting VectorScope

Option A: PyPI Installation (Recommended)

If you installed via pip install vectorscope, start VectorScope with:

vectorscope

This single command starts the backend API and serves the frontend UI together. Open http://localhost:8000 in your browser. You should see the VectorScope interface with the logo and an empty graph editor.

Command-line options:

vectorscope --port 9000      # Use a different port
vectorscope --host 0.0.0.0   # Listen on all interfaces
vectorscope --reload         # Auto-reload for development

Option B: Development Installation

If you cloned the repository and installed with Pixi, you can run the backend and frontend separately for development with hot-reloading:

# Terminal 1: Backend with auto-reload
pixi run uvicorn backend.main:app --reload --port 8000

# Terminal 2: Frontend dev server
cd frontend && npm run dev

Open http://localhost:5173 in your browser. The frontend dev server provides hot module replacement for faster development.

Configuring Ports

By default, the server runs on port 8000.

To change the backend port:

uvicorn backend.main:app --port 8001

To change the frontend port:

cd frontend && npm run dev -- --port 3000

Note

If you change the backend port, you must also update the proxy target in frontend/vite.config.ts to match.

Your First Visualization

VectorScope initial state

VectorScope initial state with empty graph editor.

Loading Data

When VectorScope starts with no data, you’ll see three options:

  • Load Data - Upload your own CSV, NPY, or NPZ file

  • Create Synthetic - Generate random clustered data

  • Load Dataset - Use a standard sklearn dataset (Iris, Wine, etc.)

Let’s start with the Iris dataset:

  1. Click Load Dataset

  2. Select Iris from the list

  3. VectorScope automatically creates a PCA projection

Exploring the Graph Editor

The default view is the Graph Editor, which shows your data pipeline:

Graph editor with Iris dataset

Graph editor showing the Iris dataset layer.

  • Green node (Iris) - The source data layer (150 points, 4 dimensions)

  • Blue node (PCA) - The projection that creates 2D coordinates

Click on a node to see its configuration in the right panel.

Viewing the Data

Switch to the View Editor tab to see the actual scatter plot:

View editor showing PCA projection

View editor with the Iris PCA projection.

  1. Select a view from the dropdown (e.g., “Iris: PCA”)

  2. The plot shows points colored by their class (setosa, versicolor, virginica)

  3. Hover over points to see their labels

Adding Another View

  1. Go back to the Graph Editor

  2. Click on the Iris layer node

  3. In the config panel, find “Add View”

  4. Select t-SNE and click Add View

Graph with view node

Graph editor showing a layer with a view node attached.

Now you have two projections of the same data. Switch to Viewports mode to see them side by side.

Adding Transformations

You can apply transformations to your data before projecting:

  1. Click on the layer node

  2. In the config panel, click “Add Transformation”

  3. Choose a transformation type (PCA, scaling, rotation, etc.)

Graph with PCA transformation

Graph showing a PCA transformation node creating a derived layer.

The transformation creates a new derived layer that you can project separately. For example, PCA transformation decorrelates your features, which can reveal different structure when you apply subsequent projections.

Exploring Multiple Views

Switch to the Viewports tab to see multiple projections side by side:

Multiple viewports

Viewports mode showing PCA (left) and t-SNE (right) projections of the same data.

This lets you compare how the same points appear in different projections. PCA shows the directions of maximum variance, while t-SNE emphasizes cluster structure.

Exploring Feature Distributions

VectorScope provides 1D views for exploring individual feature distributions.

Density View

To see the distribution of values for a single dimension:

  1. Click on a layer node

  2. Click the “+” button and select Density

  3. Switch to View Editor and select the density view

  4. Use the dimension selector to explore different features

  5. Toggle between KDE (default) and Histogram modes

Density view

Density view showing the distribution of a single dimension using KDE curves. Points are colored by class, making it easy to see how classes separate along each feature.

Box Plot View

To compare feature distributions across classes:

  1. Click on a layer node

  2. Click the “+” button and select Box Plot

  3. Switch to View Editor and select the box plot view

Box plot view

Box plot view showing feature distributions grouped by class. This helps identify which features best separate your data classes.

Violin Plot View

Violin plots combine box plots with density curves to show both summary statistics and the full distribution shape:

  1. Click on a layer node

  2. Click the “+” button and select Violin

  3. Switch to View Editor and select the violin view

Violin plot view

Violin plot view showing distribution shapes for each class. The width of each violin represents the density of points at that value.

Violin plots are particularly useful for:

  • Seeing bimodal or multimodal distributions within classes

  • Comparing distribution shapes across classes

  • Getting both box plot statistics and density visualization in one view

Saving Your Work

  1. Click Save in the toolbar

  2. Enter a name for your session

  3. Your data, projections, and settings are saved

To reload later:

  1. Click Open

  2. Select your saved session

Next Steps