Merge pull request #87 from davidanthoff/doc3

Doc3

docs/make.jl

@@ -14,19 +14,27 @@ makedocs(
     "Getting Started" => Any[
         "Quick Tour" => "gettingstarted/quick.md"
     ],
-    "Examples" => Any[
-        "Simple Charts" => "examples/examples_simplecharts.md",
-        "Bar Charts & Histograms" => "examples/examples_barchartshistograms.md",
-        "Scatter & Strip Plots" => "examples/examples_scatter_strip_plots.md",
-        "Line Charts" => "examples/examples_line_charts.md",
-        "Area Charts & Streamgraphs" => "examples/examples_area_Charts_streamgraphs.md",
-        "Table-based Plots" => "examples/examples_table_based_plots.md",
-        "Faceting (Trellis Plot / Small Multiples)" => "examples/examples_faceting.md",
-        "Repeat & Concatenation" => "examples/examples_repeat_concatenation.md"
-    ],
     "User Guide" => Any[
         "Vega-lite specifications" => "userguide/vlspec.md"
     ],
+    "Examples" => Any[
+        "Simple Charts" => "examples/examples_simplecharts.md",
+        "Single-View Plots" => Any[            
+            "Bar Charts & Histograms" => "examples/examples_barchartshistograms.md",
+            "Scatter & Strip Plots" => "examples/examples_scatter_strip_plots.md",
+            "Line Charts" => "examples/examples_line_charts.md",
+            "Area Charts & Streamgraphs" => "examples/examples_area_Charts_streamgraphs.md",
+            "Table-based Plots" => "examples/examples_table_based_plots.md"
+        ],
+        "Layered Plots" => Any[
+            "Error Bars & Error Bands" => "examples/examples_error_bars_bands.md",
+            "Box Plots" => "examples/examples_box_plots.md"
+        ],
+        "Multi-View Displays" => Any[
+            "Faceting (Trellis Plot / Small Multiples)" => "examples/examples_faceting.md",
+            "Repeat & Concatenation" => "examples/examples_repeat_concatenation.md"
+        ]        
+    ],
     "Reference Manual" => [
         "Global settings" => "referencemanual/global.md",
         "Outputs" => "referencemanual/output.md",

docs/src/examples/examples_area_Charts_streamgraphs.md

@@ -1,3 +1,5 @@
+# Area Charts & Streamgraphs
+
 ## Area Chart
 
 ```@example

docs/src/examples/examples_barchartshistograms.md

@@ -1,3 +1,5 @@
+# Bar Charts & Histograms
+
 ## Simple Bar Chart
 
 ```@example

docs/src/examples/examples_box_plots.md

@@ -0,0 +1,105 @@
+# Box Plots
+
+## Box Plot with Min/Max Whiskers
+
+```@example
+using VegaLite, VegaDatasets
+
+dataset("population") |>
+@vlplot(
+    transform=[{
+        aggregate=[
+            {op=:q1, field=:people, as=:lowerBox},
+            {op=:q3, field=:people, as=:upperBox},
+            {op=:median, field=:people, as=:midBox},
+            {op=:min, field=:people, as=:lowerWhisker},
+            {op=:max, field=:people, as=:upperWhisker}
+        ],
+        groupby=[:age]
+    }]
+) +
+@vlplot(
+    mark={:rule, style=:boxWhisker},
+    y={"lowerWhisker:q", axis={title="population"}},
+    y2="lowerBox:q",
+    x="age:o"
+) +
+@vlplot(
+    mark={:rule, style=:boxWhisker},
+    y="upperBox:q",
+    y2="upperWhisker:q",
+    x="age:o"
+) +
+@vlplot(
+    mark={:bar, style=:box},
+    y="lowerBox:q",
+    y2="upperBox:q",
+    x="age:o",
+    size={value=5}
+) +
+@vlplot(
+    mark={:tick, style=:boxMid},
+    y="midBox:q",
+    x="age:o",
+    color={value=:white},
+    size={value=5}
+)
+```
+
+## Tukey Box Plot (1.5 IQR)
+
+```@example
+using VegaLite, VegaDatasets
+
+dataset("population") |>
+@vlplot(
+    transform=[
+        {
+            aggregate=[
+                {op=:q1, field=:people, as=:lowerBox},
+                {op=:q3, field=:people, as=:upperBox},
+                {op=:median, field=:people, as=:midBox}
+            ],
+            groupby=[:age]
+        },
+        {
+            calculate="datum.upperBox - datum.lowerBox",
+            as=:IQR
+        },
+        {
+            calculate="datum.lowerBox - datum.IQR * 1.5",
+            as=:lowerWhisker
+        },
+        {
+            calculate="datum.upperBox + datum.IQR * 1.5",
+            as=:upperWhisker
+        }
+    ]
+) +
+@vlplot(
+    mark={:rule, style=:boxWhisker},
+    y={"lowerWhisker:q", axis={title="population"}},
+    y2="lowerBox:q",
+    x="age:o"
+) +
+@vlplot(
+    mark={:rule, style=:boxWhisker},
+    y="upperBox:q",
+    y2="upperWhisker:q",
+    x="age:o"
+) +
+@vlplot(
+    mark={:bar, style=:box},
+    y="lowerBox:q",
+    y2="upperBox:q",
+    x="age:o",
+    size={value=5}
+) +
+@vlplot(
+    mark={:tick, style=:boxMid},
+    y="midBox:q",
+    x="age:o",
+    color={value=:white},
+    size={value=5}
+)
+```

docs/src/examples/examples_error_bars_bands.md

@@ -0,0 +1,119 @@
+# Error Bars & Error Bands
+
+## Error Bars showing Confidence Interval
+
+```@example
+using VegaLite, VegaDatasets
+
+dataset("barley") |>
+@vlplot() +
+@vlplot(
+    mark={
+        :point,
+        filled=true
+    },
+    x={
+        "mean(yield)",
+        scale={zero=false},
+        axis={title="Barley Yield"}
+    },
+    y={
+        "variety:o",
+        color={value=:black}
+    }
+) +
+@vlplot(:rule, x="ci0(yield)", x2="ci1(yield)", y="variety:o")
+```
+
+## Error Bars showing Standard Deviation
+
+```@example
+using VegaLite, VegaDatasets
+
+dataset("barley") |>
+@vlplot(
+    transform=[
+        {
+            aggregate=[
+                {op=:mean, field=:yield, as=:mean},
+                {op=:stdev, field=:yield, as=:stdev}
+            ],
+            groupby=[:variety]
+        },
+        {calculate="datum.mean-datum.stdev", as=:lower},
+        {calculate="datum.mean+datum.stdev", as=:upper}
+    ]
+) +
+@vlplot(
+    mark={
+        :point,
+        filled=true
+    },
+    x={
+        "mean:q",
+        scale={zero=false},
+        axis={title="Barley Yield"}
+    },
+    y="variety:o",
+    color={value=:black}
+) +
+@vlplot(:rule, x="upper:q", x2="lower:q", y="variety:o")
+```
+
+## Line Chart with Confidence Interval Band
+
+```@example
+using VegaLite, VegaDatasets
+
+dataset("cars") |>
+@vlplot() +
+@vlplot(
+    :area,
+    x="year(Year):t",
+    y={
+        "ci0(Miles_per_Gallon)",
+        axis={title="Mean of Miles per Gallon (95% CIs)"}
+    },
+    y2="ci1(Miles_per_Gallon)",
+    opacity={value=0.3}
+) +
+@vlplot(
+    :line,
+    x="year(Year)",
+    y="mean(Miles_per_Gallon)"
+)
+```
+
+## Scatterplot with Mean and Standard Deviation Overlay
+
+```@example
+using VegaLite, VegaDatasets
+
+dataset("cars") |>
+@vlplot() +
+@vlplot(
+    :point,
+    x=:Horsepower,
+    y=:Miles_per_Gallon
+) +
+(
+    @vlplot(
+        transform=[
+            {aggregate=[
+                {op=:mean, field=:Miles_per_Gallon, as=:mean_MPG},
+                {op=:stdev, field=:Miles_per_Gallon, as=:dev_MPG}
+                ],
+                groupby=[]
+            },
+            {calculate="datum.mean_MPG - datum.dev_MPG", as=:lower},
+            {calculate="datum.mean_MPG + datum.dev_MPG", as=:upper}
+        ]) +
+    @vlplot(:rule,y={"mean_MPG:q",axis=nothing}) +
+    @vlplot(
+        :rect,
+        y={"lower:q",axis=nothing},
+        y2="upper:q",
+        opacity={value=0.2}
+    )
+)
+```

docs/src/examples/examples_faceting.md

@@ -1,3 +1,5 @@
+# Faceting (Trellis Plot / Small Multiples)
+
 ## Trellis Bar Chart
 
 ```@example
@@ -35,7 +37,7 @@ dataset("movies") |>
 @vlplot(:point, column="MPAA_Rating:o", x=:Worldwide_Gross, y=:US_DVD_Sales)
 ```
 
-### Trellis Histograms
+## Trellis Histograms
 
 ```@example
 using VegaLite, VegaDatasets

docs/src/examples/examples_line_charts.md

@@ -1,3 +1,5 @@
+# Line Charts
+
 ## Line Chart
 
 ```@example
@@ -102,7 +104,7 @@ dataset("stocks") |>
 )
 ```
 
-### Connected Scatterplot (Lines with Custom Paths)
+## Connected Scatterplot (Lines with Custom Paths)
 
 ```@example
 using VegaLite, VegaDatasets

docs/src/examples/examples_repeat_concatenation.md

@@ -1,3 +1,5 @@
+# Repeat & Concatenation
+
 ## Repeat and layer to show different weather measures
 
 ```@example

docs/src/examples/examples_scatter_strip_plots.md

@@ -1,3 +1,5 @@
+# Scatter & Strip Plots
+
 ## Scatterplot
 
 ```@example

docs/src/examples/examples_simplecharts.md

@@ -1,3 +1,5 @@
+# Simple Charts
+
 ## Simple Bar Chart
 
 ```@example

docs/src/examples/examples_table_based_plots.md

@@ -1,3 +1,5 @@
+# Table-based Plots
+
 ## Table Heatmap
 
 ```@example

docs/src/gettingstarted/quick.md

@@ -1,5 +1,9 @@
 # Quick tour
 
+!!! note
+
+    This section is outdated and does not reflect the latest API of the package.
+
 ### Simple scatter plot
 
 Use functions linked by the `|>` operator to build your visuialization incrementally. VegaLite.jl can use DataFrames or DataTables as sources for data. For a scatter plot, specify that the mark should a point by `markpoint()`, then how the data in the DataFrame `mpg` (fields `:Cty`, `:Hwy` and `:Manufacturer`) should be connected to the encoding channels (x, y and color respectively). Finally, global configuration options are provided in a `config` function (type `? config``to see all the options).

docs/src/index.md

@@ -1,33 +1,29 @@
+# VegaLite.jl
 
-[VegaLite.jl](https://github.com/fredo-dedup/VegaLite.jl) enables the generation of [Vega-Lite](https://vega.github.io/vega-lite/) plots from Julia.
+## Overview
 
-[Vega-Lite](https://vega.github.io/vega-lite/) is a visualization grammar describing mappings from data to graphical properties (e.g. marks, axes, scales). For rendering it uses pre-defined design rules that keep the visualization specification succinct while still leaving user control.
+[VegaLite.jl](https://github.com/fredo-dedup/VegaLite.jl) is a plotting package for the [julia](https://julialang.org/) programming language. The package is based on [Vega-Lite](https://vega.github.io/vega-lite/), which extends a traditional [grammar of graphics](https://doi.org/10.1007/0-387-28695-0) API into a [grammar of interactive graphics](https://doi.org/10.1109/TVCG.2016.2599030).
 
-Vega-Lite supports:
-- data transformation, sorting, filtering and grouping.
-- aggregation, binning, and simple statistical analysis (e.g. mean, std, var, count).
-- plots can be faceted, layered and stacked vertically or horizontally.
-
-### Installation
-
-To install the package run `Pkg.add("VegaLite")`.
-
-### Principles
-
-The package is essentially a thin layer translating Julia statements to the [Vega-Lite](https://vega.github.io/vega-lite/) visualization specification format.
-
-One can take any Vega-Lite specification and easily translate it into corresponding julia code. In addition, the package provides various ways to specify figures in a much more concise way. Here is an example of a scatter plot with a legend:
+[VegaLite.jl](https://github.com/fredo-dedup/VegaLite.jl) allows you to create a wide range of statistical plots. It exposes the full functionality of the underlying [Vega-Lite](https://vega.github.io/vega-lite/) and is a the same time tightly integrated into the julia ecosystem. Here is an example of a scatter plot:
 
 ```@example
 using VegaLite, VegaDatasets
 
 dataset("cars") |>
 @vlplot(
-  :point,
-  x=:Horsepower,
-  y=:Miles_per_Gallon,
-  color=:Origin,
-  width=400,
-  height=400
+    :point,
+    x=:Horsepower,
+    y=:Miles_per_Gallon,
+    color=:Origin,
+    width=400,
+    height=400
 )
 ```
+
+## Installation
+
+To install [VegaLite.jl](https://github.com/fredo-dedup/VegaLite.jl), run the following julia code:
+
+```julia
+Pkg.add("VegaLite")
+```

docs/src/referencemanual/functions.md

@@ -1,3 +1,7 @@
+!!! note
+
+    This section is outdated and does not reflect the latest API of the package.
+
 ## Functions