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.
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 )
]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.
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.
A list of numeric literals. For lists that contain a mixture of numeric literals and signals use numList instead.
List of numeric values referenced by the values in the named signals.
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" ]))String values referenced by the values in the named signals.
List of signals that will generate Boolean values.
Used by functions that expect values of mixed types.
Band number or fraction of a band number. Band scales are used when aggregating data into discrete categories such as in a frequency histogram.
Custom key-value pair to be stored in an object generated by vObject.
List of values. Useful for nesting collections of possibly mixed types.
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 ]
]
]A scale field used to dynamically look up a scale name.
See the Vega field value documentation.
Expression that references a field but can perform calculations on each datum in the field.
fExpr "scale('xScale', datum.Horsepower)"Perform a lookup on the current data object using the given field. Once evaluated this is similar to simply providing a string value.
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.
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.
Indicate time unit is to specified as quarter (starting at one of January, April, July or October).
Indicate time unit is to specified as a millisecond of a second (0-999).
A color value.
Define a color in HCL space (parameters in H - C - L order).
Define a color in HSL space (parameters in H - S - L order).
Define a color in CIELab space (parameters in L - A - B order).
Color in RGB space.
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.
Indicates a linear color gradient.
Indicates a radial color gradient. See the Vega color gradient documentation.
The x-coordinate, normalized 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.
The y-coordinate, normalized 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.
The x-coordinate, normalized 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.
The y-coordinate, normalized 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.
The radius, normalized to [0, 1], of the inner circle for a radial color gradient. Default is 0.
The radius, normalized to [0, 1], of the outer circle for a radial color gradient. Default is 0.5.
Color interpolation points. Each tuple in the list is a position normalised [0, 1] and its associated color.
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.
Starting coordinate for the gradient as an [x, y] list normalized to [0, 1]. This coordinate is relative to the bounds of the item being colored (default is [0, 0]).
Stopping coordinate for the gradient as an [x, y] list normalized to [0, 1]. This coordinate is relative to the bounds of the item being colored (default is [1, 0] indicating a horizontal gradient).
Target number of sample points to take from the color scale.
See the Vega data and the Vega data reference documentation.
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.
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.
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.
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.
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.
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.
Data file to be loaded when generating a dataset.
Data format to use when loading or generating a dataset.
Name a data source when generating a dataset.
Name a collection of data sources when generating a dataset.
Data value(s) for generating a dataset inline.
Updates to insert, remove, and toggle data values, or clear the data in a dataset when trigger conditions are met.
Generate a global sphere dataset.
Reference a dataset with the given name.
Reference a data field with the given value.
Reference a collection of data fields with the given values.
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") ]
]
]
)
]Make a data reference with a signal.
Reference a collection of nested data references.
See the Vega sort and Vega type comparison documentation.
Sort a data reference.
Indicate sorting is to be applied from low to high.
Indicate sorting is to be applied from high to low.
Sorting operation.
Field to be used when sorting.
Sorting type referenced by the value in the named signal.
Sorting order referenced by the value in the named signal.
Indicate a CSV (comma-separated) format when parsing a data source.
Indicate a TSV (tab-separated) format when parsing a data source.
DSV (delimited separated value) format with a custom delimiter.
Apache arrow data file format.
Indicate a JSON format when parsing a data source.
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.
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.
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.
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.
TopoJSON feature format. The first parameter is the name of the feature object set to extract.
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.
Indicate automatic type inference on data types should be applied when parsing a data source.
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" ) ] ]
]
]Date format for parsing data using D3's formatting specifiers.
UTC date format for parsing data using D3's formatting specifiers.
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.
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.
See the Vega aggregate documentation
Group and summarize 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.
Data fields to group by when performing an aggregation transformation. If not specified, a single group containing all data objects will be used.
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.
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.
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.
Whether or not the full cross-product of all groupby values should
be included in the output of an aggregation transformation.
Whether or not empty (zero count) groups should be dropped when in an aggregation transformation.
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" ]
]
]An input data object containing the maximum field value to be used in an aggregation operation.
An input data object containing the minimum field value to be used in an aggregation operation.
Count of distinct data objects to be used in an aggregation operation.
Sample standard deviation of field values to be used in an aggregation operation.
Population standard deviation of field values to be used in an aggregation operation.
Count of values that are not null, undefined or NaN to be used in an
aggregation operation.
Sample variance of field value to be used in an aggregation operation.
Population variance of field value to be used in an aggregation operation.
See the Vega join aggregation documentation.
Group and summarize 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.
Fields to group by in a join aggregate transform.
Fields to aggregate in join aggregate transform.
Operations in a join aggregate transform.
Output fields to be generated by a join aggregate transform.
See the Vega bin and Vega dotBin documentation.
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" ]
]
]Whether or not a bin transformation should output both the start and end bin values. If false, only the starting bin value is output.
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.
Maximum number of bins to create with a bin transform.
Number base to use for automatic bin determination in a bin transform (default is base 100).
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.
Step size to use between bins in a bin transform.
Allowable step sizes between bins to choose from when performing a bin transform.
Minimum allowable bin step size between bins when performing a bin transform.
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.
Whether or not the bin boundaries in a binning transform will use human-friendly values such as multiples of ten.
Bind the specification of a binning transform (its start, step and stop properties) to a signal with the given name.
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.
The data fields to group by when performing a dot bin transformation. If not specified, all data objects used to generate a single group.
The bin width to use when stacking dots in a dot bin transformation.
Whether or not dot density stacks should be smoothed to reduce variance in a dot bin transformation. False if not specified.
Bind the computed dot binning parameters (an object with start, stop and step properties) to a signal with the given name.
The name to give the output bins field from a trDotbin
transformation. If not specified, output is named bin.
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.
Time units to determine the bins. If not specified, units will be inferred based on the extent of values to be binned.
Number of steps between bins in terms of the smallest time unit provided to
tbUnits (ignored if not tbUnits not specified).
Timezone to use when specifying dates and times.
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.
Minimum and maximum timestamps defining the full range of the time bins. Only applies if tbUnits not specified.
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)"Maximum number of temporal bins to create (default 40). Applies only if tbUnits is not specified.
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.
Names to give the fields holding start and end boundaries for each temporal bin.
If not specified, these will be named unit0 and unit1.
Collect all the objects in a data stream within a single list, allowing sorting by data field values.
See the Vega count pattern documentation.
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.
Define a match in a count pattern transformation with a regular expression (escaping backslashes):
transform [ trCountPattern (field "data") [ cpPattern (str "[\\w']{3,}") ] ]Text case transformation to apply before performing a count pattern transformation. The default, as generated by mixedcase, will leave text untransformed.
Define text to ignore in a count pattern transformation with a regular expression (escaping backslashes).
Names the two output fields generated by a count pattern transformation.
By default they are named text and count.
See the Vega cross-product documentation.
Compute the cross-product of a data stream with itself.
Filter for limiting the results of a cross-product transform.
Name the two output fields of a cross-product transform.
See the Vega impute documentation.
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.
Use minimum of a group when imputing a missing value.
Use maximum of a group when imputing a missing value.
Use the mean value of a group when imputing a missing value.
Use the median value of a group when imputing a missing value.
Use a specific value when imputing a missing value.
Additional collection of key values that should be considered for imputation as part of an impute transform.
Imputation method to be used as part of an impute transform. If not specified
the default imByMean method will be used.
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.
Value to use when an imputation method is set with imByValue in an impute transform.
See the Vega density documentation.
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.
A two-element list [min, max] from which to sample a distribution in a density transform.
Type of distribution to generate in a density transform.
Probability density function (PDF).
Cumulative density function (CDF).
Density function referenced by the value in the named signal.
Exact number of uniformly spaced steps to take along an extent domain in a density transform.
Minimum number of uniformly spaced steps (default 25) to take along an extent domain in a density transform.
Maximum number of uniformly spaced steps (default 200) to take along an extent domain in a density transform.
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.
Normal (Gaussian) probability distribution with a given mean (first parameter) and standard deviation (second parameter).
Uniform probability distribution with given minimum (first parameter) and maximum (second parameter) bounds.
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.
Weighted mixture of probability distributions. The parameter should be a list of tuples representing the component distributions and their corresponding weights.
See the Vega KDE transform documentation.
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.
The data fields to group by for a KDE transform. If not specified a single group of all data objects is used.
Whether or not a KDE transform generates cumulative density estimates. Default is false.
Whether or not a KDE transform should generate smoothed counts (true) or probability estimates (false, default).
Width of the Gaussian kernel for a KDE transform. If 0 (default), the bandwidth is determined from the input via Scott's method.
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.
The minimum number of samples (default 25) to take along the extent domain when performing a KDE transform.
The maximum number of samples (default 200) to take along the extent domain when performing a KDE transform.
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.
Indicate that multiple densities should be treated independently in a KDE transform.
Resolution type referenced by the value in the named signal.
The exact number of samples to take along the extent domain when performing a KDE transform. Overrides kdMinSteps and kdMaxSteps.
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.
See the Vega 2d KDE transform documentation.
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.
The data fields to group by for a 2d KDE transform. If not specified a single group of all data objects is used.
The data point weight field used in a 2d KDE density estimation. If unspecified, all points are assumed to have an equal unit weighting.
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.
Widths of the 2d Gaussian kernel for a 2d KDE transform in x, y order. If 0 (default), the bandwidth is automatically determined.
Whether or not a 2d KDE transform should generate smoothed counts (true) or probability estimates (false, default).
Field to contain a 2d KDE transform's raster values If not specified, the
output will allocated to a field named grid.
Calculate quantile values from an input data stream. Useful for examining distributional properties of a data stream and for creating Q-Q plots.
The data fields to group by when performing a quantile transformation. If not specified, all data objects are used to create a single group.
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.
The probability step size to use when performing a quantile transformation. Only used if quProbs is not specified. The default is 0.01.
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.
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
Group by a given set of fields when performing a regression transform. If not specified, all data objects are used.
Type of regression model to use.
A linear regression model (y = a + bx).
A log regression model (y = a + b.log(x)).
An exponential regression model (y = a + e^(bx)).
A power regression model (y = ax^b).
A quadratic regression model (y = a + bx + cx^2).
A polynomial regression model (y = a + bx + ... + kx^n). The order (n) of the polynomial can be set with reOrder.
Regression model referenced by the value in the named signal.
Convenience function for generating a value representing a given regression method. Useful when generating signals representing method types.
The polynomial order for a rePoly regression model.
Start and end values of the regression line on the independent (predictor) axis expressed as a two-element numeric list.
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).
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.
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.
Group by a given set of fields when performing a loess (locally estimated regression) transform.
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).
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.
See the Vega sample documentation.
Generate a random sample from a data stream to generate a smaller stream. The parameter determines the maximum number of data items to sample.
See the Vega extent documentation.
Compute the minimum and maximum values for a data field, producing a two-element [min, max] list.
Compute the minimum and maximum values for a given data field and bind it to a signal with the given name.
See the Vega filter and crossfilter documentation.
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.
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).
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.
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.
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.
Similar to trFlatten but allowing the output fields to be named.
Similar to trFlattenWithIndex but allowing the output fields to be named.
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.
Similar to trFold but allows the new output key and value fields
to be given alternative names (second and third parameters respectively).
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.
Fields to group by when performing a pivot transform. If not specified, a single group containing all data objects will be used.
Maximum number of fields to generate when performing a pivot transform or 0 for no limit.
Aggregation operation to use by when performing a pivot transform. If not specified, fields will be aggregated by their sum.
See the Vega formula, lookup, identifier, project and window documentation.
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 "https://vega.github.io/vega/data/world-110m.json")
, daFormat [ topojsonFeature "countries" ]
]
|> transform
[ trFormula "geoCentroid('myProj', datum)" "myCentroid" ]
]Similar to trFormula but will apply the formula only once even if the data changes.
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.
Output fields in which to write data found in the secondary stream of a lookup.
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.
Default value to assign if lookup fails in a lookup transformation.
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.
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.
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 ) ] ]
]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 ]
]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 ) ] ]
]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"
]
[]
]Assign consecutive row number to values in a data object to be applied in a window transform.
Rank function to be applied in a window transform.
Dense rank function to be applied in a window transform.
Percentile of values in a sliding window to be applied in a window transform.
Cumulative distribution function to be applied in a window transform.
Value preceding the current object in a sliding window to be applied in a window transform.
Value preceding the current object in a sliding window to be applied in a window transform.
Value following the current object in a sliding window to be applied in a window transform.
First value in a sliding window to be applied in a window transform.
Last value in a sliding window to be applied in a window transform.
Nth value in a sliding window to be applied in a window transform.
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.
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.
Window operation referenced by the value in the named signal. For names of valid window operations see the Vega window operation documentation
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.
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.
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.
Whether or not a sliding frame in a window transform should ignore peer values.
See the Vega sequence documentation.
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"
]
]Similar to trSequence but allowing the resulting sequence to be named (fourth parameter).
Transformations that work with spatial, often geographic, data.
See the Vega isocontour documentation
Generate geoJSON representing contours threaded through a given raster surface. See the Vega Isocontour documentation for details.
The name of the field containing raster data to contour in an isocontour transform.
The desired number of contour levels in an isocontour transform (ignored if icThresholds is specified).
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.
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.
Whether or not an isocontour transformation should use zero as a baseline value.
Whether or not contour lines should be smoothed (ignored if using 2d KDE for input generation).
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.
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.
Provide name for an isocontour transform output. Default is for output field
to be named contour.
Generate a raster image from a raster grid that can be rendered with an image mark.
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.
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)"))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)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.
Name to give the output of a heatmap transform. If not specified, defaults to
image.
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.
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.
Data field containing GeoJSON data when applying a geoShape or geoPath transformation. If unspecified, the full input data object will be used.
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.
Output field in which to write a generated shape instance following a geoShape or geoPath transformation.
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).
Fields containing longitude (first parameter) and latitude (second parameter) to be consolidated into a feature collection by a geoJSON transform.
Field containing the GeoJSON objects to be consolidated into a feature collection by a geoJSON transform.
Name of the a new signal to capture the output of generated by a geoJSON 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.
Similar to trGeoPoint but allowing the projected coordinates to be named (last two parameters).
See the Vega graticule documentation.
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.
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.
Major extent of a graticule. Parameter should evaluate to a two-element list representing longitude and latitude extents.
Minor extent of a graticule. Parameter should evaluate to a two-element list representing longitude and latitude extents.
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.
Major step angles of a graticule. Parameter should be a two-element list representing longitude and latitude spacing.
Minor step angles of a graticule. Parameter should be a two-element list representing longitude and latitude spacing.
Field used to bin when generating a graticule.
Precision in degrees with which graticule arcs are generated. The default value is 2.5 degrees.
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.
Field for the source x-coordinate in a linkPath transformation.
The default is source.x.
Field for the source y-coordinate in a linkPath transformation.
The default is source.y.
Field for the target x-coordinate in a linkPath transformation.
The default is target.x.
Field for the target y-coordinate in a linkPath transformation.
The default is target.y.
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.
Shape of a link path in a linkPath transformation.
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.
Name for the output field of a link path in a linkPath transformation. If not specified, the default is "path".
Curved diagonal lines linking nodes in a link diagram.
Orthogonal lines linking nodes in a link diagram.
See the Vega pie documentation.
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.
The field to encode with angular spans in a pie chart transform.
The starting angle in radians in a pie chart transform. The default is 0 indicating that the first slice starts 'north'.
End angle in radians in a pie chart transform. The default is 2 PI indicating the final slice ends 'north'.
Indicate whether or not pie slices should be stored in angular size order.
Output fields for the computed start and end angles for each arc in a pie transform.
See the Vega stack documentation.
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.
Field that determines the stack heights in a stack transform.
Grouping of fields with which to partition data into separate stacks in a stack transform.
Criteria for sorting values in a stack transform.
Baseline offset used in a stack transform.
Names of the output fields for the computed start and end stack values of a stack transform.
Offset a stacked layout using a baseline at the foot of a stack.
Offset a stacked layout using a central stack baseline.
Rescale a stacked layout to use a common height while preserving relative size of stacked quantities.
Stacking offset referenced by the value in the named signal.
See the Vega force documentation.
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.
Whether a simulation in a force transformation should be computed in batch to produce a static layout (true) or should be animated (false).
Whether a simulation in a force transformation should restart when node object fields are modified.
Number of iterations in a force transformation when in static mode (default 300).
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.
Minimum amount by which to lower the alpha value on each simulation iteration under a force transform.
Target alpha value to which a simulation converges under a force transformation.
Friction to be applied to a simulation in a force transformation. This is applied after the application of any forces during an iteration.
Forces to include in a force-directed simulation resulting from a force transform.
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.
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.
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.
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.
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.
Force attraction towards a particular x-coordinate (first parameter), with a given strength (second parameter) on a per-node basis.
Force attraction towards a particular y-coordinate (first parameter), with a given strength (second parameter) on a per-node basis.
Relative strength of a force or link constraint in a force simulation.
Distance in pixels by which the link constraint should separate nodes (default 30).
Number of iterations to run collision detection or link constraints (default 1) in a force directed simulation.
Approximation parameter for aggregating more distance forces in a force-directed simulation (default 0.9).
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).
Maximum distance over which an n-body force acts. If two nodes exceed this value, they will not exert forces on each other.
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.
See the Vega Voronoi documentation.
Compute a voronoi diagram for a set of input points and return the computed cell paths.
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].
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.
Name of the output field of a voronoi transform. If not specified, the default
is path.
See the Vega wordcloud documentation.
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 ])
]
]
]Font family to use for a word in a wordcloud.
Font style to use for words in a wordcloud.
Font weights to use for words in a wordcloud.
Font size to use for a word in a wordcloud.
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.
Padding, in pixels, to be placed around words in a wordcloud.
Angle in degrees of words in a wordcloud layout.
Data field with the input word text for a wordcloud transform.
Size of layout created by a wordcloud transform. The parameter should resolve to a two-element list [width, height] in pixels.
Spiral layout method for a wordcloud transform.
Archimedean spiralling for sequential positioning of words in a wordcloud.
Rectangular spiralling for sequential positioning of words in a wordcloud.
Word cloud spiral type (archimedean or rectangular) referenced by the
value in the named signal.
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.
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.
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.
See the Vega pack documentation.
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.
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.
Packing transform sorting properties. The inputs to subject to sorting are tree node objects, not input data objects.
The size of a packing layout, provided as a two-element list in [width, height] order (or a signal that generates such a list).
Node radius to use in a packing transform. If Nothing (the
default), the radius of each leaf circle is derived from the field value.
The approximate padding to include between packed circles.
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.
See the Vega partition documentation.
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.
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.
Sorting properties of sibling nodes during a partition layout transform.
Padding between adjacent nodes for a partition layout transform.
Whether or not node layout values should be rounded in a partition transform. The default is false.
Size of a partition layout as two-element list corresponding to [width, height] (or a signal that generates such a list).
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.
See the Vega tree and tree links documentation.
Compute a node-link diagram layout for hierarchical data. Supports both cluster layouts (for example, to create dendrograms) and tidy layouts.
Data corresponding to a numeric value to be associated with nodes in a tree transform.
Sorting properties of sibling nodes in a tree layout transform.
Layout method used in a tree transform.
A clustering tree layout method to be used in a tree transform.
A tidy tree layout method to be used in a tree transform.
Tree layout method (tidy or cluster) referenced by the value in the named signal.
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.
Size of of a tree layout as a two-element [width,height] list (or a signal that generates such a list).
Size of each node in a tree layout as a two-element [width,height] list (or a signal that generates such a list).
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.
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.
See the Vega treemap documentation.
Recursively subdivide an area into rectangles with areas proportional to each node’s associated value.
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.
Sorting properties of sibling nodes is in a treemap layout transform.
Layout method to use in a treemap transform.
A squarifying treemap layout method used in a treemap transform.
A resquarifying treemap layout method used in a treemap transform.
A binary treemap layout method used in a treemap transform.
A slicing treemap layout method used in a treemap transform.
A dicing treemap layout method used in a treemap transform.
A slice and dice treemap layout method used in a treemap transform.
Treemap layout method referenced by the value in the named signal.
Inner and outer padding values for a treemap layout transform.
Inner padding values for a treemap layout transform.
Outer padding values for a treemap layout transform.
Padding between the top edge of a node and its children in a treemap layout transform.
Padding between the left edge of a node and its children in a treemap layout transform.
Padding between the bottom edge of a node and its children in a treemap layout transform.
Padding between the right edge of a node and its children in a treemap layout transform.
Target aspect ratio for the tmSquarify or tmResquarify treemap layout transformations. The default is the golden ratio, φ = (1 + sqrt(5)) / 2.
Whether or not node layout values should be rounded in a treemap transform. The default is false.
Size of a treemap layout as two-element list (or signal) corresponding to [width, height].
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.
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 to be used to add a dynamic component to a visualization.
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".
Initial value of a signal. This value is assigned prior to the evaluation of
any expressions specified via siInit or siUpdate.
Bind a signal to an external input element such as a slider, selection list or radio button group.
Text description of a signal, useful for inline documentation.
Initialise a signal with an expression, which may include other signals.
This will occur only once, and cannot be used in parallel with siUpdate.
Event stream handlers for updating a signal value in response to input events.
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.
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 initialization.
Make signal updates target a signal in an enclosing scope. Used when creating nested signals in a group mark.
See the Vega signal binding documentation.
A checkbox input element for representing a boolean state.
A free text input element.
A numeric input element.
A date selector input element.
A local data time selector input element.
A time selector input element.
A month selector input element.
A week selector input element.
A radio button input element for representing a single selection from a list of alternatives.
A slider input element for representing a value within a numeric range.
A drop-down list input element for representing a single selection from a list of options.
A telephone number input element.
A color selector input element.
Delay event handling until the given milliseconds have elapsed since the last event was fired. Helps to limit event broadcasting.
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.
Options to be selected from a Radio or Select input element.
Labels to represent options values. If unspecified, the options value will be coerced to a string and used as the label.
Minimum value for a range slider input element.
Maximum value for a range slider input element.
Step value (increment between adjacent selectable values) for a range slider input element.
Place-holding text for input elements before any value has been entered.
Whether autocomplete should be turned on or off for input elements that support it.
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 "" ]
]
]Expression to be evaluated when an event occurs, the result of which becomes the new signal value.
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.
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.
See the Vega event stream documentation
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.
Signal that triggers an event stream. Allows an update to be triggered whenever the given signal changes.
Merge a list of event streams into a single stream.
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)" ]
]
]Compact representation of an event stream for modelling user input (alternative to esObject).
Source for an event selector.
Type of event stream for handling user interaction events.
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")Whether or not an event stream is consumed once it has been captured. If false, the event is made available for subsequent event handling.
Predicate expressions that must all evaluate to true for an event to be
captured.
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.
Named mark to be the source for an event stream. The name given here
must correspond to that provided via mName.
Mark type to be the source for an event stream.
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.
Event selector used to generate an event stream.
Event source from any mark. Equivalent to the * selector.
Limit event source to events from the main group in which a nested group sits.
Event source from the current Vega view component.
Event source from the browser window object.
DOM node to be the source for an event selector. Referenced with a standard CSS selector.
Double click interaction event type.
Drag entry interaction event type.
Drag exit interaction event type.
Drag over interaction event type.
Key press interaction event type.
Mouse down interaction event type.
Mouse movement interaction event type.
Mouse exit interaction event type.
Mouse over interaction event type.
Mouse wheel interaction event type.
Touch end interaction event type.
Touch move interaction event type.
Touch start interaction event type.
Fire an event at a regular interval determined by the number of milliseconds
provided with esThrottle.
See the Vega trigger documentation.
Add a list of triggers to the given data table.
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.
Expression that evaluates to data objects to insert as triggers. Insert operations are only applicable to datasets, not marks.
Expression that evaluates to data objects to remove. Remove operations are only applicable to datasets, not marks.
Remove all data object triggers.
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.
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.
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 to be used to map data values to visual properties.
Reverse the order of a scale range.
Whether to round numeric output values to integers. Helpful for snapping to the pixel grid.
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.
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.
Extend the range of a scale domain so it starts and ends on 'nice' round values.
Whether or not a scale domain should include zero. The default is true for linear, sqrt and power scales and false for all others.
Exponent to be used in power scale.
The desired desired slope of the scSymLog function at zero. If unspecified, the default is 1.
Base of the logarithm used in a logarithmic scale.
Alignment of elements within each step of a band scale, as a fraction of the step size. Should be in the range [0,1].
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.
Expand a scale domain to accommodate the specified number of pixels between inner bands in a band scale.
Expand a scale domain to accommodate the specified number of pixels outside the outer bands in a band scale.
Step size for band and point scales.
'Nice' values are ones rounded for easy interpretation, such as 100,200,300.
Nice time intervals that try to align with rounded milliseconds.
Desired number of tick marks in a 'nice' scaling.
'Nice' temporal interval values when scaling.
'nice' number-scaling type referenced by the value in the named signal.
Type of a named scale.
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) ])An ordinal band 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.
A quantile scale.
A quantizing scale.
A threshold scale.
The extent scaling input data.
Domain of input data values for a scale.
Maximum value of a scale domain, overriding a scDomain setting. Only intended
for scales with continuous domains.
Minimum value of a scale domain, overriding a scDomain setting.
This is only used with scales having continuous domains.
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.
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")
]List of numeric values (e.g. nums [1981, 2019]) representing a scale domain.
List of strings (e.g. strs ["cat","dog","fish"]) representing a scale domain.
Scale domain referenced by the value in the named signal.
Scale domains referenced by the values in the named signals.
Data reference object specifying field values in one or more datasets to define a scale domain.
The extent of scaled values after transformation.
Range of a scale representing the set of visual values.
Use default width range of scale output values.
Use default height range of scale output values.
Use default (discrete) symbol range of scale output values.
Use default category range of scale output values.
Use default diverging range of scale output values.
Use default ordinal range of scale output values.
Use default (continuous) ramp range of scale output values.
Use default heatmap range of scale output values.
Scale range as a list of numbers.
Scale range as a list of strings.
Scale range as a list of values.
Default range scaling referenced by the value in the named signal.
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.
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") ])
]Step size for a band scale range.
Custom range default scheme. Used when a new named default has been created as part of a config setting is required.
See the Vega Vega color scale and color scheme documentation.
Name a color scheme to use.
Number of colors to use in a color scheme.
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.
Interpolation method for a quantitative scale.
Cube helix color interpolation using the given gamma value (anchored at 1).
A long path cube-helix color interpolation using the given gamma value (anchored at 1).
A hue-chroma-luminance color interpolation.
A long-path hue-chroma-luminance color interpolation.
A hue-saturation-lightness color interpolation.
A long-path hue-saturation-lightness color interpolation.
RGB color interpolation. The parameter is a gamma value to control the brightness of the color trajectory.
An CIELab color interpolation.
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].
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.
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.
First bin in a series of bins.
Last bin in a series of bins.
For arranging collections of marks in a grid to create small multiples, faceted plots etc. See the Vega layout documentation.
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) ]Number of columns to include in a grid layout. If unspecified, a single row with unlimited columns will be assumed.
Padding in pixels to add between elements within rows and columns of a grid layout.
Similar to loPadding but allowing row and column settings to be specified separately.
Orthogonal offset in pixels by which to displace grid header, footer and title cells from their position along the edge of a grid layout.
Similar to loOffset but allowing row and column settings to be specified separately.
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.
Similar to loFHeaderBand but allowing row and column settings to be specified separately.
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.
Similar to loTitleBand but allowing row and column settings to be specified separately.
Bounds calculation method to use for determining the extent of a sub-plot in a grid layout.
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.
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.
Indicate that the bounds calculation type is to be determined by a named signal.
Alignment to apply to grid rows and columns in a grid layout.
Layout alignment to apply to grid rows. Used in cases when alignment rules are different for rows and columns.
Layout alignment to apply to grid columns. Used in cases when alignment rules are different for rows and columns.
Indicate grid elements will be aligned and each row or column will be sized identically based on the maximum observed size.
Indicate grid elements will be aligned into a clean grid structure, but each row or column may be of variable size.
Indicate a flow grid layout will be used in which adjacent plots are placed one after the other.
Layout alignment referenced by the value in the named signal.
The transformation of global longitude/latitude locations into 2d screen position. See the Vega map projection documentation.
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 ]) ]Map projection for transforming geo data onto a plane.
Type of map projection to use in a projection transformation.
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.
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.
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.
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.
Map projection’s centre as a two-element list of longitude and latitude in degrees.
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.
Default radius (in pixels) to use when drawing projected GeoJSON Point and MultiPoint geometries. The default value is 4.5.
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.
'Hammer' map projection's coefficient (defaults to 2).
'Satellite' map projection's distance value. Values are expressed as a proportion of the Earth's radius (defaults to 2).
'Bottomley' map projection's fraction parameter (defaults to 0.5).
Number of lobes in radial map projections such as the Berghaus Star.
Parallel used for map projections such as the Armadillo (defaults to 20 degrees N).
Radius for the 'Gingery' map projection. Defaults to 30 degrees.
'Hill' map projection's ratio allowing it to vary continuously between Maurer 73 (0) and Eckert IV projections (infinity). Defaults to 1.
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.
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.
Spacing for a Lagrange conformal map projection (defaults to 0.5).
Tilt angle for a Satellite map projection (defaults to 0 degrees).
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.
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).
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")
]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")
]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")
]An Albers map projection.
An Albers USA map projection that combines continental USA with Alaska and Hawaii.
An azimuthal equal area map projection.
An azimuthal equidistant map projection.
A conformal conic map projection.
An equal area conic map projection.
An equidistant conic map projection.
An equal-earth map projection that provides a reasonable shape approximation while retaining relative areas.
An equirectangular (default) map projection that maps longitude to x and latitude to y.
A gnomonic map projection.
An 'identity' projection where longitude is projected directly to the x position and latitude to the y position.
A Mercator map projection.
A mollweide global map projection.
A natural earth map projection.
An orthographic map projection.
A stereographic map projection.
A transverse Mercator map 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")).
Map projection referenced by the value in the named signal.
Convenience function for generating a value representing a given projection type. Useful when generating signals representing projection types.
Whether or not the title should be included as an ARIA attribute for providing accessible SVG output associated with an axis.
Anchor positioning of a title. Used for aligning title text.
Angle in degrees of a title.
Horizontal alignment of a title. If specified this will override the tiAnchor setting (useful when aligning rotated title text).
Vertical title text baseline.
Color of a title.
Additional horizontal offset of a title's position.
Additional vertical offset of a title's position.
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 customization 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 ) ]Indicates a title text element within a title group.
Indicates a subtitle text element within a title group.
Indicates a title group (rectangular area containing title and optional subtitle).
Font name of a title.
Font size of a title.
Font style of a title such as str "normal" or str "italic".
Font weight of a title (can be a number such as vNum 300 or text
such as vStr "bold").
Reference frame for the anchor position of a title.
Title anchor position calculation assuming text anchor is relative to the full bounding box.
Title anchor position calculation assuming text anchor is relative to the group width / height.
Title anchor calculation type (bounds or group) referenced by the value in
the named signal.
Color of a subtitle.
Font name of a subtitle.
Font size of a subtitle.
Font style of a subtitle such as str "normal" or str "italic".
Font weight of a subtitle (can be a number such as vNum 300 or text
such as vStr "bold").
Line height in pixels of each line of text in a subtitle.
Padding in pixels between title and subtitle text.
Maximim allowed length of a title in pixels.
Line height in pixels of each line of text in a title.
Orthogonal offset in pixels by which to displace the title from its position along the edge of the chart.
Position a title relative to the chart.
z-index indicating the layering of the title group relative to other axis, mark and legend groups.
Indicate that an anchor position is to be determined by a named signal.
The signal should generate one of start, middle or end.
Create the axes used to visualize spatial scale mappings.
ax =
axes
<< axis "myXScale" siBottom [ axTitle (str "Population") ]
<< axis "myYScale" siLeft [ axTickCount (num 5) ]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) ]Mark encodings for custom axis styling.
ARIA properties for providing accessible SVG output associated with an axis. If an empty list is provided, ARIA tagging will be switched off.
The minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles.
Maximum extent in pixels that axis ticks and labels should use.
Orthogonal offset in pixels by which to displace the axis from its position along the edge of the chart.
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.
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.
No overlap strategy to be applied when there is not space to show all items on an axis.
Give all items equal weight in overlap strategy to be applied when there is not space to show them all on an axis.
Greedy overlap strategy to be applied when there is not space to show all items on an axis.
Overlap strategy referenced by the value in the named signal.
Whether or not the domain (the axis baseline) should be included as part of an axis.
Stroke cap ending style for an axis baseline (domain). To guarantee valid cap names, use strokeCapStr to generate the parameter.
Color of an axis domain line.
Stroke dash of an axis's domain line as a list of dash-gap lengths or empty list for solid line.
Pixel offset from which to start the domain dash list.
Opacity of an axis domain line.
Width in pixels of an axis domain line.
Convenience function for generating a Str representing a given stroke cap type.
Whether or not grid lines should be included as part of an axis.
Stroke cap ending style for gridlines. To guarantee valid cap names, use strokeCapStr to generate the parameter.
Color of an axis's grid lines.
Opacity of an axis's grid lines.
Stroke dash of an axis's grid lines as a list of dash-gap lengths or empty list for solid lines.
Pixel offset from which to start the grid line dash list.
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.
Width of an axis's grid lines in pixel units.
Whether or not if labels should be included as part of an axis.
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.
Horizontal alignment of axis tick labels.
Vertical alignment of axis tick labels.
Angle of text for an axis.
Color of an axis label.
Opacity of an axis label.
Font name of an axis label.
Font size of an axis label.
Font style of an axis label such as str "normal" or str "italic".
Font weight of an axis label. This can be a number (e.g. vNum 300)
or text (e.g. vStr "bold").
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.
Number of pixels by which to offset flush-adjusted labels.
Maximum length in pixels of axis tick labels.
Line height in pixels for multi-line label text or label text with valineTop or vaLineBottom baselines.
Offset in pixels to apply to labels, in addition to axTickOffset.
Padding in pixels between labels and ticks.
Strategy to use for resolving overlap of axis labels.
Minimum separation that must be between labels for them to be considered non-overlapping. Ignored if axLabelOverlap resolution not enabled.
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.
Indicate that axis labels should be formatted as numbers. To control the precise numeric format, additionally use axFormat providing a d3 numeric format string.
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.
Indicate that axis labels should be formatted as UTC dates/times.
Explicitly set an axis tick and label values.
Whether or not ticks should be included as part of an axis.
Specify how axis ticks should be aligned when using a band scale.
Indicates axis ticks for band scales should be centered on each band.
Indicates axis ticks for band scales should be aligned with the extent of each band.
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.
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.
Line capping style for axis ticks. To guarantee valid cap names, use strokeCapStr to generate the parameter.
Color of an axis's ticks.
Stroke dash of an axis's tick marks as a list of dash-gap lengths or empty list for solid lines.
Pixel offset from which to start the tick dash list.
Opacity of an axis's ticks.
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.
Minimum desired step between axis ticks in scale domain units.
Offset in pixels of an axis's ticks, labels and gridlines.
Whether or not pixel position values for an axis's ticks should be rounded to the nearest integer.
Width in pixels of an axis's ticks.
Size in pixels of axis ticks.
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.
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)" ])Horizontal alignment of an axis's title.
The anchor position for placing an axis title.
Angle of an axis's title text.
Vertical alignment of an axis's title.
Color of an axis's title.
Opacity of an axis's title.
Font to be used for an axis's title.
Size of font in pixels for an axis's title.
Font style of an axis title such as str "normal" or str "italic".
Font weight of an axis's title. This can be a number (e.g. vNum 300)
or text (e.g. vStr "bold").
Maximum allowed length of an axis's title.
Line height in pixels of each line of text in a multi-line axis title.
Offset in pixels between an axis's labels and title.
X position of an axis title relative to the axis group, overriding the standard layout.
Y position of an axis title relative to the axis group, overriding the standard layout.
Translate the axis coordinate system by a give number of pixels. Can be used for detailed alignment of axes when generating precise SVG output.
Reference the axis element when customising an axis.
Reference the tick element when customising an axis.
Reference the grid element when customising an axis.
Reference the label element when customising an axis.
Reference the title element when customising an axis.
Reference the domain (line) element when customising an axis.
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"
]Create a legend used to visualize a color, size or shape mapping.
Explicitly set visible legend values.
Type of legend.
legend with discrete items.
Legend to represent continuous data.
Legend type (symbol or gradient) referenced by the value in the named signal.
Opacity of a color gradient in a legend.
Maximum allowed length of gradient labels in a legend. Used only when configuring legends via cfLegend.
Vertical offset in pixels for gradient labels in a legend. Used only when configuring legends via cfLegend.
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.
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.
Color of a legend's color gradient border.
Width of a legend's color gradient border.
Horizontal text alignment for a legend label.
Vertical text alignment for a legend label.
Text color for legend labels.
Font for legend labels.
Font size in pixels for legend labels.
Font style of an legend label such as str "normal" or str "italic".
Font weight for legend labels.
Maximum allowed length in pixels of a legend label.
Opacity for a legend's labels.
Horizontal pixel offset for a legend's symbols.
Strategy to use for resolving overlap of labels in gradient legends.
Minimum separation that must be between labels for them to be considered non-overlapping. Ignored if leLabelOverlap resolution not enabled.
Format pattern for legend labels. Text should be either a d3-format specifier or a d3-time-format specifier.
Indicate that legend labels should be formatted as numbers. To control the precise numeric format, additionally use leFormat providing a d3 numeric format string.
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.
Indicate that legend labels should be formatted as UTC dates/times. To control the precise temporal format.
Fill color for legend symbols.
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.
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.
Stroke dash of an legend's symbols as a list of dash-gap lengths or empty list for solid lines.
Pixel offset from which to start a legend's symbol dash list.
Default direction for legend symbols. This is only applied when configuring legends via cfLegend.
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.
Offset in pixels between legend labels their corresponding symbol or gradient.
Opacity for a legend's symbols.
Default symbol area size in square pixel units.
Border color for legend symbols.
Default symbol border width used in a legend.
Default symbol shape used in a legend.
Height in pixels to clip a symbol legend entries and limit its size. By default no clipping is performed.
Desired number of tick values for quantitative legends.
Minimum desired step between quantitative legend's ticks in scale domain units.
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.
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)" ])Horizontal alignment for a legend title.
The anchor position for placing a legend title.
Vertical alignment for a legend title.
Text color for a legend title.
Opacity for a legend's title.
Font for a legend title.
Font size in pixel units for a legend title.
Font style of an legend title such as str "normal" or str "italic".
Font weight for a legend title.
Maximum allowed length in pixels of a legend title.
Line height in pixels of each line of text in a multi-line legend title.
Positioning of a legend's title relative to its content.
Padding between the legend title and entries.
Direction of a legend.
Orientation of the legend, determining where the legend is placed relative to a chart’s data rectangle.
Position legend to the left of the visualization it describes.
Position legend to be within the top-left of the visualization it describes.
Position legend above the top of the visualization it describes.
Position legend to be within the top-right of the visualization it describes.
Position legend to the right of the visualization it describes.
Position legend to be within the bottom-right of the visualization it describes.
Position legend below the bottom of the visualization it describes.
Position legend to be within the bottom-left of the visualization it describes.
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 ] ] ] ]
]Legend position referenced by the value in the named signal.
Offset in pixels by which to displace the legend from the data rectangle and axes.
Padding between the border and content of the legend group.
x-position of legend group in pixel units for absolute positioning when
leOrient is set to loNone.
y-position of legend group in pixel units for absolute positioning when
leOrient is set to loNone.
z-index indicating the layering of the legend group relative to other axis, mark and legend groups. The default value is 0.
Alignment to apply to symbol legends rows and columns.
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.
Horizontal padding between entries in a symbol legend.
Vertical padding between entries in a symbol legend.
The anchor position for placing a legend relative to its nearest axis.
The type of bounding box calculation to use for determining legend extents.
Whether or not a legend should be centred within its layout area. Default is false.
The direction in which subsequent legends should be positioned in a
multi-legend layout. Should be one of orHorizontal or orVertical.
Margin in pixel units to place between adjacent legends in a multi-legend layout.
Name of the scale that maps to the legend symbols' fill colors.
Name of the scale that maps to the legend symbols' opacities.
Name of the scale that maps to the legend symbols' shapes.
Name of the scale that maps to the legend symbols' sizes.
Name of the scale that maps to the legend symbols' strokes.
Name of the scale that maps to the legend symbols' stroke dashing.
Corner radius for an enclosing legend rectangle.
Background color of an enclosing legend rectangle.
Border color of an enclosing legend rectangle.
Name of the scale that maps to a stroke width used in a legend.
ARIA properties for providing accessible SVG output associated with a legend. If an empty list is provided, ARIA tagging will be switched off.
For custom encoding of legend appearance.
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"
]Custom encoding for a legend group mark.
Custom ecoding for a legend title.
Custom encoding for legend labels.
Custom encoding for symbol (discrete) legends.
Custom encoding for gradient (continuous) legends.
Name for a custom legend encoding set.
Whether or not a custom legend encoding set is to be interactive.
The primary means of providing a visual representation of data values. See the Vega mark documentation.
## 12.1 Top-Level Marks
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 ]
]
]
]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.
ARIA properties for providing accessible SVG output associated with a mark. If an empty list is provided, ARIA tagging will be switched off.
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']"))
...Description of a mark, useful for inline comments.
The visual encoding rules for a mark.
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.
Whether a mark can serve as an input event source. If false, no mouse or touch events corresponding to the mark will be generated.
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.
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.
Triggers for modifying a mark's properties in response to signal changes.
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 ) ]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.
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.
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 [] ]
]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.
Whether or not clipping should be applied to a set of marks within a group mark.
Clipping path to be applied to a set of marks within a region. Should be a valid SVG path string.
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.
Split up a data source between group mark items.
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") ]
]
]
]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.
For data-driven facets, specify a list of field names by which to partition the data. This is required if using pre-faceted data.
For data-driven facets, a list aggregate transform properties for the aggregate data values generated for each facet group item.
The primary x-coordinate of a mark in pixels.
The secondary x-coordinate of a mark in pixels.
The centre x-coordinate of a mark in pixels. This is an alternative to maX
or maX2, not an addition.
The width of a mark in pixels.
The primary y-coordinate of a mark in pixels.
The secondary y-coordinate of a mark in pixels.
The centre y-coordinate of a mark in pixels. This is an alternative to maY
or maY2, not an addition.
Height of a mark in pixels.
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.
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.
The opacity of a mark in the range 0 to 1.
Fill color of a mark.
The fill opacity of a mark in the range 0 to 1.
Stroke color of a mark.
Convenience function for specifying a transparent setting for marks that can be colored (e.g. with maFill)
Convenience function for specifying a black color setting for marks that can be colored (e.g. with maStroke)
Convenience function for specifying a white color setting for marks that can be colored (e.g. with maStroke)
Stroke opacity of a mark in the range 0 to 1.
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.
Indicate the default blend mode should be applied when drawing over some background.
Multiplicative blend mode to be applied when drawing over some background.
Color dodge blend mode to be applied when drawing over some background.
Color burn blend mode to be applied when drawing over some background.
Hard light blend mode to be applied when drawing over some background.
Soft light blend mode to be applied when drawing over some background.
Difference blend mode to be applied when drawing over some background.
Exclusion blend mode to be applied when drawing over some background.
Saturation blend mode to be applied when drawing over some background.
Luminosity blend mode to be applied when drawing over some background.
Stroke width of a mark in pixels.
Stroke cap ending style for a mark. To guarantee valid stroke cap names, use strokeCapValue.
Stroke dash style of a mark. The list should consist of alternating dash-gap lengths in pixels.
A mark's offset of the first stroke dash in pixels.
Stroke join method for a mark. To guarantee valid stroke join names, use strokeJoinValue.
Miter limit at which to bevel a line join for a mark.
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.
The font size in pixels used by a text mark.
The font weight, such as normal or bold used by a text mark.
The font style, such as normal or italic used by a text mark.
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.
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.
The height in pixels of each line of text in a multi-line text mark.
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.
Horizontal offset in pixels (before rotation), between the text and anchor point of a text mark.
Vertical offset in pixels (before rotation), between the text and anchor point of a text mark.
Ellipsis string for text truncated in response to the limit parameter of a text mark.
Polar coordinate radial offset in pixels, relative to the origin determined by the x and y properties of a text mark.
The text to display in a text mark.
Polar coordinate angle in radians, relative to the origin determined by the x and y properties of a text mark.
Cursor to be displayed over a mark. To guarantee valid cursor type names, use cursorValue.
URL to load upon mouse click. If defined, the mark acts as a hyperlink.
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.
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 ] ] ]
]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 ] ] ]
]Corner radius in pixels of an arc or rect mark.
The radius in pixels of the top-left corner of a rectangle mark. Will override any value specified in maCornerRadius.
The radius in pixels of the top-right corner of a rectangle mark. Will override any value specified in maCornerRadius.
The radius in pixels of the bottom-left corner of a rectangle mark. Will override any value specified in maCornerRadius.
The radius in pixels of the bottom-right corner of a rectangle mark. Will override any value specified in maCornerRadius.
Whether or not a group stroke should be drawn on top of group content rather than in the background.
Offset in pixels at which to draw a group stroke and fill.
Interpolation style of a linear mark. To guarantee valid interpolation type names, use markInterpolationValue.
The interpolation tension in the range 0 to 1 of a linear mark. Applies only to cardinal and catmull-rom interpolators.
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”.
Start angle in radians clockwise from north for an arc mark.
End angle in radians clockwise from north for an arc mark.
The padding angle in radians clockwise from north for an arc mark.
The inner radius in pixel units of an arc mark.
The outer radius in pixel units of an arc mark.
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.
Indicate if the visible group content should be clipped to the group’s specified width and height.
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.
A dynamically created image that may be displayed as an image mark.
Whether or not image aspect ratio should be preserved in an image mark.
Whether or not an image is smoothed when interpolating to its non-native size.
The SVG path string describing the geometry of a path mark.
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 ] ]
]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.
Rotation angle in degrees of a text, path or symbol mark.
Amount by which to scale a path mark horizontally before applying any rotation.
Amount by which to scale a path mark vertically before applying any rotation.
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.
See the Vega mark encoding documentation.
Properties to be encoded when a mark item is first instantiated or resized.
Properties to be encoded when a mark item is updated such as in response to a signal change.
Properties to be encoded when a pointer hovers over a mark item.
Properties to be encoded when the data backing a mark item is removed.
Named custom encoding set. Also requires a signal event handler with an
encode directive.
Cubic basis spline interpolation between points.
Bundle curve interpolation between points.
Cubic cardinal spline interpolation between points.
Cubic Catmull-Rom spline interpolation between points.
Linear (straight) interpolation between points.
Cubic spline interpolation that preserves monotonicity between points.
Natural cubic spline interpolation between points.
Piecewise (stepped) constant interpolation function centred on each point in a sequence.
Piecewise (stepped) constant interpolation function after each point in a sequence.
Piecewise (stepped) constant interpolation function before each point in a sequence.
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) ]Specify a horizontal orientation of a mark, legend or link path (e.g. horizontally or vertically oriented bars).
Specify a vertical orientation of a mark, legend or link path (e.g. horizontally or vertically oriented bars).
Specify a radial orientation of a mark or link path. Note that not all marks can use a radial orientation.
Orientation referenced by the value in the named signal.
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 ]Top vertical text alignment calculated relative to line height rather than just font size.
Bottom vertical text alignment calculated relative to line height rather than just font size.
'Alphabetic' vertical alignment aligning font baseline. Applies to text marks only.
Convenience function for indicating a line-bottom vertical alignment.
Convenience function for indicating an alphabetic vertical alignment.
Specify a diamond symbol for a shape mark.
Specify an arrow symbol for a shape mark. Useful when encoding symbol with a direction.
Specify a triangular wedge symbol for a shape mark. Useful when encoding symbol with a direction.
Specify a triangular symbol for a shape mark.
Specify an upward triangular symbol for a shape mark.
Specify a downward triangular symbol for a shape mark.
Specify a left-pointing triangular symbol for a shape mark.
Specify a right-pointing triangular symbol for a shape mark.
Specify a stroke (line) symbol. Can be used, for example, to show legend symbols as lines.
A custom symbol shape as an SVG path description.
Convenience function for generating a value representing a given symbol type.
Stroke cap (butt, round and square) referenced by the value in the
named signal.
Convenience function for generating a value representing a given stroke cap type.
Mitered stroke join.
Bevelled stroke join.
Rounded stroke join.
Stroke join (miter, round or bevel) referenced by the value in the
named signal.
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.
Left-to-right text render direction determining which end of a text string is truncated if it cannot be displayed within a restricted space.
Right-to-left text render direction determining which end of a text string is truncated if it cannot be displayed within a restricted space.
Text direction (ltr or rtl) referenced by the value in the named signal.
Create a text direction value.
See the CSS cursor documentation
Context menu cursor.
Progress cursor.
Crosshair cursor.
Vertical text cursor.
'Not allowed' cursor.
Scrolling cursor.
Resizing cursor.
Resizing cursor.
Resizing cursor.
Resizing cursor.
Resizing cursor.
Resizing cursor.
Resizing cursor.
Resizing cursor.
Resizing cursor.
Resizing cursor.
Grabbing cursor.
A convenience function for generating a text value representing a given cursor type.
Providing consistent default settings across a specification. See the Vega configuration documentation.
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)
]
]Default autosizing properties of view.
Default background of the view.
Default text description for visualizations. This also determines the aria-label attribute for accessibility purposes.
Default padding around the visualization in pixel units. The way padding is
interpreted will depend on the autosize properties.
Default padding around the visualization in pixel units in left, top, right, bottom order.
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.
Default width of visualizations.
Default width of visualizations specified via a named signal.
Default height of visualizations.
Default height of visualizations specified via a named signal.
Default properties of the top-level group mark representing the data rectangle of a chart.
Set the default text to represent a line break in multi-line text values.
Configure default event handling. This can be used to, for example, filter only certain types of events.
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).
Indicate that any DOM-signal bindings should be handled.
Indicate that only DOM-signal bindings originating from the view container should be handled.
Indicate that no DOM-signal bindings should be handled.
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.
Prevent events of a certain type from being handled.
Allow events of a certain type to be handled.
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.
Configure whether or not to permit timer event listeners. Can be useful for turning dynamic visualizations on or off.
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.
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.
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.
Default properties of a given mark type.
Default properties of all marks.
Default properties of axes.
Default properties of legends.
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.
Default stroke width of the border around legends in pixel units. Used only when configuring legends via cfLegend.
Specify legend layout properties when arranging multiple legends. Used only when configuring legends via cfLegend.
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.
Default properties of a title.
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") []) ]Create a named style. The first parameter is the name to give the style, the second its mark properties.
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") ]
]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€")
]Symbol used to indicate decimal point as part of a locale specification.
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.
Number of digits to represent what is by default a 'thousands' group, as part of a locale specification.
Indicate prefix (first parameter) and suffix (second parameter) currency symbols
as part of a locale specification. e.g. loCurrency (str "£") (str "").
List of 10 symbols to replace the numerals 0–9 as part of a locale specification. Use strs to represent the list.
Symbol used to indicate percentages as part of a locale specification.
Symbol used to indicate minus/negative as part of a locale specification.
Symbol used to indicate a 'not-a-number' value, as part of a locale specification.
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")
Default format of date representation as part of a locale specification. Uses
d3-time-format symbols. For example
loDate(str "%_d %B %Y")
Default format of time representation as part of a locale specification. Uses
d3-time-format symbols. For example
loTime(str "%I:%M %p")
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.").
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.
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.
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.
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.
Interpret visualization dimensions to be for the data rectangle (external padding added to this size).
Interpret visualization dimensions to be for the entire visualization (data rectangle is shrunk to accommodate external decorations padding).
Interpret visualization width to be for the entire visualization (data rectangle is shrunk to accommodate external decorations and padding).
Interpret visualization height to be for the entire visualization (data rectangle is shrunk to accommodate external padding).
Automatically expand size of visualization from the given dimensions in order to fit in all supplementary decorations (legends etc.).
Interpret visualization width to be for the entire visualization (data rectangle is shrunk to accommodate external padding).
Indicate that an auto-sizing rule is to be determined by a named signal.
Override the default height of the visualization. If not specified, the height will be calculated based on the content of the visualization.
Override the default height of the visualization. This requires a signal expression to be used representing the height.
Padding around the visualization in pixel units. The way padding is
interpreted will depend on the autosize properties.
Padding around the visualization in pixel units in left, top, right, bottom order.
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.
Override the default width of the visualization. If not specified, the width will be calculated based on the content of the visualization.
Override the default width of the visualization. This requires a signal expression to be used representing the width.
The fill background color of a visualization. This should be specified as a color string or signal (via strSignal) representing a color.
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.
Provide a text description of the visualization. This also determines the aria-label attribute for accessibility purposes.
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 )
]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.
Disable ARIA attributes when generating SVG output. Default is that Aria is enabled.
Description to be provided in ARIA tag when generating SVG output. If not specified, the an auto-generated description will be provided.
Types that are not specified directly, provided here for reference with links to the functions that generate them.
Generated by anStart, anMiddle, anEnd and anchorSignal.
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.
Generated by bmNormal, bmMultiply, bmScreen, bmOverlay, bmDarken, bmLighten, bmColorDodge, bmColorBurn, bmHardLight, bmSoftLight, bmDifference, bmExclusion, bmHue, bmSaturation, bmColor and bmLuminosity.
Generated by cfeBind, cfeDefaults, cfeGlobalCursor cfeSelector, cfeTimer, cfeView and cfeWindow.
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.
Generated by cpPattern, cpCase, cpStopwords and cpAs.
Generated by functions that start with cu.
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)) ]
]A single column of data. Generated when creating inline data with dataColumn.
A single table of data (collection of dataColumn specifications).
Generated by data, dataFromColumns,
dataFromRows, on and transform.
Generated by dnExtent, dnMethod, dnSteps dnMinSteps, dnMaxSteps and dnAs.
Generated by esObject, esSelector, esSignal and esMerge.
Generated by esSource, esType, esBetween, esConsume, esFilter, esDebounce, esMarkName, esMark, esThrottle and esStream.
Generated by etClick, etDblClick, etDragEnter, etDragLeave, etDragOver, etKeyDown, etKeyPress, etKeyUp, etMouseDown, etMouseMove, etMouseOut, etMouseOver, etMouseUp, etMouseWheel, etTouchEnd, etTouchMove, etTouchStart, etWheel and etTimer.
Generated by faAggregate, faField and faGroupBy.
Generated by featureSignal and feName.
Generated by fpDistance, fpDistanceMax, fpDistanceMin, fpId, fpIterations, fpStrength and fpTheta.
Generated by fsAlpha, fsAlphaMin, fsAlphaTarget, fsAs, fsForces, fsIterations, fsRestart, fsStatic and fsVelocityDecay.
Generated by csv, tsv, dsv, arrow, json, jsonProperty, topojsonFeature, topojsonMesh, topojsonMeshExterior, topojsonMeshInterior, parse, parseAuto and fpSignal.
Generated by gpField, gpAs and gpPointRadius.
Generated by grField, grExtent, grExtentMajor, grExtentMinor, grStep, grStepMajor, grStepMinor and grPrecision.
Generated by grAlignAll, grAlignEach, grAlignNone, grAlignRow, grAlignColumn and grAlignSignal.
Generated by imByMin, imByMax, imByMean, imByMedian and imByValue.
Generated by inDebounce, inElement, inOptions, inLabels, inMin, inMax, inStep, inPlaceholder and inAutocomplete.
Generated by icField, icThresholds, icLevels, icNice, icResolve, icZero, icSmooth, icScale, icTranslate and icAs.
Generated by kdGroupBy, kdCumulative, kdCounts, kdBandwidth, kdExtent, kdMinSteps, kdMaxSteps, kdResolve, kdSteps and kdAs.
Generated by kd2dGroupBy, kd2Weight, kd2CellSize, kd2Bandwidth, kd2Counts and kd2As.
Generated by loAlign, loBounds, loColumns, loPadding, loPaddingRC, loOffset, loOffsetRC, loHeaderBand, loHeaderBandRC, loFooterBand, loFooterBandRC, loTitleBand and loTitleBandRC.
Generated by enLegend, enTitle, enLabels, enSymbols and enGradient.
Generated by loLeft, loTopLeft, loTop, loTopRight, loRight, loBottomRight, loBottom, loBottomLeft, loNone and loSignal.
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.
Generated by ltSymbol, ltGradient and ltSignal.
Generated by lsLine, lsArc, lsCurve, lsDiagonal, lsOrthogonal and lsSignal.
Generated by loDecimal, loThousands, loGrouping, loCurrency, loNumerals, loPercent, loMinus, loNan, loDateTime, loDate, loTime, loPeriods, loDays, loShortDays, loMonths and loShortMonths.
Generated by lsGroupBy, lsBandwidth and lsAs.
Generated by miBasis, miBundle, miCardinal, miCatmullRom, miLinear, miMonotone, miNatural, miStepwise, miStepAfter and miStepBefore.
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.
Generated by ascend, descend and orderSignal.
Generated by orHorizontal, orVertical, orRadial and orSignal.
Generated by piField, piStartAngle, piEndAngle, piSort and piAs.
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.
Generated by reShared, reIndependent and resolveSignal.
Generated by scLinear, scPow, scSqrt, scLog, scSymLog, scTime, scUtc, scOrdinal, scBand, scPoint, scBinOrdinal, scQuantile, scQuantize,scThreshold, scCustom and scSignal.
Generated by niTrue, niFalse, niMillisecond, niSecond, niMinute, niHour, niDay, niWeek, niMonth, niYear, niTickCount, niInterval and niSignal.
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.
Generated by sbAny, sbContainer and sbNone.
Generated by siName, siBind, siDescription, siInit, siOn, siUpdate, siReact, siValue and siPushOuter.
Generated by soAscending, soDescending, soOp, soByField and soSignal.
A Vega specification. Specs can be (and usually are) nested. They can range from a single Boolean value up to the entire Vega specification.
Generated by spArchimedean, spRectangular and spSignal.
Generated by stZero, stCenter, stNormaize and stOffset.
Generated by symCircle, symSquare, symCross, symWedge, symArrow, symStroke, symDiamond, symTriangle, symTriangleUp, symTriangleDown, symTriangleLeft, symTriangleRight, symPath and symSignal.
Generated by tdLeftToRight, tdRightToLeft and tdSignal.
Generated by tbUnits,tbStep, tbTimezone, tbInterval, tbExtent, tbMaxBins, tbSignal and tbAs.
Generated by teTitle, teSubtitle and teGroup.
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.
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, trLinkPath, trLookup, trNest, trPack, trPartition, trPie, trPivot, trProject, trResolveFilter, trSample, trSequence, trStack, trStratify, trTree, trTreeLinks, trTreemap, trVoronoi, trWindow and trWordCloud.
Generated by tmSquarify, tmResquarify, tmBinary, tmDice, tmSlice, tmSliceDice and tmSignal.
Generated by tmField, tmSort, tmMethod, tmPadding, tmPaddingInner, tmPaddingOuter, tmPaddingTop, tmPaddingRight, tmPaddingBottom, tmPaddingLeft, tmRatio, tmRound, tmSize and tmAs.
Generated by teField, teSort, teMethod, teSeparation, teSize, teNodeSize and teAs.
Generated by tgInsert, tgRemove, tgRemoveAll, tgToggle and tgModifyValues.
Generated by vaTop, vaMiddle, vaBottom, vaLineTop, vaLineBottom, vaAlphabetic and vaSignal.
Generated by wnOperation, wnOperationOn and wnAggOperation.
Generated by wnSort, wnGroupBy, wnFrame and wnIgnorePeers.
Generated by woRowNumber, woRank, woDenseRank, woPercentRank, woCumeDist, woPercentile, woLag, woLead, woFirstValue, woLastValue, woNthValue woPrevValue, woNextValue and woSignal.
Generated by wcFont, wcFontStyle, wcFontWeight, wcFontSize, wcFontSizeRange, wcPadding, wcRotate, wcText, wcSize, wcSprial and wcAs.
Deprecated in favour of cfEventHandling. For example, instead of
cfEvents cfDeny [ etMouseMove, etMouseOver ]use
cfEventHandling [ cfeDefaults cfDeny [ etMouseMove, etMouseOver ] ]Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.
Kernel density estimation bandwidth used in a contour transformation.
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.
Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.
Size of cells used for density estimation in a contour transformation.
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.
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.
Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.
Explicit contour values to be generated by a contour transformation.
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.
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.
Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.
X-coordinate field used for density estimation in a contour transformation.
Deprecated in favour of IsocontourProperty generating functions for use with trIsocontour.
Y-coordinate field used for density estimation in a contour transformation.
Deprecated in favour of IsocontourProperty for use with trIsocontour.
Deprecated: in favour of scLinear.
Deprecated in favour of tiEncodeElements.
Deprecated in favour of tiEncodeElements.
Deprecated in favour of tiEncodeElements.
Deprecated in favour of tiEncodeElements.
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.
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.
dsfor the data source,scfor scales,sifor signals,axfor axes etc.) and construct a list of them. For example,