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: .. code-block:: bash 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:** .. code-block:: bash 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: .. code-block:: bash # 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: .. code-block:: bash uvicorn backend.main:app --port 8001 To change the frontend port: .. code-block:: bash 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 ------------------------ .. figure:: _static/images/initial_state.png :alt: VectorScope initial state :width: 100% 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: .. figure:: _static/images/graph_editor.png :alt: Graph editor with Iris dataset :width: 100% 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: .. figure:: _static/images/view_editor.png :alt: View editor showing PCA projection :width: 100% 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** .. figure:: _static/images/graph_with_view.png :alt: Graph with view node :width: 100% 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.) .. figure:: _static/images/graph_with_transformation.png :alt: Graph with PCA transformation :width: 100% 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: .. figure:: _static/images/viewports.png :alt: Multiple viewports :width: 100% 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 .. figure:: _static/images/density_view.png :alt: Density view :width: 100% 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 .. figure:: _static/images/boxplot_view.png :alt: Box plot view :width: 100% 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 .. figure:: _static/images/violin_view.png :alt: Violin plot view :width: 100% 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 ---------- * Learn about :doc:`concepts` - layers, transformations, projections * Explore :doc:`user_guide/loading_data` - work with your own data * Read :doc:`user_guide/transformations` - apply scaling, rotation, etc.