API Pain-points

Altair is about mapping the Vega-Lite grammar to a Python API. There are a few places where this mapping is not as user-friendly as it perhaps could be. A running list:

• sort options in encodings. Awkward because alt.SortField/alt.EncodingSortField require an op parameter even if one isn’t needed. Maybe a good candidate for a shorthand syntax? (see #884)
• transform_bin(). Awkward because it doesn’t follow the pattern of transform_calculate, and the field is specified as a string. (See https://altair-viz.github.io/user_guide/transform.html?highlight=transform_window#bin-transforms)
• transform_window(). Awkward because it requires a list of dicts, and those dicts include the keyword as so the associated objects cannot be used (see e.g. https://altair-viz.github.io/gallery/percentage_of_total.html?highlight=transform_window; #850) see #957 for a fix
• normalized histogram. So many transforms required… (see https://groups.google.com/forum/#!topic/altair-viz/NMynW-PUqZk)
• chart.facet() and dataset specification… (see end of Facet docs section https://altair-viz.github.io/user_guide/compound_charts.html#faceted-charts)

[jeffbaumes]

I have not been using the Altair API too long but +1 to chart.facet(). It is tough to keep composition options (layer, facet, repeat) straight. For dealing with the chart later after a facet or other composition you have to know when to reach into the spec or layer object, where to put data, etc. I seem to get the “required field ‘data’ missing” frequently. There are also some other gotchas (can’t facet a facet, facet ordering does not seem possible, config values cannot be inside the facet spec but need to be at the top level).

However, this is complexity inherent in Vega Lite that may be difficult/impossible to hide in Altair.

[jakevdp]

pull requests welcome 😄