marks Property

Marks visually encode data using geometric primitives.

General JSON format:

"marks": [
  {
    "type": points | line | polys | symbol,
    "from": { data: <dataSourceID> },
    "properties": { <propName>: <propVal> }, ... { <propName>: <propVal> }
    "transform": { <transformType>: <transformName> }
  },
  {
    ...
  }
],

A Vega marks specification includes the following properties:

Each marks property is associated with the specified data property.

Marks are rendered in marks property array order.

Marks property values can be constants or as data references. You can use the scales property to transform marks property values to the visualization area.

Apply the x and y scales to the x and y database table columns to scale the data to the visualization area width and height. For example:

const exampleVega = {
  "width:" 384,
  "height:" 564,
  "data:" [ ... elided ... ],
  "scales:" [
    {
      "name:" "x",
      "type:" "linear",
      "domain:" [-3650484.1235206556,7413325.514451755],
      "range:" "width"
    },
    {
      "name:" "y",
      "type:" "linear",
      "domain:" [-5778161.9183506705, 10471808.487466192],
      "range:" "height"
    }
  ],
  "marks:" [
    {
      "type:" "points",
      "from:" { "data:" "tweets" },
      "properties:" {
        "x:" { "scale:" "x", "field:" "x" },
        "y:" { "scale:" "y","field:" "y"}
      }
    }
  ]
};

marks Properties

type

Marks must include a type property that specifies the geometric primitive to use to render the data.

points Type

Specify x and y coordinate values using either constants, or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be constants.

points Examples

Define a point with size, color, and opacity:

{
  "width" : 1024,
  "height" : 1024,
  "data": [
    {
      "name" : "table",
        "values": [
          {"x": 412, "y": 512, "val": 0.9,"color": "red"},
          {"x": 512, "y": 512, "val": 0.3, "color": "violet"},
          {"x": 612, "y": 512, "val": 0.5,"color": "green"}
        ]
     }
      ],
  "marks" : [
    {
      "type" : "points",
      "from" : {"data" : "table"},
        "properties" : {
          "x" : { "field" : "x" },
          "y" : { "field" : "y" },
          "fillColor" : {
              "field" : "color"
                      },
                      "size" : 150.0,
                      "fillOpacity" : {
                              "field" : "val"
                      },
                      "opacity" : 0.8
               }
             }
       ]
     }

Associate the points geometric primitive with tweets data items.

vegaSpec = {
    "width": 384,
    "height": 564,
    "data": [
        {
            "name": "tweets",
            "sql": "SELECT  ... elided ... "
        }
    ],
    "scales": [ ... elided ... ],
    "marks": [
        {
            "type": "points",
            "from": { data: "tweets" },
            "properties": { ... elided ... }
        },
        { ... elided ... }
    ]
};

lines Type

Specifying the data format property as lines causes the rendering engine to assume a lines database table layout and to extract line-related columns from the table.

Specify x and y coordinate values using either constants, or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be constants.

lines Example

{
  "type": "lines",
  "from": {"data": "table"},
  "properties": {
    "x": {
      "field": "x",
      "scale": "x"
    },
    "y": {
      "field": "y",
      "scale": "y"
    },
    "strokeColor": {
      "scale": "strokeColor",
      "field": "color"
    },
    "strokeWidth": 2,
    "lineJoin": "miter",
    "miterLimit": 10
  }
}

polys Type

The polys type renders data as a polygon. When the data format property is polys, the rendering engine assumes a polys database table layout and extracts the poly-related columns from the table. A polys database table layout implies that the first data column is the vertex x- and y-positions. The vertices are interleaved x and y values, such that vertex[0] = vert0.x, vertex[1] = vert0.y, vertex[2] = vert1.x, and vertex[3] = vert1.y, for example. The next three positions of a polys database table are the triangulated indices, and line loop and drawing information for unpacking multiple, associated polygons that can be packed as a single data item.

polys Example

const exampleVega = {
  "width": 1004,
  "height": 336,
  "data": [
    {
      "name": "polys",
      "format": "polys",
      "sql": "SELECT ... elided ..."
    }
  ],
  "scales": [ ... elided ... ]
  "marks": [
    {
      "type": "polys",
      "from": {
        "data": "polys"
      },
      "properties": {
        "x": {
          "scale": "x",
          "field": "x"
        },
        "y": {
          "scale": "y",
          "field": "y"
        },
        "fillColor": {
          "scale": "polys_fillColor",
          "field": "avgContrib"
        },
        "strokeColor": "white",
        "strokeWidth": 0,
        "lineJoin": "miter",
        "miterLimit": 10
      }
    }
  ]
}

symbol Type

The symbol marks type renders data as one of the supported shapes.

Currently, in symbol mark types, strokes are not visible beneath other marks, regardless of opacity settings.

Specify x and y coordinate values using either constants or domain and range values of a data reference. If the from property is not specified, the x and y properties fields must be specified using constant values.

symbol Examples

const exampleVega = {
  "width": 733,
  "height": 530,
  "data": [
    {
      "name": "heatmap_query",
      "sql": "SELECT ... elided ... "
    }
  ],
  "scales": [ ... elided ... ],
  ],
  "marks": [
    {
      "type": "symbol",
      "from": {
        "data": "heatmap_query"
      },
      "properties": {
        "shape": "square",
        "x": { "field": "x" },
        "y": { "field": "y" },
        "width": 1,
        "height": 1,
        "fillColor": { "scale": "heat_color", "field": "cnt" }
      }
    }
  ]
};

The following example defines symbol mark types including fill, stroke, and general opacity properties:

{
  "width" : 1024,
  "height" : 1024,
  "data": [
      {
          "name" : "table",
          "values": [
              {"x": 200,  "x2": 0.0, "y": 200.0, "y2": 0.0, "val" : 0, "color" : "red", "color2": "yellow", "opacity": 1.0, "fillOpacity":0.75, "strokeOpacity": 0.25},
              {"x": 220.806,  "x2": 0.0, "y": 263.75, "y2": 0.0, "val" : 1, "color" : "blue", "color2": "green", "opacity": 0.5, "fillOpacity": 0.5, "strokeOpacity": 0.5},
              {"x": 240.61216,  "x2": 0.0, "y": 327.5, "y2": 0.0, "val" : 0, "color" : "maroon", "color2": "magenta", "opacity": 0.1, "fillOpacity": 0.25, "strokeOpacity": 0.75}
          ]
      }
  ],
  "marks" : [
      {
          "type" : "symbol",
          "from" : {"data" : "table"},
          "properties" : {
                      "shape" : "circle",
              "xc" : { "field" : "x" },
              "yc" : { "field" : "y" },
                      "width": 150.0,
                  "height": 150.0,
              "opacity": 0.9,
              "fillOpacity": {
                  "field": "fillOpacity"
              },
              "fillColor" : {
                  "field": "color2"
              },
                      "strokeWidth" : 10.0,
                      "strokeColor" : {
                  "field": "color"
              },
              "strokeOpacity": {
                  "field": "strokeOpacity"
              }
          }
      }
   ]
}

from

The from field specifies the input database table to use.

Example

Use the tweets database table for marks input data.

vegaSpec = {
    "width": 384,
    "height": 564,
    "data": [
        {
          "name": "tweets",
          "sql": "SELECT ... elided ... "
        }
    ],
    "scales": [ ... elided ... ],
    "marks": [
        {
            "type": "polys",
            "from": {"data": "tweets"},
            "properties": { ... elided ... }
        }
    ]
};

If from is not specified, the data source is implicitly a single point with the value defined in the points properties.

properties

The properties property specifies type-dependent visual encoding that define the position and appearance of mark instances. The property value is specified using one of the Value Reference options.

Typically, a single mark instance is generated per input data element, except for polys, which uses multiple data elements to represent a line or area shape.

The following table describes the various marks properties and lists the types for which the property is valid.

Value Reference

A value reference describes how to specify marks properties values. The value can be a constant or data object reference:

Examples:

Statically set the point fillColor and size.

"marks:" [
  {
    "type:" "points",
    "from:" {
      "data:" "tweets"
    },
    "properties:" {

         ... elided ...

      "fillColor": "blue",
      "size": 3
      }
    }
  }
]

For the x marks property, apply the x scale transform to the implicit x-coordinate data column.

"marks": [
  {
    "type": "polys",
    "from": {
      "data": "polys"
    },
    "properties": {
      "x": {
        "scale": "x",
        "field": "x"
      },

      ... elided ...

    }
  }
]

Field Reference

A field reference is either a string literal or an object. For object values, the following properties are supported:

Color Value Reference

Typically, color values are specified as a single RGB color value. To specify specific color fields or use a different color space, use one of the following color value reference formats:

Examples

Set the red and blue channels of an RGB color as constants, and uses a scale transform to determine the green channel:

"fill": {
  "r": {"value": 255},
  "g": {"scale": "green", "field": "g"},
  "b": {"value": 0}
}

Use the rgb color space for the color field:

"fillColor": {
    "field": "color",
    "colorSpace": "rgb"
}

transform

The transform object specifies any Vega projections to be applied to the mark. Each transform is specified as a key:value pair in the transform object:

},
"transform": {
      "<key>": "<value>"
}

The value references an existing Vega object by name.

For example, the following transform references the projection my_mercator_projection defined in the top-level Vega projections property.

"projections": [
{
  "name": "my_mercator_projection",
  "type": "mercator",
  "bounds": {
    "x": [-120.0, 120.0],
    "y": [-20.0, 20.0]
  }
}
]
"marks": [
{
  "type": "symbol",
  "from": { "data": "fec_contributions_oct" },
  "properties": { ... elided ... }
  "transform": {
    "projection": "my_mercator_projection"
  }
}
]

Currently, the only supported transform is projection.