GoFish Graphics

Tutorial: From a Rectangle to a Polar Ribbon ​

Welcome to GoFish! In this tutorial we'll start with a rectangle and gradually turn it into a polar ribbon chart. Along the way, we'll encounter the pieces that make up a GoFish chart: shapes, graphical operators, scales, and coordinate transforms.

To start, duplicate this tab to follow along in the live editor!

import "./styles.css";

document.getElementById("app").innerHTML = `
<h1>Hello world</h1>
`;
Open on CodeSandboxOpen Sandbox

The Dataset ​

The dataset we'll work with in this tutorial is counts of the number of fish caught in different lakes.

ts
type SeafoodData = {
  lake: "Lake A" | "Lake B" | "Lake C" | "Lake D" | "Lake E" | "Lake F";
  species: "Bass" | "Trout" | "Catfish" | "Perch" | "Salmon";
  count: number;
};

const seafood: SeafoodData[] = [
  {
    lake: "Lake A",
    species: "Bass",
    count: 23,
  },
  {
    lake: "Lake A",
    species: "Trout",
    count: 31,
  },
  {
    lake: "Lake A",
    species: "Catfish",
    count: 29,
  },
  ...
];

The Starter Code and Rectangle Shape ​

Let's take a look at the starter code. First, we grab a DOM element that will serve as the container we render into:

ts
const root = document.getElementById("app");

Next, we render a rectangle into it!

ts
chart(seafood)
  .mark(rect({ fill: color.green[5] }))
  .render(root, { w: 500, h: 300 });

chart() creates a chart from data. We pass an array with a single object containing the rectangle's position and size. Then we use .mark() to specify that we want to render rect shapes. The fill parameter specifies the color. We are using a green from GoFish's default color palette for this chart. Try changing green to blue or changing 5 to a higher or lower number.

Finally, we call .render to render the chart to the DOM, specifying a width and height for the entire graphic.

Bar Chart ​

The first thing we'll do is compare the number of fish in each lake. We can use a bar chart for that. To turn our stack of rectangles into a bar chart, we'll need to take a few steps. First, we'll just create one bar for each lake in the dataset:

ts
chart(seafood)
  .flow(spread("lake", { dir: "x" }))
  .mark(rect({ w: 32, h: 300, fill: color.green[5] }))
  .render(root, { w: 500, h: 300 });

Note that we've added w: 32 and h: 300 to the rectangles to set manually set their widths and heights.

The spread operator ​

We've introduced a spread graphical operator in the .flow() method that spaces its children apart. The spread operator groups the data by the field we specify (in this case, lake) and creates one shape for each group. Here, we're spreading along the x direction with dir: "x", which will create six rectangles (one for each lake).

Data-Driven Fields ​

To turn this into a bar chart, we'll change the h encoding of the rect shape to a data-driven quantity.

ts
chart(seafood)
  .flow(spread("lake", { dir: "x" }))
  .mark(rect({ w: 32, h: "count", fill: color.green[5] }))
  .render(root, { w: 500, h: 300 });

Inferred Fields ​

We remove the w field from our spec to have GoFish infer it for us. GoFish uses the overall size of the chart we gave to render (as well as information from the graphical operators) to determine the width of each rectangle.

ts
chart(seafood)
  .flow(spread("lake", { dir: "x" }))
  .mark(rect({ h: "count", fill: color.green[5] }))
  .render(root, { w: 500, h: 300 });

Axes ​

Great! Now let's talk about how to add axes to your chart. GoFish can automatically infer axes from your spec as long as you put axes: true in the render method like so:

ts
chart(seafood)
  .flow(spread("lake", { dir: "x" }))
  .mark(rect({ h: "count", fill: color.green[5] }))
  .render(root, { w: 500, h: 300, axes: true });

Voila! Now we have a y-axis and labels for each of the bars.

Stacked Bar Chart ​

Now we have a sense of the number of fish in each lake. It seems like Lake B has the most. What if we broke this down by species? We can use a stacked bar chart for that. A stacked bar chart is kinda like a normal bar chart, except instead of a line of rectangles, it's a line of stacked rectangles.

ts
chart(seafood)
  .flow(
    spread("lake", { dir: "x" }), //
    stack("species", { dir: "y", label: false })
  )
  .mark(rect({ h: "count", fill: color.green[5] }))
  .render(root, { w: 500, h: 300, axes: true });

We've added the stack operator to stack rectangles on top of each other vertically. It's pretty similar to spread, but doesn't put any spacing between the shapes it lays out.

Now we have a rectangle for each species in each lake. But we can't tell the fish apart! Let's add a color encoding so that each rectangle's color corresponds to the species of fish.

ts
chart(seafood)
  .flow(
    spread("lake", { dir: "x" }), //
    stack("species", { dir: "y", label: false })
  )
  .mark(rect({ h: "count", fill: "species" }))
  .render(root, { w: 500, h: 300, axes: true });

Much better! Notice that we also have a color legend telling us what each color represents. This was created automatically because have set axes: true on the render method.

Ribbon Chart ​

Data Transformation ​

Now we have a sense of the break down by lake, but these lakes are connected by a river! It's hard to track how the proportion of fish changes between each lake. Let's first try ordering the bars by their counts:

ts
chart(seafood)
  .flow(
    spread("lake", { dir: "x" }),
    derive((d) => orderBy(d, "count")),
    stack("species", { dir: "y", label: false })
  )
  .mark(rect({ h: "count", fill: "species" }))
  .render(root, { w: 500, h: 300, axes: true });

We've used the derive operator, which lets us add data transforms into our flow!

Some trends pop out. The salmon population spikes between lakes B and C while catfish appear to decline. We can make these trends more obvious by connecting rectangles of the same species together.

Layering and Selection ​

ts
layer([
  chart(seafood)
    .flow(
      spread("lake", { dir: "x" }),
      derive((d) => orderBy(d, "count", "desc")),
      stack("species", { dir: "y", label: false })
    )
    .mark(rect({ h: "count", fill: "species" }))
    .as("bars"),
  chart(select("bars"))
    .flow(group("species"))
    .mark(area({ opacity: 0.8 })),
]).render(root, {
  w: 500,
  h: 300,
  axes: true,
});

Great! This is already a ribbon chart but it's a little funky. We'll fix the funkiness in a second, but first let's understand what's going on.

To add some ribbons, we first created a layer so we can add the ribbons as a second layer. Then we name the marks in the first layer using as("bars") and select those marks in the second layer. We group them by species using group("species"), and finally draw an area mark for each group.

To make this look more like a traditional ribbon chart, all we have to do is change the spacing of the spread operator.

ts
layer([
  chart(seafood)
    .flow(
      spread("lake", { dir: "x", spacing: 64 }),
      derive((d) => orderBy(d, "count", "desc")),
      stack("species", { dir: "y", label: false })
    )
    .mark(rect({ h: "count", fill: "species" }))
    .as("bars"),
  chart(select("bars"))
    .flow(group("species"))
    .mark(area({ opacity: 0.8 })),
]).render(root, {
  w: 500,
  h: 300,
  axes: true,
});

Polar Ribbon Chart ​

Finally it's time to make our polar ribbon chart! To do so, we'll add a clock coordinate transform to the layer and adjust the parameters to spread so that it looks better in polar space.

ts
layer({ coord: clock() }, [
  chart(seafood)
    .flow(
      spread("lake", {
        dir: "x",
        spacing: (2 * Math.PI) / 6,
        mode: "center",
        y: 50,
        label: false,
      }),
      derive((d) => orderBy(d, "count")),
      stack("species", { dir: "y", label: false })
    )
    .mark(rect({ h: "count", fill: "species" }))
    .as("bars"),
  chart(select("bars"))
    .flow(group("species"))
    .mark(area({ opacity: 0.8 })),
]).render(root, {
  w: 500,
  h: 300,
  transform: { x: 200, y: 200 },
  axes: true,
});

What's next? ​

Go check out some of our examples!