New doc-page on data formats

[Hvass-Labs]

Please consider making a separate doc-page about valid data formats.

When I started using your plotting system, I originally thought I could supply arrays of data directly to the plotting functions, because that is how Matplotlib for Python does it. But I couldn't get that working, and based on your introductory doc-pages I thought the only valid data-format was an array of dicts like this:

data = [{x: 1, y: 200}, {x: 2, y: 300}, ...]

I have probably made nearly 30 plots by now, where the data comes from a web-server. In order to transfer the data efficiently to the web-browser and supply it to Plot as an array of dicts, I had to create all kinds of "clever" packing/unpacking and conversion functions.

Based on a short comment to another question here, I found out that it is actually possible to supply arrays directly to the plotting functions. It is very briefly mentioned in the Marks / Mark options doc-page:

Plot also supports columnar data for greater efficiency with bigger datasets; for example, data can be specified as any array of the appropriate length (or any iterable or value compatible with Array.from), and then separate arrays of values can be passed as options.

And then there is a small example, where I can see that I couldn't get this working originally, because I have to supply an index which is basically just an array that enumerates the data from 0 to the array-length minus 1. It's not clear why this is necessary when the data-arrays need to have the same length anyway.

Please write a doc-page about the valid data-formats and their pro's and con's. This would have saved me a ton of time, and I'm probably not the only one. I think this topic is so important, that I would suggest writing a separate doc-page called e.g. "Data Formats" and placing it under "Features" right after "Plots" and before "Marks".

Allow me to make a general remark about your docs. It is very challenging to write good docs, and you mostly do succeed. But your plotting system is complex with many advanced features. It is almost like a whole programming language unto itself. Although it is thoroughly documented, some of the docs are very abstract and concise in their writing-style (they read almost like an academic paper), while others are more tutorial-like. The latter writing-style is much easier to understand, especially for users who just want to quickly lookup a solution to their problem, without having to spend hours reading through and trying to understand fairly abstract docs. I'm not expecting you to immediately rewrite your more abstract doc-pages, but it is perhaps something to keep in mind when you write new ones.

I hope this came across as constructive feedback.

[Fil]

you could probably make the example work by specifying data as {length: N}?