Add API wrappers for data generators

altair/vegalite/v3/api.py

@@ -93,7 +93,8 @@ def _prepare_data(data, context):
 
     # if data is still not a recognized type, then return
     if not isinstance(data, (dict, core.Data, core.UrlData,
-                             core.InlineData, core.NamedData)):
+                             core.InlineData, core.NamedData,
+                             core.GraticuleGenerator, core.SequenceGenerator)):
         warnings.warn("data of type {} not recognized".format(type(data)))
 
     return data
@@ -1962,3 +1963,25 @@ def remove_data(subchart):
             subcharts = [remove_data(c) for c in subcharts]
 
     return data, subcharts
+
+
+@utils.use_signature(core.SequenceParams)
+def sequence(start, stop=None, step=Undefined, as_=Undefined, **kwds):
+  """Sequence generator."""
+  if stop is None:
+    start, stop = 0, start
+  params = core.SequenceParams(
+    start=start, stop=stop, step=step, **{'as': as_}
+  )
+  return core.SequenceGenerator(sequence=params, **kwds)
+
+
+@utils.use_signature(core.GraticuleParams)
+def graticule(**kwds):
+  """Graticule generator."""
+  if not kwds:
+      # graticule: True indicates default parameters
+      graticule = True
+  else:
+      graticule = core.GraticuleParams(**kwds)
+  return core.GraticuleGenerator(graticule=graticule)

altair/vegalite/v3/tests/test_api.py

@@ -840,3 +840,22 @@ def test_facet(chart_type, facet_arg):
         assert dct['facet'] == expected
     else:
         assert dct['facet'][facet_arg] == expected
+
+
+def test_sequence():
+    data = alt.sequence(100)
+    assert data.to_dict() == {'sequence': {'start': 0, 'stop': 100}}
+
+    data = alt.sequence(5, 10)
+    assert data.to_dict() == {'sequence': {'start': 5, 'stop': 10}}
+
+    data = alt.sequence(0, 1, 0.1, as_='x')
+    assert data.to_dict() == {'sequence': {'start': 0, 'stop': 1, 'step': 0.1, 'as': 'x'}}
+
+
+def test_graticule():
+    data = alt.graticule()
+    assert data.to_dict() == {'graticule': True}
+
+    data = alt.graticule(step=[15, 15])
+    assert data.to_dict() == {'graticule': {'step': [15, 15]}}

doc/user_guide/data.rst

@@ -229,6 +229,52 @@ With it, the above chart can be reproduced as follows:
 Notice that unlike the pandas ``melt`` function we must explicitly specify the columns
 to be folded. The ``as_`` argument is optional, with the default being ``["key", "value"]``.
 
+
+.. _data-generated:
+
+Generated Data
+~~~~~~~~~~~~~~
+At times it is convenient to not use an external data source, but rather generate data for
+display within the chart specification itself. The benefit is that the chart specification
+can be made much smaller for generated data than for embedded data.
+
+Sequence Generator
+^^^^^^^^^^^^^^^^^^
+Here is an example of using the :func:`sequence` function to generate a sequence of  *x*
+data, along with a :ref:`user-guide-calculate-transform` to compute *y* data.
+
+.. altair-plot::
+
+   import altair as alt
+
+   # Note that the following generator is functionally similar to
+   # data = pd.DataFrame({'x': np.arange(0, 10, 0.1)})
+   data = alt.sequence(0, 10, 0.1, as_='x')
+
+   alt.Chart(data).transform_calculate(
+       y='sin(datum.x)'
+   ).mark_line().encode(
+       x='x:Q',
+       y='y:Q',
+   )
+
+Graticule Generator
+^^^^^^^^^^^^^^^^^^^
+Another type of data that is convenient to generate in the chart itself is the latitude/longitude
+lines on a geographic visualization, known as a graticule. These can be created using Altair's
+:func:`graticule` generator function. Here is a simple example:
+
+.. altair-plot::
+
+   import altair as alt
+
+   data = alt.graticule(step=[15, 15])
+
+   alt.Chart(data).mark_geoshape().project(
+       'orthographic',
+       rotate=[0, -45, 0]
+   )
+
 .. _Pandas: http://pandas.pydata.org/
 .. _Pandas pivot documentation: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.pivot.html
 .. _Pandas melt documentation: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.melt.html#pandas.DataFrame.melt