Breaking Down D3 API

[00:00:00]
>> Shirley Wu: I want to show you the D3 API again. I want to break it down so that you know which parts of the D3 API might be relevant to you, and which parts you can replace it with other things. So this is kind of what we were talking about before.

[00:00:21]
These are some of the, I call it the, so the first section, this first column, I call it data preparation. And this is how I think of like all of the utility kind of like utility functions, where you could just use native JavaScript or low dash functions. This is like the D3 dot map.

[00:00:45]
I'm sorry, this is like the map functions, filter, reduce Is I think in a lot of these array ones, I think in the transformations. The D3 min and max and extend is under statistics. So each of the bolded things are D3 modules. So, this is how you can find it in the documentation.

[00:01:06]
So like for D3 coords for example, you can judy say D3 dash coord. And that's how you find the documentation for it.
>> Shirley Wu: And then, each of these are subsections within that module. So each of these little bolded sections are modules of D3. And so these two sections, I mostly ignore because I end up just using native array functions or lodash but it really depends on what you feel comfortable with.

[00:01:45]
This and the next part are what I think is really the most powerful things about D3 and what makes it a unique selling point of D3 for me. These are functions that are helpful for getting the data ready for D3's scale/shape/layout functions. So you can see like this coord you pass in raw data to this code, function and then that will return the data that is necessary for this code, will then function that will then give you the path.

[00:02:15]
String, and similar things for a nessen hierarchy will get you data that you can then pass into the hierarchy section to get you back x-y positions. And pies are really helpful for getting like this one, if you pass in an array of numbers, it will give you back the start an angle.

[00:02:36]
Radius, et cetera for the arcs. Which is what we just used. So, this, and I mispoke earlier, so this is really the unique selling point of d3 for me. Because this is where d3 will help turn your raw data into what SVG needs to draw. This is how you can get XY positions.

[00:03:01]
This is how you can get path strings, et cetera. That otherwise, would be really hard for you to do it yourself, or it would just take a lot of calculations to do it for yourself. And I kind of want to show you some of the things that are available.

[00:03:15]
So, this whole time we've been using D3 Shape and D3 Shape will help you draw pie charts, so that's using arcs. It will help you create line charts.
>> Shirley Wu: Area charts if you want to do anything stacked.
>> Shirley Wu: And then, we'll also help you do a stacked bar chart and this stream graph thing, which I never fully understood as a visualization.

[00:03:52]
I think this is another one of those like very controversial visualizations where some people are like, this is great! And then there's other people like me that are like I don't get it. But it's possible with D3. And for each one of these, the way that you read the documentation is it will always, always tell you what it expects as an input.

[00:04:11]
So for example it's saying, this one is telling you D3 expects the data to be in this format and then it expects you to give this as kind of the settings so this one in particular. Saying like to create stack bar chart, you need to give me this kind of data.

[00:04:32]
And then, you need to tell me what the keys are to make the stacks out of each of the levels of stacks. And then, it will basically then give you this array. Of arrays, and this is what then you plug in to an xScale or yScale to figure out how to draw this stack.

[00:05:00]
So that's how you can go through the documentation. If you get for work handed an area chart, you come over here, find the area chart. And then figure out what it expects for it's input, and then what kind of settings you need to give it, the default settings you need to give it.

[00:05:23]
And then it will tell you what it returns somewhere. Somewhere here will tell you what it returns, or you can console log what it returns. So that's one of them. This helps you calculate histograms. So this is chord diagram, this one is for showing flows, source to target flow.

[00:05:49]
And so for this one I think you can just take a look, this is how it expects the input. And then it will give you as output these things that you can then plug into this ribbon function. So this is how you expect its input, this is how you expects its output.

[00:06:10]
And so the documentation follows this sort of pattern for every single thing that it does. So this one in particular is heirarchy. This one is the one that helps you draw trees. So draws trees, draws these tree maps, and this is kinda showing hierarchy. It's basically I think categorical hierarchy and it's showing you everything here is a child of this.

[00:06:45]
And then I think it shows you the size. It's laid out based on the size of that particular child relative to everything else. And then this partition, I'm in a circle packs.
>> Speaker 2: So when you're reading through the documentation and you see some code and you just want to run it to see how it works, is there a website or a sandbox or something that you can-

[00:07:09]
>> Shirley Wu: Again, a great question. [LAUGH] I wish I was smart enough to plant these questions. So a lot of times, if you just click on the picture, it will take you to, so this is kind of the example. So before Mike Bostock, the creator of D3 went and made observable networks, he actually hosted a lot of his examples on blocks, B,L .ox.org and this is where like a lot of the examples and code.

[00:07:48]
And then what you can do is going here and then instead of ox.org I'm replace that with blogbuilder.org. And this is something that Ian Johnson, who's one of the primary organizers of the D3 user group built. So if you just replace the blogs.org part with blockbuilder.org, then it will pop you into this online editor where you can kinda play around with the code.

[00:08:26]
Like, maybe if I was like, what does this do? And I just delete this whole thing. Look, it live updates to show you I've deleted all the rectangles. So that's what I would recommend. So, like for each of these. Usually if you click on the picture sometimes it's a little disappointing and it just takes you to the picture itself, but most of the time it actually takes you to the code.

[00:08:53]
And, you just replace a blocks part with blockbuilder.org and it takes you to a live editor. I think these days. A lot of the most popular examples I think are being replaced and redone in Observable. So I think if you go to observable dot, so it's beta.observable@hq.com, but the notebooks that we've been working in and if you just look for Any of the modules that you want to try, like the cord one earlier.

[00:09:26]
So somebody will have done an example with it. So, look at that. So I highly recommend you checking out. Any of these. So either on Observable search whatever you're looking for and go to someone's notebook and then you can actually like this. As you know, because we've been using it, we can live edit and see what happens.

[00:09:58]
Or in block builder. I think this one I'm really a fan of blockbuilder.org/search. This one let's you search by the API function so then I can do d3.chord. And this will have basically have every single block ever that uses D3.cord and then you can edit those. So, when you're trying to find that layout to implement whichever design.

[00:10:36]
Yeah, just try clicking on the image and then if not, try going to observable HQ and try and find it. In one of the examples, or Block-Build our search, quite a few options, yeah.
>> Speaker 3: You said that d3 is going to be the tool to put the data in the format it needs to.

[00:10:59]
How does it get the data? Can it go to a database?
>> Shirley Wu: No. Okay, so that's the part it doesn't do. It does have a little bit of functionality for helping you with requests. So it will have things like It helps you to get request, I think post request?

[00:11:22]
Json, it has one like D3.json so helps you like fetch json files, csv files, etcetera but it doesn't ever try to talk to any database that you need something else too. D3 is really for once you've gotten the data. From wherever your data source is then translating that into what you need to draw it onto the screen.

[00:11:51]
>> Speaker 3: So it's always like a flat file type thing? I'm not clear when you say already gotten the data, is it like XML string? What does it look like?
>> Shirley Wu: So, usually, you want to get whatever your data is, wherever it's from, to I think for most of the calculations, most of the D3 functions, it would want it in a JSON format.

[00:12:23]
Yeah. And then, so just arrays and objects. And then, you can go from there to do whatever you need with D3. Yeah. That's a great question also. D3 contour. This is one of the new things that got added in in Version 5.
>> Shirley Wu: I think it helps with, this says density contour, I haven't really quite read into exactly what it's for, but it's one of the options.

[00:12:58]
And the force layout, that helps you layout network diagrams or bee swarm plots, sometimes physics simulations. And then, I'm of course, D3 geo, that helps you with mapping. And it has all of these different projections that you can choose from. And unfortunately I think most people go with mercader.

[00:13:28]
I'm glad isn't even the first thing on here. And then this is the U.S.A., so a lot of different projections to get geodata onto the screen. And this is how we do that we saw earlier. Now there's directions and write ups on how to get geodata onto the screen too.

[00:13:55]
So yeah, so that's the, this whole part of the layout calculations. And this is where, what I use a lot for getting data into what SVG needs to draw and this to me is, personally I think the best part of D3.