Documentation for each mark type

doc/user_guide/marks/arc.rst

@@ -0,0 +1,71 @@
+.. currentmodule:: altair
+
+.. _user-guide-arc-marks:
+
+Arc
+~~~
+
+Arc marks are circular arcs defined by a center point plus angular and radial extents. 
+Arc marks are typically used for radial plots such as pie and donut charts.
+
+Examples
+--------
+
+We can create a pie chart by encoding ``theta`` or ``color`` arc marks.
+
+.. altair-plot::
+    import pandas as pd
+    import altair as alt
+
+    source = pd.DataFrame({"category": [1, 2, 3, 4, 5, 6], "value": [4, 6, 10, 3, 7, 8]})
+
+    alt.Chart(source).mark_arc().encode(
+        theta=alt.Theta(
+            field="value", 
+            type="quantitative"),
+        color=alt.Color(
+            field="category", 
+            type="nominal"),
+        )
+
+Setting ``innerRadius`` to non-zero values will create a donut chart. 
+
+.. altair-plot::
+    import pandas as pd
+    import altair as alt
+
+    source = pd.DataFrame({"category": [1, 2, 3, 4, 5, 6], "value": [4, 6, 10, 3, 7, 8]})
+
+    alt.Chart(source).mark_arc(innerRadius=50).encode(
+        theta=alt.Theta(
+            field="value", 
+            type="quantitative"),
+        color=alt.Color(
+            field="category", 
+            type="nominal"),
+        )
+
+You can also add a text layer to add labels to a pie chart.
+
+.. altair-plot::
+    import pandas as pd
+    import altair as alt
+
+    source = pd.DataFrame(
+        {"category": ["a", "b", "c", "d", "e", "f"], "value": [4, 6, 10, 3, 7, 8]}
+    )
+
+    base = alt.Chart(source).encode(
+        theta=alt.Theta("value:Q", stack=True), color=alt.Color("category:N", legend=None)
+    )
+
+    pie = base.mark_arc(outerRadius=120)
+    text = base.mark_text(radius=140, size=20).encode(text="category:N")
+
+    pie + text
+
+Area Config 
+^^^^^^^^^^^
+The ``arc`` property of the top-level ``config`` object sets the default properties for all arc marks. If mark property encoding channels are specified for marks, these config values will be overridden.
+
+The area config can contain any area mark properties (except ``type``, ``style``, and ``clip``).

doc/user_guide/marks/area.rst

@@ -0,0 +1,165 @@
+.. currentmodule:: altair
+
+.. _user-guide-area-marks:
+
+Area
+~~~~~~~~~~
+``area`` represent multple data element as a single area shape. 
+Area marks are often used to show change over time, using either a single area or stacked areas.
+
+Examples
+--------
+
+Area Chart
+^^^^^^^^^^
+Using ``area`` mark with one temporal or ordinal field (typically on ``x``) and 
+one quantitative field (typically on ``y``) produces an area chart. For example, 
+the following area chart shows a number of unemployment people in the US over time.
+
+.. altair-plot::
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.unemployment_across_industries.url
+
+    alt.Chart(source).mark_area().encode(
+        x = 'yearmonth(date):T',
+        y = 'sum(count):Q',
+    ).properties(
+        width=300,
+        height=200
+    )
+
+Area Chart with Overlaying Lines and Point Markers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By setting ``line`` and ``point`` properties of the mark definition 
+to ``true`` or an object defining a property of the overlaying point marks, we can overlay line and point markers on top of area.
+
+.. altair-plot:: 
+    import altair as alt
+    from vega_datasets import data
+    from altair.expr import datum
+
+    source = data.stocks.url
+
+    alt.Chart(source).mark_area(line = True, point = True).encode(
+        x = 'date:T',
+        y = 'price:Q',
+    ).transform_filter(
+        datum.symbol == 'GOOG'
+    )
+
+Instead of using a single color as the fill color of the area, we can set it to a gradient. 
+In this example, we are also customizing the overlay. For more information about gradient options see the Vega-Lite Gradient documentation. 
+
+.. altair-plot.:: 
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.stocks()
+
+    alt.Chart(source).transform_filter(
+        'datum.symbol==="GOOG"'
+    ).mark_area(
+        line={'color':'darkgreen'},
+        color=alt.Gradient(
+            gradient='linear',
+            stops=[alt.GradientStop(color='white', offset=0),
+                alt.GradientStop(color='darkgreen', offset=1)],
+            x1=1,
+            x2=1,
+            y1=1,
+            y2=0
+        )
+    ).encode(
+        alt.X('date:T'),
+        alt.Y('price:Q')
+    )
+
+Stacked Area Chart
+^^^^^^^^^^^^^^^^^^
+Adding a color field to area chart creates stacked area chart by default. For example, here we split the area chart by industry.
+
+.. altair-plot::
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.unemployment_across_industries.url
+
+    alt.Chart(source).mark_area().encode(
+        alt.X('yearmonth(date):T',
+            axis=alt.Axis(format='%Y', domain=False, tickSize=0)
+        ),
+        alt.Y('sum(count):Q'),
+        alt.Color('series:N',
+            scale=alt.Scale(scheme='category20b')
+    ))
+
+Normalized Stacked Area Chart
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also create a normalized stacked area chart by setting ``"stack"`` to ``"normalize"`` in the encoding channel. Here we can easily see the percentage of unemployment across industries.
+
+.. altair-plot::
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.unemployment_across_industries.url
+
+    alt.Chart(source).mark_area().encode(
+        alt.X('yearmonth(date):T',
+            axis=alt.Axis(format='%Y', domain=False, tickSize=0)
+        ),
+        alt.Y('sum(count):Q', stack = 'normalize'),
+        alt.Color('series:N',
+            scale=alt.Scale(scheme='category20b')
+    ))
+
+Steamgraph
+^^^^^^^^^^^
+
+We can also shift the stacked area chart’s baseline to center and produces a streamgraph by setting ``"stack"`` to ``"center"`` in the encoding channel. 
+Adding the ``interactive`` method allows for changing the scales.
+
+.. altair-plot::
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.unemployment_across_industries.url
+
+    alt.Chart(source).mark_area().encode(
+        alt.X('yearmonth(date):T',
+            axis=alt.Axis(format='%Y', domain=False, tickSize=0)
+        ),
+        alt.Y('sum(count):Q', stack='center', axis=None),
+        alt.Color('series:N',
+            scale=alt.Scale(scheme='category20b')
+        )
+    ).interactive()
+
+Ranged Area
+^^^^^^^^^^^
+Specifying ``x2`` or ``y2`` for the quantitative axis of area marks produce ranged areas. For example, we can use ranged area with the ``ci0`` and ``ci0`` 
+aggregation operators to highlight 95% confidence interval of a line chart that shows mean values over time.
+
+.. altair-plot::
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.seattle_weather()
+
+    alt.Chart(source).mark_area(opacity=0.7).encode(
+        alt.X('monthdate(date):T', title = 'Date'),
+        alt.Y('mean(temp_max):Q', title = "Daily Temperature Range (C)"),
+        alt.Y2('mean(temp_min):Q', )
+    ).properties(
+        width=600,
+        height=300
+    )
+
+Area Config 
+^^^^^^^^^^^
+The ``area`` property of the top-level ``config`` object sets the default properties for all area marks. If mark property encoding channels are specified for marks, these config values will be overridden.
+
+The area config can contain any area mark properties (except ``type``, ``style``, ``clip``, and ``orient``).

doc/user_guide/marks/bar.rst

@@ -0,0 +1,121 @@
+.. currentmodule:: altair
+
+.. _user-guide-bar-marks:
+
+Bar 
+~~~
+
+Bar marks are useful in many visualizations, including bar charts, stacked bar charts, and timelines.
+
+Examples 
+--------
+
+Single Bar Chart 
+^^^^^^^^^^^^^^^^
+Mapping a quantitative field to either ``x`` or ``y`` of the ``bar`` mark produces a single bar chart.
+
+.. altair-plot::
+    import altair as alt
+    from altair import datum
+    from vega_datasets import data
+
+    source = data.population.url
+
+    alt.Chart(source).mark_bar().encode(
+        alt.X('sum(people):Q', title = "Population")
+    ).transform_filter(
+        datum.year == 2000
+    )
+
+Bar Chart 
+^^^^^^^^^
+If we map a different discrete field to the ``y`` channel, we can produce a horizontal bar chart. Specifying ``alt.Step(100)`` will adjust the bar’s height per discrete step.
+
+.. altair-plot::
+    import altair as alt
+    from altair import datum
+    from vega_datasets import data
+
+    source = data.population.url
+
+    alt.Chart(source).mark_bar().encode(
+        alt.X('sum(people):Q', title = "Population"),
+        alt.Y('age:O')
+    ).transform_filter(
+        datum.year == 2000
+    ).properties(height = 500)
+
+Bar Chart with a Temporal Axis
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+While the ``bar`` mark typically uses the x and y channels to encode a pair of discrete and continuous fields, it can also be used with continuous fields on both channels. For example, given a bar chart with a temporal field on x, we can see that the x-scale is a continuous scale. By default, the size of bars on continuous scales will be set based on the ``continuousBandSize`` config.
+
+.. altair-plot:: 
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.seattle_weather()
+
+    alt.Chart(source).mark_bar().encode(
+        alt.X('month(date):T', title = 'Date'),
+        alt.Y('mean(precipitation):Q'),
+    )
+
+Histograms
+^^^^^^^^^^
+
+If the data is not pre-aggregated (i.e. each record in the data field represents one item), mapping a binned quantitative field to ``x`` and aggregate ``count`` to ``y`` produces a histogram.
+
+.. altair-plot::
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.movies.url
+
+    alt.Chart(source).mark_bar().encode(
+        alt.X("IMDB_Rating:Q", bin=True),
+        y='count()',
+    )
+
+Stacked Bar Chart
+^^^^^^^^^^^^^^^^^
+Adding color to the bar chart (by using the ``color`` attribute) creates a stacked bar chart by default. Here we also customize the color’s scale range to make the color a little nicer. (See ``stack`` for more details about customizing stack.)
+
+.. altair-plot::
+    import altair as alt
+    from vega_datasets import data
+
+    source = data.barley()
+
+    alt.Chart(source).mark_bar().encode(
+        x='variety',
+        y='sum(yield)',
+        color='site'
+    )
+
+Grouped Bar Chart with Offset 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. altair-plot::
+    import altair as alt
+    import pandas as pd
+
+    source = pd.DataFrame({
+        'category': ['A', 'A', 'B','B', "C", "C"],
+        'group': ['x', 'y', 'z', 'x', 'y', 'z'],
+        'value': [0.1, 0.6, 0.9, 0.7, 0.2, 0.6]
+    })
+
+    alt.Chart(source).mark_bar().encode(
+        x = alt.X('category:N'),
+        xOffset = 'group:N',
+        y = alt.Y('value:Q'),
+        color = alt.Color('group:N')
+    )
+
+Bar Config 
+^^^^^^^^^^
+
+The ``bar`` property of the top-level ``config`` object sets the default properties for all bar marks. If mark property encoding channels are specified for marks, these config values will be overridden.
+
+Besides standard mark properties, bar config can contain the following additional properties:
+binSpacing, continuousBandSize, and discreteBandSize.