Exploring the squarified tree map algorithm with ReasonML (2-part beginner tutorial)

#1

As a newcomer to ReasonML, I recently wrote a two-part tutorial (part one and part two) to showcase to other people how the language can be used to elegantly solve real-world problems. Feedback is welcome!

#2

Having finished part one, it’s very well written. Just one point of confusion – I am reading this line:

Partition the original 6Ă—4 container into the same number of rectangles as the number of children at level 1 (6 partitions)

But when I count the children at level 1 in your hand-drawn diagram: A, B, C, D, E, F, G, I get a total of seven. This had me confused for a moment, until I realized that partitions = rectangles - 1.

#3

It should say 7 partitions. Thanks for spotting the mistake. I’ll fix it.

#4

Part 2: Overall, it builds very nicely and keeps information in manageable compartments.

  • After the text “This is called a let binding,…“, you might want to note that you have explicitly annotated/specified the data type rectangle
  • Your description of data types is quite elegant.
  • In file tree-type-definition.png, the vertical bars look like slashes (probably an artifact of your syntax highlighter)
  • “Note that in the visual output, only leaf nodes (terminal nodes) remain.” You might want to mention this in part one after you finish the first classic tree map.
  • After “This JavaScript output is very clean and readable”, it might be useful to have a footnote saying that the record field names x0, y0, etc. are verified at compile time and become indices into an array at run time.
  • After “a function called the reducer…”, do you want another footnote to point out that “this is how you do an anonymous function in ReasonML,” or is it the same as in JavaScript?
  • “Below are two passing test cases from the test code"” The |> is new to JavaScript programmers, but you can’t explain it right there because it would take the discussion off track. Don’t know what to do about that.
  • Excellent explanation of partial application.
  • Thank you for giving the formula for calculating the aspect ratio rather than asking us to derive it ourselves :grinning:
  • Good explanation of the double set of parentheses for the tuple.
  • “all nodes must already be in the result array, meaning we can return the result array” – do you want to say list instead of array here?
  • In the discussion of the general case, do you want to explain what List.rev does?

One general comment: I am the only person in the world who doesn’t like dark-theme editors; I find the low contrast makes it hard to read the comments in the screenshots at smaller font sizes. I’d rather see non-syntax-highlighted text rather than an image of the code (or have the image link to the github source), but I realize that text would take up too much vertical space in the article, and links would be too difficult to add manually.

#5

Thanks for phenomenal feedback. I have incorporated most of them into the article and added a credit to you at the end.

I added a note clarifying this point of possible confusion.

Fixed as recommended. I also added a link to the discussion why JavaScript arrays were chosen as the representation instead of JavaScript objects.

I added a footnote to quickly explain it.

I think List.rev might not be optimal from a pedagogical stand point so I changed the implementation and updated the tutorial accordingly.

I’m using screenshots instead of regular code blocks because I haven’t found a good syntax highlighter for Reason.