This course has been updated! We now recommend you take the Introduction to D3.js course.

Check out a free preview of the full Introduction to Data Visualization with d3.js v4 course:
The "d3-shape Module" Lesson is part of the full, Introduction to Data Visualization with d3.js v4 course featured in this preview video. Here's what you'd learn in this lesson:

The d3-shape library is proviudes graphical primitives for visualization, such as lines and areas. This library generates the value of the SVG d attribute, which is a string which contains a series of path descriptions, for creating curves and angles for line chart or pie charts.

Get Unlimited Access Now

Transcript from the "d3-shape Module" Lesson

>> Shirley Wu: Sometimes, maybe you don't want to do it by hand, because it's like still a lot of work, and that's when this thing called D3 shapes, the shapes library the module comes in super super useful. So this one D3 shape is the module and then, it essentially has some convenience functions for you, for drawing like pie charts, or line charts or aerial curves these are some of the things that it helps you do, and this module is absolutely amazing because It takes care of figuring out that D attribute, so you don't have to.

>> Shirley Wu: So like all of these you can like, you just pass in data and they like figures out what the D attribute should be and then you take that and then you apply it and then you just get this. So basically, d3-shape calculates the path attribute so we don't have to.

[00:01:02] So for example, this little line chart, this is actually the same temperature data that we were doing with the bar chart. So,
>> Shirley Wu: This, the de-attribute for this line chart looks like this. And that's definitely not something that you want to write by hand, ever.
>> Shirley Wu: So d3 shapes makes this easy.

[00:01:35] And here are some other examples of d3 shapes. So this is basically an area chart. Actually, let me, can you guys see that fine? So these are like area charts and then just different curves that connect the different points like this one's kind of curvy and this one's block e.

[00:02:00] And those are, and that's something that you can also specify with a curve generator with D3 shape. So there's this thing called Curves, and then if each of these points are a data point. If each of these points is a datum in data set, how do you want them to be connected together?

[00:02:27] So these are all of the different curves that are provided. Basically, makes making pretty looking things really easy, because all you have to do is like call this function and then for just the matter of switching between different curves, you can get these different effects of blocky or curvy.

[00:02:51] So yeah. Let's get into just two of the shapes. I want to cover D3.line which helps you make the line chart. And then I want to quickly cover. Actually, if we have time now, I'll quickly cover the pie chart, cuz I feel like I feel like even though we bash on Python just a lot, like with the database community, for some reason, we end up using them a lot anyway.

[00:03:19] And if we don't don't have time to cover it then, at least it is in the slides for you to kinda tag on and look at. So, yeah, this is d3.line and let's say this is our data set. It looks a little bit different from. Actually, it should look the same as previous.

[00:03:38] So we have our date, that could be our X axis. And we have some sort of a value that could act as our Y axis. Each of these objects in the array will turn into a point in our line chart. So this is the input, the array of objects and all that d3.line, actually, all that D3 line does for us is figure out the path attribute such that it just draws a line through all of these points.

[00:04:13] And that's all it's doing underneath the hood. And so, like once we, how we use it is, right here, this is how we define it. Sorry. So we say d3.line, and it just asks for two things. How do I get my X and how do I get my Y?

[00:04:35] So this should look very similar to,
>> Shirley Wu: The code is wrong. I will fix that later. But this should look very similar to the bar chart we just did, where for the X, we returned X scale and pass and do that date. And then, for the Y, we use Y scale and pass in the value.

[00:04:59] And so this tell us D3 how it's supposed to get the x and values of of each point so that it can draw the line between it. And then once we have that defined this also returns a function and when you see happen here is all we have to do is say attribute D, give me back, call line with our data.

[00:05:30] And this will give us back that really ugly. This will essentially output. This.
>> Shirley Wu: And then it will draw this. So that whole code snippet would draw that.
>> Shirley Wu: Yeah.
>> Shirley Wu: And that's there, all there is to d3.line actually for just that, those six lines or so, you get the beauty of that line chart.

[00:06:04] I guess there wasn't that much to it. So we'll go into the pie chart now.
>> Shirley Wu: [LAUGH] I just want to make sure the d3 line is all good. It's like a super straightforward but super powerful function. Okay, so pie chart is a little bit more involved, in that there's actually two parts to it.

[00:06:25] For you to, for most people, for you to make a pie chart, with d3, the first part being this d3.pie. And all that does is given your data, let's say this is your data
>> Shirley Wu: If you say d3.pie() and then pass in that data, all it does is it figures out what the start angle and end angle should be.

[00:06:59] So it's basically saying, okay, so each of these data points are a pie slice, right? So the one will become a pie slice, and then the two will become a pie slice, etc. So if they are the pie slices, what should be start and end angle for my one, and what should be start and end angle for my two, so that's all that pie does.

[00:07:26] Figure out the start and end angle for each of your data points in your data set. So that you don't have to.
>> Shirley Wu: And then you take that output,
>> Shirley Wu: And you pass it into something called d3.arc. So what d3.arc does is it takes in your startAngle, your endAngle, and you also need to provide it with an inner and outerRadius.

[00:07:57] So in this case, I'm just saying my inner radius, I want that to start at 0, and then the outer radius is 100 pixels. If you want one of those donut shapes, you could just be like I want my inner radius to be 50 or 60 or whatever, as long as it's less than your outer radius, and that's how people make those donut shapes.

[00:08:18] And then you like, you take that start and angle that you got from your pie. In this case, it's as simple as saying like, my start angle is d.startangle. And the angle is g.endangle. And this, and in calling arcpie so, calling arg, d3 arg, on that data gives you this.

[00:08:49] Which looks like that. So, each of those.
>> Shirley Wu: So, each of these arc pies will give you one of these arcs.
>> Shirley Wu: Yeah, so this is exactly that one, one, two, whatever, so it's like one, one, two, three, something, something. Yeah, that's all there is to a pie chart with D3.

>> Shirley Wu: And then here is the code, the whole code because it kind of gloss over a little bit about like and you can,
>> Shirley Wu: So here what's happening is, here's my data. I applied d3.pie to my data to get like the start and angle for all of the each of these and that should give me, an array of objects with star and angles.

>> Shirley Wu: Yeah, so it's an array with the original data star with an angle and then if you want to provide padding there is also the padding, and then I'm defining my ark, and I'm saying slairt all the paths. Pass him this a ray of object with start an angles inquiry of path for each of those.

>> Shirley Wu: So this is what's happening here, so then that creates the eight paths on the screen. And then call arc on each of those so this is essentially,
>> Shirley Wu: What's happening under the hood is d yeah. So Is then calling arch each single one of those like pie slices thus creating this pie chart.

[00:10:56] And that was just,
>> Shirley Wu: 20 lines.
>> Shirley Wu: Gets you this pie chart. So that's what d3 shape is great for.
>> Speaker 2: So for that one-
>> Speaker 3: Can you tell me a little about that colors that you picked there, or what palettes are available? How do you set it in your own palette?

>> Shirley Wu: Okay, so yeah, I've been ignoring the whole colors thing. So D3 has some built in color schemes for you, and it's actually under the scale module.
>> Shirley Wu: Because colors are essentially just category scales, right? So there is essentially some, I think the way to think about it is, these are basically just, d3 has this defined for you, all of these.

[00:12:00] And you use this as the range, the output. So you pass in some sort of, you don't actually need to pass in, okay. You can use any of these as your colors. And the way that you use it is essentially you say create an ordinal scale, because my inputs and outputs are discrete and then this line is actually equivalent to saying,

>> Shirley Wu: It's actually equivalent to just saying this. The beauty of it is is that we don't have to specify a domain when it's ordinal. Because as you start, I won't go into the details of that one. But it's basically saying, I want you to output these colors. And that's how you can use the colors that are built into D3.

[00:12:57] You can also define your own colors, but this is a super simple quick way, yeah. And then, so you have a question?
>> Speaker 2: So I was just trying to think through, so it's this one instead of passing your data directly through the SVG, do you have this intermediary step with the arc?

>> Shirley Wu: Yeah.
>> Speaker 2: But that's not the actual path this itself the arc is generating.
>> Shirley Wu: Sorry the last part, can you say that again?
>> Speaker 2: So your data gets turned into angles and then you pass it to that arc.
>> Shirley Wu: We create this arc function and that gets passed into that arc yeah.

>> Speaker 2: Okay you created an arc function. And then, but that's not actually, that's helping you generate the path and ultimately helping you determine where the path needs to sit.
>> Shirley Wu: Yes, what the path should look like. So actually, maybe it would helpful if I, because you guys have seen, maybe this will be helpful if I console.log.

[00:14:02] And this is why I was like, console.log everything because it really helps. So let's console.log the data, and let's also console.log what arc and pass in the data will look like.
>> Shirley Wu: So this is what D3 is seeing as it's looping through all of the elements. It's essentially our data is that object with the start and endAngle, and once you call arc on it, it gives back this path command.

[00:14:38] Thing that then get set on the D attribute. So I think I go to think about these things is like SVG. So pretty much a lot of the things that D3 helps you do is like SVG or a canvas likes things in a certain like there's the d attribute that is specified.

[00:15:07] So svg has a certain spike, and then D3 is just basically helping you get your data and translate that data into what svg takes in and what it specifies. And that's how you can think of everything in the D3 library, almost everything. So what you were saying before, like if our data is just this array or like an array of objects, all D3 is doing is helping us get this to this down here that SVG can then use to render.

[00:15:44] And it just so happens that getting this to that actually requires an intermediary that get you this start and end angles. And there's actually a lot of really, and I think it's quite genius why it's pulled apart, into pie and arc, because they are times when you might only need pie, and there are times when you might only need arc.

[00:16:06] So that's why it's separated out.