Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: transitioning docs to Documenter.jl #879

Merged
merged 12 commits into from
Sep 8, 2016
Merged

WIP: transitioning docs to Documenter.jl #879

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
0ff0668
initial implementation of new docs, working on #878
tlnagy Aug 23, 2016
58de1db
clean out old landing page that was left behind
tlnagy Aug 23, 2016
c398751
[ci skip] modernize readme and remove duplicate info
tlnagy Aug 24, 2016
48cebc6
clean up example plotting code in docs
tlnagy Aug 25, 2016
a7daa0c
clarify coord info and add element descriptions
tlnagy Aug 27, 2016
ab178b6
add Mattriks' new geometry to updated docs
tlnagy Sep 1, 2016
db2f01f
update function names in theme docs, fixes #852
tlnagy Sep 5, 2016
49207bd
[ci skip] add back author information and add credits
tlnagy Sep 5, 2016
dc0bb16
transition to using the new @setup syntax
tlnagy Sep 5, 2016
51de60f
prepare travis and documenter for auto deployment [ci skip]
tlnagy Sep 5, 2016
ff53ec8
Add .documenter.enc
dcjones Sep 6, 2016
8ec1f6a
Merge pull request #1 from dcjones/tlnagy-docs
tlnagy Sep 7, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .travis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,5 @@ script:
- julia --check-bounds=yes -e 'Pkg.test("Gadfly", coverage=true)'
after_success:
- julia -e 'cd(Pkg.dir("Gadfly")); Pkg.add("Coverage"); using Coverage; Coveralls.submit(Coveralls.process_folder())'
- julia -e 'Pkg.add("Documenter")'
- julia -e 'cd(Pkg.dir("Gadfly")); include(joinpath("docs", "make.jl"))'
246 changes: 43 additions & 203 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,229 +1,69 @@
[![Gadfly](http://pkg.julialang.org/badges/Gadfly_0.3.svg)](http://pkg.julialang.org/?pkg=Gadfly&ver=0.3)
[![Gadfly](http://pkg.julialang.org/badges/Gadfly_0.4.svg)](http://pkg.julialang.org/?pkg=Gadfly&ver=0.4)
[![Gadfly](http://pkg.julialang.org/badges/Gadfly_0.5.svg)](http://pkg.julialang.org/?pkg=Gadfly&ver=0.5)
<div align="center">
<img src="docs/src/assets/logo.svg" alt="Gadfly Logo" width="210"></img>
</div>


[![DOI](https://zenodo.org/badge/6322/dcjones/Gadfly.jl.png)](http://dx.doi.org/10.5281/zenodo.11876) [![Build Status](http://img.shields.io/travis/dcjones/Gadfly.jl.svg)](https://travis-ci.org/dcjones/Gadfly.jl) [![Coverage Status](http://img.shields.io/coveralls/dcjones/Gadfly.jl.svg)](https://coveralls.io/r/dcjones/Gadfly.jl)

[![Join the chat at https://gitter.im/dcjones/Gadfly.jl](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dcjones/Gadfly.jl?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
| **Documentation** | **PackageEvaluator** | **Build Status** |
|:------------------------:|:-------------------------------------------------------------------------------------:|:------------------------------------------------:|
| [![][docs-stable-img]][docs-stable-url] | [![][pkg-0.4-img]][pkg-0.4-url] [![][pkg-0.5-img]][pkg-0.5-url] | [![][travis-img]][travis-url] [![][codecov-img]][codecov-url] |

**Gadfly** is a plotting and data visualization system written in
[Julia](http://julialang.org/).

It's influenced heavily by Leland Wilkinson's book
[The Grammar of Graphics](http://www.cs.uic.edu/~wilkinson/TheGrammarOfGraphics/GOG.html)
and Hadley Wickham's refinement of that grammar in
[ggplot2](http://ggplot2.org/).
It's influenced heavily by Leland Wilkinson's book [The Grammar of Graphics][gog-book]
and Hadley Wickham's refinement of that grammar in [ggplot2](http://ggplot2.org/).

It renders publication quality graphics to PNG, Postscript, PDF, SVG. The SVG
backend uses embedded javascript, powered by [Snap.svg](http://snapsvg.io/) to
add interactivity like panning, zooming, and toggling.
If you use **Gadfly** in a publication please consider citing it: [![DOI][citation-img]][citation-url]

Other interactive features like selecting and inspecting values are available
through [Immerse.jl](https://github.com/JuliaGraphics/Immerse.jl).
## Package features

Check out the [manual](http://dcjones.github.io/Gadfly.jl/) for more details and
examples.
- Renders publication quality graphics to SVG, PNG, Postscript, and PDF
- Intuitive and consistent plotting interface
- Works with [IJulia](https://github.com/JuliaLang/IJulia.jl) out of the box
- Tight integration with [DataFrames.jl](https://github.com/JuliaStats/DataFrames.jl)
- Interactivity like panning, zooming, toggling powered by [Snap.svg](http://snapsvg.io/)
- Supports a large number of common plot types

# Installation
## Installation

From the Julia REPL a reasonably up to date version can be installed with
**Gadfly** is registered on `METADATA.jl` and so can be installed using `Pkg.add`.

```julia
Pkg.add("Gadfly")
```

This will likely result in two dozen or so other packages also being
installed.

## Optional: cairo, pango, and fontconfig

Gadfly works best with the C libraries cairo, pango, and fontconfig installed.
The PNG, PS, and PDF backends require cairo, but without it the SVG backends
(`SVG` and `SVGJS`) are still available.

Complex layouts involving text are also somewhat more accurate when pango and
fontconfig are available.

Julia's Cairo bindings can be installed with

```julia
Pkg.add("Cairo")
```

# Three Invocations

All interaction with Gadfly is through the `plot` function, which takes three
major forms.


## Orthodox

```julia
plot(data::AbstractDataFrame, elements::Element...; mapping...)
```

This form is the standard "grammar of graphics" method of plotting. Data is
supplied in the form of a
[dataframe](https://github.com/juliastats/dataframes.jl), columns of the data
are bound to *aesthetics*, and plot elements including **scales**,
**coordinates**, **statistics**, **guides**, and **geometries** are added to the
plot.

All of the examples that follow will be plotting data from
[RDatasets](https://github.com/johnmyleswhite/RDatasets.jl).

To render these plots to a file, call `draw` on the resulting plot.

```julia
draw(SVG("myplot.svg", 6inch, 3inch), plot(...))
```

A few examples now.


```julia
# E.g.
plot(dataset("datasets", "iris"),x="SepalLength", y="SepalWidth", Geom.point)
```

![Iris](http://homes.cs.washington.edu/~dcjones/gadfly/iris.svg)

```julia
# E.g.
plot(dataset("car", "SLID"), x="Wages", color="Language", Geom.histogram)
```

![Car](http://homes.cs.washington.edu/~dcjones/gadfly/car.svg)

A catalog of plot elements is given later in this document.


## Heretical

```julia
plot(elements::Element...; mapping...)
```

Along with the orthodox invocation of `plot`, some relaxed invocations of the
grammar exist as a "slang of graphics". This form of `plot` omits the the data
frame. Instead, plain old arrays are bound to aesthetics.

```julia
# E.g.
plot(x=collect(1:100), y=sort(rand(100)))
```

![Points](http://homes.cs.washington.edu/~dcjones/gadfly/points.svg)
## Documentation

If no geometry is specified, like in the example above, a `Geom.point` is stuck
into your plot.
- [**STABLE**][docs-stable-url] &mdash; **most recently tagged version of the documentation.**
- [**LATEST**][docs-latest-url] &mdash; *in-development version of the documentation.*

This `plot` otherwise works the same. We might want to name these axis, for
example.
## Contributing and Questions

```julia
# E.g.
plot(x=collect(1:100), y=sort(rand(100)),
Guide.XLabel("Index"), Guide.YLabel("Step"))
```

![Labeled_points](http://homes.cs.washington.edu/~dcjones/gadfly/labeled_points.svg)


## Functions and Expressions

```julia
plot(f::Function, a, b, elements::Element...)

plot(fs::Array, a, b, elements::Element...)
```

Some special forms of `plot` exist for quickly generating 2d plots of functions.

```julia
# E.g.
plot([sin, cos], 0, 25)
```

![Sin/Cos](http://homes.cs.washington.edu/~dcjones/gadfly/sin_cos.svg)


# Elements

Plot elements in Gadfly are statistics, scales, geometries, and guides. Each
operates on data bound to aesthetics, but in different ways.

### Statistics

Statistics are functions taking as input one or more aesthetics, operating on
those values, then output to one or more aesthetics. For example, drawing of
boxplots typically uses the boxplot statistic (Stat.boxplot) that takes as input
the `x` and `y` aesthetic, and outputs the middle, and upper and lower hinge,
and upper and lower fence aesthetics.

### Scales

Scales, similarly to statistics, apply a transformation to the original data,
typically mapping one aesthetic to the same aesthetic, while retaining the
original value. The `Scale.x_log10` aesthetic maps the `x` aesthetic back to
the `x` aesthetic after applying a log10 transformation, but keeps track of
the original value so that data points are properly identified.

### Geometries

Finally, geometries are responsible for actually doing the drawing. A geometry
takes as input one or more aesthetics, and used data bound to these aesthetics
to draw things. The `Geom.point` geometry draws points using the `x` and `y`
aesthetics, the `Geom.line` geometry draws lines, and so on.

### Guides

Very similar to geometries are guides, which draw graphics supporting the actual
visualization, such as axis ticks and labels and color keys. The major
distinction is that geometries always draw within the rectangular plot frame,
while guides have some special layout considerations.

# Drawing to backends

Gadfly plots can be rendered to number of formats. Without cairo, or any
non-julia libraries, it can produce SVG. Installing cairo gives you access to
the `PNG`, `PDF`, and `PS` backends. Rendering to a backend works the same for
any of these.

```julia
some_plot = plot(x=[1,2,3], y=[4,5,6])
draw(PNG("myplot.png", 6inch, 3inch), some_plot)
```

## Using the SVGJS backend

The `SVGJS` backend writes SVG with embedded javascript. There are a couple
subtleties with using the output from this backend.

Drawing to the backend works like any other.
This is a new and fairly complex piece of software. [Filing an
issue](https://github.com/dcjones/Gadfly.jl/issues/new) to report a bug,
counterintuitive behavior, or even requesting a feature is extremely valuable in
helping us prioritize what to work on, so don't hesitate.

```julia
draw(SVGJS("mammals.js.svg", 6inch, 6inch), p)
```
If you have a question then you can ask for help in the [Gitter chat room][gitter-url].

If included with an `<img>` tag, it will display as a static SVG image.
```html
<img src="mammals.js.svg"/>
```
[docs-latest-img]: https://img.shields.io/badge/docs-latest-blue.svg
[docs-latest-url]: https://dcjones.github.io/Gadfly.jl/latest

For the interactive javascript features to be enabled, the output either needs
to be included inline in the HTML page, or included with an object tag, like.
[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
[docs-stable-url]: https://dcjones.github.io/Gadfly.jl/stable

```html
<object data="mammals.js.svg" type="image/svg+xml"></object>
```
[pkg-0.4-img]: http://pkg.julialang.org/badges/Gadfly_0.4.svg
[pkg-0.4-url]: http://pkg.julialang.org/?pkg=Gadfly
[pkg-0.5-img]: http://pkg.julialang.org/badges/Gadfly_0.5.svg
[pkg-0.5-url]: http://pkg.julialang.org/?pkg=Gadfly

# Reporting Bugs
[travis-img]: http://img.shields.io/travis/dcjones/Gadfly.jl.svg
[travis-url]: https://travis-ci.org/dcjones/Gadfly.jl
[codecov-img]: http://img.shields.io/coveralls/dcjones/Gadfly.jl.svg
[codecov-url]: https://coveralls.io/r/dcjones/Gadfly.jl

This is a new and fairly complex piece of software. [Filing an
issue](https://github.com/dcjones/Gadfly.jl/issues/new) to report a bug,
counterintuitive behavior, or even requesting a feature is extremely valuable in
helping me prioritize what to work on, so don't hesitate.
[citation-img]: https://zenodo.org/badge/6322/dcjones/Gadfly.jl.png
[citation-url]: http://dx.doi.org/10.5281/zenodo.11876

[gog-book]: http://www.cs.uic.edu/~wilkinson/TheGrammarOfGraphics/GOG.html

[gitter-url]: https://gitter.im/dcjones/Gadfly.jl
Loading