DOCSEARCHbyAlgolia
Submit Docs

Gadfly.jl Documentation

repository·master·Indexed 23 days ago

https://github.com/giovineitalia/gadfly.jl

Gadfly is a plotting and data visualization system for Julia based on the Grammar of Graphics and influenced by ggplot2. It supports publication-quality rendering to SVG, PNG, Postscript, and PDF, and integrates with IJulia, Pluto.jl, and DataFrames.jl. The library provides a wide array of geometries including Geom.point, Geom.line, Geom.bar, Geom.histogram, and Geom.boxplot, transforming plot specifications into Compose.jl scene graphs.

Tokens
23.6K
Snippets
85
Records
111
Agent score
81%

What's inside Gadfly.jl

  1. Overview of Gadfly features

    master

    Gadfly is a plotting and data visualization system for Julia based on the Grammar of Graphics. Key features include:

    • Publication Quality: Renders graphics to SVG, PNG, Postscript, and PDF.
    • Notebook Integration: Works out of the box with IJulia and Pluto.jl.
    • Data Integration: Tight integration with DataFrames.jl.
    • Interactivity: Supports panning, zooming, and toggling via Snap.svg.
    • Versatility: Supports a large number of common plot types with an intuitive and consistent interface.

  2. Understand Coordinate Systems in Gadfly

    master
    Coordinate systems in Gadfly act as mappings between a raw coordinate space (the data values) and the 2D rendered output. While the current implementation focuses on 2D Cartesian coordinates, the architecture is designed to support other systems such as polar, barycentric, or projections of 3D coordinates in the future.

  3. Relationship between Gadfly and Compose.jl

    master
    Gadfly and Compose.jl are tightly intertwined. If you are developing with or contributing to the master branch of Gadfly to access the latest features and bug fixes, you will likely need to check out the master branch of Compose.jl as well to ensure compatibility.

  4. How aesthetics, scales, and guides work together

    master

    Gadfly follows a grammar of graphics where:

    • Aesthetics (e.g., x, y, color, size, alpha, shape) map data to visual properties.
    • Scales (e.g., Scale.x_continuous, Scale.color_discrete) define how data values are translated into aesthetic values.
    • Guides (e.g., Guide.xlabel, Guide.colorkey, Guide.xticks) provide visual cues like axes, legends, and labels.

    For example, to map color to a column and add a color legend, you use color=:ColumnName and Guide.colorkey().

  5. Understand how Scales work in Gadfly

    master

    Scales in Gadfly are used to apply transformations to data aesthetics. They typically map one aesthetic to another (often the same aesthetic name) while preserving the relationship to the original data values.

    For example, a scale like Scale.x_log10 transforms the x aesthetic using a $\log_{10}$ function but maintains a mapping to the original values so that data points can be correctly identified and labeled in the plot. This allows for visual transformations (like logarithmic axes) while keeping the underlying data semantics intact.

  6. How Statistics work within layers

    master

    When using Statistics (Stat) with layers, Gadfly follows two rules:

    1. Inside a layer: All Geometries within that specific layer will use the specified Stat. Example: layer(Stat.smooth(method=:lm), Geom.line, Geom.ribbon) applies the smooth statistic to both the line and the ribbon.
    2. Outside a layer (Directly in plot): If Geometries and Statistics are passed directly to plot (not wrapped in layer()), Gadfly creates a new layer for each Geometry, and each Statistic is added to the newest layer. Example: plot(x=xdata, y=rand(30), Geom.point, Stat.binmean(n=5), Geom.line, Stat.step) will create separate layers for the point and the line, each receiving the preceding statistic.

  7. Manage themes using the Theme stack

    master

    Gadfly uses a stack to manage themes, applying values from the topmost theme. This allows you to set a theme for a sequence of plots and then revert to a previous state.

    • push_theme(t::Theme): Pushes a new theme onto the stack.
    • pop_theme(): Removes the topmost theme from the stack.
    • with_theme(f, t::Theme): Temporarily sets a theme for the duration of a function f (which can be a do-block), ensuring the theme is automatically popped afterwards.
    latex_fonts = Theme(major_label_font="CMU Serif", major_label_font_size=16pt,
                    minor_label_font="CMU Serif", minor_label_font_size=14pt,
                    key_title_font="CMU Serif", key_title_font_size=12pt,
                    key_label_font="CMU Serif", key_label_font_size=10pt)
Gadfly.push_theme(latex_fonts)
gasoline = dataset("Ecdat", "Gasoline")
p = plot(gasoline, x=:Year, y=:LGasPCar, color=:Country, Geom.point, Geom.line)
Gadfly.pop_theme()

# Alternatively, using with_theme for automatic cleanup:
Gadfly.with_theme(latex_fonts) do
    gasoline = dataset("Ecdat", "Gasoline")
    plot(gasoline, x=:Year, y=:LGasPCar, color=:Country, Geom.point, Geom.line)
end

  8. How statistics work in Gadfly

    master

    In Gadfly, a statistic is a transformation function that takes one or more aesthetics as input, performs a calculation, and outputs one or more new aesthetics.

    For example, a boxplot statistic (Stat.boxplot) consumes the x and y aesthetics and produces new aesthetics representing the middle, upper/lower hinges, and upper/lower fences. This allows Gadfly to transform raw data points into summarized visual representations.

  10. Understand the Gadfly rendering pipeline

    master

    Gadfly transforms a plot specification into a Compose scene graph consisting of guides (e.g., axis ticks, color keys) and one or more layers of geometry.

    Layer Specifications

    Each layer in a plot is defined by:

    • Data source: The dataset used (e.g., dataset("ggplot2", "diamonds")).
    • Geometry: The visual representation (e.g., Geom.bar, Geom.point).
    • Mappings: Associating data elements with aesthetics (e.g., x = :Price, color = :Cut).
    • Statistics: Optional layer-wise transformations (e.g., Stat.histogram).

    Shared Plot Elements

    All layers in a single plot share:

    • Coordinates: The coordinate system (e.g., Coord.cartesian, Coord.polar).
    • Scales: How data values map to aesthetics (e.g., Scale.x_continuous, Scale.color_discrete).
    • Statistics: Plot-wide transformations applied to all layers.
    • Guides: Visual aids like Guide.xticks, Guide.yticks, or Guide.colorkey.

    The Rendering Process

    1. Data Mapping: Subsets of the data source are mapped to a Data object (e.g., mapping :Price to the :x field).
    2. Scale Application: Scales transform data into plottable aesthetics (e.g., mapping categorical strings to specific colors).
    3. Statistical Transformation: Layer-wise and plot-wise statistics are applied (e.g., Stat.histogram transforming x values into bin positions and calculating y counts).
    4. Coordinate Transformation: A Compose context is created using the coordinate system to map data to screen coordinates.
    5. Geometry Rendering: Each layer renders its specific geometry.
    6. Guide Rendering: Guides are computed and rendered on top of the plot context.
    # A minimal specification where many elements are inferred or defaulted
p = plot(df,
         x = :Price, color = :Cut,
         Stat.histogram,
         Geom.bar)

# A full specification explicitly defining all components
p = plot(layer(df,
               x = :Price, color = :Cut,
               Stat.histogram,
               Geom.bar),
         Scale.x_continuous,
         Scale.color_discrete,
         Coord.cartesian,
         Guide.xticks, Guide.yticks,
         Guide.xlabel("Price"),
         Guide.colorkey(title="Cut"))

  11. How Gadfly's grammar of graphics works

    master

    Gadfly uses a "grammar of graphics" approach where plots are constructed by binding data to aesthetics (special named variables) and specifying several elements:

    • Scales: Define how data maps to visual properties.
    • Coordinates: Define the coordinate system (e.g., Coord.cartesian).
    • Guides: Add annotations like titles (Guide.title) or axis labels (Guide.xlabel).
    • Geometries: Define the visual marks (e.g., Geom.line).

    Instead of using special-case functions for every plot type, you connect data to aesthetics, which act as input leads to these self-contained elements to produce the final result.

  12. How geometries work in Gadfly

    master

    Geometries are the components responsible for the actual drawing in Gadfly. A geometry takes one or more aesthetics (such as x and y) as input and uses the data bound to those aesthetics to render visual elements.

    There are two main types of geometries:

    1. Core geometries: These perform direct mapping from aesthetics to visual elements (e.g., Geom.point uses x and y to draw points).
    2. Derived geometries: These build upon core geometries by automatically applying a default statistic to the data before drawing.