Skip to content

Grammar of Graphics in q

Overview

For a general overview of the Grammar of Graphics in q, please see the Grammar of Graphics section of the user guide, which includes additional examples.

Basic usage

    // Below will produce a plot matrix from `t` of columns x, y, and z

    .qp.go[500; 500] .qp.plot[t; `x`y`z; ::]

.gg.display

Displays an initialized GG object using the default GG renderer

Parameter(s):

Name Type Description
w long width
h long height
gg dict initialized GG

Throws:

Type Description
"resize error: canvas is not large enough to hold frame components"

See Also: .gg.resizeUsing

.gg.displayUsing

Display and render using an explicit renderer. A renderer is a dictionary/namespace with the following:

  • atextL : state, settings -> state
  • atextM : state, settings -> state
  • atextR : state, settings -> state
  • circle : state, settings -> state
  • line : state, settings -> state
  • path : state, settings -> state
  • rect : state, settings -> state
  • remove : state -> ()
  • render : state -> any
  • new : w, h -> state

In each of the above, state is anything that the renderer needs to track, and settings is a dictionary of settings for each geometry. These settings have the following keys:

  • atextL : `pt`fontsize`fillcolour`angle
  • atextM : `pt`fontsize`fillcolour`angle
  • atextR : `pt`fontsize`fillcolour`angle
  • circle : `center`radius`strokecolour`strokewidth`fillcolour
  • line : `x1`y1`x2`y2`strokewidth`fillcolour
  • path : `xs`ys`strokewidth`strokecolour`fillcolour
  • rect : `x`y`w`h`strokewidth`strokecolour`fillcolour

Stroke-colour and Fill-colour are both byte arrays of the form 0xAARRGGBB.

When stroke is not used, stroke-width is 0 and stroke-colour is undefined.

Parameter(s):

Name Type Description
r dict render API
w long width
h long height
gg dict initialized GG object

Returns:

Name Type Description
<returns> dict Rendered GG

Example:

 .gg.displayUsing[.myrenderer; 500; 500] .gg.new spec

.gg.new

Creates a new initialized GG object from a specification tree. The default theme is added, or used to extend the root node if it is a theme node itself in order to have a fully specified theme for every node in the tree.

Parameter(s):

Name Type Description
s table A specification tree (see .gg.spec)

Returns:

Name Type Description
<returns> dict Initialized GG object

Throws:

Type Description
Initialization errors

Example:

     .gg.new .gg.spec.single .gg.layer.new @

.gg.resize

Parameter(s):

Name Type Description
w long
h long
gg dict Main GG container
gg.id guid
gg.origSpec table
gg.spec table
gg.output dict

Returns:

Name Type Description
<returns> dict Main GG container
<returns>.id guid
<returns>.origSpec table
<returns>.spec table
<returns>.output dict

Throws:

Type Description
"resize error: canvas is not large enough to hold frame components"

See Also: .gg.resizeUsing

.gg.resizeUsing

Given a renderer implementation, display an initialized GG object with the given width and height.

A new specification tree will be created, and returned as part of the resulting GG object. The new specification tree will have every node in the tree correctly sized with a origin (w,h), width, and height. Tree nodes for all frame components for every layer and stack will be added to the tree. The origin of each node will be specified as an absolute location.

As an example, the following uninitialized specification tree:

  Example 1 below

becomes (without padding, styling, etc):

  Example 2 below

The tree is descended starting at the root, drawing each node individually.

Parameter(s):

Name Type Description
r dict renderer implementation
w long width
h long height
gg dict initialized GG object

Returns:

Name Type Description
<returns> dict a new GG object with an updated specification tree and output

See Also: .gg.displayUsing

Example: 1

      vert
      \_ layer

Example: 2

      vert (0,0), 500, 500
      \_ layer (0,0), 500, 500
         \_ canvas (50, 0), 450, 450
         \_ xaxis (50, 450), 450, 50
         \_ yaxis (0,0), 50, 450
         \_ ...

.qp.dsl

Take a string of GG DSL or an hsym pointing to a gg DSL file, as well as an environment dictionary of parameter names to table values, and produce a rendered GG.

Parameter(s):

Name Type Description
e dict
f symbol | string

Returns:

Name Type Description
<returns> dict pre-rendered gg

Example:

 .qp.push .gg.dsl[()!()] `:image.gg

.qp.plot

Create a plot of the indicated columns from a table. Creates a best-guess plot based on the types of the columns. If more than two columns are specified, a plot of pairs of all columns will be created.

Parameter(s):

Name Type Description
table table data to be visualized
cs symbol[] list of columns to be visualized
settings null | dict settings for the visual (geom/etc)

Returns:

Name Type Description
<returns> table specification table

Example: A single column

 t: ([]x:45?45; y:45?45; z:45?5?`5);

 .qp.plot[t; `x; ::]

Image

Example: Two columns

 .qp.plot[t; `x`y; ::]

Image

Example: Three columns

 .qp.plot[t; `x`y`z; ::]

Image

Example: All columns

 .qp.plot[t; (); ::]

Image