What is your suggestion?

When setting initial values for a selection interval based on date values, users must manually convert dates to timestamps, as discussed here. This requirement does not appear to be clearly documented or exemplified in this repository. Solutions could be one or more of the following:

Potential Solutions

• Example Gallery: Update this example to include an initial value for the interval (see below)
• API Reference: Briefly reference in the description of the value paramater in the API Reference here
• Docs: Incorporate into the docs on selections

Questions:

1. Which, if any, of these suggestions should be implemented?
2. The linked stackoverflow discussion above highlights an important distinction between datetime.datetime and numpy.datetime64 in this context. Should this point be referenced in any documentation, and if so, how?

Sample diff for current example gallery item

import altair as alt
from vega_datasets import data

source = data.sp500.url

+ # Define an initial date range as timestamps
+ x_init = pd.to_datetime(['2005-01-01', '2009-01-01']).astype(int) / 1E6

+# Create a brush (interval) selection with initial range
+brush = alt.selection_interval(
+    encodings=['x'], 
+   value={'x': list(x_init)}  # Initialize selection
+)

brush = alt.selection_interval(encodings=['x'])

base = alt.Chart(source, width=600, height=200).mark_area().encode(
    x = 'date:T',
    y = 'price:Q'
)

upper = base.encode(
    alt.X('date:T').scale(domain=brush)
)

lower = base.properties(
    height=60
).add_params(brush)

upper & lower

Have you considered any alternative solutions?

I've proposed three possible solutions above.