altair
altair copied to clipboard
altair-viz
Document the differences between `value` and `datum`?
I struggle to find a use case for alt.value since alt.datum was introduced in 4.2.0. It seems like the latter completely covers the function of the former + more. ~~If that is the case, should value be deprecated to encourage the usage of the more powerful datum? Deprecation or not,~~ I can add something to the documentation once I get more clarity on the relationship between the two.
I just found one difference that I don't know if it is significant. I seems like datum constructs an axis when used with a primitive value / constant, whereas as value does not (this could possibly be more convenient when trying to place in a single label in a chart since you don't have to worry about hiding axes?):
alt.Chart().mark_text().encode(
x=alt.datum(0),
y=alt.value(0),
)
I didn't realize that value comes from vegalite, I thought it was a convenience function in altair. I will change this issue to add documentation on their differences as per https://vega.github.io/vega-lite/docs/encoding.html#value-def (although I am not clear on when one is preferred over the other so input welcome).
This would be good to document. In short, alt.value() specifies a constant range value, while alt.datum specifies a domain value. So x=alt.value(100) would place a mark 100 pixels from the left edge of the plot, while x=alt.datum(100) would place a mark corresponding to the location of x=100 on the x axis.
I've been wanting alt.datum forever - it was such a relief to finally have that functionality available in the last release!
Another good example: color=alt.datum('label') creates a mark with whatever color is associated with the value "label" in the color scale, while color=alt.value('red') creates a red mark regardless of the color scale.
