Expand and document support for column names with special characters

[joelostblom]

Continuing on some of the discussion in #2824. This issue has been raised a few times in the past so thought it was worth documenting and supporting slightly better:

• plotting a column name with '.' in it eventually leads to a vega error #284
• escape special characters in names... #2494
• transform_fold does not work if hyphen (-) in column name #2600

Updated docs:

[mattijn]

Its good to document this! I keep having the same question that I do not yet see answered. I know why special characters are not allowed when using:

shorthand='column_cannot_have_special_characters:Q'`

but are special characters allowed if one define it using field/type combination?

field='column_with_special_character', type='quantitative'

Eg. I found out that vl-convert cannot deal with the shorthand approach using a colon-datatype.

[joelostblom]

Good point, currently the long form with explicit type works for fields with a colon, but not with a period or bracket (they fail silently as they would in the shortform because the look for a nested attribute). Do you think I should update this PR so that colon raises an error in long form with explicit type too to make it consistent with how it is treated in shortform? Even if that limitation is "artifical".

It is too bad we cannot show an informative message when . or [] are used since they will "work" but look for nested attributes so they show an empty plot. That is #2825 again and probably needs to be fixed at the VL level.

[mattijn]

I think the escaping of colons is a feature of using shorthand and should not become a feature of field.

Also I'm fine with the possibility of finding nested data using the brackets. I use this approach myself sometimes and is also used in VL here: https://vega.github.io/vega-lite/examples/facet_bullet.html and in Altair https://stackoverflow.com/a/55214346/2459096

[joelostblom]

I think the escaping of colons is a feature of using shorthand and should not become a feature of field.

Agree. I added a note in the docs about them not having to be escaped in the long form.

Also I'm fine with the possibility of finding nested data using the brackets.

Yes, I also like having this, just wish it was immediately clear when this is happening, e.g. instead of showing an empty plot it would be great if VL outputed an error message along the lines of "No nested attribute found in the data" or similar. But nothing we can do about that here; this is good to merge from my side.