Skip to content

tutorial.md

Latest commit

 

History

History
108 lines (64 loc) · 4.73 KB

tutorial.md

File metadata and controls

108 lines (64 loc) · 4.73 KB
Raw

Tutorial: Explore your first tree in ArborView

This lesson walks you from a blank browser tab to confidently reading a decision tree on screen. By the end you will have the app open and will understand what every part of the screen is telling you.

You do not need R for this tutorial. ArborView ships with sample datasets, and we will explore one of them — a small regression tree built from R's built-in mtcars data.

Time: about 10 minutes. You will need: a web browser. Node.js 18 or newer (this includes npm) only if you choose to run locally in Step 1.

Step 1 — Open the app

There are two ways to open ArborView. Pick whichever suits you — every later step is identical.

Option A: Use the deployed app (nothing to install)

Visit https://arborview-delta.vercel.app/ in your browser.

Option B: Run it locally

Not sure if Node is installed? Run node --version. If you see a version number of 18 or higher, you are ready. If the command is not found, install Node from https://nodejs.org and reopen your terminal.

Clone the repository (or download it), install the front-end packages, and start the development server:

git clone https://github.com/jrkasprzyk/ArborView.git
cd ArborView
npm install
npm run dev

npm install reads package.json and downloads D3, the tooltip library, and the Vite build tool into a local node_modules/ folder. This runs once; you will not repeat it each session.

npm run dev compiles the app with Vite and prints a local URL, usually:

  ➜  Local:   http://localhost:5173/

Open that URL in your browser.

What you should see

Either way, the page shows the ArborView header with a dataset dropdown, a large canvas, and a sidebar on the right.

Step 2 — Choose the mtcars dataset

In the header dropdown, select mtcars mpg (regression).

A tree appears on the canvas. This tree predicts a car's fuel economy (miles per gallon) from its other attributes. Because it is a regression tree, each leaf predicts a number — the average mpg of the cars that landed there.

Take a moment to notice:

  • Circles are nodes. Bigger circles contain more training observations.
  • Lines are splits. Each line is labelled with the rule that sends cars left or right, for example cyl >= 5.
  • The top node is the root — every car starts here before the tree sorts it down to a leaf.

Step 3 — Hover a node to read its statistics

Move your mouse over any node. A tooltip appears, and the sidebar panels update to describe that node:

  • Decision path lists the rules from the root down to this node, ending with its prediction.
  • Node detail shows the sample count, the predicted mpg, impurity (MSE here), complexity, and deviance.

Hover a few different nodes and watch how the predicted value changes as you move toward the leaves. Deeper leaves describe narrower, more specific groups of cars.

Step 4 — Click a node to pin it

Hovering is exploratory; clicking commits. Click a leaf node near the bottom of the tree.

The sidebar now stays focused on that node even as you move your mouse elsewhere. This lets you read a leaf's details carefully — its decision path is the full "story" of how a car with those attributes is predicted to get that mpg.

Click the canvas background to unpin.

Step 5 — Pan, zoom, and tidy the layout

The canvas is interactive:

  • Pan: click-and-drag on empty canvas background.
  • Zoom: scroll your mouse wheel.
  • Reposition a node: click-and-drag a single node. Its edges and rule labels follow in real time.

Dragging a node only moves it on screen — it never changes the tree's structure or statistics. Use it to untangle crowded branches.

Step 6 — Read the variable-importance chart

Find the Variable importance panel in the sidebar. Each bar shows how much a predictor contributed among the variables that actually appear in tree splits, normalised so the most important shown variable fills the full width.

Notice that an important variable is not always the one used at the very top split — a predictor can earn importance by being reused at several deeper splits.

What you have learned

You can now:

  • open ArborView in the browser (deployed, or locally with npm run dev),
  • load a dataset and read the tree, tooltip, and sidebar panels,
  • pin a node and trace its decision path,
  • pan, zoom, and rearrange the canvas,
  • interpret the variable-importance chart.

Where to go next