gicentre / elm-vega / Vega

Create Vega visualization specifications in Elm. This package allows you to generate the JSON specs that may be passed to the Vega runtime library to activate the visualization.

  1. Creating a specification
  2. Passing values into a specification
  3. Specifying input data
  4. Transforming data
  5. Signals, triggers and interaction events
  6. Scales
  7. Layout composition
  8. Map projections
  9. Titles
  10. Axes
  11. Legends
  12. Marks
  13. Configuration
  14. Supplementary Properties
  15. Type Reference

1. Creating A Vega Specification

toVega : List ( VProperty, Spec ) -> Spec

Convert a list of Vega specifications into a single JSON object that may be passed to Vega for graphics generation. Recommended practice for top-level properties that have more than a simple parameter is to create as a series of compactly named functions (e.g. ds for the data source, sc for scales, si for signals, ax for axes etc.) and construct a list of them. For example,

helloWorld : Spec
helloWorld =
    let
        table =
            dataFromColumns "table" []
                << dataColumn "label" (vStrs [ "Hello", "from", "elm-vega" ])
                << dataColumn "x" (vNums [ 1, 2, 3 ])

        ds =
            dataSource [ table [] ]

        sc =
            scales
                << scale "xScale"
                    [ scDomain (doData [ daDataset "table", daField (field "x") ])
                    , scRange raWidth
                    ]

        mk =
            marks
                << mark text
                    [ mFrom [ srData (str "table") ]
                    , mEncode
                        [ enEnter
                            [ maX [ vScale "xScale", vField (field "x") ]
                            , maText [ vField (field "label") ]
                            ]
                        ]
                    ]
    in
    toVega
        [ width 100, ds, sc [], mk [] ]

combineSpecs : List LabelledSpec -> Spec

Combine a list of labelled specifications into a single specification that may be passed to JavaScript for rendering. Useful for creating a single page with multiple visualizations.

combineSpecs
    [ ( "vis1", myFirstVis )
    , ( "vis2", mySecondVis )
    , ( "vis3", myOtherVis )
    ]


type VProperty

Top-level Vega properties (see the specification documentation).

Data properties specify the input data to be visualized. Generated by dataSource that can collect together data tables such as those read from a URL or generated inline.

Signal properties specify dynamic variables that respond reactively to other signals or interactions. Generated by signals.

Scale properties map data values to visual channels such as position, or color. Generated by scales.

Projection properties specify how geospatial data referenced with longitude, latitude coordinates are projected onto a plane for visualization. Generated by projections.

Axis properties specify how spatial scale mappings are visualized, such as with tick marks, grid lines and labels. Generated by axes.

Legend properties specify how visual scale mappings such as color, shape and size are visualized. Generated by legends.

Title properties specify how a visualization title should appear. Generated by title.

Layout properties specify how a group of visual marks are organised within a grid. This allows visualizations to be composed of other visualizations, for example in a dashboard or collection of small multiples. Generated by layout.

Mark properties specify how to visually encode data with graphical primitives such as points, lines and other symbols. Generated by marks.

Top-level group encodings specify the appearance of the chart's data rectangle. For example setting the background color of the plotting area. Generated by encode.

Config properties specify default settings of a specification. Allows consistent and easily modifiable styles to be applied to a visualization. Generated by config.

Supplementary properties add metadata and some styling to one or more visualizations. Generated by width, height, padding, paddings, autosize, background, description and userMeta.

2. Passing Values into a Vega Specification

Data types such as numbers, strings and Booleans are generated by functions. For example, expressions generate new values based on operations applied to existing ones; fields reference a column of a data table; signals respond dynamically to data or interaction.

2.1 Numbers

num : Basics.Float -> Num

A numeric literal.

nums : List Basics.Float -> Num

A list of numeric literals. For lists that contain a mixture of numeric literals and signals use numList instead.

numSignal : String -> Num

Numeric value referenced by the value in the named signal.

numSignals : List String -> Num

List of numeric values referenced by the values in the named signals.

numExpr : Expr -> Num

An expression that evaluates to a numeric value.

numList : List Num -> Num

List of potentially mixed numeric types. Useful when a domain is specified as being bounded by 0 and some signal:

scDomain (doNums (numList [ num 0, numSignal "mySignal" ]))

numNull : Num

An absence of a numeric value.

2.2 Strings

str : String -> Str

A string literal.

strs : List String -> Str

A list of string literals.

strSignal : String -> Str

String value referenced by the value in the named signal.

strSignals : List String -> Str

String values referenced by the values in the named signals.

strList : List Str -> Str

List of potentially mixed string types (e.g. literals and signals).

strExpr : Expr -> Str

Expression that when evaluated, is a string.

strNull : Str

An absence of a string value.

2.3 Booleans

true : Boo

A Boolean true value.

false : Boo

A Boolean false value.

boos : List Basics.Bool -> Boo

List of Boolean literals.

booSignal : String -> Boo

Name of a signal that will generate a Boolean value.

booSignals : List String -> Boo

List of signals that will generate Boolean values.

booExpr : Expr -> Boo

Expression that when evaluated, will be a Boolean value.

2.4 Generic Values

Used by functions that expect values of mixed types.

vNum : Basics.Float -> Value

A numeric value.

vNums : List Basics.Float -> Value

A list of numbers.

vStr : String -> Value

A string value.

vStrs : List String -> Value

A list of string values.

vTrue : Value

A 'true' value.

vFalse : Value

A 'false' value.

vBoos : List Basics.Bool -> Value

A list of Boolean values.

vSignal : String -> Value

A named signal.

vField : Field -> Value

A data or signal field.

vBand : Num -> Value

Band number or fraction of a band number. Band scales are used when aggregating data into discrete categories such as in a frequency histogram.

vObject : List Value -> Value

Object containing a list of key-value pairs.

keyValue : String -> Value -> Value

Custom key-value pair to be stored in an object generated by vObject.

vValues : List Value -> Value

List of values. Useful for nesting collections of possibly mixed types.

ifElse : String -> List Value -> List Value -> Value

Values conditional on whether an expression (first parameter) evaluates as true. The second and third parameters represent the 'then' and 'else' branches of the test.

To include nested conditions, subsequent ifElse calls should be placed in the 'else' branch.

maFontWeight
    [ ifElse "indata('selected', 'source', datum.id)"
        [ vStr "bold" ]
        [ ifElse "indata('selected', 'target', datum.id)"
            [ vStr "bold" ]
            [ vNull ]
        ]
    ]

vNull : Value

An absence of a value.

vMultiply : Value -> Value

A multiplication value modifier.

vExponent : Value -> Value

An exponential value modifier.

vOffset : Value -> Value

An additive value modifier.

vRound : Boo -> Value

A rounding value modifier. Rounding is applied after all other modifiers.

vScale : String -> Value

Name of a scale.

vScaleField : Field -> Value

A scale field used to dynamically look up a scale name.

2.5 Indirect References

See the Vega field value documentation.

field : String -> Field

Name of a field to reference.

fSignal : String -> Field

Field referenced by the value in the named signal.

fExpr : String -> Field

Expression that references a field but can perform calculations on each datum in the field.

fExpr "scale('xScale', datum.Horsepower)"

fDatum : Field -> Field

Perform a lookup on the current data object using the given field. Once evaluated this is similar to simply providing a string value.

fGroup : Field -> Field

Property of the enclosing group mark instance as a field value.

fParent : Field -> Field

Field of the enclosing group mark’s data object as a field.

expr : String -> Expr

Expression to enable custom calculations specified in the Vega expression language. In contrast to a field reference or signal, the expression is evaluated once per datum behaving like an anonymous (lambda) function.

exField : String -> Expr

Field lookup that forms a Vega Expr. In contrast to an expression generated by expr, a field lookup is applied once to an entire field rather than evaluated once per datum.

2.6 Thematic Data Types

Temporal

year : TimeUnit

Indicate time unit is specified as a year.

quarter : TimeUnit

Indicate time unit is to specified as quarter (starting at one of January, April, July or October).

month : TimeUnit

A month time unit.

date : TimeUnit

Indicate time unit is to specified as a day of a month (1st, 2nd, ... 30th, 31st).

week : TimeUnit

Indicate time unit is to specified as a week.

day : TimeUnit

Indicate time unit is to specified as a day of week (Monday, Tuesday etc.)

dayOfYear : TimeUnit

Indicate time unit is to specified as a day of year (1 to 366).

hour : TimeUnit

Indicate time unit is to specified as an hour of the day.

minute : TimeUnit

Indicate time unit is to specified as a minute of the hour (0-59).

second : TimeUnit

Indicate time unit is to specified as a second of a minute (0-59).

millisecond : TimeUnit

Indicate time unit is to specified as a millisecond of a second (0-999).

tuSignal : String -> TimeUnit

Time unit referenced by the value in the named signal.

Color

vColor : ColorValue -> Value

A color value.

cHCL : List Value -> List Value -> List Value -> ColorValue

Define a color in HCL space (parameters in H - C - L order).

cHSL : List Value -> List Value -> List Value -> ColorValue

Define a color in HSL space (parameters in H - S - L order).

cLAB : List Value -> List Value -> List Value -> ColorValue

Define a color in CIELab space (parameters in L - A - B order).

cRGB : List Value -> List Value -> List Value -> ColorValue

Color in RGB space.

vGradient : ColorGradient -> List GradientProperty -> Value

A literal color gradient value. The first parameter indicates whether the scale should be linear or radial. The second is a set of customisation options for the colors, positioning and rate of change of the gradient. For example, to set a radial red-blue color gradient as a fill for a mark:

maFill
    [ vGradient grRadial
        [ grStops [ ( num 0, "red" ), ( num 1, "blue" ) ] ]
    ]

To set a color gradient based on a color scale, use vGradientScale instead.

grLinear : ColorGradient

Indicates a linear color gradient.

grRadial : ColorGradient

Indicates a radial color gradient. See the Vega color gradient documentation.

grX1 : Num -> GradientProperty

The x-coordinate, normalised to [0, 1], for the start of a color gradient. If the gradient is linear the default is 0; if radial, it is the x-position of the centre of the inner circle with a default of 0.5.

grY1 : Num -> GradientProperty

The y-coordinate, normalised to [0, 1], for the start of a color gradient. If the gradient is linear the default is 0; if radial, it is the y-position of the centre of the inner circle with a default of 0.5.

grX2 : Num -> GradientProperty

The x-coordinate, normalised to [0, 1], for the end of a color gradient. If the gradient is linear the default is 1; if radial, it is the x-position of the centre of the outer circle with a default of 0.5.

grY2 : Num -> GradientProperty

The y-coordinate, normalised to [0, 1], for the end of a color gradient. If the gradient is linear the default is 1; if radial, it is the y-position of the centre of the outer circle with a default of 0.5.

grR1 : Num -> GradientProperty

The radius, normalised to [0, 1], of the inner circle for a radial color gradient. Default is 0.

grR2 : Num -> GradientProperty

The radius, normalised to [0, 1], of the outer circle for a radial color gradient. Default is 0.5.

grStops : List ( Num, String ) -> GradientProperty

Color interpolation points. Each tuple in the list is a position normalised [0, 1] and its associated color.

vGradientScale : Value -> List GradientScaleProperty -> Value

A color gradient value based on a color scale. The first parameter should be the color scale to use. The second parameter is a set of customisation options for projecting the color scale onto the mark area. For example:

maFill
    [ vGradientScale (vScale "cScale")
        [ grStart (nums [ 1, 0 ]), grStop (nums [ 1, 1 ]) ]
    ]

To set a literal color gradient without a color scale, use vGradient instead.

grStart : Num -> GradientScaleProperty

Starting coordinate for the gradient as an [x, y] list normalised to [0, 1]. This coordinate is relative to the bounds of the item being coloured (default is [0, 0]).

grStop : Num -> GradientScaleProperty

Stopping coordinate for the gradient as an [x, y] list normalised to [0, 1]. This coordinate is relative to the bounds of the item being coloured (default is [1, 0] indicating a horizontal gradient).

grCount : Num -> GradientScaleProperty

Target number of sample points to take from the color scale.

3. Specifying Input Data

See the Vega data and the Vega data reference documentation.

3.1 Data Sources

dataSource : List DataTable -> Data

Data source to be used by a visualization. A data source is a collection of data tables which themselves may be generated inline, loaded from a URL or the result of a transformation.

data : String -> List DataProperty -> DataTable

Declare a named dataset. Depending on the properties provided this may be from an external file, from a named data source or inline literal values.

dataFromColumns : String -> List FormatProperty -> List DataColumn -> DataTable

Declare a data table from a list of column values. Each column contains values of the same type, but types may vary between columns. Columns should all contain the same number of items; if not the dataset will be truncated to the length of the shortest.

The first parameter should be the name given to the data table for later reference. Field formatting specifications can be provided in the second parameter or as an empty list to use the default formatting. The columns are most easily generated with dataColumn.

dataColumn : String -> Value -> List DataColumn -> List DataColumn

Create a column of data. A column has a name and a list of values. The final parameter is the list of any other columns to which this is added.

dataFromRows : String -> List FormatProperty -> List DataRow -> DataTable

Declare a data table from a list of row values. Each row is specified with a list of tuples where the first value is the column name, and the second the column value for that row. Each column can have a value of a different type but you must ensure that when multiple rows are added, they match the types of other values in the same column. Field formatting specifications can be provided in the first parameter or as an empty list to use the default formatting.

Rows are most easily generated with dataRow. If you are creating data inline (as opposed to reading from a file), generally, adding data by column is more efficient and less error-prone.

dataRow : List ( String, Value ) -> List DataRow -> List DataRow

Create a row of data. A row comprises a list of (columnName, value) pairs. The final parameter is the list of any other rows to which this is added.

daUrl : Str -> DataProperty

Data file to be loaded when generating a dataset.

daFormat : List FormatProperty -> DataProperty

Data format to use when loading or generating a dataset.

daSource : String -> DataProperty

Name a data source when generating a dataset.

daSources : List String -> DataProperty

Name a collection of data sources when generating a dataset.

daValue : Value -> DataProperty

Data value(s) for generating a dataset inline.

daOn : List Trigger -> DataProperty

Updates to insert, remove, and toggle data values, or clear the data in a dataset when trigger conditions are met.

daSphere : DataProperty

Generate a global sphere dataset.

daDataset : String -> DataReference

Reference a dataset with the given name.

daField : Field -> DataReference

Reference a data field with the given value.

daFields : List Field -> DataReference

Reference a collection of data fields with the given values.

daValues : Value -> DataReference

Create a data reference from a list of literals. Useful when combining with data references from existing data streams. For example

scale "myScale"
    [ scDomain
        (doData
            [ daReferences
                [ [ daValues (vNums [ 2, 4 ]) ]
                , [ daDataset "myData", daField (field "myField") ]
                ]
            ]
        )
    ]

daSignal : String -> DataReference

Make a data reference with a signal.

daReferences : List (List DataReference) -> DataReference

Reference a collection of nested data references.

3.2 Data Sorting

See the Vega sort and Vega type comparison documentation.

daSort : List SortProperty -> DataReference

Sort a data reference.

soAscending : SortProperty

Indicate sorting is to be applied from low to high.

soDescending : SortProperty

Indicate sorting is to be applied from high to low.

soOp : Operation -> SortProperty

Sorting operation.

soByField : Str -> SortProperty

Field to be used when sorting.

soSignal : String -> SortProperty

Sorting type referenced by the value in the named signal.

ascend : Order

Indicate ascending order when sorting.

descend : Order

Indicate descending order when sorting.

orderSignal : String -> Order

Sorting order referenced by the value in the named signal.

3.3 Data Parsing and Formatting

csv : FormatProperty

Indicate a CSV (comma-separated) format when parsing a data source.

tsv : FormatProperty

Indicate a TSV (tab-separated) format when parsing a data source.

dsv : Str -> FormatProperty

DSV (delimited separated value) format with a custom delimiter.

arrow : FormatProperty

Apache arrow data file format.

json : FormatProperty

Indicate a JSON format when parsing a data source.

jsonProperty : Str -> FormatProperty

Property to be extracted from some JSON when it has some surrounding structure or meta-data. e.g., specifying the property values.features is equivalent to retrieving json.values.features from the loaded JSON object with a custom delimiter.

topojsonMesh : Str -> FormatProperty

Create a single mesh instance from a named property in a topoJSON file. Unlike topojsonFeature, geo data are returned as a single unified instance rather than individual GeoJSON features.

topojsonMeshExterior : Str -> FormatProperty

Create a single mesh instance from a named property in a topoJSON file, storing the exterior boundary only. Unlike topojsonFeature, geo data are returned as a single unified instance.

topojsonMeshInterior : Str -> FormatProperty

Create a single mesh instance from a named property in a topoJSON file comprising interior feature boundaries only. Unlike topojsonFeature, geo data are returned as a single unified instance.

topojsonFeature : Str -> FormatProperty

TopoJSON feature format. The first parameter is the name of the feature object set to extract.

fpSignal : String -> FormatProperty

Format referenced by the value in the named signal (e.g. csv, tsv, json). Useful when dynamic loading of data with different formats is required.

parseAuto : FormatProperty

Indicate automatic type inference on data types should be applied when parsing a data source.

parse : List ( String, DataType ) -> FormatProperty

Data parsing rules as a list of tuples where each corresponds to a field name paired with its desired data type. This is only necessary if there is some ambiguity that could prevent correct type inference, such as time text:

dataSource
    [ data "timeData"
        [ daUrl (str "data/timeSeries.json")
        , daFormat [ parse [ ( "timestamp", foDate "%d/%m/%y %H:%M" ) ] ]
        ]
    ]

foNum : DataType

Specify numeric values are to be parsed when reading input data.

foBoo : DataType

Specify Boolean values are to be parsed when reading input data.

foDate : String -> DataType

Date format for parsing data using D3's formatting specifiers.

foUtc : String -> DataType

UTC date format for parsing data using D3's formatting specifiers.

4. Transforming Data

Applying a transform to a data stream can filter or generate new fields in the stream, or derive new data streams. Pipe (|>) the stream into the transform function and specify the transform to apply via one or more of these functions. See the Vega transform documentation.

transform : List Transform -> DataTable -> DataTable

Apply the given ordered list of transforms to the given data stream. Transform examples include filtering, creating new data fields from expressions and creating new data fields suitable for a range of visualization and layout types.

4.1 Basic Transforms

Aggregation

See the Vega aggregate documentation

trAggregate : List AggregateProperty -> Transform

Group and summarise an input data stream to produce a derived output stream. Aggregate transforms can be used to compute counts, sums, averages and other descriptive statistics over groups of data objects.

agGroupBy : List Field -> AggregateProperty

Data fields to group by when performing an aggregation transformation. If not specified, a single group containing all data objects will be used.

agFields : List Field -> AggregateProperty

Data fields to compute aggregate functions when performing an aggregation transformation. The list of fields should align with the operations and field names provided by agOps and agAs. If no fields and operations are specified, a count aggregation will be used by default.

agOps : List Operation -> AggregateProperty

Aggregation operations to apply to the fields when performing an aggregation transformation. The list of operations should align with the fields output field names provided by agFields and agAs.

agAs : List String -> AggregateProperty

The output field names generated when performing an aggregation transformation. The list of field names should align with the fields operations provided by agFields and agOps. If not provided, automatic names are generated by appending _field to the operation name.

agCross : Boo -> AggregateProperty

Whether or not the full cross-product of all groupby values should be included in the output of an aggregation transformation.

agDrop : Boo -> AggregateProperty

Whether or not empty (zero count) groups should be dropped when in an aggregation transformation.

agKey : Field -> AggregateProperty

Field to act as a unique key when performing an agGroupBy aggregation. This can speed up the aggregation but should only be used when there is redundancy in the list of groupBy fields (as there is when binning for example).

transform
    [ trBin (field "examScore") (nums [ 0, 100 ]) []
    , trAggregate
        [ agKey (field "bin0")
        , agGroupBy [ field "bin0", field "bin1" ]
        , agOps [ opCount ]
        , agAs [ "count" ]
        ]
    ]

opArgMax : Operation

An input data object containing the maximum field value to be used in an aggregation operation.

opArgMin : Operation

An input data object containing the minimum field value to be used in an aggregation operation.

opCI0 : Operation

Lower 95% confidence interval to be used in an aggregation operation.

opCI1 : Operation

Upper 95% confidence interval to be used in an aggregation operation.

opCount : Operation

Total count of data objects to be used in an aggregation operation.

opDistinct : Operation

Count of distinct data objects to be used in an aggregation operation.

opMax : Operation

Maximum field value to be used in an aggregation operation.

opMean : Operation

Mean value to be used in an aggregation operation.

opMedian : Operation

Median field value to be used in an aggregation operation.

opMin : Operation

Minimum field value to be used in an aggregation operation.

opMissing : Operation

Count of null or undefined field value to be used in an aggregation operation.

opProduct : Operation

Product of field values to be used in an aggregation operation.

opQ1 : Operation

Lower quartile boundary of field values to be used in an aggregation operation.

opQ3 : Operation

Upper quartile boundary of field values to be used in an aggregation operation.

opStderr : Operation

Standard error of field values to be used in an aggregation operation.

opStdev : Operation

Sample standard deviation of field values to be used in an aggregation operation.

opStdevP : Operation

Population standard deviation of field values to be used in an aggregation operation.

opSum : Operation

Sum of field values to be used in an aggregation operation.

opValid : Operation

Count of values that are not null, undefined or NaN to be used in an aggregation operation.

opVariance : Operation

Sample variance of field value to be used in an aggregation operation.

opVarianceP : Operation

Population variance of field value to be used in an aggregation operation.

opSignal : String -> Operation

Aggregation operation referenced by the value in the named signal.

Join Aggregation

See the Vega join aggregation documentation.

trJoinAggregate : List JoinAggregateProperty -> Transform

Group and summarise an input data stream in a similar way to trAggregate but which is then joined back to the input stream. Helpful for creating derived values that combine both raw data and aggregate calculations, such as percentages of group totals.

jaGroupBy : List Field -> JoinAggregateProperty

Fields to group by in a join aggregate transform.

jaFields : List Field -> JoinAggregateProperty

Fields to aggregate in join aggregate transform.

jaOps : List Operation -> JoinAggregateProperty

Operations in a join aggregate transform.

jaAs : List String -> JoinAggregateProperty

Output fields to be generated by a join aggregate transform.

Numeric Binning

See the Vega bin and Vega dotBin documentation.

trBin : Field -> Num -> List BinProperty -> Transform

Discretises numeric values into a set of bins. The first parameter is the field to bin, the second a two-element numeric list representing the min/max extent of the bins. Optional binning properties can be provided in the final parameter. Commonly used to create frequency histograms by combining with trAggregate to do the counting of field values in each bin.

transform
    [ trBin (field "examScore") (nums [ 0, 100 ]) []
    , trAggregate
        [ agKey (field "bin0")
        , agGroupBy [ field "bin0", field "bin1" ]
        , agOps [ opCount ]
        , agAs [ "count" ]
        ]
    ]

bnInterval : Boo -> BinProperty

Whether or not a bin transformation should output both the start and end bin values. If false, only the starting bin value is output.

bnAnchor : Num -> BinProperty

Value in the binned domain at which to anchor the bins of a bin transform, shifting the bin boundaries if necessary to ensure that a boundary aligns with the anchor value. If not specified, the minimum bin extent value serves as the anchor.

bnMaxBins : Num -> BinProperty

Maximum number of bins to create with a bin transform.

bnBase : Num -> BinProperty

Number base to use for automatic bin determination in a bin transform (default is base 100).

bnSpan : Num -> BinProperty

The span over which to generate bin boundaries (default is extent[1] - extent[0]). The parameter allows automatic step size determination over custom spans (for example, a zoomed-in region) while retaining the overall extent.

bnStep : Num -> BinProperty

Step size to use between bins in a bin transform.

bnSteps : Num -> BinProperty

Allowable step sizes between bins to choose from when performing a bin transform.

bnMinStep : Num -> BinProperty

Minimum allowable bin step size between bins when performing a bin transform.

bnDivide : Num -> BinProperty

Allowable bin step sub-divisions when performing a binning transformation. The parameter should evaluate to a list of numeric values. If not specified, the default of [5, 2] is used, which indicates that for base 10 numbers automatic bin determination can consider dividing bin step sizes by 5 and/or 2.

bnNice : Boo -> BinProperty

Whether or not the bin boundaries in a binning transform will use human-friendly values such as multiples of ten.

bnSignal : String -> BinProperty

Bind the specification of a binning transform (its start, step and stop properties) to a signal with the given name.

bnAs : String -> String -> BinProperty

Output field names to contain the extent of a binning transform (start and end bin values). If not specified these can be retrieved as bin0 and bin1.

trDotBin : Field -> List DotBinProperty -> Transform

Calculates bin positions for stacking dots in a dot plot. The first parameter is the filed to bin, the second a list of binning options. To stack the computed dot positions combine with trStack.

dbroupBy : List Field -> DotBinProperty

The data fields to group by when performing a dot bin transformation. If not specified, all data objects used to generate a single group.

dbStep : Num -> DotBinProperty

The bin width to use when stacking dots in a dot bin transformation.

dbSmooth : Boo -> DotBinProperty

Whether or not dot density stacks should be smoothed to reduce variance in a dot bin transformation. False if not specified.

dbSignal : String -> DotBinProperty

Bind the computed dot binning parameters (an object with start, stop and step properties) to a signal with the given name.

dbAs : String -> DotBinProperty

The name to give the output bins field from a trDotbin transformation. If not specified, output is named bin.

Temporal Binning

trTimeUnit : Field -> List TimeBinProperty -> Transform

Bin a temporal field into discrete time units. For example, to aggregate points in time into weekly groups. The first parameter is the field to bin, the second a list of optional temporal binning properties. The result will be two new fields unit0 and unit1 that contain the lower and upper boundaries of each temporal bin.

tbUnits : List TimeUnit -> TimeBinProperty

Time units to determine the bins. If not specified, units will be inferred based on the extent of values to be binned.

tbStep : Num -> TimeBinProperty

Number of steps between bins in terms of the smallest time unit provided to tbUnits (ignored if not tbUnits not specified).

tbTimezone : Timezone -> TimeBinProperty

Timezone to use when specifying dates and times.

tzLocal : Timezone

Indicates a local timezone (as opposed to UTC).

tzUtc : Timezone

Indicates a UTC timezone (as opposed to using local timezone).

tzSignal : String -> Timezone

Indicates timezone to be set via the named signal.

tbInterval : Boo -> TimeBinProperty

Determines whether or not both the start and end unit values should be output. If false, only the starting (floored) time unit value is written to the output.

tbExtent : DateTime -> DateTime -> TimeBinProperty

Minimum and maximum timestamps defining the full range of the time bins. Only applies if tbUnits not specified.

dtMillis : Basics.Int -> DateTime

Express a timestamp by the number of milliseconds since the Unix epoch.

dtExpr : String -> DateTime

Express a timestamp with a vega Date expression such as datetime(). For example, to represent 12:34pm on 28th February 2001 (noting that months count from 0, not 1):

dtExpr "datetime(2001,1,28,12,34)"

tbMaxBins : Num -> TimeBinProperty

Maximum number of temporal bins to create (default 40). Applies only if tbUnits is not specified.

tbSignal : String -> TimeBinProperty

Bind trTimeUnit output to a signal with the given name. The bound signal has properties unit (smallest time unit), units (all time units), step, start and stop properties.

tbAs : String -> String -> TimeBinProperty

Names to give the fields holding start and end boundaries for each temporal bin. If not specified, these will be named unit0 and unit1.

Collection

See the Vega collect documentation.

trCollect : List ( Field, Order ) -> Transform

Collect all the objects in a data stream within a single list, allowing sorting by data field values.

Text Pattern Counting

See the Vega count pattern documentation.

trCountPattern : Field -> List CountPatternProperty -> Transform

Count the number of occurrences of a text pattern, as defined by a regular expression. This transform will iterate through each data object and count all unique pattern matches found within the designated text field.

The first parameter is the field containing the text to count, the second a list of optional counting properties. The transform generates two fields named text and count unless renamed via cpAs.

cpPattern : Str -> CountPatternProperty

Define a match in a count pattern transformation with a regular expression (escaping backslashes):

transform [ trCountPattern (field "data") [ cpPattern (str "[\\w']{3,}") ] ]

cpCase : Case -> CountPatternProperty

Text case transformation to apply before performing a count pattern transformation. The default, as generated by mixedcase, will leave text untransformed.

lowercase : Case

Make text lowercase when pre-processing as part of a count pattern transformation.

uppercase : Case

Make text uppercase when pre-processing as part of a count pattern transformation.

mixedcase : Case

Leave text unchanged when pre-processing as part of a count pattern transformation.

cpStopwords : Str -> CountPatternProperty

Define text to ignore in a count pattern transformation with a regular expression (escaping backslashes).

cpAs : String -> String -> CountPatternProperty

Names the two output fields generated by a count pattern transformation. By default they are named text and count.

Cross Product

See the Vega cross-product documentation.

trCross : List CrossProperty -> Transform

Compute the cross-product of a data stream with itself.

crFilter : Expr -> CrossProperty

Filter for limiting the results of a cross-product transform.

crAs : String -> String -> CrossProperty

Name the two output fields of a cross-product transform.

Imputing Missing Values

See the Vega impute documentation.

trImpute : Field -> Field -> List ImputeProperty -> Transform

Generate new values for missing data. The first parameter is the data field for which missing values should be imputed. The second is a key field that uniquely identifies the data objects within a group and so allows missing values to be identified. The third is a list of optional properties for customising the imputation.

imByMin : ImputeMethod

Use minimum of a group when imputing a missing value.

imByMax : ImputeMethod

Use maximum of a group when imputing a missing value.

imByMean : ImputeMethod

Use the mean value of a group when imputing a missing value.

imByMedian : ImputeMethod

Use the median value of a group when imputing a missing value.

imByValue : ImputeMethod

Use a specific value when imputing a missing value.

imKeyVals : Value -> ImputeProperty

Additional collection of key values that should be considered for imputation as part of an impute transform.

imMethod : ImputeMethod -> ImputeProperty

Imputation method to be used as part of an impute transform. If not specified the default imByMean method will be used.

imGroupBy : List Field -> ImputeProperty

List of fields by which to group values in an impute transform. Imputation is then performed on a per-group basis, such as a within group mean rather than global mean.

imValue : Value -> ImputeProperty

Value to use when an imputation method is set with imByValue in an impute transform.

Probability Density Function Calculation

One-dimensional Probability Density

See the Vega density documentation.

trDensity : Distribution -> List DensityProperty -> Transform

Compute a new data stream of uniformly-spaced samples drawn from a one-dimensional probability density function (pdf) or cumulative distribution function (cdf). Useful for representing probability distributions and generating continuous distributions from discrete samples through kernel density estimation.

dnExtent : Num -> DensityProperty

A two-element list [min, max] from which to sample a distribution in a density transform.

dnMethod : DensityFunction -> DensityProperty

Type of distribution to generate in a density transform.

dnPdf : DensityFunction

Probability density function (PDF).

dnCdf : DensityFunction

Cumulative density function (CDF).

dnSignal : String -> DensityFunction

Density function referenced by the value in the named signal.

dnSteps : Num -> DensityProperty

Exact number of uniformly spaced steps to take along an extent domain in a density transform.

dnMinSteps : Num -> DensityProperty

Minimum number of uniformly spaced steps (default 25) to take along an extent domain in a density transform.

dnMaxSteps : Num -> DensityProperty

Maximum number of uniformly spaced steps (default 200) to take along an extent domain in a density transform.

dnAs : String -> String -> DensityProperty

Fields to contain a density transform's values (assigned to a new field named in the first parameter) and probabilities (field named in the second parameter). If not specified, the output will allocated to fields named value and probability.

diNormal : Num -> Num -> Distribution

Normal (Gaussian) probability distribution with a given mean (first parameter) and standard deviation (second parameter).

diUniform : Num -> Num -> Distribution

Uniform probability distribution with given minimum (first parameter) and maximum (second parameter) bounds.

diKde : String -> Field -> Num -> Distribution

Kernel density estimate (smoothed probability distribution) for a set of numerical values. The first parameter is the dataset containing the source data, the second the name of the field containing the numerical values and the third the kernel bandwidth. If the bandwidth is 0, it will be estimated from the input data.

diMixture : List ( Distribution, Num ) -> Distribution

Weighted mixture of probability distributions. The parameter should be a list of tuples representing the component distributions and their corresponding weights.

One-dimensional Kernel Density Estimation

See the Vega KDE transform documentation.

trKde : Field -> List KdeProperty -> Transform

Perform a one-dimensional kernel density estimation over an input data stream and generate uniformly spaced samples of the estimated densities. Unlike trDensity, this supports the ability to group by a set of fields and the scaling of densities as probabilities or smoothed counts.

kdGroupBy : List Field -> KdeProperty

The data fields to group by for a KDE transform. If not specified a single group of all data objects is used.

kdCumulative : Boo -> KdeProperty

Whether or not a KDE transform generates cumulative density estimates. Default is false.

kdCounts : Boo -> KdeProperty

Whether or not a KDE transform should generate smoothed counts (true) or probability estimates (false, default).

kdBandwidth : Num -> KdeProperty

Width of the Gaussian kernel for a KDE transform. If 0 (default), the bandwidth is determined from the input via Scott's method.

kdExtent : Num -> KdeProperty

The minimum and maximum from which to sample the distribution for a KDE transform, expressed as a two-element list. If not specified, the full domain extent is used.

kdMinSteps : Num -> KdeProperty

The minimum number of samples (default 25) to take along the extent domain when performing a KDE transform.

kdMaxSteps : Num -> KdeProperty

The maximum number of samples (default 200) to take along the extent domain when performing a KDE transform.

kdResolve : Resolution -> KdeProperty

Indicate how multiple densities should be resolved when performing a KDE transform. If reIndependent (default), each density may have its own extent and number of curve sample steps. If reShared all densities share the same extent and samples, which is useful for stacked densities.

reIndependent : Resolution

Indicate that multiple densities should be treated independently in a KDE transform.

reShared : Resolution

Indicate that multiple densities should be treated independently in a KDE or KDE2d transform.

resolveSignal : String -> Resolution

Resolution type referenced by the value in the named signal.

kdSteps : Num -> KdeProperty

The exact number of samples to take along the extent domain when performing a KDE transform. Overrides kdMinSteps and kdMaxSteps.

kdAs : String -> String -> KdeProperty

Fields to contain a KDE transform's values (assigned to a new field named in the first parameter) and probabilities (field named in the second parameter). If not specified, the output will allocated to fields named value and density.

Two-dimensional Kernel Density Estimation

See the Vega 2d KDE transform documentation.

trKde2d : Num -> Num -> Field -> Field -> List Kde2Property -> Transform

Perform a two-dimensional kernel density estimation over an input data stream and generates one or more raster grids of density estimates. The first two parameters are the width and height over which to perform the estimation. The next two parameters are the x and y fields holding the 2d data over which to perform the KDE.

kd2GroupBy : List Field -> Kde2Property

The data fields to group by for a 2d KDE transform. If not specified a single group of all data objects is used.

kd2Weight : Field -> Kde2Property

The data point weight field used in a 2d KDE density estimation. If unspecified, all points are assumed to have an equal unit weighting.

kd2CellSize : Num -> Kde2Property

Density calculation cell size determining the level of spatial approximation in a 2d KDE transform. The default value of 4 results in 2x reduction to the width and height of the estimation; a value of 1 would result in an output raster matching the dimensions of the estimator's size.

kd2Bandwidth : Num -> Num -> Kde2Property

Widths of the 2d Gaussian kernel for a 2d KDE transform in x, y order. If 0 (default), the bandwidth is automatically determined.

kd2Counts : Boo -> Kde2Property

Whether or not a 2d KDE transform should generate smoothed counts (true) or probability estimates (false, default).

kd2As : String -> Kde2Property

Field to contain a 2d KDE transform's raster values If not specified, the output will allocated to a field named grid.

Quantile Calculation

trQuantile : Field -> List QuantileProperty -> Transform

Calculate quantile values from an input data stream. Useful for examining distributional properties of a data stream and for creating Q-Q plots.

quGroupBy : List Field -> QuantileProperty

The data fields to group by when performing a quantile transformation. If not specified, all data objects are used to create a single group.

quProbs : Num -> QuantileProperty

Quantile values to compute scaled as probabilities in the range (0, 1). For example,

quProbs [ 0.25, 0.5, 0.75 ]

will specify that quartiles are to be calculated.

If not provided the default step size of 0.01 or that specified via quStep will be used to provide the quantile probabilities.

quStep : Num -> QuantileProperty

The probability step size to use when performing a quantile transformation. Only used if quProbs is not specified. The default is 0.01.

quAs : String -> String -> QuantileProperty

Name the output fields from a quantile transformation. The first parameter is the name to give the quantile bin, the second the name of its associated value. Default names are prob and value.

Regression

trRegression : Field -> Field -> List RegressionProperty -> Transform

Create a two-dimensional regression model. The first two parameters are the names of the independent (predictor) and dependent (predicted) fields respectively. The third is a list of optional customisation functions. See the Vega regression documentation

reGroupBy : List Field -> RegressionProperty

Group by a given set of fields when performing a regression transform. If not specified, all data objects are used.

reMethod : RegressionMethod -> RegressionProperty

Type of regression model to use.

reLinear : RegressionMethod

A linear regression model (y = a + bx).

reLog : RegressionMethod

A log regression model (y = a + b.log(x)).

reExp : RegressionMethod

An exponential regression model (y = a + e^(bx)).

rePow : RegressionMethod

A power regression model (y = ax^b).

reQuad : RegressionMethod

A quadratic regression model (y = a + bx + cx^2).

rePoly : RegressionMethod

A polynomial regression model (y = a + bx + ... + kx^n). The order (n) of the polynomial can be set with reOrder.

reSignal : String -> RegressionMethod

Regression model referenced by the value in the named signal.

reMethodValue : RegressionMethod -> Value

Convenience function for generating a value representing a given regression method. Useful when generating signals representing method types.

reOrder : Num -> RegressionProperty

The polynomial order for a rePoly regression model.

reExtent : Num -> RegressionProperty

Start and end values of the regression line on the independent (predictor) axis expressed as a two-element numeric list.

reParams : Boo -> RegressionProperty

Whether or not a regression transform should return the fit model parameters (one object per group), or the trend line points. If true, the resulting objects include a coef list of fitted coefficient values (starting with the intercept term and then including terms of increasing order) and an rSquared value (indicating the total variance explained by the model).

reAs : String -> String -> RegressionProperty

Names of regression output fields representing the independent (predictor) and dependent (predicted) smoothed values. If not supplied, the names of the input independent and dependent fields will be used.

trLoess : Field -> Field -> List LoessProperty -> Transform

Create a trend line via locally estimated regression. This creates the smoothed line via a moving window in contrast to the parametric regression lines generated via trRegression. The first two parameters are the names of the independent (predictor) and dependent (predicted) fields respectively. The third is a list of optional customisation functions.

lsGroupBy : List Field -> LoessProperty

Group by a given set of fields when performing a loess (locally estimated regression) transform.

lsBandwidth : Num -> LoessProperty

Bandwidth to be used when performing a loess (locally estimated regression) transform. The parameter is is the proportion of the entire dataset to include in the sliding window. Default is 0.3 (i.e. 30% of values).

lsAs : String -> String -> LoessProperty

Names of loess (locally estimated regression) output fields representing the independent (predictor) and dependent (predicted) smoothed values. If not supplied, the names of the input independent and dependent fields will be used.

Sampling

See the Vega sample documentation.

trSample : Num -> Transform

Generate a random sample from a data stream to generate a smaller stream. The parameter determines the maximum number of data items to sample.

Range calculation

See the Vega extent documentation.

trExtent : Field -> Transform

Compute the minimum and maximum values for a data field, producing a two-element [min, max] list.

trExtentAsSignal : Field -> String -> Transform

Compute the minimum and maximum values for a given data field and bind it to a signal with the given name.

Filtering

See the Vega filter and crossfilter documentation.

trFilter : Expr -> Transform

Remove objects from a data stream based on the given filter expression.

trCrossFilter : List ( Field, Num ) -> Transform

Maintain a filter mask for multiple dimensional queries, using a set of sorted indices. The parameter is a list of (field,range) pairs indicating which fields to filter and the numeric range of values in the form of a num that should resolve to a [min (inclusive), max (exclusive)] pair.

trCrossFilterAsSignal : List ( Field, Num ) -> String -> Transform

Perform a crossfilter transform. This version can be used with trResolvefilter to enable fast interactive querying over large datasets. The final parameter is the name of a new signal with which to bind the results of the filter (which can then be referenced by trResolveFilter).

trResolveFilter : String -> Num -> Transform

Use a filter mask generated by a crossfilter transform to generate filtered data streams efficiently. The first parameter is the signal created by trCrossFilterAsSignal and the second a bit mask indicating which fields in the crossfilter should be ignored. Each bit corresponds to a field and query in the crossfilter transform’s fields and query lists. If the corresponding bit is on, that field and query will be ignored when resolving the filter. All other queries must pass the filter for a tuple to be included downstream.

Flattening

trFlatten : List Field -> Transform

Map list-valued fields to a set of individual data objects, one per list entry. This version generates the output fields with names corresponding to the list field used.

trFlattenWithIndex : String -> List Field -> Transform

Similar to trFlatten except an additional field with the name given by the first parameter is output containing zero-index of the original unflattened data item. See the Vega documentation for an example.

trFlattenAs : List Field -> List String -> Transform

Similar to trFlatten but allowing the output fields to be named.

trFlattenWithIndexAs : String -> List Field -> List String -> Transform

Similar to trFlattenWithIndex but allowing the output fields to be named.

Folding and Pivoting

See the Vega fold and pivot documentation.

trFold : List Field -> Transform

Perform a gather operation to tidy a table. Collapse multiple data fields into two new data fields: key containing the original data field names and value containing the corresponding data values. This performs the same function as the gather operation in R and in the Tidy Elm package.

trFoldAs : List Field -> String -> String -> Transform

Similar to trFold but allows the new output key and value fields to be given alternative names (second and third parameters respectively).

trPivot : Field -> Field -> List PivotProperty -> Transform

Map unique values from a field to new aggregated fields in the output stream. The first parameter is the field to pivot on (providing new field names). The second is the field containing values to aggregate to populate new values. The third allows the transform to be customised.

piGroupBy : List Field -> PivotProperty

Fields to group by when performing a pivot transform. If not specified, a single group containing all data objects will be used.

piLimit : Num -> PivotProperty

Maximum number of fields to generate when performing a pivot transform or 0 for no limit.

piOp : Operation -> PivotProperty

Aggregation operation to use by when performing a pivot transform. If not specified, fields will be aggregated by their sum.

Deriving New Fields

See the Vega formula, lookup, identifier, project and window documentation.

trFormula : String -> String -> Transform

Extend a data object with new values according to the given Vega expression. The second parameter is a new field name to give the result of the evaluated expression. This version will reapply the formula if the data changes. To perform a one-off formula calculation use trFormulaInitOnly.

dataSource
    [ data "world"
        [ daUrl (str "world-110m.json")
        , daFormat [ topojsonFeature "countries" ]
        ]
        |> transform
            [ trFormula "geoCentroid('myProj', datum)" "myCentroid" ]
    ]

trFormulaInitOnly : String -> String -> Transform

Similar to trFormula but will apply the formula only once even if the data changes.

trLookup : String -> Field -> List Field -> List LookupProperty -> Transform

Extend a primary data stream by looking up values on a secondary data stream. The first parameter is the name of the secondary data stream upon which to perform the lookup. The second is the key field in that secondary stream. The third is the set of key fields from the primary data stream, each of which are then searched for in a single key field of the secondary data stream. Optional customisation provided as a list of properties in the final parameter.

luAs : List String -> LookupProperty

Output fields in which to write data found in the secondary stream of a lookup.

luValues : List Field -> LookupProperty

Fields to copy from the secondary stream to the primary stream in a lookup transformation. If not specified, a reference to the full data record is copied.

luDefault : Value -> LookupProperty

Default value to assign if lookup fails in a lookup transformation.

trIdentifier : String -> Transform

Extend a data object with a globally unique key value. Identifier values are assigned using an internal counter. This counter is shared across all instances of this transform within a single Vega view, including different data sources, but not across different Vega views.

trProject : List ( Field, String ) -> Transform

Perform a relational algebra projection transform resulting in a new stream of derived data objects that include one or more fields from the input stream. The parameter is a list of field-name pairs where the fields are those fields to be copied over in the projection and the names are the new names to give the projected fields.

trWindow : List WindowOperation -> List WindowProperty -> Transform

Performs calculations such as ranking, lead/lag analysis and running sums over sorted groups of data objects . Calculated values are written back to the input data stream.

transform
    [ trWindow [ wnOperation woRowNumber "rank" ]
        [ wnSort [ ( field "myField", descend ) ] ]
    ]

wnAggOperation : Operation -> Maybe Field -> String -> WindowOperation

Aggregate operation to be applied during a window transformation. This version is suitable for operations without parameters (e.g. woRowNumber) and that are not applied to a specific field.

The parameters are the operation to apply, the input field (or Nothing if no input field) and the name to give to the field that will contain the results of the calculation.

The example below calculates the average over an unbounded window:

transform
    [ trWindow [ wnAggOperation opMean (Just (field "IMDB_Rating")) "avScore" ]
        [ wnFrame numNull ]
    ]

wnOperation : WOperation -> String -> WindowOperation

Window-specific operation to be applied during a window transformation. This version is suitable for operations without parameters (e.g. woRowNumber) and that are not applied to a specific field.

The parameters are the operation to apply and the name to give to the field which will contain the results of the calculation.

transform
    [ trWindow [ wnOperation woRank "order" ]
        [ wnSort [ ( field "Gross", descend ) ] ]
    ]

wnOperationOn : WOperation -> Maybe Num -> Maybe Field -> String -> WindowOperation

Window-specific operation to be applied during a window transformation. This version is suitable for operations that have a parameter (e.g. woLag or woLead) and/or operations that require a specific field as input (e.g. woLastValue). The parameters are in order: the type of operation, a possible operation parameter, the field to apply it to and its output field name.

transform
    [ trWindow
        [ wnOperationOn woLag
            (Just (num 5))
            (Just (field "temperature"))
            "oldTemp"
        ]
        []
    ]

woRowNumber : WOperation

Assign consecutive row number to values in a data object to be applied in a window transform.

woRank : WOperation

Rank function to be applied in a window transform.

woDenseRank : WOperation

Dense rank function to be applied in a window transform.

woPercentRank : WOperation

Percentile of values in a sliding window to be applied in a window transform.

woCumeDist : WOperation

Cumulative distribution function to be applied in a window transform.

woPercentile : WOperation

Value preceding the current object in a sliding window to be applied in a window transform.

woLag : WOperation

Value preceding the current object in a sliding window to be applied in a window transform.

woLead : WOperation

Value following the current object in a sliding window to be applied in a window transform.

woFirstValue : WOperation

First value in a sliding window to be applied in a window transform.

woLastValue : WOperation

Last value in a sliding window to be applied in a window transform.

woNthValue : WOperation

Nth value in a sliding window to be applied in a window transform.

woPrevValue : WOperation

If the current field value is not null and not undefined, it is returned. Otherwise, the nearest previous non-missing value in the sorted group is returned. This operation is performed relative to the sorted group, not the window frame.

woNextValue : WOperation

If the current field value is not null and not undefined, it is returned. Otherwise, the next non-missing value in the sorted group is returned. This operation is performed relative to the sorted group, not the window frame.

woSignal : String -> WOperation

Window operation referenced by the value in the named signal. For names of valid window operations see the Vega window operation documentation

wnSort : List ( Field, Order ) -> WindowProperty

Indicate how sorting data objects is applied within a window transform.

transform
    [ trWindow [ wnOperation woRowNumber "order" ]
        [ wnSort [ ( field "score", ascend ) ] ]
    ]

If two objects are equal in terms of sorting field datum by they are considered 'peers'. If no sorting comparator is specified, data objects are processed in the order they are observed.

wnGroupBy : List Field -> WindowProperty

Data fields by which to partition data objects into separate windows during a window transform. If not specified, a single group containing all data objects will be used.

wnFrame : Num -> WindowProperty

Two-element list indicating how a sliding window should proceed during a window transform. The list entries should either be a number indicating the offset from the current data object, or numNull to indicate unbounded rows preceding or following the current data object.

wnIgnorePeers : Boo -> WindowProperty

Whether or not a sliding frame in a window transform should ignore peer values.

Data Generation

See the Vega sequence documentation.

trSequence : Num -> Num -> Num -> Transform

Generate a data stream of numbers between a start (first parameter) and end (second parameter) inclusive in increments specified by the third parameter. If the end value is less than the start value, the third parameter should be negative. The resulting output field will be called data.

Sequences can be used to feed other transforms to generate data to create random (x,y) coordinates:

dataSource
    [ data "randomData" []
        |> transform
            [ trSequence (num 1) (num 1000) (num 1)
            , trFormula "random()" "x"
            , trFormula "random()" "y"
            ]
    ]

trSequenceAs : Num -> Num -> Num -> String -> Transform

Similar to trSequence but allowing the resulting sequence to be named (fourth parameter).

4.2 Spatial Transforms

Transformations that work with spatial, often geographic, data.

Contouring

See the Vega isocontour documentation

trIsocontour : List IsocontourProperty -> Transform

Generate geoJSON representing contours threaded through a given raster surface. See the Vega Isocontour documentation for details.

icField : Field -> IsocontourProperty

The name of the field containing raster data to contour in an isocontour transform.

icThresholds : Num -> IsocontourProperty

Provide a list of explicit contour levels for an isocontour transformation. If specified, icLevels, icNice, icResolve and icZero will be ignored.

icLevels : Num -> IsocontourProperty

The desired number of contour levels in an isocontour transform (ignored if icThresholds is specified).

icNice : Boo -> IsocontourProperty

Whether or not contour levels should be aligned with 'nice' human-friendly values. If set to true, this may alter the precise number of contour levels generated.

icResolve : Resolution -> IsocontourProperty

The method of resolving contour thresholds across multiple input grids. Setting to reShared is useful when combining multiple contour plots that need to use a common scale.

icZero : Boo -> IsocontourProperty

Whether or not an isocontour transformation should use zero as a baseline value.

icSmooth : Boo -> IsocontourProperty

Whether or not contour lines should be smoothed (ignored if using 2d KDE for input generation).

icScale : Num -> IsocontourProperty

Scale the output isocontour coordinates by the given factor. To scale x and y axes independently supply a two-element nums list. Useful for scaling contours to match a desired output resolution.

icTranslate : Num -> Num -> IsocontourProperty

Translate the output isocontour coordinates by the given factors in the x and y directions respectively. Useful for scaling contours to match a desired coordinate space.

icAs : String -> IsocontourProperty

Provide name for an isocontour transform output. Default is for output field to be named contour.

Rasters

trHeatmap : List HeatmapProperty -> Transform

Generate a raster image from a raster grid that can be rendered with an image mark.

hmField : Field -> HeatmapProperty

The field containing the raster grid data to transform into a heatmap image. If not provided, the data object to which transform is being applied is assumed to be the raster grid.

hmColor : Str -> HeatmapProperty

Encode raster cells in a heatmap transform with a colour. If using an expression, it has access datum.$x, datum.$y, datum.$value and datum.$max representing the x and y positions of each raster cell, its raster value and the global maximum of raster values respectively. Expressions also have access to any parent data fields. For example, to colour by a grandparent's temperature field:

hmColor (strExpr (expr "scale('cScale', datum.datum.temperature)"))

hmOpacity : Num -> HeatmapProperty

Encode raster cells in a heatmap transform with an opacity value. If using an expression, it has access to datum.$x, datum.$y, datum.$value and datum.$max representing the x and y positions of each raster cell, its raster value and the global maximum of raster values respectively.

For example, to make opacity proportional to the cube of each raster value:

hmOpacity (numExpr (expr "pow(datum.$value,3) / pow(datum.$max,3)"))

Alternatively, to set a fixed opacity:

hmOpacity (num 0.3)

hmResolve : Resolution -> HeatmapProperty

Determines how the maximum value in a heatmap transform is determined, and therefore used for scaling colours and opacity (datum.$max). Useful when standardising colour or opacity ranges across multiple rasters.

hmAs : String -> HeatmapProperty

Name to give the output of a heatmap transform. If not specified, defaults to image.

GeoJSON transformation

See the Vega geoJSON, geoPoint, geoshape and geopath documentation.

trGeoShape : String -> List GeoPathProperty -> Transform

Generate a renderer instance that maps GeoJSON features to a shape instance for use with the shape mark. Similar to the trGeoPath, but rather than generate intermediate SVG path strings, this transform produces a shape instance that directly generates drawing commands during rendering resulting in improved performance when using canvas rendering for dynamic maps.

trGeoPath : String -> List GeoPathProperty -> Transform

Map GeoJSON features to SVG path strings. The first parameter can be the name of a projection to apply to the mapping, or an empty string if no map projection. Similar to the trGeoShape but immediately generates SVG path strings.

gpField : Field -> GeoPathProperty

Data field containing GeoJSON data when applying a geoShape or geoPath transformation. If unspecified, the full input data object will be used.

gpPointRadius : Num -> GeoPathProperty

Default radius (in pixels) to use when drawing GeoJSON Point and MultiPoint geometries. An expression value may be used to set the point radius as a function of properties of the input GeoJSON.

gpAs : String -> GeoPathProperty

Output field in which to write a generated shape instance following a geoShape or geoPath transformation.

trGeoJson : List GeoJsonProperty -> Transform

Consolidate geographic data into a single feature collection. This can be captured as a signal that will represent the consolidated feature collection. If an empty list is provided as the parameter, the data are not projected (identity projection).

gjFields : Field -> Field -> GeoJsonProperty

Fields containing longitude (first parameter) and latitude (second parameter) to be consolidated into a feature collection by a geoJSON transform.

gjFeature : Field -> GeoJsonProperty

Field containing the GeoJSON objects to be consolidated into a feature collection by a geoJSON transform.

gjSignal : String -> GeoJsonProperty

Name of the a new signal to capture the output of generated by a geoJSON transform.

trGeoPoint : String -> Field -> Field -> Transform

Project a longitude, latitude pair to (x,y) coordinates according to the given map projection. The first parameter is the name of the map projection to use, the second and third the fields containing the longitude and latitude values respectively. This version generates two new fields with the name x and y holding the projected coordinates.

trGeoPointAs : String -> Field -> Field -> String -> String -> Transform

Similar to trGeoPoint but allowing the projected coordinates to be named (last two parameters).

Graticule Generation

See the Vega graticule documentation.

trGraticule : List GraticuleProperty -> Transform

Generate a reference grid of meridians (longitude) and parallels (latitude) for cartographic maps. The default graticule has meridians and parallels every 10° between ±80° latitude; for the polar regions meridians are every 90°.

It generates a new data stream containing a single GeoJSON data object for the graticule, which can subsequently be drawn using the geopath or geoshape transform.

grExtent : Num -> GraticuleProperty

Major and minor extents of a graticule to be the same values. Parameter should evaluate to a two-element list representing longitude and latitude extents.

grExtentMajor : Num -> GraticuleProperty

Major extent of a graticule. Parameter should evaluate to a two-element list representing longitude and latitude extents.

grExtentMinor : Num -> GraticuleProperty

Minor extent of a graticule. Parameter should evaluate to a two-element list representing longitude and latitude extents.

grStep : Num -> GraticuleProperty

Major and minor step angles of a graticule to be the same values. Parameter should be a two-element list representing longitude and latitude spacing.

grStepMajor : Num -> GraticuleProperty

Major step angles of a graticule. Parameter should be a two-element list representing longitude and latitude spacing.

grStepMinor : Num -> GraticuleProperty

Minor step angles of a graticule. Parameter should be a two-element list representing longitude and latitude spacing.

grField : Field -> GraticuleProperty

Field used to bin when generating a graticule.

grPrecision : Num -> GraticuleProperty

Precision in degrees with which graticule arcs are generated. The default value is 2.5 degrees.

Voronoi Diagrams

See the Vega Voronoi documentation.

trVoronoi : Field -> Field -> List VoronoiProperty -> Transform

Compute a voronoi diagram for a set of input points and return the computed cell paths.

voSize : Num -> VoronoiProperty

Extent of the voronoi cells in a voronoi transform. The single parameter should evaluate to a list of two numbers representing the bottom-right of the extent. The top-left is assumed to be [0,0].

voExtent : Num -> Num -> VoronoiProperty

Extent of the voronoi cells in a voronoi transform. The two parameters should each evaluate to a list of two numbers representing the coordinates of the top-left and bottom-right of the extent respectively.

voAs : String -> VoronoiProperty

Name of the output field of a voronoi transform. If not specified, the default is path.

4.3 Layout Transforms

Link Paths

See the Vega link path documentation.

trLinkPath : List LinkPathProperty -> Transform

Route a visual link between two nodes to draw edges in a tree or network layout. Writes one property to each datum, providing an SVG path string for the link path.

lpSourceX : Field -> LinkPathProperty

Field for the source x-coordinate in a linkPath transformation. The default is source.x.

lpSourceY : Field -> LinkPathProperty

Field for the source y-coordinate in a linkPath transformation. The default is source.y.

lpTargetX : Field -> LinkPathProperty

Field for the target x-coordinate in a linkPath transformation. The default is target.x.

lpTargetY : Field -> LinkPathProperty

Field for the target y-coordinate in a linkPath transformation. The default is target.y.

lpOrient : Orientation -> LinkPathProperty

Orientation of a link path in a linkPath transformation. If a radial orientation is specified, x and y coordinate parameters will be interpreted as an angle (in radians) and radius, respectively.

lpShape : LinkShape -> LinkPathProperty

Shape of a link path in a linkPath transformation.

lpRequire : String -> LinkPathProperty

A required signal that a linkpath transform depends upon. This is needed if source or target coordinates are set as a non-propagating side-effect of a transform in a different stream such as a force transform. In such cases the upstream transform should be bound to a signal and required with this function.

lpAs : String -> LinkPathProperty

Name for the output field of a link path in a linkPath transformation. If not specified, the default is "path".

lsLine : LinkShape

Straight lines linking nodes in a link diagram.

lsArc : LinkShape

Arcs of circles linking nodes in a link diagram.

lsCurve : LinkShape

Curved lines linking nodes in a link diagram.

lsDiagonal : LinkShape

Curved diagonal lines linking nodes in a link diagram.

lsOrthogonal : LinkShape

Orthogonal lines linking nodes in a link diagram.

lsSignal : String -> LinkShape

Line shape between nodes referenced by the value in the named signal.

Angular Layouts

See the Vega pie documentation.

trPie : List PieProperty -> Transform

Calculates the angular extents of arc segments laid out in a circle, for example to create a pie chart. Writes two properties to each datum, indicating the starting and ending angles (in radians) of an arc.

piField : Field -> PieProperty

The field to encode with angular spans in a pie chart transform.

piStartAngle : Num -> PieProperty

The starting angle in radians in a pie chart transform. The default is 0 indicating that the first slice starts 'north'.

piEndAngle : Num -> PieProperty

End angle in radians in a pie chart transform. The default is 2 PI indicating the final slice ends 'north'.

piSort : Boo -> PieProperty

Indicate whether or not pie slices should be stored in angular size order.

piAs : String -> String -> PieProperty

Output fields for the computed start and end angles for each arc in a pie transform.

Stacked Layouts

See the Vega stack documentation.

trStack : List StackProperty -> Transform

Compute a layout by stacking groups of values. The most common use case is to create stacked graphs, including stacked bar charts and stream graphs. This transform writes two properties to each datum, indicating the starting and ending stack values.

stField : Field -> StackProperty

Field that determines the stack heights in a stack transform.

stGroupBy : List Field -> StackProperty

Grouping of fields with which to partition data into separate stacks in a stack transform.

stSort : List ( Field, Order ) -> StackProperty

Criteria for sorting values in a stack transform.

stOffset : StackOffset -> StackProperty

Baseline offset used in a stack transform.

stAs : String -> String -> StackProperty

Names of the output fields for the computed start and end stack values of a stack transform.

stZero : StackOffset

Offset a stacked layout using a baseline at the foot of a stack.

stCenter : StackOffset

Offset a stacked layout using a central stack baseline.

stNormalize : StackOffset

Rescale a stacked layout to use a common height while preserving relative size of stacked quantities.

stSignal : String -> StackOffset

Stacking offset referenced by the value in the named signal.

Force Generated Layouts

See the Vega force documentation.

trForce : List ForceSimulationProperty -> Transform

Compute a force-directed layout. This layout transformation uses a model in which data objects act as charged particles (or nodes), optionally connected by a set of edges (or links). A set of forces is used to drive a physics simulation that determines the node positions.

fsStatic : Boo -> ForceSimulationProperty

Whether a simulation in a force transformation should be computed in batch to produce a static layout (true) or should be animated (false).

fsRestart : Boo -> ForceSimulationProperty

Whether a simulation in a force transformation should restart when node object fields are modified.

fsIterations : Num -> ForceSimulationProperty

Number of iterations in a force transformation when in static mode (default 300).

fsAlpha : Num -> ForceSimulationProperty

Energy level or “temperature” of a simulation under a force transform. Alpha values lie in the range [0, 1]. Internally, the simulation will decrease the alpha value over time, causing the magnitude of updates to diminish.

fsAlphaMin : Num -> ForceSimulationProperty

Minimum amount by which to lower the alpha value on each simulation iteration under a force transform.

fsAlphaTarget : Num -> ForceSimulationProperty

Target alpha value to which a simulation converges under a force transformation.

fsVelocityDecay : Num -> ForceSimulationProperty

Friction to be applied to a simulation in a force transformation. This is applied after the application of any forces during an iteration.

fsForces : List Force -> ForceSimulationProperty

Forces to include in a force-directed simulation resulting from a force transform.

fsAs : String -> String -> String -> String -> ForceSimulationProperty

Names of the output fields to which node positions and velocities are written after a force transformation. The default is ["x", "y", "vx", "vy"] corresponding to the order of parameter names.

foCenter : Num -> Num -> Force

Force that pulls all nodes towards a shared centre point in a force simulation. The two parameters specify the x and y coordinates of the centre point.

foCollide : Num -> List ForceProperty -> Force

Collision detection force that pushes apart nodes whose circular radii overlap in a force simulation. The first parameter specifies the radius of the node to which it applies. The second enables the strength and number of iterations to be specified.

foNBody : List ForceProperty -> Force

n-body force that causes nodes to either attract or repel each other in a force simulation. The parameter enables the strength, theta value, and min/max distances over which the force acts to be specified.

foLink : Str -> List ForceProperty -> Force

Link constraints that cause nodes to be pushed apart towards a target separation distance in a force simulation. The first parameter is the name of the dataset containing the link objects, each of which should contain source and target fields. The second enables the id, distance, strength and number of iterations to be specified. If an id field parameter is provided, it is used to relate link objects and node objects. Otherwise, the source and target fields should provide indices into the list of node objects.

foX : Field -> List ForceProperty -> Force

Force attraction towards a particular x-coordinate (first parameter), with a given strength (second parameter) on a per-node basis.

foY : Field -> List ForceProperty -> Force

Force attraction towards a particular y-coordinate (first parameter), with a given strength (second parameter) on a per-node basis.

fpStrength : Num -> ForceProperty

Relative strength of a force or link constraint in a force simulation.

fpDistance : Num -> ForceProperty

Distance in pixels by which the link constraint should separate nodes (default 30).

fpIterations : Num -> ForceProperty

Number of iterations to run collision detection or link constraints (default 1) in a force directed simulation.

fpTheta : Num -> ForceProperty

Approximation parameter for aggregating more distance forces in a force-directed simulation (default 0.9).

fpDistanceMin : Num -> ForceProperty

Minimum distance over which an n-body force acts. If two nodes are closer than this value, the exerted forces will be as if they are distanceMin apart (default 1).

fpDistanceMax : Num -> ForceProperty

Maximum distance over which an n-body force acts. If two nodes exceed this value, they will not exert forces on each other.

fpId : Field -> ForceProperty

Data field for a node’s unique identifier. If provided, the source and target fields of each link should use these values to indicate nodes. The field name should be prefaced with datum.. For example,

fpId (field "datum.myNodeId")

Non-overlapping label layouts

See the Vega Label transform documentation.

trLabel : Num -> Num -> List LabelOverlapProperty -> Transform

Transform the positions of text marks so they do not overlap with each other or other marks in a chart. The first two parameters are the width and height of the chart area in which to lay out the labels. The third is a list of optional layout functions.

lbAnchor : List LabelAnchorProperty -> LabelOverlapProperty

Text label anchor positions to consider when arranging non-overlapping labels. If not specified, all anchor positions other then laMiddle are considered.

lbAvoidMarks : List String -> LabelOverlapProperty

Named marks that labels should not overalp with. If not supplied, no other marks are given priority.

lbAvoidBaseMark : Boo -> LabelOverlapProperty

Whether or not labels should overlap the base mark.

lbLineAnchor : Anchor -> LabelOverlapProperty

The anchor position of labels for line marks, where one line receives one label. Note that only anStart and anEnd should be used here. Any other value, or if not supplied, assumes and end anchor.

lbMarkIndex : Num -> LabelOverlapProperty

Index of a mark in a group mark to use as the base mark (default 0). When a group mark is used as base mark, this is used to specify which mark in the group to label. Only applies when the base mark is a group mark.

lbMethod : LabelMethod -> LabelOverlapProperty

Labeling method to use for area marks. Only applies when the base mark is a group mark containing area marks.

lbOffset : Num -> LabelOverlapProperty

Label offsets in pixels for each anchor direction, relative to the base mark bounding box (defaults to 1 for all anchors). If provided as a single number, the value will be applied to all anchor directions.

lbPadding : Num -> LabelOverlapProperty

Padding in pixels (default 0) by which a label may extend past the chart bounding box.

lbSort : Field -> LabelOverlapProperty

Field indicating the order in which labels should be placed, in ascending order.

lbAs : String -> String -> String -> String -> String -> LabelOverlapProperty

Explicitly name he output fields generated by trLabel. The default is x, y, opacity, align and baseline. The parameters override these defaults respectively. Setting these values explicitly can be useful if you wish to force repositioning of labels in response to a dynamic signal.

laLeft : LabelAnchorProperty

Include a left anchor for a text label in the possiblities for a non-overlapping label transform.

laTopLeft : LabelAnchorProperty

Include a top-left anchor for a text label in the possiblities for a non-overlapping label transform.

laTop : LabelAnchorProperty

Include a top anchor for a text label in the possiblities for a non-overlapping label transform.

laTopRight : LabelAnchorProperty

Include a top-right anchor for a text label in the possiblities for a non-overlapping label transform.

laRight : LabelAnchorProperty

Include a right anchor for a text label in the possiblities for a non-overlapping label transform.

laBottomRight : LabelAnchorProperty

Include a bottom-right anchor for a text label in the possiblities for a non-overlapping label transform.

laBottom : LabelAnchorProperty

Include a bottom anchor for a text label in the possiblities for a non-overlapping label transform.

laBottomLeft : LabelAnchorProperty

Include a bottom-left anchor for a text label in the possiblities for a non-overlapping label transform.

laMiddle : LabelAnchorProperty

Include a middle anchor for a text label in the possiblities for a non-overlapping label transform.

lmFloodFill : LabelMethod

Use flood-fill method when positioning non-overlapping labels.

lmReducedSearch : LabelMethod

Use reduced search method when positioning non-overlapping labels.

lmNaive : LabelMethod

Use (default) naive method when positioning non-overlapping labels.

Word Cloud Layouts

See the Vega wordcloud documentation.

trWordcloud : List WordcloudProperty -> Transform

Compute a word cloud layout similar to a 'wordle'. Useful for visualising the relative frequency of words or phrases.

mark text
    [ mTransform
        [ trWordcloud
            [ wcSize (nums [ 800, 400 ])
            , wcText (field "text")
            , wcRotate (numExpr (exField "datum.angle"))
            , wcFontSize (numExpr (exField "datum.count"))
            , wcFontWeight (strExpr (exField "datum.weight"))
            , wcFontSizeRange (nums [ 12, 56 ])
            ]
        ]
    ]

wcFont : Str -> WordcloudProperty

Font family to use for a word in a wordcloud.

wcFontStyle : Str -> WordcloudProperty

Font style to use for words in a wordcloud.

wcFontWeight : Str -> WordcloudProperty

Font weights to use for words in a wordcloud.

wcFontSize : Num -> WordcloudProperty

Font size to use for a word in a wordcloud.

wcFontSizeRange : Num -> WordcloudProperty

Font size range to use for words in a wordcloud. The parameter should resolve to a two-element list [min, max]. The size of words in a wordcloud will be scaled to lie in the given range according to the square root scale.

wcPadding : Num -> WordcloudProperty

Padding, in pixels, to be placed around words in a wordcloud.

wcRotate : Num -> WordcloudProperty

Angle in degrees of words in a wordcloud layout.

wcText : Field -> WordcloudProperty

Data field with the input word text for a wordcloud transform.

wcSize : Num -> WordcloudProperty

Size of layout created by a wordcloud transform. The parameter should resolve to a two-element list [width, height] in pixels.

wcSpiral : Spiral -> WordcloudProperty

Spiral layout method for a wordcloud transform.

spArchimedean : Spiral

Archimedean spiralling for sequential positioning of words in a wordcloud.

spRectangular : Spiral

Rectangular spiralling for sequential positioning of words in a wordcloud.

spSignal : String -> Spiral

Word cloud spiral type (archimedean or rectangular) referenced by the value in the named signal.

wcAs : String -> String -> String -> String -> String -> String -> String -> WordcloudProperty

Name output fields created by a word cloud transform. The parameters map to the following default values: x, y, font, fontSize, fontStyle, fontWeight and angle.

4.4 Hierarchy Transforms

Nesting and Stratification

See the Vega nest, stratify documentation.

trNest : List Field -> Boo -> Transform

Generate a tree data structure from input data objects by dividing children into groups based on distinct field values. This can provide input to tree layout methods such as trTree, trTreemap, trPack and trPartition.

trStratify : Field -> Field -> Transform

Generate a hierarchical (tree) data structure from input data objects, based on key fields that match an id for each node (first parameter) and their parent's key (second parameter) nodes. Internally, this transform generates a set of tree node objects that can then be transformed with tree layout functions such as trTree, trTreemap, trPack, and trPartition.

Packing

See the Vega pack documentation.

trPack : List PackProperty -> Transform

Compute an enclosure diagram that uses containment (nesting) to represent a hierarchy. The size of the leaf circles encodes a quantitative dimension of the data. The enclosing circles show the approximate cumulative size of each subtree, but due to wasted space there is some distortion; only the leaf nodes can be compared accurately.

paField : Field -> PackProperty

The data field corresponding to a numeric value for the node in a packing transform. The sum of values for a node and all its descendants is available on the node object as the value property. If radius is null, this field determines the node size.

paSort : List ( Field, Order ) -> PackProperty

Packing transform sorting properties. The inputs to subject to sorting are tree node objects, not input data objects.

paSize : Num -> PackProperty

The size of a packing layout, provided as a two-element list in [width, height] order (or a signal that generates such a list).

paRadius : Maybe Field -> PackProperty

Node radius to use in a packing transform. If Nothing (the default), the radius of each leaf circle is derived from the field value.

paPadding : Num -> PackProperty

The approximate padding to include between packed circles.

paAs : String -> String -> String -> String -> String -> PackProperty

The names to give the output fields of a packing transform. The default is ["x", "y", "r", "depth", "children"], where x and y are the layout coordinates, r is the node radius, depth is the tree depth, and children is the count of a node’s children in the tree.

Partitioning

See the Vega partition documentation.

trPartition : List PartitionProperty -> Transform

Compute the layout for an adjacency diagram: a space-filling variant of a node-link tree diagram. Nodes are drawn as solid areas (either arcs or rectangles) sized by some quantitative field, and their placement relative to other nodes reveals their position in the hierarchy.

ptField : Field -> PartitionProperty

Data field corresponding to a numeric value for a partition node. The sum of values for a node and all its descendants is available on the node object as the value property. This field determines the size of a node.

ptSort : List ( Field, Order ) -> PartitionProperty

Sorting properties of sibling nodes during a partition layout transform.

ptPadding : Num -> PartitionProperty

Padding between adjacent nodes for a partition layout transform.

ptRound : Boo -> PartitionProperty

Whether or not node layout values should be rounded in a partition transform. The default is false.

ptSize : Num -> PartitionProperty

Size of a partition layout as two-element list corresponding to [width, height] (or a signal that generates such a list).

ptAs : String -> String -> String -> String -> String -> String -> PartitionProperty

Output field names for the output of a partition layout transform. The parameters correspond to the (default name) fields x0, y0, x1, y1, depth and children.

Trees

See the Vega tree and tree links documentation.

trTree : List TreeProperty -> Transform

Compute a node-link diagram layout for hierarchical data. Supports both cluster layouts (for example, to create dendrograms) and tidy layouts.

teField : Field -> TreeProperty

Data corresponding to a numeric value to be associated with nodes in a tree transform.

teSort : List ( Field, Order ) -> TreeProperty

Sorting properties of sibling nodes in a tree layout transform.

teMethod : TreeMethod -> TreeProperty

Layout method used in a tree transform.

meCluster : TreeMethod

A clustering tree layout method to be used in a tree transform.

meTidy : TreeMethod

A tidy tree layout method to be used in a tree transform.

meSignal : String -> TreeMethod

Tree layout method (tidy or cluster) referenced by the value in the named signal.

teSeparation : Boo -> TreeProperty

Whether or not 'cousin' nodes should be placed further apart than 'sibling' nodes. If false, nodes will be uniformly separated as in a standard dendrogram.

teSize : Num -> TreeProperty

Size of of a tree layout as a two-element [width,height] list (or a signal that generates such a list).

teNodeSize : Num -> TreeProperty

Size of each node in a tree layout as a two-element [width,height] list (or a signal that generates such a list).

teAs : String -> String -> String -> String -> TreeProperty

Output field names within which to write the results of a tree layout transform. The parameters represent the names to replace the defaults in the following order: x, y, depth and children.

trTreeLinks : Transform

Generate a new stream of data objects representing links between nodes in a tree. This transform must occur downstream of a tree-generating transform such as trNest or trStratify. The generated link objects will have source and target fields that reference input data objects corresponding to parent (source) and child (target) nodes.

Tree Maps

See the Vega treemap documentation.

trTreemap : List TreemapProperty -> Transform

Recursively subdivide an area into rectangles with areas proportional to each node’s associated value.

tmField : Field -> TreemapProperty

Field corresponding to a numeric value for a treemap node. The sum of values for a node and all its descendants is available on the node object as the value property. This field determines the size of a node.

tmSort : List ( Field, Order ) -> TreemapProperty

Sorting properties of sibling nodes is in a treemap layout transform.

tmMethod : TreemapMethod -> TreemapProperty

Layout method to use in a treemap transform.

tmSquarify : TreemapMethod

A squarifying treemap layout method used in a treemap transform.

tmResquarify : TreemapMethod

A resquarifying treemap layout method used in a treemap transform.

tmBinary : TreemapMethod

A binary treemap layout method used in a treemap transform.

tmSlice : TreemapMethod

A slicing treemap layout method used in a treemap transform.

tmDice : TreemapMethod

A dicing treemap layout method used in a treemap transform.

tmSliceDice : TreemapMethod

A slice and dice treemap layout method used in a treemap transform.

tmSignal : String -> TreemapMethod

Treemap layout method referenced by the value in the named signal.

tmPadding : Num -> TreemapProperty

Inner and outer padding values for a treemap layout transform.

tmPaddingInner : Num -> TreemapProperty

Inner padding values for a treemap layout transform.

tmPaddingOuter : Num -> TreemapProperty

Outer padding values for a treemap layout transform.

tmPaddingTop : Num -> TreemapProperty

Padding between the top edge of a node and its children in a treemap layout transform.

tmPaddingLeft : Num -> TreemapProperty

Padding between the left edge of a node and its children in a treemap layout transform.

tmPaddingBottom : Num -> TreemapProperty

Padding between the bottom edge of a node and its children in a treemap layout transform.

tmPaddingRight : Num -> TreemapProperty

Padding between the right edge of a node and its children in a treemap layout transform.

tmRatio : Num -> TreemapProperty

Target aspect ratio for the tmSquarify or tmResquarify treemap layout transformations. The default is the golden ratio, φ = (1 + sqrt(5)) / 2.

tmRound : Boo -> TreemapProperty

Whether or not node layout values should be rounded in a treemap transform. The default is false.

tmSize : Num -> TreemapProperty

Size of a treemap layout as two-element list (or signal) corresponding to [width, height].

tmAs : String -> String -> String -> String -> String -> String -> TreemapProperty

Output field names for the output of a treemap layout transform. The parameters correspond to the (default name) fields x0, y0, x1, y1, depth and children.

5. Signals, Triggers and Interaction Events

See the Vega signal documentation

5.1 Signals

signals : List Spec -> ( VProperty, Spec )

Create the signals used to add dynamism to the visualization.

si =
    signals
        << signal "chartSize" [ siValue (vNum 120) ]
        << signal "chartPad" [ siValue (vNum 15) ]
        << signal "chartStep" [ siUpdate "chartSize + chartPad" ]
        << signal "width" [ siUpdate "chartStep * 4" ]

signal : String -> List SignalProperty -> List Spec -> List Spec

Signal to be used to add a dynamic component to a visualization.

siName : String -> SignalProperty

A unique name to be given to a signal. Signal names should be contain only alphanumeric characters (or “$”, or “_”) and may not start with a digit. Reserved keywords that may not be used as signal names are "datum", "event", "item", and "parent".

siValue : Value -> SignalProperty

Initial value of a signal. This value is assigned prior to the evaluation of any expressions specified via siInit or siUpdate.

siBind : Bind -> SignalProperty

Bind a signal to an external input element such as a slider, selection list or radio button group.

siDescription : String -> SignalProperty

Text description of a signal, useful for inline documentation.

siInit : String -> SignalProperty

Initialise a signal with an expression, which may include other signals. This will occur only once, and cannot be used in parallel with siUpdate.

siOn : List (List EventHandler) -> SignalProperty

Event stream handlers for updating a signal value in response to input events.

siUpdate : String -> SignalProperty

Update expression for a signal which may include other signals, in which case the signal will automatically update in response to upstream signal changes, so long as its react property is not false. Cannot be used in parallel with siInit.

siReact : Boo -> SignalProperty

Whether a signal update expression should be automatically re-evaluated when any upstream signal dependencies update. If false, the update expression will only be run upon initialisation.

siPushOuter : SignalProperty

Make signal updates target a signal in an enclosing scope. Used when creating nested signals in a group mark.

5.2 User Interface Inputs

See the Vega signal binding documentation.

iCheckbox : List InputProperty -> Bind

A checkbox input element for representing a boolean state.

iText : List InputProperty -> Bind

A free text input element.

iNumber : List InputProperty -> Bind

A numeric input element.

iDate : List InputProperty -> Bind

A date selector input element.

iDateTimeLocal : List InputProperty -> Bind

A local data time selector input element.

iTime : List InputProperty -> Bind

A time selector input element.

iMonth : List InputProperty -> Bind

A month selector input element.

iWeek : List InputProperty -> Bind

A week selector input element.

iRadio : List InputProperty -> Bind

A radio button input element for representing a single selection from a list of alternatives.

iRange : List InputProperty -> Bind

A slider input element for representing a value within a numeric range.

iSelect : List InputProperty -> Bind

A drop-down list input element for representing a single selection from a list of options.

iTel : List InputProperty -> Bind

A telephone number input element.

iColor : List InputProperty -> Bind

A color selector input element.

inDebounce : Basics.Float -> InputProperty

Delay event handling until the given milliseconds have elapsed since the last event was fired. Helps to limit event broadcasting.

inElement : String -> InputProperty

A CSS selector string indicating the parent element to which the input element should be added. This allows the option of the input element to be outside the visualization container, which could be used for linking separate visualizations.

inOptions : Value -> InputProperty

Options to be selected from a Radio or Select input element.

inLabels : Value -> InputProperty

Labels to represent options values. If unspecified, the options value will be coerced to a string and used as the label.

inMin : Basics.Float -> InputProperty

Minimum value for a range slider input element.

inMax : Basics.Float -> InputProperty

Maximum value for a range slider input element.

inStep : Basics.Float -> InputProperty

Step value (increment between adjacent selectable values) for a range slider input element.

inPlaceholder : String -> InputProperty

Place-holding text for input elements before any value has been entered.

inAutocomplete : Basics.Bool -> InputProperty

Whether autocomplete should be turned on or off for input elements that support it.

5.3 Event Handling

See the Vega event handler documentation documentation.

evHandler : List EventStream -> List EventHandler -> List EventHandler

Event handler. The first parameter is the stream(s) of events to respond to. The second, a list of handlers that respond to the event stream.

signal "tooltip"
    [ siValue (vObject [])
    , siOn
        [ evHandler [ esObject [ esMark rect, esType etMouseOver ] ] [ evUpdate "datum" ]
        , evHandler [ esObject [ esMark rect, esType etMouseOut ] ] [ evUpdate "" ]
        ]
    ]

evUpdate : String -> EventHandler

Expression to be evaluated when an event occurs, the result of which becomes the new signal value.

evEncode : String -> EventHandler

Name of a mark property encoding set to re-evaluate for the mark that is the source of an input event. This is required if evUpdate is not specified.

evForce : Boo -> EventHandler

Whether or not updates that do not change a signal value should propagate. e.g., if true and an input stream update sets the signal to its current value, downstream signals will be notified of an update.

Event Streams

See the Vega event stream documentation

esObject : List EventStreamProperty -> EventStream

Event stream for modelling user input. The parameter represents a stream object which provides a more self-explanatory and robust form of specification than using a selector string.

esSignal : String -> EventStream

Signal that triggers an event stream. Allows an update to be triggered whenever the given signal changes.

esMerge : List EventStream -> EventStream

Merge a list of event streams into a single stream.

esStream : EventStream -> EventStreamProperty

Event stream to be used as input into a derived event stream. Useful if several event streams have a common element:

si =
    let
        esStart =
            esMerge
                [ esObject [ esType etMouseDown ]
                , esObject [ esType etTouchStart ]
                ]

        esEnd =
            esObject [ esType etTouchEnd ]
    in
    signals
        << signal "down"
            [ siValue vNull
            , siOn
                [ evHandler [ esEnd ] [ evUpdate "null" ]
                , evHandler [ esStart ] [ evUpdate "xy()" ]
                ]
            ]
        << signal "xCur"
            [ siValue vNull
            , siOn
                [ evHandler [ esObject [ esStream esStart, esType etTouchEnd ] ]
                    [ evUpdate "slice(xDom)" ]
                ]
            ]

esSelector : Str -> EventStream

Compact representation of an event stream for modelling user input (alternative to esObject).

esSource : EventSource -> EventStreamProperty

Source for an event selector.

esType : EventType -> EventStreamProperty

Type of event stream for handling user interaction events.

esBetween : List EventStreamProperty -> List EventStreamProperty -> EventStreamProperty

Event stream filter that lets only events that occur between the two given event streams from being handled. Useful for capturing pointer dragging as it is a pointer movement event stream that occurs between etMouseDown and etMouseUp events.

<< signal "myDrag"
    [ siValue (vNums [ 200, 200 ])
    , siOn
        [ evHandler
            [esObject
                [ esBetween [ esMark rect, esType etMouseDown ] [ esSource esView, esType etMouseUp ]
                , esSource esView
                , esType etMouseMove
                ]
            ]
            [ evUpdate "xy()" ]
        ]
    ]

This is equivalent to the more compact, but more error-prone event stream selector:

esSelector (str "[rect:mousedown, view:mouseup] > view:mousemove")

esConsume : Boo -> EventStreamProperty

Whether or not an event stream is consumed once it has been captured. If false, the event is made available for subsequent event handling.

esFilter : List String -> EventStreamProperty

Predicate expressions that must all evaluate to true for an event to be captured.

esDebounce : Num -> EventStreamProperty

Minimum time to wait between event occurrence and processing. If a new event arrives during a debouncing window, the timer will restart and only the new event will be captured.

esMarkName : String -> EventStreamProperty

Named mark to be the source for an event stream. The name given here must correspond to that provided via mName.

esMark : Mark -> EventStreamProperty

Mark type to be the source for an event stream.

esThrottle : Num -> EventStreamProperty

Minimum time in milliseconds between captured events. New events that arrive within the throttling window will be ignored. For timer events, this determines the interval between timer ticks.

evStreamSelector : Str -> EventStream

Event selector used to generate an event stream.

esAll : EventSource

Event source from any mark. Equivalent to the * selector.

esScope : EventSource

Limit event source to events from the main group in which a nested group sits.

esView : EventSource

Event source from the current Vega view component.

esWindow : EventSource

Event source from the browser window object.

esDom : String -> EventSource

DOM node to be the source for an event selector. Referenced with a standard CSS selector.

Event types

etClick : EventType

Click interaction event type.

etDblClick : EventType

Double click interaction event type.

etDragEnter : EventType

Drag entry interaction event type.

etDragLeave : EventType

Drag exit interaction event type.

etDragOver : EventType

Drag over interaction event type.

etKeyDown : EventType

Key down interaction event type.

etKeyPress : EventType

Key press interaction event type.

etKeyUp : EventType

Key up interaction event type.

etMouseDown : EventType

Mouse down interaction event type.

etMouseMove : EventType

Mouse movement interaction event type.

etMouseOut : EventType

Mouse exit interaction event type.

etMouseOver : EventType

Mouse over interaction event type.

etMouseUp : EventType

Mouse up interaction event type.

etMouseWheel : EventType

Mouse wheel interaction event type.

etTouchEnd : EventType

Touch end interaction event type.

etTouchMove : EventType

Touch move interaction event type.

etTouchStart : EventType

Touch start interaction event type.

etWheel : EventType

Wheel interaction event type.

etTimer : EventType

Fire an event at a regular interval determined by the number of milliseconds provided with esThrottle.

5.4 Triggers

See the Vega trigger documentation.

on : List Trigger -> DataTable -> DataTable

Add a list of triggers to the given data table.

trigger : String -> List TriggerProperty -> Trigger

Creates a trigger that may be applied to a data table or mark. The first parameter is the name of the trigger and the second a list of trigger actions.

tgInsert : String -> TriggerProperty

Expression that evaluates to data objects to insert as triggers. Insert operations are only applicable to datasets, not marks.

tgRemove : String -> TriggerProperty

Expression that evaluates to data objects to remove. Remove operations are only applicable to datasets, not marks.

tgRemoveAll : TriggerProperty

Remove all data object triggers.

tgToggle : String -> TriggerProperty

Expression that evaluates to data objects to toggle. Toggled objects are inserted or removed depending on whether they are already in the dataset. Applicable only to datasets, not marks.

tgModifyValues : String -> String -> TriggerProperty

Data or mark modification trigger. The first parameter is an expression that evaluates to data objects to modify and the second an expression that evaluates to an object of name-value pairs, indicating the field values that should be updated.

mark symbol
    [ mFrom [ srData (str "countries") ]
    , mOn
        [ trigger "myDragSignal"
            [ tgModifyValues "dragged" "{fx: x(), fy: y()}" ]
        ]

would set the fx and fy properties on mark items referenced by myDragSignal to the current mouse pointer position.

6. Scales

The mapping of data values to visualization channels. See the Vega scale documentation.

scales : List Spec -> ( VProperty, Spec )

Create the scales used to map data values to visual properties.

sc =
    scales
        << scale "xScale"
            [ scType scLinear
            , scDomain (doData [ daDataset "myData", daField (field "x") ])
            , scRange raWidth
            ]
        << scale "yScale"
            [ scType scLinear
            , scDomain (doData [ daDataset "myData", daField (field "y") ])
            , scRange raHeight
            ]

scale : String -> List ScaleProperty -> List Spec -> List Spec

Scale to be used to map data values to visual properties.

6.1 Scale Properties

scReverse : Boo -> ScaleProperty

Reverse the order of a scale range.

scRound : Boo -> ScaleProperty

Whether to round numeric output values to integers. Helpful for snapping to the pixel grid.

scClamp : Boo -> ScaleProperty

Whether output values should be clamped when using a quantitative scale range (default false). If clamping is disabled and the scale is passed a value outside the domain, the scale may return a value outside the range through extrapolation. If clamping is enabled, the output value of the scale is always within the scale’s range.

scPadding : Num -> ScaleProperty

Expand a scale domain to accommodate the specified number of pixels on each end of a quantitative scale range or the padding between bands in a band scale.

scNice : ScaleNice -> ScaleProperty

Extend the range of a scale domain so it starts and ends on 'nice' round values.

scZero : Boo -> ScaleProperty

Whether or not a scale domain should include zero. The default is true for linear, sqrt and power scales and false for all others.

scExponent : Num -> ScaleProperty

Exponent to be used in power scale.

scConstant : Num -> ScaleProperty

The desired desired slope of the scSymLog function at zero. If unspecified, the default is 1.

scBase : Num -> ScaleProperty

Base of the logarithm used in a logarithmic scale.

scAlign : Num -> ScaleProperty

Alignment of elements within each step of a band scale, as a fraction of the step size. Should be in the range [0,1].

scDomainImplicit : Boo -> ScaleProperty

Whether or not ordinal domains should be implicitly extended with new values. If false, a scale will return undefined for values not included in the domain; if true, new values will be appended to the domain and an updated range value will be returned.

scPaddingInner : Num -> ScaleProperty

Expand a scale domain to accommodate the specified number of pixels between inner bands in a band scale.

scPaddingOuter : Num -> ScaleProperty

Expand a scale domain to accommodate the specified number of pixels outside the outer bands in a band scale.

scRangeStep : Num -> ScaleProperty

Step size for band and point scales.

Aligning Scales to Nice Values.

'Nice' values are ones rounded for easy interpretation, such as 100,200,300.

niTrue : ScaleNice

Enable nice scaling.

niFalse : ScaleNice

Disable nice scaling.

niMillisecond : ScaleNice

Nice time intervals that try to align with rounded milliseconds.

niSecond : ScaleNice

Nice time intervals that try to align with whole or rounded seconds.

niMinute : ScaleNice

Nice time intervals that try to align with whole or rounded minutes.

niHour : ScaleNice

Nice time intervals that try to align with whole or rounded hours.

niDay : ScaleNice

Nice time intervals that try to align with whole or rounded days.

niWeek : ScaleNice

Nice time intervals that try to align with whole or rounded weeks.

niMonth : ScaleNice

Nice time intervals that try to align with whole or rounded months.

niYear : ScaleNice

Nice time intervals that try to align with whole or rounded years.

niTickCount : Basics.Int -> ScaleNice

Desired number of tick marks in a 'nice' scaling.

niInterval : TimeUnit -> Basics.Int -> ScaleNice

'Nice' temporal interval values when scaling.

niSignal : String -> ScaleNice

'nice' number-scaling type referenced by the value in the named signal.

6.2 Scale Types

scType : Scale -> ScaleProperty

Type of a named scale.

scBand : Scale

A band scale.

scBins : ScaleBins -> ScaleProperty

Specify the bins to be used when scaling into categories. For example the following would specify a linear bin scaling between 100 and 160 in steps of 10.

 scBins (bsBins (num 10) [ bsStart (num 100), bsStop (num 160) ])

scBinOrdinal : Scale

An ordinal band scale.

scLinear : Scale

A linear scale.

scLog : Scale

A log scale.

scSymLog : Scale

A symmetrical log scale. Similar to a log scale but supports zero and negative values. The slope of the function at zero can be set with scConstant.

scOrdinal : Scale

An ordinal scale.

scPoint : Scale

A point scale.

scPow : Scale

A power scale.

scQuantile : Scale

A quantile scale.

scQuantize : Scale

A quantizing scale.

scThreshold : Scale

A threshold scale.

scSqrt : Scale

A square root scale.

scTime : Scale

A temporal scale.

scUtc : Scale

A UTC temporal scale.

scCustom : String -> Scale

Custom named scale.

scSignal : String -> Scale

Scaling referenced by the value in the named signal.

6.3 Scale Domains

The extent scaling input data.

scDomain : ScaleDomain -> ScaleProperty

Domain of input data values for a scale.

scDomainMax : Num -> ScaleProperty

Maximum value of a scale domain, overriding a scDomain setting. Only intended for scales with continuous domains.

scDomainMin : Num -> ScaleProperty

Minimum value of a scale domain, overriding a scDomain setting. This is only used with scales having continuous domains.

scDomainMid : Num -> ScaleProperty

Insert a single mid-point value into a two-element scale domain. The mid-point value must lie between the domain minimum and maximum values. Useful for setting a midpoint for diverging color scales. Only used with scales having continuous, piecewise domains.

scDomainRaw : Value -> ScaleProperty

List value that directly overrides the domain of a scale. Useful for supporting interactions such as panning or zooming a scale. The scale may be initially determined using a data-driven domain, then modified in response to user input.

scales
    << scale "xDetail"
        [ scType scTime
        , scRange raWidth
        , scDomain (doData [ daDataset "sp500", daField (field "date") ])
        , scDomainRaw (vSignal "detailDomain")
        ]

doNums : Num -> ScaleDomain

List of numeric values (e.g. nums [1981, 2019]) representing a scale domain.

doStrs : Str -> ScaleDomain

List of strings (e.g. strs ["cat","dog","fish"]) representing a scale domain.

doSignal : String -> ScaleDomain

Scale domain referenced by the value in the named signal.

doSignals : List String -> ScaleDomain

Scale domains referenced by the values in the named signals.

doData : List DataReference -> ScaleDomain

Data reference object specifying field values in one or more datasets to define a scale domain.

6.4 Scale Ranges

The extent of scaled values after transformation.

scRange : ScaleRange -> ScaleProperty

Range of a scale representing the set of visual values.

raWidth : ScaleRange

Use default width range of scale output values.

raHeight : ScaleRange

Use default height range of scale output values.

raSymbol : ScaleRange

Use default (discrete) symbol range of scale output values.

raCategory : ScaleRange

Use default category range of scale output values.

raDiverging : ScaleRange

Use default diverging range of scale output values.

raOrdinal : ScaleRange

Use default ordinal range of scale output values.

raRamp : ScaleRange

Use default (continuous) ramp range of scale output values.

raHeatmap : ScaleRange

Use default heatmap range of scale output values.

raNums : List Basics.Float -> ScaleRange

Scale range as a list of numbers.

raStrs : List String -> ScaleRange

Scale range as a list of strings.

raValues : List Value -> ScaleRange

Scale range as a list of values.

raSignal : String -> ScaleRange

Default range scaling referenced by the value in the named signal.

raScheme : Str -> List ColorSchemeProperty -> ScaleRange

Scale range as a list of color schemes. The first parameter is the name of the color scheme to use, the second any customising properties.

raData : List DataReference -> ScaleRange

Scale range as a data reference object. This is used for specifying ordinal scale ranges as a series of distinct field values.

scale "myScale"
    [ scType scOrdinal
    , scDomain (doData [ daDataset "clusters", daField (field "id") ])
    , scRange (raData [ daDataset "clusters", daField (field "name") ])
    ]

raStep : Value -> ScaleRange

Step size for a band scale range.

raCustomDefault : String -> ScaleRange

Custom range default scheme. Used when a new named default has been created as part of a config setting is required.

6.5 Color Scales

See the Vega Vega color scale and color scheme documentation.

csScheme : Str -> ColorSchemeProperty

Name a color scheme to use.

csCount : Num -> ColorSchemeProperty

Number of colors to use in a color scheme.

csExtent : Num -> ColorSchemeProperty

Extent of the color range to use in linear and diverging color schemes. The parameter should evaluate to a two-element list representing the min and max values of the extent. For example [0.2, 1] will rescale the color scheme such that color values in the range [0, 0.2] are excluded from the scheme.

scInterpolate : CInterpolate -> ScaleProperty

Interpolation method for a quantitative scale.

cubeHelix : Basics.Float -> CInterpolate

Cube helix color interpolation using the given gamma value (anchored at 1).

cubeHelixLong : Basics.Float -> CInterpolate

A long path cube-helix color interpolation using the given gamma value (anchored at 1).

hcl : CInterpolate

A hue-chroma-luminance color interpolation.

hclLong : CInterpolate

A long-path hue-chroma-luminance color interpolation.

hsl : CInterpolate

A hue-saturation-lightness color interpolation.

hslLong : CInterpolate

A long-path hue-saturation-lightness color interpolation.

rgb : Basics.Float -> CInterpolate

RGB color interpolation. The parameter is a gamma value to control the brightness of the color trajectory.

lab : CInterpolate

An CIELab color interpolation.

6.6 Scale Bins

bsNums : Num -> ScaleBins

List of numeric values (nums) specifying bin boundaries. For example the list [0, 5, 10, 15, 20] would generate bins of [0-5), [5-10), [10-15), [15-20].

bsSignal : String -> ScaleBins

Name of a signal that resolves to a list of bin boundaries or a bins object that defines the start, stop and step size of a a set of bins.

bsBins : Num -> List BinsProperty -> ScaleBins

Specify the bin scaling to categorise numeric values. The first parameter is the step size between bins. The second parameter is a list of optional start and end values for the list of bins. If not specified, the start and end are assumed to span the full range of data to scale.

bsStart : Num -> BinsProperty

First bin in a series of bins.

bsStop : Num -> BinsProperty

Last bin in a series of bins.

7. Layout Composition

For arranging collections of marks in a grid to create small multiples, faceted plots etc. See the Vega layout documentation.

layout : List LayoutProperty -> ( VProperty, Spec )

Create a layout used in the visualization. For example the following creates a three-column layout with 20 pixel padding between columns:

lo =
    layout [ loColumns (num 3), loPadding (num 20) ]

7.1 Arrangement

loColumns : Num -> LayoutProperty

Number of columns to include in a grid layout. If unspecified, a single row with unlimited columns will be assumed.

loPadding : Num -> LayoutProperty

Padding in pixels to add between elements within rows and columns of a grid layout.

loPaddingRC : Num -> Num -> LayoutProperty

Similar to loPadding but allowing row and column settings to be specified separately.

loOffset : Num -> LayoutProperty

Orthogonal offset in pixels by which to displace grid header, footer and title cells from their position along the edge of a grid layout.

loOffsetRC : Num -> Num -> LayoutProperty

Similar to loOffset but allowing row and column settings to be specified separately.

7.2 Headers, Footers and Titles

loHeaderBand : Num -> LayoutProperty

Band positioning in the interval [0,1] indicating where in a cell a header should be placed in a grid layout. For a column header, 0 maps to the left edge of the header cell and 1 to right edge. For a row footer, the range maps from top to bottom.

loHeaderBandRC : Num -> Num -> LayoutProperty

Similar to loFHeaderBand but allowing row and column settings to be specified separately.

loFooterBand : Num -> LayoutProperty

Band positioning in the interval [0,1] indicating where in a cell a footer should be placed in a grid layout.

loFooterBandRC : Num -> Num -> LayoutProperty

Similar to loFooterBand but allowing row and column settings to be specified separately.

loTitleBand : Num -> LayoutProperty

Title placement in a grid layout. For a column title, 0 maps to the left edge of the title cell and 1 to right edge. The default value is 0.5, indicating a centred position.

loTitleBandRC : Num -> Num -> LayoutProperty

Similar to loTitleBand but allowing row and column settings to be specified separately.

7.3 Bounds Calculation

loBounds : BoundsCalculation -> LayoutProperty

Bounds calculation method to use for determining the extent of a sub-plot in a grid layout.

bcFlush : BoundsCalculation

Only the width and height values of a group mark or legend are to determine the extent of a sub-plot or in a grid layout or arrangement of legends. Useful when attempting to lay out items in a uniform grid structure.

bcFull : BoundsCalculation

Entire calculated bounds (including an items such as axes or title or legend border) to determine the extent of a sub-plot in a grid layout.

bcSignal : String -> BoundsCalculation

Indicate that the bounds calculation type is to be determined by a named signal.

loAlign : GridAlign -> LayoutProperty

Alignment to apply to grid rows and columns in a grid layout.

Grid Alignment

grAlignRow : GridAlign -> GridAlign

Layout alignment to apply to grid rows. Used in cases when alignment rules are different for rows and columns.

grAlignColumn : GridAlign -> GridAlign

Layout alignment to apply to grid columns. Used in cases when alignment rules are different for rows and columns.

grAlignAll : GridAlign

Indicate grid elements will be aligned and each row or column will be sized identically based on the maximum observed size.

grAlignEach : GridAlign

Indicate grid elements will be aligned into a clean grid structure, but each row or column may be of variable size.

grAlignNone : GridAlign

Indicate a flow grid layout will be used in which adjacent plots are placed one after the other.

grAlignSignal : String -> GridAlign

Layout alignment referenced by the value in the named signal.

8. Map Projections

The transformation of global longitude/latitude locations into 2d screen position. See the Vega map projection documentation.

projections : List Spec -> ( VProperty, Spec )

Create the projections used to map geographic data onto a plane.

pr =
    projections
        << projection "myProj" [ prType orthographic ]
        << projection "myProj2" [ prType albers, prRotate (nums [ -20, 15 ]) ]

projection : String -> List ProjectionProperty -> List Spec -> List Spec

Map projection for transforming geo data onto a plane.

8.1 Projection Properties

prType : Projection -> ProjectionProperty

Type of map projection to use in a projection transformation.

prClipAngle : Num -> ProjectionProperty

Map projection’s clipping circle radius to the specified angle in degrees. A value of zero indicates antimeridian cutting should be applied rather than small-circle clipping.

prClipExtent : Num -> ProjectionProperty

Map projection’s viewport clip extent to the specified bounds in pixels. The extent bounds should be specified as a list of four numbers in [x0, y0, x1, y1] order where x0 is the left-side of the viewport, y0 is the top, x1 is the right and y1 is the bottom.

prScale : Num -> ProjectionProperty

Map projection’s scale factor. The default scale is projection-specific. It corresponds linearly to the distance between projected points; however, scale factor values are not equivalent across projections.

prTranslate : Num -> ProjectionProperty

Translation offset to the specified two-element list [tx, ty]. If not specified as a two-element list, returns the current translation offset which defaults to [480, 250]. The translation offset determines the pixel coordinates of the projection’s centre. The default translation offset places (0°,0°) at the centre of a 960×500 area.

prCenter : Num -> ProjectionProperty

Map projection’s centre as a two-element list of longitude and latitude in degrees.

prRotate : Num -> ProjectionProperty

Map projection’s three-axis rotation angle. This should be a two- or three-element list of numbers [lambda, phi, gamma] specifying the rotation angles in degrees about each spherical axis.

prPointRadius : Num -> ProjectionProperty

Default radius (in pixels) to use when drawing projected GeoJSON Point and MultiPoint geometries. The default value is 4.5.

prPrecision : Num -> ProjectionProperty

Threshold for the projection’s adaptive resampling in pixels. This corresponds to the Douglas–Peucker distance. If precision is not specified, the projection’s current resampling precision which defaults to √0.5 ≅ 0.70710 is used.

prCoefficient : Num -> ProjectionProperty

'Hammer' map projection's coefficient (defaults to 2).

prDistance : Num -> ProjectionProperty

'Satellite' map projection's distance value. Values are expressed as a proportion of the Earth's radius (defaults to 2).

prFraction : Num -> ProjectionProperty

'Bottomley' map projection's fraction parameter (defaults to 0.5).

prLobes : Num -> ProjectionProperty

Number of lobes in radial map projections such as the Berghaus Star.

prParallel : Num -> ProjectionProperty

Parallel used for map projections such as the Armadillo (defaults to 20 degrees N).

prRadius : Num -> ProjectionProperty

Radius for the 'Gingery' map projection. Defaults to 30 degrees.

prRatio : Num -> ProjectionProperty

'Hill' map projection's ratio allowing it to vary continuously between Maurer 73 (0) and Eckert IV projections (infinity). Defaults to 1.

prReflectX : Boo -> ProjectionProperty

Whether or not to Reflect the x-coordinates when using an identity projection. This creates a left-right mirror image of the geo features when subject to an identityProjection.

prReflectY : Boo -> ProjectionProperty

Whether or not to Reflect the y-coordinates when using an identity projection. This creates a top-bottom mirror image of the geo features when subject to an identityProjection.

prSpacing : Num -> ProjectionProperty

Spacing for a Lagrange conformal map projection (defaults to 0.5).

prTilt : Num -> ProjectionProperty

Tilt angle for a Satellite map projection (defaults to 0 degrees).

prExtent : Num -> ProjectionProperty

Display region into which the projection should be automatically fit. Used in conjunction with prFit. The region bounds should be specified in [x0, y0, x1, y1] order where x0 is the left-side, y0 is the top, x1 is the right and y1 is the bottom.

prSize : Num -> ProjectionProperty

Width and height of the display region into which the projection should be automatically fit. Used in conjunction with prFit this is equivalent to calling prExtent with the top-left position set to (0,0). The region size should be specified in [width, height] order (or a signal that generates such a list).

prFit : Feature -> ProjectionProperty

GeoJSON data to which a projection should attempt to automatically fit by setting its translate and scale values.

ds =
    dataSource [ data "mapData" [ daUrl (str "myGeoJson.json") ] ]

pr =
    projections
        << projection "myProjection"
            [ prType orthographic
            , prSize (numSignal "[width,height]")
            , prFit (feName "mapData")
            ]

feName : String -> Feature

Name of a geoJSON feature. Can be used with prFit to fit a map projection scaling and centre to a given geoJSON feature or feature collection.

pr =
    projections
        << projection "myProjection"
            [ prType orthographic
            , prSize (numSignal "[width,height]")
            , prFit (feName "mapData")
            ]

featureSignal : String -> Feature

geoJSON feature referenced by the value in the named signal. Can be used with prFit to fit a map projection scaling and centre to a given geoJSON feature or feature collection.

ds =
    dataSource
        [ data "myLongLatData" []
            |> transform
                [ trGeoJson
                    [ gjFields (field "longitude") (field "latitude")
                    , gjSignal "feature"
                    ]
                ]
        ]

pr =
    projections
        << projection "myProjection"
            [ prType orthographic
            , prSize (numSignal "[width,height]")
            , prFit (featureSignal "feature")
            ]

8.2 Projection Types

albers : Projection

An Albers map projection.

albersUsa : Projection

An Albers USA map projection that combines continental USA with Alaska and Hawaii.

azimuthalEqualArea : Projection

An azimuthal equal area map projection.

azimuthalEquidistant : Projection

An azimuthal equidistant map projection.

conicConformal : Projection

A conformal conic map projection.

conicEqualArea : Projection

An equal area conic map projection.

conicEquidistant : Projection

An equidistant conic map projection.

equalEarth : Projection

An equal-earth map projection that provides a reasonable shape approximation while retaining relative areas.

equirectangular : Projection

An equirectangular (default) map projection that maps longitude to x and latitude to y.

gnomonic : Projection

A gnomonic map projection.

identityProjection : Projection

An 'identity' projection where longitude is projected directly to the x position and latitude to the y position.

mercator : Projection

A Mercator map projection.

mollweide : Projection

A Mollweide global map projection.

naturalEarth1 : Projection

A natural earth map projection.

orthographic : Projection

An orthographic map projection.

stereographic : Projection

A stereographic map projection.

transverseMercator : Projection

A transverse Mercator map projection.

customProjection : Str -> Projection

Custom projection type. Additional custom projections from d3 can be defined via the Vega API and called from with this function where the parameter is the name of the D3 projection to use (e.g. customProjection (str "winkel3")).

prSignal : String -> Projection

Map projection referenced by the value in the named signal.

projectionValue : Projection -> Value

Convenience function for generating a value representing a given projection type. Useful when generating signals representing projection types.

9. Titles

See the Vega title documentation.

title : Str -> List TitleProperty -> ( VProperty, Spec )

Top-level title to be displayed as part of a visualization. The first parameter is the text of the title to display, the second any optional properties for customising the title's appearance. For titles that span multiple lines, provide a list of strings (strs) rather than a single string (str).

9.1 Title Properties

tiAria : Boo -> TitleProperty

Whether or not the title should be included as an ARIA attribute for providing accessible SVG output associated with an axis.

tiAnchor : Anchor -> TitleProperty

Anchor positioning of a title. Used for aligning title text.

tiAngle : Num -> TitleProperty

Angle in degrees of a title.

tiAlign : HAlign -> TitleProperty

Horizontal alignment of a title. If specified this will override the tiAnchor setting (useful when aligning rotated title text).

tiBaseline : VAlign -> TitleProperty

Vertical title text baseline.

tiColor : Str -> TitleProperty

Color of a title.

tiDx : Num -> TitleProperty

Additional horizontal offset of a title's position.

tiDy : Num -> TitleProperty

Additional vertical offset of a title's position.

tiEncodeElements : List ( TitleElement, List EncodingProperty ) -> TitleProperty

Specify the appearance of a title with a custom encoding. Should provide a list of tuples, each being the title element to encode (one of teTitle, teSubtitle or teGroup) and the encodings to apply to it. This can be useful when a part of a title needs more dynamic customisation than that offered by simple title property functions (tiColor, tiFont etc.). For example,

enc =
    [ enEnter [ maFill [ vStr "firebrick" ] ]
    , enUpdate [ maFontStyle [ vStr "normal" ] ]
    , enHover [ maFontStyle [ vStr "italic" ] ]
    , enInteractive true
    ]

tiEncodeElements [ ( teSubtitle, enc ) ]

teTitle : TitleElement

Indicates a title text element within a title group.

teSubtitle : TitleElement

Indicates a subtitle text element within a title group.

teGroup : TitleElement

Indicates a title group (rectangular area containing title and optional subtitle).

tiFont : Str -> TitleProperty

Font name of a title.

tiFontSize : Num -> TitleProperty

Font size of a title.

tiFontStyle : Str -> TitleProperty

Font style of a title such as str "normal" or str "italic".

tiFontWeight : Value -> TitleProperty

Font weight of a title (can be a number such as vNum 300 or text such as vStr "bold").

tiFrame : TitleFrame -> TitleProperty

Reference frame for the anchor position of a title.

tfBounds : TitleFrame

Title anchor position calculation assuming text anchor is relative to the full bounding box.

tfGroup : TitleFrame

Title anchor position calculation assuming text anchor is relative to the group width / height.

tfSignal : String -> TitleFrame

Title anchor calculation type (bounds or group) referenced by the value in the named signal.

tiSubtitle : Str -> TitleProperty

Subtitle text, placed beneath the primary title. For subtitles that span multiple lines, provide a list of strings (strs) rather than a single string (str).

tiSubtitleColor : Str -> TitleProperty

Color of a subtitle.

tiSubtitleFont : Str -> TitleProperty

Font name of a subtitle.

tiSubtitleFontSize : Num -> TitleProperty

Font size of a subtitle.

tiSubtitleFontStyle : Str -> TitleProperty

Font style of a subtitle such as str "normal" or str "italic".

tiSubtitleFontWeight : Value -> TitleProperty

Font weight of a subtitle (can be a number such as vNum 300 or text such as vStr "bold").

tiSubtitleLineHeight : Num -> TitleProperty

Line height in pixels of each line of text in a subtitle.

tiSubtitlePadding : Num -> TitleProperty

Padding in pixels between title and subtitle text.

tiLimit : Num -> TitleProperty

Maximim allowed length of a title in pixels.

tiLineHeight : Num -> TitleProperty

Line height in pixels of each line of text in a title.

tiOffset : Num -> TitleProperty

Orthogonal offset in pixels by which to displace the title from its position along the edge of the chart.

tiOrient : Side -> TitleProperty

Position a title relative to the chart.

tiZIndex : Num -> TitleProperty

z-index indicating the layering of the title group relative to other axis, mark and legend groups.

9.2 Text Anchors

anStart : Anchor

Anchor some text at its start.

anMiddle : Anchor

Anchor some text in its start.

anEnd : Anchor

Anchor some text at its end.

anchorSignal : String -> Anchor

Indicate that an anchor position is to be determined by a named signal. The signal should generate one of start, middle or end.

10. Axes

The visual appearance of chart axes. See the Vega axis documentation.

axes : List Spec -> ( VProperty, Spec )

Create the axes used to visualize spatial scale mappings.

ax =
    axes
        << axis "myXScale" siBottom [ axTitle (str "Population") ]
        << axis "myYScale" siLeft [ axTickCount (num 5) ]

axis : String -> Side -> List AxisProperty -> List Spec -> List Spec

Create an axis used to visualize a spatial scale mapping. The first parameter is the name of the scale backing this axis, the second the position of the axis relative to the data rectangle and the third a list of optional axis properties. For example,

axes
    << axis "xScale" siBottom [ axTitle "Population", axZIndex (num 1) ]

axEncode : List ( AxisElement, List EncodingProperty ) -> AxisProperty

Mark encodings for custom axis styling.

axAria : List Aria -> AxisProperty

ARIA properties for providing accessible SVG output associated with an axis. If an empty list is provided, ARIA tagging will be switched off.

10.1 Axis Positioning and Extent

axMinExtent : Value -> AxisProperty

The minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles.

axMaxExtent : Value -> AxisProperty

Maximum extent in pixels that axis ticks and labels should use.

axOffset : Value -> AxisProperty

Orthogonal offset in pixels by which to displace the axis from its position along the edge of the chart.

axPosition : Value -> AxisProperty

The anchor position of the axis in pixels. For x-axes with top or bottom orientation, this sets the axis group x coordinate. For y-axes with left or right orientation, this sets the axis group y coordinate.

axZIndex : Num -> AxisProperty

The z-index indicating the layering of an axis group relative to other axis, mark and legend groups. The default value is 0 and axes and grid lines are drawn behind any marks defined in the same specification level. Higher values (1) will cause axes and grid lines to be drawn on top of marks.

Positioning

siLeft : Side

Left side, used to specify an axis position.

siRight : Side

Right side, used to specify an axis position.

siTop : Side

Top side, used to specify an axis position.

siBottom : Side

Bottom side, used to specify an axis position.

siSignal : String -> Side

Rectangular side referenced by the value in the named signal.

Overlap Strategies

osNone : OverlapStrategy

No overlap strategy to be applied when there is not space to show all items on an axis.

osParity : OverlapStrategy

Give all items equal weight in overlap strategy to be applied when there is not space to show them all on an axis.

osGreedy : OverlapStrategy

Greedy overlap strategy to be applied when there is not space to show all items on an axis.

osSignal : String -> OverlapStrategy

Overlap strategy referenced by the value in the named signal.

10.2 Axis line

axDomain : Boo -> AxisProperty

Whether or not the domain (the axis baseline) should be included as part of an axis.

axDomainCap : Str -> AxisProperty

Stroke cap ending style for an axis baseline (domain). To guarantee valid cap names, use strokeCapStr to generate the parameter.

axDomainColor : Str -> AxisProperty

Color of an axis domain line.

axDomainDash : List Value -> AxisProperty

Stroke dash of an axis's domain line as a list of dash-gap lengths or empty list for solid line.

axDomainDashOffset : Num -> AxisProperty

Pixel offset from which to start the domain dash list.

axDomainOpacity : Num -> AxisProperty

Opacity of an axis domain line.

axDomainWidth : Num -> AxisProperty

Width in pixels of an axis domain line.

strokeCapStr : StrokeCap -> Str

Convenience function for generating a Str representing a given stroke cap type.

10.3 Axis Grid Lines

axGrid : Boo -> AxisProperty

Whether or not grid lines should be included as part of an axis.

axGridCap : Str -> AxisProperty

Stroke cap ending style for gridlines. To guarantee valid cap names, use strokeCapStr to generate the parameter.

axGridColor : Str -> AxisProperty

Color of an axis's grid lines.

axGridOpacity : Num -> AxisProperty

Opacity of an axis's grid lines.

axGridDash : List Value -> AxisProperty

Stroke dash of an axis's grid lines as a list of dash-gap lengths or empty list for solid lines.

axGridDashOffset : Num -> AxisProperty

Pixel offset from which to start the grid line dash list.

axGridScale : String -> AxisProperty

Name of the scale to use for including grid lines. By default grid lines are driven by the same scale as the ticks and labels.

axGridWidth : Num -> AxisProperty

Width of an axis's grid lines in pixel units.

10.4 Axis Labels

axLabels : Boo -> AxisProperty

Whether or not if labels should be included as part of an axis.

axLabelBound : Num -> AxisProperty

Indicate how or if labels should be hidden if they exceed the axis range. If the parameter is numNull, no check for label size is made. A number specifies the permitted overflow in pixels that can be tolerated.

axLabelAlign : HAlign -> AxisProperty

Horizontal alignment of axis tick labels.

axLabelBaseline : VAlign -> AxisProperty

Vertical alignment of axis tick labels.

axLabelAngle : Num -> AxisProperty

Angle of text for an axis.

axLabelColor : Str -> AxisProperty

Color of an axis label.

axLabelOpacity : Num -> AxisProperty

Opacity of an axis label.

axLabelFont : Str -> AxisProperty

Font name of an axis label.

axLabelFontSize : Num -> AxisProperty

Font size of an axis label.

axLabelFontStyle : Str -> AxisProperty

Font style of an axis label such as str "normal" or str "italic".

axLabelFontWeight : Value -> AxisProperty

Font weight of an axis label. This can be a number (e.g. vNum 300) or text (e.g. vStr "bold").

axLabelFlush : Num -> AxisProperty

Indicate how labels at the beginning or end of an axis should be aligned with the scale range. The parameter represents a pixel distance threshold. Labels with anchor coordinates within this threshold distance for an axis end-point will be flush-adjusted. If numNull, no flush alignment will be applied.

axLabelFlushOffset : Num -> AxisProperty

Number of pixels by which to offset flush-adjusted labels.

axLabelLimit : Num -> AxisProperty

Maximum length in pixels of axis tick labels.

axLabelLineHeight : Num -> AxisProperty

Line height in pixels for multi-line label text or label text with valineTop or vaLineBottom baselines.

axLabelOffset : Num -> AxisProperty

Offset in pixels to apply to labels, in addition to axTickOffset.

axLabelPadding : Num -> AxisProperty

Padding in pixels between labels and ticks.

axLabelOverlap : OverlapStrategy -> AxisProperty

Strategy to use for resolving overlap of axis labels.

axLabelSeparation : Num -> AxisProperty

Minimum separation that must be between labels for them to be considered non-overlapping. Ignored if axLabelOverlap resolution not enabled.

axFormat : Str -> AxisProperty

The format specifier pattern for axis labels. For numerical values, must be a legal d3-format specifier. For date-time values, must be a legal d3-time-format specifier.

axFormatAsNum : AxisProperty

Indicate that axis labels should be formatted as numbers. To control the precise numeric format, additionally use axFormat providing a d3 numeric format string.

axFormatAsTemporal : AxisProperty

Indicate that axis labels should be formatted as dates/times. To control the precise temporal format, additionally use axFormat providing a d3 date/time format string.

axFormatAsTemporalUtc : AxisProperty

Indicate that axis labels should be formatted as UTC dates/times.

axValues : Value -> AxisProperty

Explicitly set an axis tick and label values.

10.5 Axis Ticks

axTicks : Boo -> AxisProperty

Whether or not ticks should be included as part of an axis.

axTickBand : AxisTickBand -> AxisProperty

Specify how axis ticks should be aligned when using a band scale.

abCenter : AxisTickBand

Indicates axis ticks for band scales should be centered on each band.

abExtent : AxisTickBand

Indicates axis ticks for band scales should be aligned with the extent of each band.

axTickCount : Num -> AxisProperty

Desired number of ticks, for axes visualizing quantitative scales. The resulting number may be different so that values are “nice” (multiples of 2, 5, 10) and lie within the underlying scale’s range.

axTemporalTickCount : TimeUnit -> Num -> AxisProperty

Tick interval for a temporal axis. The first parameter is the type of temporal interval to use and the second the number of steps of that interval between ticks. e.g. to specify a tick is requested at 3 month intervals (January, April, July, October):

ax =
    axes
        << axis "xScale" siBottom [ axTemporalTickCount month (num 3) ]

If the second parameter is not a positive value, the number of ticks will be auto-generated for the given interval type.

axTickCap : Str -> AxisProperty

Line capping style for axis ticks. To guarantee valid cap names, use strokeCapStr to generate the parameter.

axTickColor : Str -> AxisProperty

Color of an axis's ticks.

axTickDash : List Value -> AxisProperty

Stroke dash of an axis's tick marks as a list of dash-gap lengths or empty list for solid lines.

axTickDashOffset : Num -> AxisProperty

Pixel offset from which to start the tick dash list.

axTickOpacity : Num -> AxisProperty

Opacity of an axis's ticks.

axTickExtra : Boo -> AxisProperty

Whether or not an extra axis tick should be added for the initial position of an axis. This is useful for styling axes for band scales such that ticks are placed on band boundaries rather in the middle of a band.

axTickMinStep : Num -> AxisProperty

Minimum desired step between axis ticks in scale domain units.

axTickOffset : Num -> AxisProperty

Offset in pixels of an axis's ticks, labels and gridlines.

axTickRound : Boo -> AxisProperty

Whether or not pixel position values for an axis's ticks should be rounded to the nearest integer.

axTickWidth : Num -> AxisProperty

Width in pixels of an axis's ticks.

axTickSize : Num -> AxisProperty

Size in pixels of axis ticks.

axBandPosition : Num -> AxisProperty

Interpolation fraction indicating where, for band scales, axis ticks should be positioned. A value of 0 places ticks at the left edge of their bands. A value of 0.5 places ticks in the middle of their bands.

10.6 Axis Title

axTitle : Str -> AxisProperty

A title for an axis. To specify a multi-line axis title, provide a list of title lines, one element per line. For example,

axTitle (strs [ "Speed", "(kph)" ])

axTitleAlign : HAlign -> AxisProperty

Horizontal alignment of an axis's title.

axTitleAnchor : Anchor -> AxisProperty

The anchor position for placing an axis title.

axTitleAngle : Num -> AxisProperty

Angle of an axis's title text.

axTitleBaseline : VAlign -> AxisProperty

Vertical alignment of an axis's title.

axTitleColor : Str -> AxisProperty

Color of an axis's title.

axTitleOpacity : Num -> AxisProperty

Opacity of an axis's title.

axTitleFont : Str -> AxisProperty

Font to be used for an axis's title.

axTitleFontSize : Num -> AxisProperty

Size of font in pixels for an axis's title.

axTitleFontStyle : Str -> AxisProperty

Font style of an axis title such as str "normal" or str "italic".

axTitleFontWeight : Value -> AxisProperty

Font weight of an axis's title. This can be a number (e.g. vNum 300) or text (e.g. vStr "bold").

axTitleLimit : Num -> AxisProperty

Maximum allowed length of an axis's title.

axTitleLineHeight : Num -> AxisProperty

Line height in pixels of each line of text in a multi-line axis title.

axTitlePadding : Value -> AxisProperty

Offset in pixels between an axis's labels and title.

axTitleX : Num -> AxisProperty

X position of an axis title relative to the axis group, overriding the standard layout.

axTitleY : Num -> AxisProperty

Y position of an axis title relative to the axis group, overriding the standard layout.

axTranslate : Num -> AxisProperty

Translate the axis coordinate system by a give number of pixels. Can be used for detailed alignment of axes when generating precise SVG output.

10.7 Axis Elements

aeAxis : AxisElement

Reference the axis element when customising an axis.

aeTicks : AxisElement

Reference the tick element when customising an axis.

aeGrid : AxisElement

Reference the grid element when customising an axis.

aeLabels : AxisElement

Reference the label element when customising an axis.

aeTitle : AxisElement

Reference the title element when customising an axis.

aeDomain : AxisElement

Reference the domain (line) element when customising an axis.

11. Legends

See the Vega legend documentation

legends : List Spec -> ( VProperty, Spec )

Create legends used to visualize color, size and shape mappings. Commonly the functional composition operator (<<) is used to combine multiple legend specifications. For example,

le =
    legends
        << legend
            [ leTitle (str "Income")
            , leOrient loBottomRight
            , leType ltSymbol
            , leSize "mySizeScale"
            ]
        << legend
            [ leTitle (str "Nationality")
            , leOrient loTopRight
            , leType ltSymbol
            , leFill "myColorScale"
            ]

legend : List LegendProperty -> List Spec -> List Spec

Create a legend used to visualize a color, size or shape mapping.

leValues : List Value -> LegendProperty

Explicitly set visible legend values.

11.1 Legend Type

leType : LegendType -> LegendProperty

Type of legend.

ltSymbol : LegendType

legend with discrete items.

ltGradient : LegendType

Legend to represent continuous data.

ltSignal : String -> LegendType

Legend type (symbol or gradient) referenced by the value in the named signal.

11.2 Legend Gradient

leGradientOpacity : Num -> LegendProperty

Opacity of a color gradient in a legend.

leGradientLabelLimit : Num -> LegendProperty

Maximum allowed length of gradient labels in a legend. Used only when configuring legends via cfLegend.

leGradientLabelOffset : Num -> LegendProperty

Vertical offset in pixels for gradient labels in a legend. Used only when configuring legends via cfLegend.

leGradientLength : Num -> LegendProperty

Length in pixels of the primary axis of a color gradient in a legend. This value corresponds to the height of a vertical gradient or the width of a horizontal gradient.

leGradientThickness : Num -> LegendProperty

Thickness in pixels of the color gradient in a legend. This value corresponds to the width of a vertical gradient or the height of a horizontal gradient.

leGradientStrokeColor : Str -> LegendProperty

Color of a legend's color gradient border.

leGradientStrokeWidth : Num -> LegendProperty

Width of a legend's color gradient border.

11.3 Legend Labels

leLabelAlign : HAlign -> LegendProperty

Horizontal text alignment for a legend label.

leLabelBaseline : VAlign -> LegendProperty

Vertical text alignment for a legend label.

leLabelColor : Str -> LegendProperty

Text color for legend labels.

leLabelFont : Str -> LegendProperty

Font for legend labels.

leLabelFontSize : Num -> LegendProperty

Font size in pixels for legend labels.

leLabelFontStyle : Str -> LegendProperty

Font style of an legend label such as str "normal" or str "italic".

leLabelFontWeight : Value -> LegendProperty

Font weight for legend labels.

leLabelLimit : Num -> LegendProperty

Maximum allowed length in pixels of a legend label.

leLabelOpacity : Num -> LegendProperty

Opacity for a legend's labels.

leLabelOffset : Num -> LegendProperty

Horizontal pixel offset for a legend's symbols.

leLabelOverlap : OverlapStrategy -> LegendProperty

Strategy to use for resolving overlap of labels in gradient legends.

leLabelSeparation : Num -> LegendProperty

Minimum separation that must be between labels for them to be considered non-overlapping. Ignored if leLabelOverlap resolution not enabled.

leFormat : Str -> LegendProperty

Format pattern for legend labels. Text should be either a d3-format specifier or a d3-time-format specifier.

leFormatAsNum : LegendProperty

Indicate that legend labels should be formatted as numbers. To control the precise numeric format, additionally use leFormat providing a d3 numeric format string.

leFormatAsTemporal : LegendProperty

Indicate that legend labels should be formatted as dates/times. To control the precise temporal format, additionally use leFormat providing a d3 date/time format string.

leFormatAsTemporalUtc : LegendProperty

Indicate that legend labels should be formatted as UTC dates/times. To control the precise temporal format.

11.4 Legend Symbols

leSymbolFillColor : Str -> LegendProperty

Fill color for legend symbols.

leSymbolBaseFillColor : Str -> LegendProperty

Default fill color for legend symbols. This is only applied if there is no fill scale color encoding for the legend and when configuring legends via cfLegend.

leSymbolBaseStrokeColor : Str -> LegendProperty

Default stroke color for legend symbols. This is only applied if there is no stroke scale color encoding for the legend and when configuring legends via cfLegend.

leSymbolDash : List Value -> LegendProperty

Stroke dash of an legend's symbols as a list of dash-gap lengths or empty list for solid lines.

leSymbolDashOffset : Num -> LegendProperty

Pixel offset from which to start a legend's symbol dash list.

leSymbolDirection : Orientation -> LegendProperty

Default direction for legend symbols. This is only applied when configuring legends via cfLegend.

leSymbolLimit : Num -> LegendProperty

Maximum number of allowed entries for a symbol legend. Entries exceeding this limit are replaced with a single ellipsis and an indication of how many entries have been dropped.

leSymbolOffset : Num -> LegendProperty

Offset in pixels between legend labels their corresponding symbol or gradient.

leSymbolOpacity : Num -> LegendProperty

Opacity for a legend's symbols.

leSymbolSize : Num -> LegendProperty

Default symbol area size in square pixel units.

leSymbolStrokeColor : Str -> LegendProperty

Border color for legend symbols.

leSymbolStrokeWidth : Num -> LegendProperty

Default symbol border width used in a legend.

leSymbolType : Symbol -> LegendProperty

Default symbol shape used in a legend.

leClipHeight : Num -> LegendProperty

Height in pixels to clip a symbol legend entries and limit its size. By default no clipping is performed.

11.5 Legend Ticks

leTickCount : Num -> LegendProperty

Desired number of tick values for quantitative legends.

leTickMinStep : Num -> LegendProperty

Minimum desired step between quantitative legend's ticks in scale domain units.

leTemporalTickCount : TimeUnit -> Num -> LegendProperty

Desired number of ticks for a temporal legend. The first parameter is the type of temporal interval to use and the second the number of steps of that interval between ticks. For example, to specify a tick is requested at six-month intervals (e.g. January, July):

le =
    legends
        << legend
            [ leFill "cScale"
            , leType ltGradient
            , leFormat (str "%b %Y")
            , leTemporalTickCount month (num 6)
            ]

If the second parameter is not a positive value, the number of ticks will be auto-generated for the given interval type.

11.6 Legend Title

leTitle : Str -> LegendProperty

Title for the legend (none by default). To specify a multi-line legend title, provide a list of title lines, one element per line. For example,

  leTitle (strs [ "Origin", "(country of Manufacture)" ])

leTitleAlign : HAlign -> LegendProperty

Horizontal alignment for a legend title.

leTitleAnchor : Anchor -> LegendProperty

The anchor position for placing a legend title.

leTitleBaseline : VAlign -> LegendProperty

Vertical alignment for a legend title.

leTitleColor : Str -> LegendProperty

Text color for a legend title.

leTitleOpacity : Num -> LegendProperty

Opacity for a legend's title.

leTitleFont : Str -> LegendProperty

Font for a legend title.

leTitleFontSize : Num -> LegendProperty

Font size in pixel units for a legend title.

leTitleFontStyle : Str -> LegendProperty

Font style of an legend title such as str "normal" or str "italic".

leTitleFontWeight : Value -> LegendProperty

Font weight for a legend title.

leTitleLimit : Num -> LegendProperty

Maximum allowed length in pixels of a legend title.

leTitleLineHeight : Num -> LegendProperty

Line height in pixels of each line of text in a multi-line legend title.

leTitleOrient : Side -> LegendProperty

Positioning of a legend's title relative to its content.

leTitlePadding : Num -> LegendProperty

Padding between the legend title and entries.

11.7 Legend Positioning and Layout

leDirection : Orientation -> LegendProperty

Direction of a legend.

leOrient : LegendOrientation -> LegendProperty

Orientation of the legend, determining where the legend is placed relative to a chart’s data rectangle.

loLeft : LegendOrientation

Position legend to the left of the visualization it describes.

loTopLeft : LegendOrientation

Position legend to be within the top-left of the visualization it describes.

loTop : LegendOrientation

Position legend above the top of the visualization it describes.

loTopRight : LegendOrientation

Position legend to be within the top-right of the visualization it describes.

loRight : LegendOrientation

Position legend to the right of the visualization it describes.

loBottomRight : LegendOrientation

Position legend to be within the bottom-right of the visualization it describes.

loBottom : LegendOrientation

Position legend below the bottom of the visualization it describes.

loBottomLeft : LegendOrientation

Position legend to be within the bottom-left of the visualization it describes.

loNone : LegendOrientation

Do not perform automatic legend positioning (allows legend to be located explicitly via x y coordinates). For example,

legend
    [ leTitle (str "Weight")
    , leOpacity "oScale"
    , leSymbolType symCircle
    , leOrient loNone
    , leEncode [ enLegend [ enEnter [ maX [ vNum 320 ], maY [ vNum 30 ] ] ] ]
    ]

loSignal : String -> LegendOrientation

Legend position referenced by the value in the named signal.

leOffset : Num -> LegendProperty

Offset in pixels by which to displace the legend from the data rectangle and axes.

lePadding : Num -> LegendProperty

Padding between the border and content of the legend group.

leX : Num -> LegendProperty

x-position of legend group in pixel units for absolute positioning when leOrient is set to loNone.

leY : Num -> LegendProperty

y-position of legend group in pixel units for absolute positioning when leOrient is set to loNone.

leZIndex : Num -> LegendProperty

z-index indicating the layering of the legend group relative to other axis, mark and legend groups. The default value is 0.

Layout

leGridAlign : GridAlign -> LegendProperty

Alignment to apply to symbol legends rows and columns.

leColumns : Num -> LegendProperty

Number of columns in which to arrange symbol legend entries. A value of 0 or lower indicates a single row with one column per entry. The default is 0 for horizontal symbol legends and 1 for vertical symbol legends.

leColumnPadding : Num -> LegendProperty

Horizontal padding between entries in a symbol legend.

leRowPadding : Num -> LegendProperty

Vertical padding between entries in a symbol legend.

llAnchor : Anchor -> LeLayoutProperty

The anchor position for placing a legend relative to its nearest axis.

llBounds : BoundsCalculation -> LeLayoutProperty

The type of bounding box calculation to use for determining legend extents.

llCenter : Boo -> LeLayoutProperty

Whether or not a legend should be centred within its layout area. Default is false.

llDirection : Orientation -> LeLayoutProperty

The direction in which subsequent legends should be positioned in a multi-legend layout. Should be one of orHorizontal or orVertical.

llMargin : Num -> LeLayoutProperty

Margin in pixel units to place between adjacent legends in a multi-legend layout.

llOffset : Num -> LeLayoutProperty

Offset of a legend from the chart body in pixel units.

11.8 Legend Appearance

leFill : String -> LegendProperty

Name of the scale that maps to the legend symbols' fill colors.

leOpacity : String -> LegendProperty

Name of the scale that maps to the legend symbols' opacities.

leShape : String -> LegendProperty

Name of the scale that maps to the legend symbols' shapes.

leSize : String -> LegendProperty

Name of the scale that maps to the legend symbols' sizes.

leStroke : String -> LegendProperty

Name of the scale that maps to the legend symbols' strokes.

leStrokeDash : String -> LegendProperty

Name of the scale that maps to the legend symbols' stroke dashing.

leCornerRadius : Num -> LegendProperty

Corner radius for an enclosing legend rectangle.

leFillColor : Str -> LegendProperty

Background color of an enclosing legend rectangle.

leStrokeColor : Str -> LegendProperty

Border color of an enclosing legend rectangle.

leStrokeWidth : String -> LegendProperty

Name of the scale that maps to a stroke width used in a legend.

leAria : List Aria -> LegendProperty

ARIA properties for providing accessible SVG output associated with a legend. If an empty list is provided, ARIA tagging will be switched off.

11.9 Legend Encoding

For custom encoding of legend appearance.

leEncode : List LegendEncoding -> LegendProperty

Mark encodings for custom legend styling. For example, to create a horizontal dash symbol (using a simple SVG path) for each legend item:

legend
    [ leEncode [ enSymbols [ enEnter [ maShape [ vStr "M-0.5,0H1" ] ] ] ]
    , leStroke "myColourScale"
    ]

enLegend : List EncodingProperty -> LegendEncoding

Custom encoding for a legend group mark.

enTitle : List EncodingProperty -> LegendEncoding

Custom ecoding for a legend title.

enLabels : List EncodingProperty -> LegendEncoding

Custom encoding for legend labels.

enSymbols : List EncodingProperty -> LegendEncoding

Custom encoding for symbol (discrete) legends.

enGradient : List EncodingProperty -> LegendEncoding

Custom encoding for gradient (continuous) legends.

enName : String -> EncodingProperty

Name for a custom legend encoding set.

enInteractive : Boo -> EncodingProperty

Whether or not a custom legend encoding set is to be interactive.

12. Marks

The primary means of providing a visual representation of data values. See the Vega mark documentation.

12.1 Top-Level Marks

marks : List Spec -> ( VProperty, Spec )

Create the marks used in the visualization. Multiple mark specifications are commonly combined using the functional composition operator (<<). For example,

  mk =
      marks
          << mark line
              [ mFrom [ srData (str "myData") ]
              , mEncode
                  [ enEnter
                      [ maX [ vScale "xScale", vField (field "distance") ]
                      , maY [ vScale "yScale", vField (field "energy") ]
                      , maStroke [ black ]
                      ]
                  ]
              ]
          << mark symbol
              [ mFrom [ srData (str "myData") ]
              , mEncode
                  [ enEnter
                      [ maX [ vScale "xScale", vField (field "distance") ]
                      , maY [ vScale "yScale", vField (field "energy") ]
                      , maFill [ white ]
                      , maStroke [ black ]
                      ]
                  ]
              ]

mark : Mark -> List TopMarkProperty -> List Spec -> List Spec

A mark definition. Marks form the visible components of a visualization. Each mark specification can include a list of mark properties (second parameter) that customise the appearance of the mark and relate its appearance to data streams or signals.

Mark Types

arc : Mark

An arc mark.

area : Mark

An area mark.

image : Mark

An image mark.

group : Mark

An group mark for assembling nested marks.

line : Mark

A line mark.

path : Mark

A path mark.

rect : Mark

A rectangle mark.

rule : Mark

A rule (single line) mark.

shape : Mark

A shape mark.

symbol : Mark

A symbol mark.

text : Mark

A text mark.

trail : Mark

A trail mark (line with variable width).

Top-Level Mark Properties

mAria : List Aria -> TopMarkProperty

ARIA properties for providing accessible SVG output associated with a mark. If an empty list is provided, ARIA tagging will be switched off.

mClip : Clip -> TopMarkProperty

Indicate whether or how marks should be clipped to a specified shape. For a simple case of clipping to the retangular 'data rectangle':

mClip (clEnabled true)

To clip by some arbitrary simple polygon use clPath either to specify an SVG path string explicitly in pixel coordinates, or more usefully for geographic coordinates use the output of trGeoPath:

ds =
    dataSource
        [ data "myClippingPoly"
            [ daUrl (str "myPolyFile.json")
            , daFormat [ topojsonFeature "idOfClippingPoly" ]
            ]
            |> transform [ trGeoPath "myProjection" [] ]
        ...

mk =
    marks
          << mark path
              [ mFrom [ srData (str "myMapSource") ]
              , mClip (clPath (strSignal "data('myClippingPoly')[0]['path']"))
              ...

mDescription : String -> TopMarkProperty

Description of a mark, useful for inline comments.

mEncode : List EncodingProperty -> TopMarkProperty

The visual encoding rules for a mark.

mFrom : List Source -> TopMarkProperty

Data source to be visualized by a mark. If not specified, a single element dataset containing an empty object is assumed. The source can either be a dataset to use or a faceting directive to subdivide a dataset across a set of group marks.

mInteractive : Boo -> TopMarkProperty

Whether a mark can serve as an input event source. If false, no mouse or touch events corresponding to the mark will be generated.

mKey : Field -> TopMarkProperty

Field to use as a unique key for data binding. When a visualization’s data is updated, the key value will be used to match data elements to existing mark instances. Use a key field to enable object constancy for transitions over dynamic data.

mName : String -> TopMarkProperty

Unique name to be given to a mark. This name can be used to refer to the mark in another mark or within an event stream definition. SVG renderers will add this name value as a CSS class name on the enclosing SVG group (g) element containing the mark instances.

mOn : List Trigger -> TopMarkProperty

Triggers for modifying a mark's properties in response to signal changes.

mSort : List ( Field, Order ) -> TopMarkProperty

Fields and sort order for sorting mark items. The sort order will determine the default rendering order. This is defined over generated scenegraph items and sorting is performed after encodings are computed, allowing items to be sorted by size or position. To sort by underlying data properties in addition to mark item properties, append the prefix datum to a field name.

mSort [ ( field "datum.y", ascend ) ]

mTransform : List Transform -> TopMarkProperty

Post-encoding transforms to be applied after any encode blocks, that operate directly on mark scenegraph items (not backing data objects). These can be useful for performing layout with transforms that can set x, y, width, height, etc. properties. Only data transforms that do not generate or filter data objects should be used.

mStyle : List String -> TopMarkProperty

Names of custom styles to apply to a mark. A style is a named collection of mark property defaults defined within the configuration. These properties will be applied to the mark’s enter encoding set, with later styles overriding earlier styles. Any properties explicitly defined within the mark’s encode block will override a style default.

mGroup : List ( VProperty, Spec ) -> TopMarkProperty

Assemble a group of top-level marks. Used to create nested groups of marks within a group mark (including further nested group specifications) by supplying the specification as a series of properties. For example,

marks
    << mark group
        [ mFrom [ srData (str "myData") ]
        , mGroup [ mkGroup1 [], mkGroup2 [] ]
        ]

mZIndex : Num -> TopMarkProperty

z-index (draw order) of a mark. Marks with higher values are drawn 'on top' of marks with lower numbers. Useful when drawing node-link diagrams and the node symbol should sit on top of connected edge lines.

clEnabled : Boo -> Clip

Whether or not clipping should be applied to a set of marks within a group mark.

clPath : Str -> Clip

Clipping path to be applied to a set of marks within a region. Should be a valid SVG path string.

clSphere : Str -> Clip

Clip a spherical outline subject to a given map projection name. This is useful in conjunction with map projections that include content such as graticule lines outside the bounds of the globe.

srData : Str -> Source

Name of the source for a set of marks.

12.2 Faceting

Split up a data source between group mark items.

srFacet : Str -> String -> List Facet -> Source

Create a facet directive for a set of marks. The first parameter is the name of the source dataset from which the facet partitions are to be generated. The second is the name to be given to the generated facet source. Marks defined with the faceted group mark can reference this data source name to visualize the local data partition.

mark group
    [ mFrom [ srFacet (str "table") "facet" [ faGroupBy [ field "category" ] ] ]
    , mEncode [ enEnter [ maY [ vScale "yScale", vField (field "category") ] ] ]
    , mGroup [ nestedMk [] ]
    ]

nestedMk =
    marks
        << mark rect
            [ mName "bars"
            , mFrom [ srData (str "facet") ]
            , mEncode
                [ enEnter
                    [ maY [ vScale "pos", vField (field "position") ]
                    , maHeight [ vScale "pos", vBand (num 1) ]
                    , maX [ vScale "xScale", vField (field "value") ]
                    , maX2 [ vScale "xScale", vBand (num 0) ]
                    , maFill [ vScale "cScale", vField (field "position") ]
                    ]
                ]
            ]

faField : Field -> Facet

For pre-faceted data, the name of the data field containing a list of data values to use as the local partition. This is required if using pre-faceted data.

faGroupBy : List Field -> Facet

For data-driven facets, specify a list of field names by which to partition the data. This is required if using pre-faceted data.

faAggregate : List AggregateProperty -> Facet

For data-driven facets, a list aggregate transform properties for the aggregate data values generated for each facet group item.

12.3 Lower-level Mark Properties

See the Vega mark encoding documentation.

Mark Positioning and Size

maX : List Value -> MarkProperty

The primary x-coordinate of a mark in pixels.

maX2 : List Value -> MarkProperty

The secondary x-coordinate of a mark in pixels.

maXC : List Value -> MarkProperty

The centre x-coordinate of a mark in pixels. This is an alternative to maX or maX2, not an addition.

maWidth : List Value -> MarkProperty

The width of a mark in pixels.

maY : List Value -> MarkProperty

The primary y-coordinate of a mark in pixels.

maY2 : List Value -> MarkProperty

The secondary y-coordinate of a mark in pixels.

maYC : List Value -> MarkProperty

The centre y-coordinate of a mark in pixels. This is an alternative to maY or maY2, not an addition.

maHeight : List Value -> MarkProperty

Height of a mark in pixels.

maSize : List Value -> MarkProperty

Area in pixels of the bounding box of point-based mark such as a symbol. Note that this value sets the area of the mark; the side lengths will increase with the square root of this value.

maZIndex : List Value -> MarkProperty

An integer z-index indicating the layering order of sibling mark items. The default value is 0. Higher values (1) will cause marks to be drawn on top of those with lower z-index values. Setting the z-index as an encoding property only affects ordering among sibling mark items; it will not change the layering relative to other mark definitions.

Mark Colouring

maOpacity : List Value -> MarkProperty

The opacity of a mark in the range 0 to 1.

maFill : List Value -> MarkProperty

Fill color of a mark.

maFillOpacity : List Value -> MarkProperty

The fill opacity of a mark in the range 0 to 1.

maStroke : List Value -> MarkProperty

Stroke color of a mark.

transparent : Value

Convenience function for specifying a transparent setting for marks that can be coloured (e.g. with maFill)

black : Value

Convenience function for specifying a black color setting for marks that can be coloured (e.g. with maStroke)

white : Value

Convenience function for specifying a white color setting for marks that can be coloured (e.g. with maStroke)

maStrokeOpacity : List Value -> MarkProperty

Stroke opacity of a mark in the range 0 to 1.

Blend Modes

maBlend : List Value -> MarkProperty

Color blend mode for drawing an item over its current background. Standard CSS blend modes can be specified with blendModeValue providing an appropriate blend mode such as bmHue, bmDarken etc.

bmNormal : BlendMode

Indicate the default blend mode should be applied when drawing over some background.

bmMultiply : BlendMode

Multiplicative blend mode to be applied when drawing over some background.

bmScreen : BlendMode

Screen blend mode to be applied when drawing over some background.

bmOverlay : BlendMode

Overlay blend mode to be applied when drawing over some background.

bmDarken : BlendMode

Darken blend mode to be applied when drawing over some background.

bmLighten : BlendMode

Lighten blend mode to be applied when drawing over some background.

bmColorDodge : BlendMode

Color dodge blend mode to be applied when drawing over some background.

bmColorBurn : BlendMode

Color burn blend mode to be applied when drawing over some background.

bmHardLight : BlendMode

Hard light blend mode to be applied when drawing over some background.

bmSoftLight : BlendMode

Soft light blend mode to be applied when drawing over some background.

bmDifference : BlendMode

Difference blend mode to be applied when drawing over some background.

bmExclusion : BlendMode

Exclusion blend mode to be applied when drawing over some background.

bmHue : BlendMode

Hue blend mode to be applied when drawing over some background.

bmSaturation : BlendMode

Saturation blend mode to be applied when drawing over some background.

bmColor : BlendMode

Color blend mode to be applied when drawing over some background.

bmLuminosity : BlendMode

Luminosity blend mode to be applied when drawing over some background.

blendModeValue : BlendMode -> Value

Convenience function for generating a value representing a given blend mode.

Mark Stroke Appearance

maStrokeWidth : List Value -> MarkProperty

Stroke width of a mark in pixels.

maStrokeCap : List Value -> MarkProperty

Stroke cap ending style for a mark. To guarantee valid stroke cap names, use strokeCapValue.

maStrokeDash : List Value -> MarkProperty

Stroke dash style of a mark. The list should consist of alternating dash-gap lengths in pixels.

maStrokeDashOffset : List Value -> MarkProperty

A mark's offset of the first stroke dash in pixels.

maStrokeJoin : List Value -> MarkProperty

Stroke join method for a mark. To guarantee valid stroke join names, use strokeJoinValue.

maStrokeMiterLimit : List Value -> MarkProperty

Miter limit at which to bevel a line join for a mark.

Mark Text

maFont : List Value -> MarkProperty

Typeface used by a text mark. This can be a generic font description such as sans-serif, monospace or any specific font name made accessible via a css font definition.

maFontSize : List Value -> MarkProperty

The font size in pixels used by a text mark.

maFontWeight : List Value -> MarkProperty

The font weight, such as normal or bold used by a text mark.

maFontStyle : List Value -> MarkProperty

The font style, such as normal or italic used by a text mark.

maLimit : List Value -> MarkProperty

The maximum length of a text mark in pixels (default 0, indicating no limit). The text value will be automatically truncated if the rendered size exceeds this limit.

maLineBreak : List Value -> MarkProperty

A delimiter, such as a newline character, used to break text strings into multiple lines. Ignored if input text is specified via multi-line strs.

maLineHeight : List Value -> MarkProperty

The height in pixels of each line of text in a multi-line text mark.

maDir : List Value -> MarkProperty

Direction text is rendered in a text mark. This determines which side is truncated in response to the text size exceeding the value of the limit parameter. To guarantee valid direction type names, use textDirectionValue.

maDx : List Value -> MarkProperty

Horizontal offset in pixels (before rotation), between the text and anchor point of a text mark.

maDy : List Value -> MarkProperty

Vertical offset in pixels (before rotation), between the text and anchor point of a text mark.

maEllipsis : List Value -> MarkProperty

Ellipsis string for text truncated in response to the limit parameter of a text mark.

maRadius : List Value -> MarkProperty

Polar coordinate radial offset in pixels, relative to the origin determined by the x and y properties of a text mark.

maText : List Value -> MarkProperty

The text to display in a text mark.

maTheta : List Value -> MarkProperty

Polar coordinate angle in radians, relative to the origin determined by the x and y properties of a text mark.

Interaction Cues

maCursor : List Value -> MarkProperty

Cursor to be displayed over a mark. To guarantee valid cursor type names, use cursorValue.

maHRef : List Value -> MarkProperty

URL to load upon mouse click. If defined, the mark acts as a hyperlink.

maTooltip : List Value -> MarkProperty

The tooltip text to show upon mouse hover over a mark. This may be specified directly, via a field, a signal or any other text-generating value.

Mark-Specific Properties

maAlign : List Value -> MarkProperty

Horizontal alignment of a text or image mark. To guarantee valid alignment type names, use hCenter, hLeft etc. For example:

<< mark text
    [ mEncode
        [ enEnter [ maAlign [ hCenter ] ] ]
    ]

maBaseline : List Value -> MarkProperty

Vertical baseline of a text or image mark. To guarantee valid alignment type names, use vTop, vMiddle etc. For example:

<< mark text
    [ mEncode
        [ enEnter [ maBaseline [ vTop ] ] ]
    ]

maCornerRadius : List Value -> MarkProperty

Corner radius in pixels of an arc or rect mark.

maCornerRadiusTopLeft : List Value -> MarkProperty

The radius in pixels of the top-left corner of a rectangle mark. Will override any value specified in maCornerRadius.

maCornerRadiusTopRight : List Value -> MarkProperty

The radius in pixels of the top-right corner of a rectangle mark. Will override any value specified in maCornerRadius.

maCornerRadiusBottomLeft : List Value -> MarkProperty

The radius in pixels of the bottom-left corner of a rectangle mark. Will override any value specified in maCornerRadius.

maCornerRadiusBottomRight : List Value -> MarkProperty

The radius in pixels of the bottom-right corner of a rectangle mark. Will override any value specified in maCornerRadius.

maStrokeForeground : List Value -> MarkProperty

Whether or not a group stroke should be drawn on top of group content rather than in the background.

maStrokeOffset : List Value -> MarkProperty

Offset in pixels at which to draw a group stroke and fill.

maInterpolate : List Value -> MarkProperty

Interpolation style of a linear mark. To guarantee valid interpolation type names, use markInterpolationValue.

maTension : List Value -> MarkProperty

The interpolation tension in the range 0 to 1 of a linear mark. Applies only to cardinal and Catmull-Rom interpolators.

maDefined : List Value -> MarkProperty

Indicate if the current data point in a linear mark is defined. If false, the corresponding line/trail segment will be omitted, creating a “break”.

maStartAngle : List Value -> MarkProperty

Start angle in radians clockwise from north for an arc mark.

maEndAngle : List Value -> MarkProperty

End angle in radians clockwise from north for an arc mark.

maPadAngle : List Value -> MarkProperty

The padding angle in radians clockwise from north for an arc mark.

maInnerRadius : List Value -> MarkProperty

The inner radius in pixel units of an arc mark.

maOuterRadius : List Value -> MarkProperty

The outer radius in pixel units of an arc mark.

maOrient : List Value -> MarkProperty

The orientation of an area mark. With a vertical orientation, an area mark is defined by the x, y, and (y2 or height) properties; with a horizontal orientation, the y, x and (x2 or width) properties must be specified instead. To guarantee valid orientation type names, use orientationValue.

maGroupClip : List Value -> MarkProperty

Indicate if the visible group content should be clipped to the group’s specified width and height.

maUrl : List Value -> MarkProperty

The URL of an image file to be displayed as an image mark. This may be specified directly, via a field, a signal or any other text-generating value.

maImage : List Value -> MarkProperty

A dynamically created image that may be displayed as an image mark.

maAspect : List Value -> MarkProperty

Whether or not image aspect ratio should be preserved in an image mark.

maSmooth : List Value -> MarkProperty

Whether or not an image is smoothed when interpolating to its non-native size.

maPath : List Value -> MarkProperty

The SVG path string describing the geometry of a path mark.

maShape : List Value -> MarkProperty

A shape instance that provides a drawing method to invoke within the renderer. Shape instances cannot be specified directly, instead they must be generated by a data transform such as symbol generation or a geoshape:

shapeEncoding =
    [ maShape [ symbolValue symSquare ]
    , maStroke [ black ]
    ]

le =
    legends
        << legend
            [ leFill "cScale"
            , leOrient loBottomRight
            , leEncode [ enSymbols [ enUpdate shapeEncoding ] ]
            ]

maSymbol : List Value -> MarkProperty

A symbol shape that describes a symbol mark. For preset shapes, use symbolValue. For correct sizing of custom shape paths, define coordinates within a square ranging from -1 to 1 along both the x and y dimensions.

maAngle : List Value -> MarkProperty

Rotation angle in degrees of a text, path or symbol mark.

maScaleX : List Value -> MarkProperty

Amount by which to scale a path mark horizontally before applying any rotation.

maScaleY : List Value -> MarkProperty

Amount by which to scale a path mark vertically before applying any rotation.

maCustom : String -> List Value -> MarkProperty

Create a custom mark property. For example:

mEncode
    [ enEnter
        [ maFill [ vScale "cScale", vField (field "group") ]
        , maCustom "myName" [ vScale "xScale", vField (field "group") ]
        ]
    ]

See the Vega beeswarm plot example.

12.4 Mark Encoding

See the Vega mark encoding documentation.

enEnter : List MarkProperty -> EncodingProperty

Properties to be encoded when a mark item is first instantiated or resized.

enUpdate : List MarkProperty -> EncodingProperty

Properties to be encoded when a mark item is updated such as in response to a signal change.

enHover : List MarkProperty -> EncodingProperty

Properties to be encoded when a pointer hovers over a mark item.

enExit : List MarkProperty -> EncodingProperty

Properties to be encoded when the data backing a mark item is removed.

enCustom : String -> List MarkProperty -> EncodingProperty

Named custom encoding set. Also requires a signal event handler with an encode directive.

miBasis : MarkInterpolation

Cubic basis spline interpolation between points.

miBundle : MarkInterpolation

Bundle curve interpolation between points.

miCardinal : MarkInterpolation

Cubic cardinal spline interpolation between points.

miCatmullRom : MarkInterpolation

Cubic Catmull-Rom spline interpolation between points.

miLinear : MarkInterpolation

Linear (straight) interpolation between points.

miMonotone : MarkInterpolation

Cubic spline interpolation that preserves monotonicity between points.

miNatural : MarkInterpolation

Natural cubic spline interpolation between points.

miStepwise : MarkInterpolation

Piecewise (stepped) constant interpolation function centred on each point in a sequence.

miStepAfter : MarkInterpolation

Piecewise (stepped) constant interpolation function after each point in a sequence.

miStepBefore : MarkInterpolation

Piecewise (stepped) constant interpolation function before each point in a sequence.

markInterpolationValue : MarkInterpolation -> Value

A convenience function for generating a value representing a given mark interpolation type. Used instead of specifying an interpolation type as a literal string to avoid problems of mistyping the interpolation name.

signals
    << signal "interp" [ siValue (markInterpolationValue miLinear) ]

orHorizontal : Orientation

Specify a horizontal orientation of a mark, legend or link path (e.g. horizontally or vertically oriented bars).

orVertical : Orientation

Specify a vertical orientation of a mark, legend or link path (e.g. horizontally or vertically oriented bars).

orRadial : Orientation

Specify a radial orientation of a mark or link path. Note that not all marks can use a radial orientation.

orSignal : String -> Orientation

Orientation referenced by the value in the named signal.

orientationValue : Orientation -> Value

A convenience function for generating a value representing a given mark orientation type. Used instead of specifying an orientation type as a literal string to avoid problems of mistyping its name.

 maOrient [ orientationValue orHorizontal ]

haLeft : HAlign

Left horizontal text alignment.

haCenter : HAlign

Center horizontal text alignment.

haRight : HAlign

Right horizontal text alignment.

haSignal : String -> HAlign

Horizontal text alignment referenced by the value in the named signal.

hLeft : Value

Convenience function for indicating a left horizontal alignment.

hCenter : Value

Convenience function for indicating a central horizontal alignment.

hRight : Value

Convenience function for indicating a right horizontal alignment.

vaTop : VAlign

Top vertical text alignment.

vaLineTop : VAlign

Top vertical text alignment calculated relative to line height rather than just font size.

vaMiddle : VAlign

Middle vertical text alignment.

vaBottom : VAlign

Bottom vertical text alignment.

vaLineBottom : VAlign

Bottom vertical text alignment calculated relative to line height rather than just font size.

vaAlphabetic : VAlign

'Alphabetic' vertical alignment aligning font baseline. Applies to text marks only.

vaSignal : String -> VAlign

Vertical text alignment referenced by the value in the named signal.

vTop : Value

Convenience function for indicating a top vertical alignment.

vLineTop : Value

Convenience function for indicating a line-top vertical alignment.

vMiddle : Value

Convenience function for indicating a middle vertical alignment.

vBottom : Value

Convenience function for indicating a bottom vertical alignment.

vLineBottom : Value

Convenience function for indicating a line-bottom vertical alignment.

vAlphabetic : Value

Convenience function for indicating an alphabetic vertical alignment.

symCircle : Symbol

Specify a circular symbol for a shape mark.

symCross : Symbol

Specify a cross symbol for a shape mark.

symDiamond : Symbol

Specify a diamond symbol for a shape mark.

symSquare : Symbol

Specify a square symbol for a shape mark.

symArrow : Symbol

Specify an arrow symbol for a shape mark. Useful when encoding symbol with a direction.

symWedge : Symbol

Specify a triangular wedge symbol for a shape mark. Useful when encoding symbol with a direction.

symTriangle : Symbol

Specify a triangular symbol for a shape mark.

symTriangleUp : Symbol

Specify an upward triangular symbol for a shape mark.

symTriangleDown : Symbol

Specify a downward triangular symbol for a shape mark.

symTriangleLeft : Symbol

Specify a left-pointing triangular symbol for a shape mark.

symTriangleRight : Symbol

Specify a right-pointing triangular symbol for a shape mark.

symStroke : Symbol

Specify a stroke (line) symbol. Can be used, for example, to show legend symbols as lines.

symPath : String -> Symbol

A custom symbol shape as an SVG path description.

symSignal : String -> Symbol

Symbol type referenced by the value in the named signal.

symbolValue : Symbol -> Value

Convenience function for generating a value representing a given symbol type.

caButt : StrokeCap

Butt stroke cap.

caSquare : StrokeCap

Square stroke cap.

caRound : StrokeCap

Rounded stroke cap.

caSignal : String -> StrokeCap

Stroke cap (butt, round and square) referenced by the value in the named signal.

strokeCapValue : StrokeCap -> Value

Convenience function for generating a value representing a given stroke cap type.

joMiter : StrokeJoin

Mitred stroke join.

joBevel : StrokeJoin

Bevelled stroke join.

joRound : StrokeJoin

Rounded stroke join.

joSignal : String -> StrokeJoin

Stroke join (miter, round or bevel) referenced by the value in the named signal.

strokeJoinValue : StrokeJoin -> Value

Convenience function for generating a text string representing a given stroke join type. Used instead of specifying an stroke join type as a literal string to avoid problems of mistyping its name.

tdLeftToRight : TextDirection

Left-to-right text render direction determining which end of a text string is truncated if it cannot be displayed within a restricted space.

tdRightToLeft : TextDirection

Right-to-left text render direction determining which end of a text string is truncated if it cannot be displayed within a restricted space.

tdSignal : String -> TextDirection

Text direction (ltr or rtl) referenced by the value in the named signal.

textDirectionValue : TextDirection -> Value

Create a text direction value.

12.5 Cursors

See the CSS cursor documentation

cuAuto : Cursor

Automatically determine a cursor type depending on interaction context.

cuDefault : Cursor

Default cursor.

cuNone : Cursor

No cursor.

cuContextMenu : Cursor

Context menu cursor.

cuHelp : Cursor

Help cursor.

cuPointer : Cursor

Pointer cursor.

cuProgress : Cursor

Progress cursor.

cuWait : Cursor

Waiting cursor.

cuCell : Cursor

Cell cursor.

cuCrosshair : Cursor

Crosshair cursor.

cuText : Cursor

Text cursor.

cuVerticalText : Cursor

Vertical text cursor.

cuAlias : Cursor

Alias cursor.

cuCopy : Cursor

Copy cursor.

cuMove : Cursor

Move cursor.

cuNoDrop : Cursor

'No drop' cursor.

cuNotAllowed : Cursor

'Not allowed' cursor.

cuAllScroll : Cursor

Scrolling cursor.

cuColResize : Cursor

Resizing cursor.

cuRowResize : Cursor

Resizing cursor.

cuNResize : Cursor

Resizing cursor.

cuEResize : Cursor

Resizing cursor.

cuSResize : Cursor

Resizing cursor.

cuWResize : Cursor

Resizing cursor.

cuNEResize : Cursor

Resizing cursor.

cuNWResize : Cursor

Resizing cursor.

cuSEResize : Cursor

Resizing cursor.

cuSWResize : Cursor

Resizing cursor.

cuEWResize : Cursor

Resizing cursor.

cuNSResize : Cursor

Resizing cursor.

cuNESWResize : Cursor

Resizing cursor.

cuNWSEResize : Cursor

Resizing cursor.

cuZoomIn : Cursor

Zooming cursor.

cuZoomOut : Cursor

Zooming cursor.

cuGrab : Cursor

Grab cursor.

cuGrabbing : Cursor

Grabbing cursor.

cursorValue : Cursor -> Value

A convenience function for generating a text value representing a given cursor type.

13. Configuration

Providing consistent default settings across a specification. See the Vega configuration documentation.

config : List ConfigProperty -> ( VProperty, Spec )

Create a collection of configuration settings. This allows default stylings to be defined for a collection of visualizations or visualization components.

cf =
    config
        [ cfMark text [ maFont [ vStr "Roboto Condensed, sans-serif" ] ]
        , cfTitle
            [ tiFont (str "Roboto Condensed, sans-serif")
            , tiFontWeight (vNum 500)
            , tiFontSize (num 17)
            ]
        , cfAxis axAll
            [ axLabelFont (str "Roboto Condensed, sans-serif")
            , axLabelFontSize (num 12)
            ]
        ]

13.1 Configuring the View

cfAutosize : List Autosize -> ConfigProperty

Default autosizing properties of view.

cfBackground : Str -> ConfigProperty

Default background of the view.

cfDescription : String -> ConfigProperty

Default text description for visualizations. This also determines the aria-label attribute for accessibility purposes.

cfPadding : Basics.Float -> ConfigProperty

Default padding around the visualization in pixel units. The way padding is interpreted will depend on the autosize properties.

cfPaddings : Basics.Float -> Basics.Float -> Basics.Float -> Basics.Float -> ConfigProperty

Default padding around the visualization in pixel units in left, top, right, bottom order.

cfPaddingSignal : String -> ConfigProperty

Default padding around the visualization in pixel units specified as a signal. The parameter is the name of a signal that can evaluate either to a single number or an object with properties left, top, right and bottom.

cfWidth : Basics.Float -> ConfigProperty

Default width of visualizations.

cfWidthSignal : String -> ConfigProperty

Default width of visualizations specified via a named signal.

cfHeight : Basics.Float -> ConfigProperty

Default height of visualizations.

cfHeightSignal : String -> ConfigProperty

Default height of visualizations specified via a named signal.

cfGroup : List MarkProperty -> ConfigProperty

Default properties of the top-level group mark representing the data rectangle of a chart.

cfLineBreak : Str -> ConfigProperty

Set the default text to represent a line break in multi-line text values.

13.2 Configuring Events

cfEventHandling : List ConfigEventHandler -> ConfigProperty

Configure default event handling. This can be used to, for example, filter only certain types of events.

cfeBind : SignalBind -> ConfigEventHandler

Configure the way DOM elements are bound to signals. The parameter determines if all bindings are allowed (sbAny; default), just those in the view container (sbContainer) or no bindings (sbNone).

sbAny : SignalBind

Indicate that any DOM-signal bindings should be handled.

sbContainer : SignalBind

Indicate that only DOM-signal bindings originating from the view container should be handled.

sbNone : SignalBind

Indicate that no DOM-signal bindings should be handled.

cfeDefaults : EventFilter -> List EventType -> ConfigEventHandler

Configure default filtering of events. This can specified in the first parameter as either a 'whitelist' (efAllow) or 'blacklist' (efPrevent) comprising the event types to be considered in the second parameter. If that list is empty, all event types will be placed in the black/white list.

efPrevent : EventFilter

Prevent events of a certain type from being handled.

efAllow : EventFilter

Allow events of a certain type to be handled.

cfeSelector : List EventType -> ConfigEventHandler

Configure event listeners from CSS-specified external sources. The parameter is a list of event types that will be listened for. If empty, no event types will be listened for. If this function is not specified, all event types will be listened for.

cfeTimer : Boo -> ConfigEventHandler

Configure whether or not to permit timer event listeners. Can be useful for turning dynamic visualizations on or off.

cfeGlobalCursor : Boo -> ConfigEventHandler

Configure whether or not cursor setting applies to the entire document body. Default is false indicating cursor applies only to the Vega view element only.

cfeView : List EventType -> ConfigEventHandler

Configure event listeners from a Vega-view source. The parameter is a list of event types that will be listened for. If empty, no event types will be listened for. If this function is not specified, all event types will be listened for.

cfeWindow : List EventType -> ConfigEventHandler

Configure event listeners from the browser window source. The parameter is a list of event types that will be listened for. If empty, no event types will be listened for. If this function is not specified, all event types will be listened for.

13.3 Configuring Marks

cfMark : Mark -> List MarkProperty -> ConfigProperty

Default properties of a given mark type.

cfMarks : List MarkProperty -> ConfigProperty

Default properties of all marks.

13.4 Configuring Axes

cfAxis : AxisType -> List AxisProperty -> ConfigProperty

Default properties of axes.

axAll : AxisType

All axis types to be configured with cfAxis.

axLeft : AxisType

Left axes to be configured with cfAxis.

axTop : AxisType

Top axes to be configured with cfAxis.

axRight : AxisType

Right axes to be configured with cfAxis.

axBottom : AxisType

Bottom axes to be configured with cfAxis.

axX : AxisType

x-axes to be configured with cfAxis.

axY : AxisType

y-axes to be configured with cfAxis.

axBand : AxisType

Band axes to be configured with cfAxis.

13.5 Configuring Legends

cfLegend : List LegendProperty -> ConfigProperty

Default properties of legends.

leBorderStrokeDash : List Value -> LegendProperty

Stroke dash style of the border of a legend block. The list should consist of alternating dash-gap lengths in pixels or an empty list for a solid line. Used only when configuring legends via cfLegend.

leBorderStrokeWidth : Num -> LegendProperty

Default stroke width of the border around legends in pixel units. Used only when configuring legends via cfLegend.

leLayout : List LeLayoutProperty -> LegendProperty

Specify legend layout properties when arranging multiple legends. Used only when configuring legends via cfLegend.

leOrientLayout : List ( LegendOrientation, List LeLayoutProperty ) -> LegendProperty

Specify legend layout properties for specific orientations when arranging multiple legends. Each tuple in the list should match an orientation with a list of layout properties. For example,

leOrientLayout
    [ ( loBottom, [ llAnchor anEnd ] )
    , ( loTop, [ llMargin (num 50), llCenter true ] )
    ]

Used only when configuring legends via cfLegend.

13.6 Configuring Titles

cfTitle : List TitleProperty -> ConfigProperty

Default properties of a title.

13.7 Configuring Scales

cfScaleRange : ScaleRange -> ScaleRange -> ConfigProperty

Create a named range to be used as part of a scale specification. The first parameter is the named range label (e.g. raOrdinal, raCategory, etc.). The second is the new range of values to be associated with this range.

cf =
    config [ cfScaleRange raHeatmap (raScheme (str "greenblue") []) ]

13.8 Configuring Styles

cfStyle : String -> List MarkProperty -> ConfigProperty

Create a named style. The first parameter is the name to give the style, the second its mark properties.

13.9 Configuration Signals

cfSignals : List Spec -> ConfigProperty

Create a signal to be used in a configuration. Useful for standardising font sizes, colors etc. across chart elements. The first parameter is a list of signal definitions, specified in the same way as any other signal. Once defined, the named signals can be used in other configuration options.

cf =
    config
        [ (cfSignals << signal "baseFontSize" [ siValue (vNum 10) ]) []
        , cfTitle [ tiFontSize (numSignal "baseFontSize*4") ]
        , cfAxis axAll [ axTitleFontSize (numSignal "baseFontSize*1.5") ]
        , cfLegend [ leTitleFontSize (numSignal "baseFontSize*2") ]
        ]

13.10 Configuring Locales

cfLocale : List LocaleProperty -> ConfigProperty

Specify the default local settings. Allows, for example, local currency, time and thousands separators to be defined as the default. For example a German locale might be defined as

cfLocale
    [ loDecimal (str ",")
    , loThousands (str ".")
    , loGrouping (num 3)
    , loCurrency (str "") (str "\\u00a0€")
    ]

loDecimal : Str -> LocaleProperty

Symbol used to indicate decimal point as part of a locale specification.

loThousands : Str -> LocaleProperty

Symbol used to indicate 'thousands' separator as part of a locale specification. Note that digits may be grouped in units other than thousands if loGrouping is set to a value other than 3.

loGrouping : Num -> LocaleProperty

Number of digits to represent what is by default a 'thousands' group, as part of a locale specification.

loCurrency : Str -> Str -> LocaleProperty

Indicate prefix (first parameter) and suffix (second parameter) currency symbols as part of a locale specification. e.g. loCurrency (str "£") (str "").

loNumerals : Str -> LocaleProperty

List of 10 symbols to replace the numerals 0–9 as part of a locale specification. Use strs to represent the list.

loPercent : Str -> LocaleProperty

Symbol used to indicate percentages as part of a locale specification.

loMinus : Str -> LocaleProperty

Symbol used to indicate minus/negative as part of a locale specification.

loNan : Str -> LocaleProperty

Symbol used to indicate a 'not-a-number' value, as part of a locale specification.

loDateTime : Str -> LocaleProperty

Default format of date-time representation as part of a locale specification.. Uses d3-time-format symbols. For example loDatetime (str "%a %b %e %X %Y")

loDate : Str -> LocaleProperty

Default format of date representation as part of a locale specification. Uses d3-time-format symbols. For example loDate(str "%_d %B %Y")

loTime : Str -> LocaleProperty

Default format of time representation as part of a locale specification. Uses d3-time-format symbols. For example loTime(str "%I:%M %p")

loPeriods : Str -> Str -> LocaleProperty

Symbols used to indicate a time of day 'AM' (first parameter) and 'PM' (second parameter) equivalent, as part of a locale specification. For example, loPeriods (str "a.m.") (str "p.m.").

loDays : Str -> LocaleProperty

List of the text representing the 7 days of the week (starting Sunday) as part of a locale specification. Use strs to represent the list.

loShortDays : Str -> LocaleProperty

List of the text representing the 7 abbreviated days of the week (starting Sunday) as part of a locale specification. Use strs to represent the list.

loMonths : Str -> LocaleProperty

List of the text representing the 12 months of the year (starting January) as part of a locale specification. Use strs to represent the list.

loShortMonths : Str -> LocaleProperty

List of the text representing the 12 abbreviated months of the year (starting January) as part of a locale specification. Use strs to represent the list.

14. Supplementary Properties

See the Vega specification documentation

autosize : List Autosize -> ( VProperty, Spec )

Indicate how the view is sized.

asContent : Autosize

Interpret visualization dimensions to be for the data rectangle (external padding added to this size).

asFit : Autosize

Interpret visualization dimensions to be for the entire visualization (data rectangle is shrunk to accommodate external decorations padding).

asFitX : Autosize

Interpret visualization width to be for the entire visualization (data rectangle is shrunk to accommodate external decorations and padding).

asFitY : Autosize

Interpret visualization height to be for the entire visualization (data rectangle is shrunk to accommodate external padding).

asNone : Autosize

No autosizing to be applied.

asPad : Autosize

Automatically expand size of visualization from the given dimensions in order to fit in all supplementary decorations (legends etc.).

asPadding : Autosize

Interpret visualization width to be for the entire visualization (data rectangle is shrunk to accommodate external padding).

asResize : Autosize

Recalculate autosizing on every view update.

asSignal : String -> Autosize

Indicate that an auto-sizing rule is to be determined by a named signal.

height : Basics.Float -> ( VProperty, Spec )

Override the default height of the visualization. If not specified, the height will be calculated based on the content of the visualization.

heightSignal : String -> ( VProperty, Spec )

Override the default height of the visualization. This requires a signal expression to be used representing the height.

padding : Basics.Float -> ( VProperty, Spec )

Padding around the visualization in pixel units. The way padding is interpreted will depend on the autosize properties.

paddings : Basics.Float -> Basics.Float -> Basics.Float -> Basics.Float -> ( VProperty, Spec )

Padding around the visualization in pixel units in left, top, right, bottom order.

paddingSignal : String -> ( VProperty, Spec )

Padding around the visualization in pixel units specified as a signal. The parameter is the name of a signal that can evaluate either to a single number or an object with properties left, top, right and bottom.

width : Basics.Float -> ( VProperty, Spec )

Override the default width of the visualization. If not specified, the width will be calculated based on the content of the visualization.

widthSignal : String -> ( VProperty, Spec )

Override the default width of the visualization. This requires a signal expression to be used representing the width.

background : Str -> ( VProperty, Spec )

The fill background color of a visualization. This should be specified as a color string or signal (via strSignal) representing a color.

encode : List EncodingProperty -> ( VProperty, Spec )

Encoding directives for the visual properties of the top-level group mark representing a chart’s data rectangle. For example, this can be used to set a background fill color for the plotting area, rather than the entire view.

description : String -> ( VProperty, Spec )

Provide a text description of the visualization. This also determines the aria-label attribute for accessibility purposes.

userMeta : List ( String, Value ) -> ( VProperty, Spec )

Provide a metadata description to be associated with the specification. The argument should be a list of the desired metadata keys and values. For example,

userMeta
    [ ( "Org", vStr "giCentre" )
    , ( "Date", vStr "2019-10-29" )
    , ( "Version", vNum 3.2 )
    ]

14.1 ARIA Accessibility Properties

arEnable : Aria

Enable ARIA attributes when generating SVG output. Default is that Aria is enabled, so this is only useful when overriding more global disabling of Aria attributes.

arDisable : Aria

Disable ARIA attributes when generating SVG output. Default is that Aria is enabled.

arDescription : Str -> Aria

Description to be provided in ARIA tag when generating SVG output. If not specified, the an auto-generated description will be provided.

15. Type Reference

Types that are not specified directly, provided here for reference with links to the functions that generate them.


type AggregateProperty

Generated by agAs, agCross, agDrop, agFields, agGroupBy, agOps and agKey.


type Anchor

Generated by anStart, anMiddle, anEnd and anchorSignal.


type Autosize

Generated by asContent, asFit, asFitX, asFitY, asNone, asPad, asPadding, asResize and asSignal.


type AxisElement

Generated by aeAxis, aeTicks, aeGrid, aeLabels, aeTitle and aeDomain.


type AxisProperty

Generated by axAria, axBandPosition, axDomain, axDomainCap, axDomainColor, axDomainDash, axDomainDashOffset, axDomainOpacity, axDomainWidth, axEncode, axFormat, axFormatAsNum, axFormatAsTemporal, axFormatAsTemporalUtc, axGrid, axGridCap, axGridColor, axGridDash, axGridDashOffset, axGridOpacity, axGridScale, axGridWidth, axLabels, axLabelAlign, axLabelBaseline, axLabelBound, axLabelColor, axLabelFlush, axLabelFlushOffset, axLabelFont, axLabelFontSize, axLabelFontStyle, axLabelFontWeight, axLabelLimit, axLabelLineHeight, axLabelOffset, axLabelOpacity axLabelOverlap, axLabelPadding, axLabelSeparation, axMaxExtent, axMinExtent, axOffset, axPosition, axTicks, axTickBand, axTickColor, axTickCount, axTemporalTickCount, axTickDash, axTickDashOffset, axTickExtra, axTickMinStep, axTickOffset, axTickOpacity, axTickRound, axTickSize, axTickWidth, axTitle, axTitleAlign, axTitleAnchor, axTitleAngle, axTitleBaseline, axTitleColor, axTitleFont, axTitleFontSize, axTitleFontStyle, axTitleFontWeight, axTitleLimit, axTitleLineHeight, axTitleOpacity, axTitlePadding, axTitleX, axTitleY, axTranslate, axValues and axZIndex.


type AxisType

Generated by axAll, axLeft, axTop, axRight, axBottom, axX, axY and axBand


type Bind

Generated by iRange, iCheckbox, iRadio, iSelect, iText, iNumber, iDate, iTime, iMonth, iWeek, iDateTimeLocal, iTel and iColor.


type BinProperty

Generated by bnInterval, bnAnchor, bnMaxBins, bnBase, bnSpan, bnStep, bnSteps, bnMinStep, bnDivide, bnNice, bnSignal and bnAs.


type BinsProperty

Generated by bsStart and bsStop.


type BlendMode

Generated by bmNormal, bmMultiply, bmScreen, bmOverlay, bmDarken, bmLighten, bmColorDodge, bmColorBurn, bmHardLight, bmSoftLight, bmDifference, bmExclusion, bmHue, bmSaturation, bmColor and bmLuminosity.


type Boo

Generated by true, false, boos, booSignal, booSignals and booExpr


type BoundsCalculation

Generated by bcFull, bcFlush and bc.


type Case

Generated by lowercase, uppercase and mixedcase.


type CInterpolate

Generated by hcl, hsl, lab, cubeHelix, cubeHelixLong, hclLong, hslLong and rgb.


type Clip

Generated by clEnabled, clPath and clSphere.


type ColorSchemeProperty

Generated by csScheme, csCount and csExtent.


type ColorGradient

Generated by grLinear and grRadial.


type ColorValue

Generated by cRGB, cHSL, cLAB and cHCL


type ConfigEventHandler

Generated by cfeBind, cfeDefaults, cfeGlobalCursor cfeSelector, cfeTimer, cfeView and cfeWindow.


type ConfigProperty

Generated by cfAutosize, cfBackground, cfDescription, cfLocale, cfPadding, cfPaddings, cfPaddingSignal, cfWidth, [cfWidthSignal], cfHeight, cfHeightSignal, cfGroup, cfLineBreak, cfEventHandling, cfMark, cfMarks, cfStyle, cfAxis, cfLegend, cfTitle, cfScaleRange and cfSignals.


type CountPatternProperty

Generated by cpPattern, cpCase, cpStopwords and cpAs.


type CrossProperty

Generated by crFilter and crAs.


type Cursor

Generated by functions that start with cu.


type alias Data =
( VProperty, Spec )

Convenience type annotation label for use with data generation functions. Generated by dataSource but is also useful when creating your own data generating functions. For example:

myData : Int -> Data
myData yr =
    dataSource
        [ data "population" [ daSource "pop" ]
            |> transform [ trFilter (expr ("datum.year == " ++ toString yr)) ]
        ]


type alias DataColumn =
List LabelledSpec

A single column of data. Generated when creating inline data with dataColumn.


type DataProperty

Generated by daFormat, daSource, daSources, daValue,daOn, daUrl and daSphere.


type DataReference

Generated by daDataset, daField, daFields, daSignal, daValues daReferences and daSort.


type alias DataRow =
Spec

A single row of data. Generated when creating inline data with dataRow.


type alias DataTable =
List LabelledSpec

A single table of data (collection of dataColumn specifications). Generated by data, dataFromColumns, dataFromRows, on and transform.


type DateTime

Generated by dtExpr and dtMillis.


type DataType

Generated by foNum, foBoo, foDate and foUtc.


type DensityFunction

Generated by dnPdf, dnCdf and dnSignal


type DensityProperty

Generated by dnExtent, dnMethod, dnSteps dnMinSteps, dnMaxSteps and dnAs.


type Distribution

Generated by diNormal, diUniform, diKde and diMixture.


type DotBinProperty

Generated by dbGroupBy, dbStep, dbSmooth, dbSignal and dbAs.


type EncodingProperty

Generated by enEnter, enUpdate, enExit, enHover, enName, enInteractive and enCustom.


type EventFilter

Generated by efPrevent and efAllow.


type EventHandler

Generated by evHandler, evUpdate, evEncode and evForce.


type EventSource

Generated by esAll, esView, esScope, esWindow and esDom.


type EventStream

Generated by esObject, esSelector, esSignal and esMerge.


type EventStreamProperty

Generated by esSource, esType, esBetween, esConsume, esFilter, esDebounce, esMarkName, esMark, esThrottle and esStream.


type EventType

Generated by etClick, etDblClick, etDragEnter, etDragLeave, etDragOver, etKeyDown, etKeyPress, etKeyUp, etMouseDown, etMouseMove, etMouseOut, etMouseOver, etMouseUp, etMouseWheel, etTouchEnd, etTouchMove, etTouchStart, etWheel and etTimer.


type Expr

Generated by exField and expr.


type Facet

Generated by faAggregate, faField and faGroupBy.


type Feature

Generated by featureSignal and feName.


type Field

Generated by fExpr, fDatum, fGroup, field, fParent and fSignal.


type Force

Generated by foCollide, foLink, foNBody, foX and foY.


type ForceProperty

Generated by fpDistance, fpDistanceMax, fpDistanceMin, fpId, fpIterations, fpStrength and fpTheta.


type ForceSimulationProperty

Generated by fsAlpha, fsAlphaMin, fsAlphaTarget, fsAs, fsForces, fsIterations, fsRestart, fsStatic and fsVelocityDecay.


type FormatProperty

Generated by csv, tsv, dsv, arrow, json, jsonProperty, topojsonFeature, topojsonMesh, topojsonMeshExterior, topojsonMeshInterior, parse, parseAuto and fpSignal.


type GeoJsonProperty

Generated by gjFields, gjFeature and gjSignal.


type GeoPathProperty

Generated by gpField, gpAs and gpPointRadius.


type GradientProperty

Generated by grX1, grY1, grX2, grY2, grR1, grR2 and grStops.


type GradientScaleProperty

Generated by grStart, grStop and grCount.


type GraticuleProperty

Generated by grField, grExtent, grExtentMajor, grExtentMinor, grStep, grStepMajor, grStepMinor and grPrecision.


type GridAlign

Generated by grAlignAll, grAlignEach, grAlignNone, grAlignRow, grAlignColumn and grAlignSignal.


type HAlign

Generated by haLeft, haCenter, haRight and haSignal.


type HeatmapProperty

Generated by hmField, hmColor, hmOpacity, hmResolve and hmAs.


type ImputeMethod

Generated by imByMin, imByMax, imByMean, imByMedian and imByValue.


type ImputeProperty

Generated by , imMethod, imGroupBy and imValue.


type InputProperty

Generated by inDebounce, inElement, inOptions, inLabels, inMin, inMax, inStep, inPlaceholder and inAutocomplete.


type IsocontourProperty

Generated by icField, icThresholds, icLevels, icNice, icResolve, icZero, icSmooth, icScale, icTranslate and icAs.


type JoinAggregateProperty

Generated by jaGroupBy, jaFields, jaOps and jaAs.


type KdeProperty

Generated by kdGroupBy, kdCumulative, kdCounts, kdBandwidth, kdExtent, kdMinSteps, kdMaxSteps, kdResolve, kdSteps and kdAs.


type Kde2Property

Generated by kd2dGroupBy, kd2Weight, kd2CellSize, kd2Bandwidth, kd2Counts and kd2As.


type LabelAnchorProperty

Generated by laLeft, laTopLeft, laTop, laTopRight, laRight, laBottomRight, laBottom, laBottomLeft and laMiddle.


type LabelMethod

Generated by lmFloodFill, lmReducedSearch and lmNaive.


type LabelOverlapProperty

Generated by lbAnchor, lbAvoidMarks, lbAvoidBaseMark, lbLineAnchor, lbMarkIndex, lbMethod, lbOffset, lbPadding, lbSort and lbAs.


type LayoutProperty

Generated by loAlign, loBounds, loColumns, loPadding, loPaddingRC, loOffset, loOffsetRC, loHeaderBand, loHeaderBandRC, loFooterBand, loFooterBandRC, loTitleBand and loTitleBandRC.


type LegendEncoding

Generated by enLegend, enTitle, enLabels, enSymbols and enGradient.


type LegendOrientation

Generated by loLeft, loTopLeft, loTop, loTopRight, loRight, loBottomRight, loBottom, loBottomLeft, loNone and loSignal.


type LegendProperty

Generated by [leAria])(#leAria), leType, leDirection, leOrient, leFill, leOpacity, leShape, leSize, leStroke, leStrokeDash, leStrokeWidth, leBorderStrokeDash, leBorderStrokeWidth, leEncode, leFormat, leFormatAsNum, leFormatAsTemporal, leFormatAsTemporalUtc, leGridAlign, leClipHeight, leColumns, leColumnPadding, leRowPadding, leCornerRadius, leFillColor, leOffset, lePadding, leStrokeColor, leGradientLength, leGradientLabelLimit, leGradientLabelOffset, leGradientOpacity, leGradientThickness, leGradientStrokeColor, leGradientStrokeWidth, leLabelAlign, leLabelBaseline, leLabelColor, leLabelFont, leLabelFontSize, leLabelFontStyle, leLabelSeparation, leLabelFontWeight, leLabelLimit, leLabelOpacity, leLabelOffset, leLabelOverlap, leSymbolDash, leSymbolDashOffset, leSymbolFillColor, leSymbolLimit, leSymbolOpacity, leSymbolOffset, leSymbolSize, leSymbolStrokeColor, leSymbolStrokeWidth, leSymbolType, leTickCount, leTickMinStep, leTemporalTickCount, leTitle, leTitleAlign, leTitleAnchor, leTitleBaseline, leTitleColor, leTitleFont, leTitleFontStyle, leTitleFontSize, leTitleFontWeight, leTitleLimit, leTitleLineHeight, leTitleOpacity, leTitleOrient, leTitlePadding, leValues, leX, leY and leZIndex.


type LegendType

Generated by ltSymbol, ltGradient and ltSignal.


type LinkPathProperty

Generated by lpSourceY, lpTargetX, lpTargetY, lpOrient, lpShape, lpRequire and lpAs.


type LinkShape

Generated by lsLine, lsArc, lsCurve, lsDiagonal, lsOrthogonal and lsSignal.


type LocaleProperty

Generated by loDecimal, loThousands, loGrouping, loCurrency, loNumerals, loPercent, loMinus, loNan, loDateTime, loDate, loTime, loPeriods, loDays, loShortDays, loMonths and loShortMonths.


type LoessProperty

Generated by lsGroupBy, lsBandwidth and lsAs.


type LookupProperty

Generated by luValues, luAs and luDefault.


type Mark

Generated by arc, area, image, group, line, path, rect, rule, shape, symbol, text and trail.


type MarkInterpolation

Generated by miBasis, miBundle, miCardinal, miCatmullRom, miLinear, miMonotone, miNatural, miStepwise, miStepAfter and miStepBefore.


type MarkProperty

Generated by maX, maX2, maXC, maWidth, maY, maY2, maYC, maHeight, maOpacity, maFill, maFillOpacity, maBlend, maStroke, maStrokeOpacity, maStrokeWidth, maStrokeCap, maStrokeDash, maStrokeDashOffset, maStrokeJoin, maStrokeMiterLimit, maCursor, maHRef, maTooltip, maZIndex, maAlign, maBaseline, maCornerRadius, maCornerRadiusTopLeft, maCornerRadiusTopRight, maCornerRadiusBottomLeft, maCornerRadiusBottomRight, maStrokeForeground, maStrokeOffset, maInterpolate, maTension, maDefined, maSize, maStartAngle, maEndAngle, maPadAngle, maInnerRadius, maOuterRadius, maOrient, maGroupClip, maUrl, maImage, maAspect, maSmooth, maPath, maShape, maSymbol, maAngle, maDir, maDx, maDy, maEllipsis, maFont, maFontSize, maFontWeight, maFontStyle, maLineBreak, maLineHeight, maLimit, maRadius, maScaleX, maScaleY, ] maText and maTheta.


type Num

Generated by num, nums, numSignal, numSignals, numList, numExpr and numNull


type Operation

Generated by opArgMax, opArgMin, opCI0, opCI1, opCount, opDistinct, opMax, opMean, opMedian, opMin, opMissing, opProduct, opQ1, opQ3, opStderr, opStdev, opStdevP, opSum, opValid, opVariance, opVarianceP. and opSignal.


type Order

Generated by ascend, descend and orderSignal.


type Orientation

Generated by orHorizontal, orVertical, orRadial and orSignal.


type OverlapStrategy

Generated by osNone, osGreedy, osParity and osSignal.


type PackProperty

Generated by paField, paSort, paSize, paRadius, paPadding and paAs.


type PartitionProperty

Generated by ptField, ptSort, ptPadding, ptRound, ptSize and ptAs.


type PieProperty

Generated by piField, piStartAngle, piEndAngle, piSort and piAs.


type PivotProperty

Generated by piGroupBy, piLimit and piOp.


type Projection

Generated by albers, albersUsa, azimuthalEqualArea, azimuthalEquidistant, conicConformal, conicEqualArea, conicEquidistant, equalEarth, equirectangular, gnomonic, identityProjection, mercator, mollweide, naturalEarth1, orthographic, stereographic, transverseMercator, customProjection and prSignal.


type ProjectionProperty

Generated by prType, prClipAngle, prClipExtent, prScale, prTranslate, prCenter, prRotate, prPointRadius, prPrecision, prFit, prExtent, prSize, prCoefficient, prDistance, prFraction, prLobes, prParallel, prRadius, prRatio, prSpacing, and prTilt, prReflectX and prReflectY.


type QuantileProperty

Generated by quGroupBy, quProbs, quStep, and quAs.


type RegressionMethod

Generated by reLinear, reLog, reExp, rePow, reQuad, rePoly and reSignal.


type RegressionProperty

Generated by reGroupBy, reMethod, reOrder, reExtent, reParams and reAs.


type Resolution

Generated by reShared, reIndependent and resolveSignal.


type Scale

Generated by scLinear, scPow, scSqrt, scLog, scSymLog, scTime, scUtc, scOrdinal, scBand, scPoint, scBinOrdinal, scQuantile, scQuantize,scThreshold, scCustom and scSignal.


type ScaleBins

Generated by bsNums, bsBins and bsSignal.


type ScaleDomain

Generated by doNums, doStrs and doData.


type ScaleNice

Generated by niTrue, niFalse, niMillisecond, niSecond, niMinute, niHour, niDay, niWeek, niMonth, niYear, niTickCount, niInterval and niSignal.


type ScaleProperty

Generated by scType, scDomain, scDomainMax, scDomainMin, scDomainMid, scDomainRaw, scRange, scBins, scReverse, scRound, scClamp, scInterpolate, scPadding, scNice, scZero, scExponent, scConstant, scBase, scAlign, scDomainImplicit, scPaddingInner, scPaddingOuter and scRangeStep.


type ScaleRange

Generated by raWidth, raHeight, raSymbol, raCategory, raDiverging, raOrdinal, raRamp, raHeatmap, raNums, raStrs, raValues, raScheme, raData, raStep, raCustomDefault and raSignal.


type Side

Generated by siLeft, siRight, siTop, siBottom and siSignal.


type SignalBind

Generated by sbAny, sbContainer and sbNone.


type SignalProperty

Generated by siName, siBind, siDescription, siInit, siOn, siUpdate, siReact, siValue and siPushOuter.


type SortProperty

Generated by soAscending, soDescending, soOp, soByField and soSignal.


type Source

Generated by srData and srFacet.


type alias Spec =
Json.Encode.Value

A Vega specification. Specs can be (and usually are) nested. They can range from a single Boolean value up to the entire Vega specification.


type Spiral

Generated by spArchimedean, spRectangular and spSignal.


type StackOffset

Generated by stZero, stCenter, stNormaize and stOffset.


type StackProperty

Generated by stField, stGroupBy, stSort, stOffset and stAs.


type Str

Generated by str, strs, strList, strSignal, strSignals, strExpr and strNull.


type StrokeCap

Generated by caButt, caRound, caSquare and caSignal.


type StrokeJoin

Generated by joMiter, joRound, joBevel and joSignal


type Symbol

Generated by symCircle, symSquare, symCross, symWedge, symArrow, symStroke, symDiamond, symTriangle, symTriangleUp, symTriangleDown, symTriangleLeft, symTriangleRight, symPath and symSignal.


type TextDirection

Generated by tdLeftToRight, tdRightToLeft and tdSignal.


type TimeBinProperty

Generated by tbUnits,tbStep, tbTimezone, tbInterval, tbExtent, tbMaxBins, tbSignal and tbAs.


type TimeUnit

Generated by year, quarter, month, date, week, day, dayOfYear, hour, minute, second, millisecond and tuSignal.


type Timezone

Generated by tzLocal, tzUtc and tzSignal.


type TitleElement

Generated by teTitle, teSubtitle and teGroup.


type TitleFrame

Generated by tfBounds, tfGroup and tfSignal.


type TitleProperty

Generated by tiAria, tiOrient, tiAnchor, tiAngle, tiAlign, tiBaseline, tiColor, tiDx, tiDy, tiEncodeElements, tiFont, tiFontSize, tiFontStyle, tiFontWeight, tiFrame, tiLimit, tiLineHeight, tiOffset, tiSubtitle, tiSubtitleColor, tiSubtitleFont, tiSubtitleFontSize, tiSubtitleFontStyle, tiSubtitleFontWeight, tiSubtitlePadding and tiZIndex.


type TopMarkProperty

Generated by mAria, mType, mClip, mDescription, mEncode, mFrom, mInteractive, mKey, mName, mOn, mSort, mTransform, mStyle, mGroup and mZIndex.


type Transform

Generated by trAggregate, trBin, trCollect, trCountPattern, trCross, trCrossFilter, trCrossFilterAsSignal, trDensity, trDotBin, trExtent, trExtentAsSignal, trFilter, trFlatten, trFlattenWithIndex, trFlattenAs, trFlattenWithIndexAs, trFold, trFoldAs, trForce, trFormula, trFormulaInitOnly, trGeoJson, trGeoPath, trGeoPoint, trGeoPointAs, trGeoShape, trGraticule, trHeatmap trIdentifier, trImpute, trIsocontour, trJoinAggregate, trKde, trKde2d, trLabel, trLinkPath, trLookup, trNest, trPack, trPartition, trPie, trPivot, trProject, trResolveFilter, trSample, trSequence, trStack, trStratify, trTree, trTreeLinks, trTreemap, trVoronoi, trWindow and trWordCloud.


type TreemapMethod

Generated by tmSquarify, tmResquarify, tmBinary, tmDice, tmSlice, tmSliceDice and tmSignal.


type TreemapProperty

Generated by tmField, tmSort, tmMethod, tmPadding, tmPaddingInner, tmPaddingOuter, tmPaddingTop, tmPaddingRight, tmPaddingBottom, tmPaddingLeft, tmRatio, tmRound, tmSize and tmAs.


type TreeMethod

Generated by meTidy, meCluster and meSignal.


type TreeProperty

Generated by teField, teSort, teMethod, teSeparation, teSize, teNodeSize and teAs.


type alias Trigger =
Spec

Generated by trigger.


type TriggerProperty

Generated by tgInsert, tgRemove, tgRemoveAll, tgToggle and tgModifyValues.


type VAlign

Generated by vaTop, vaMiddle, vaBottom, vaLineTop, vaLineBottom, vaAlphabetic and vaSignal.


type Value

Generated by vStr, vStrs, vNum, vNums, vTrue, vFalse, vBoos, vObject, keyValue, vValues, vSignal, vColor, vGradient, vGradientScale, vField, vScale, vScaleField, vBand, vExponent, vMultiply, vOffset, vRound, vNull and ifElse.


type VoronoiProperty

Generated by voExtent, voSize and voAs.


type WindowOperation

Generated by wnOperation, wnOperationOn and wnAggOperation.


type WindowProperty

Generated by wnSort, wnGroupBy, wnFrame and wnIgnorePeers.


type WOperation

Generated by woRowNumber, woRank, woDenseRank, woPercentRank, woCumeDist, woPercentile, woLag, woLead, woFirstValue, woLastValue, woNthValue woPrevValue, woNextValue and woSignal.


type WordcloudProperty

Generated by wcFont, wcFontStyle, wcFontWeight, wcFontSize, wcFontSizeRange, wcPadding, wcRotate, wcText, wcSize, wcSprial and wcAs.

Deprecated Functions and types

cfEvents : EventFilter -> List EventType -> ConfigProperty

Deprecated in favour of cfEventHandling. For example, instead of

cfEvents cfDeny [ etMouseMove, etMouseOver ]

use

cfEventHandling [ cfeDefaults cfDeny [ etMouseMove, etMouseOver ] ]

cnBandwidth : Num -> ContourProperty

Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.

Kernel density estimation bandwidth used in a contour transformation.

cnCount : Num -> ContourProperty

Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.

Desired number of contours used in a contour transformation. Ignored if cnThresholds setting explicit contour values are provided.

cnCellSize : Num -> ContourProperty

Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.

Size of cells used for density estimation in a contour transformation.

cnNice : Boo -> ContourProperty

Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.

Whether or not contour threshold values should be automatically aligned to 'nice', human-friendly values when performing a contour transformation.

cnSmooth : Boo -> ContourProperty

Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.

Whether or not contour polygons should be smoothed in a contour transformation. Ignored if kernel density estimation is used.

cnThresholds : Num -> ContourProperty

Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.

Explicit contour values to be generated by a contour transformation.

cnValues : Num -> ContourProperty

Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.

Grid of values over which to compute contours. If not provided, trContour will compute contours of the kernel density estimate of input data instead.

cnWeight : Field -> ContourProperty

Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.

Weight field used for density estimation in a contour transformation. This allows different weights to be attached to each value when estimating kernel density.

cnX : Field -> ContourProperty

Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.

X-coordinate field used for density estimation in a contour transformation.

cnY : Field -> ContourProperty

Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.

Y-coordinate field used for density estimation in a contour transformation.


type ContourProperty

Deprecated in favour of IsocontourProperty for use with trIsocontour.

scSequential : Scale

Deprecated: in favour of scLinear.

tiEncode : List EncodingProperty -> TitleProperty

Deprecated in favour of tiEncodeElements.

tiInteractive : Boo -> TitleProperty

Deprecated in favour of tiEncodeElements.

tiName : String -> TitleProperty

Deprecated in favour of tiEncodeElements.

tiStyle : Str -> TitleProperty

Deprecated in favour of tiEncodeElements.

trContour : Num -> Num -> List ContourProperty -> Transform

Deprecated in favour of the more flexible trIsocontour.

Generate a set of contour (iso) lines at a set of discrete levels. Commonly used to visualize density estimates for 2D point data.

The first two parameters are the width and height over which to compute the contours. The third a list of optional contour properties. The transform generates a new stream of GeoJSON data as output which may be visualized using either the trGeoShape or trGeoPath transforms.