Chart vs Properties for Changing Title

[mcp292]

The docs mention setting title with alt.Chart(df, title=""). I'm not sure where I picked it up as I cannot find it in the docs, but I am accustomed to using alt.Chart().properties(title="").

What is the difference why is only one discussed?

[mcp292]

This might be combining two ideas, but I guess where I'm going with this is it would be nice to retroactively change title, xlabel, ylabel, at the end. This will allow for neat organization, concise chart code above, and one single location for tinkering with labels:

alt.Chart(df).mark_line().encode(
    x="X:O",
    y="Y:Q"
).properties(
    title="Title",
    xlabel="X Label",
    ylabel="Y Label (units)"
)

---

I find it much cleaner and more readable than:

alt.Chart(
    df,
    title="Title"
).mark_line().encode(
    x=alt.X("X:O", axis=alt.Axis(title="X Label"),
    y=alt.Y("Y:Q", axis=alt.Axis(title="Y Label (units)")
)

[joelostblom]

I believe properties takes any of the parameters that go into Chart, such as data, title etc. For the encodings there are specific configure options, so you should be able to do something like this (I think):

alt.Chart(df).mark_line().encode(
    x="X:O",
    y="Y:Q"
).properties(
    title="Title"
).configure_axisX(
    title="X Title"
).configure_axisY(
    title="Y Title"
)

Although I don't find this clearer than using the more common syntax (note that the axis part in your original spec is not necessary, you coudl just set title= directly inside alt.X(), and in the release candidate of Altair, you can use the new method syntax like this:

alt.Chart(df, title="Title").mark_line().encode(
    x=alt.X("X:O").title("X Title"),
    y=alt.Y("Y:Q").title("Y Title (units)")
)

I guess that underneath this, there is a theory/philosophy decision taken in the Altair/Vega-Lite grammar of whether all things related to the one encoding (values, labels, titles) belong together, or whether all things of the same type belong together (all labels (X, Y, Color, etc) separate from all titles etc). Personally, I quite like having all things that belong to the same encoding in one place, particularly when doing modifications to e.g. the title offset that would be different for x and y (but I understand this preference differs)

[mcp292]

This is a great discussion. Thank you for taking the time to address this so thoroughly!

I wasn't aware that you didn't need the axis part. The docs don't show a simpler way.

The axis verbosity was my main gripe actually, so I'd say that this is a nice compromise:

alt.Chart(df).mark_line().encode(
    x=alt.X("X:O", title="X Label"),
    y=alt.Y("Y:Q", title="Y Label (units)"
).properties(
    title="Title"
)

I like the conciseness of your second codeblock, but with longer titles I find the above more readable than:

alt.Chart(
    df,
    title="Very Long, Yet Descriptive Title"
).mark_line().encode(
    x=alt.X("X:O", title="X Label"),
    y=alt.Y("Y:Q", title="Y Label (units)"
)

Curious to know which you prefer on a normal basis.

I do like the new method syntax too! Thanks for sharing. Will the docs be updated to discuss this? That is always where I check first.

[joelostblom]

I wasn't aware that you didn't need the axis part. The docs don't show a simpler way.... I do like the new method syntax too! Thanks for sharing. Will the docs be updated to discuss this? That is always where I check first.

Both of these will be made more visible in the docs when #2983 is merged. There is currently a short section on the new encoding option syntax here https://altair-viz.github.io/user_guide/encodings/index.html#alternative-syntax-for-channel-options.

Curious to know which you prefer on a normal basis.

I tend to use properties less often and prefer to write it in the chart. Either as you showed above or by defining a variable with the long title just above the chart:

title="Very Long, Yet Descriptive Title"
alt.Chart(df, title=title).mark_line().encode(
    x=alt.X("X:O").title("X Title"),
    y=alt.Y("Y:Q").title("Y Title (units)")
)

[mcp292]

Happy to hear this will be made more visible!

That's a nice solution with using a variable.