Transform Spec#

VegaFusion can be used to evaluate datasets in a Vega spec, remove unused columns, and inline the results in a transformed Vega spec. This transformed Vega spec is self-contained and may be displayed with the standard Vega JavaScript library.

This is the foundation of Vega-Altair’s "vegafusion" data transformer when used with the default HTML or static image renderers.

Warning

The pre-transform process will, by default, preserve the interactive behavior of the input Vega specification. For interactive charts that perform filtering, this may result in the generation of a spec containing the full input dataset. If interactivity does not need to be preserved (e.g. if the resulting chart is used in a static context) then the preserve_interactivity option should be set to False. If interactivity is needed, then the Chart State workflow may be more appropriate.

Python#

VegaFusionRuntime.pre_transform_spec(spec: dict[str, Any] | str, local_tz: str | None = None, default_input_tz: str | None = None, row_limit: int | None = None, preserve_interactivity: bool = True, inline_datasets: dict[str, Any] | None = None, keep_signals: list[str | tuple[str, list[int]]] | None = None, keep_datasets: list[str | tuple[str, list[int]]] | None = None) → tuple[dict[str, Any], list[PreTransformWarning]]#

Evaluate supported transforms in an input Vega specification

Produces a new specification with pre-transformed datasets included inline.

Parameters:

  • spec – A Vega specification dict or JSON string

  • local_tz – Name of timezone to be considered local. E.g. ‘America/New_York’. Defaults to the value of vf.get_local_tz(), which defaults to the system timezone if one can be determined.

  • default_input_tz – Name of timezone (e.g. ‘America/New_York’) that naive datetime strings should be interpreted in. Defaults to local_tz.

  • row_limit – Maximum number of dataset rows to include in the returned specification. If exceeded, datasets will be truncated to this number of rows and a RowLimitExceeded warning will be included in the resulting warnings list

  • preserve_interactivity – If True (default) then the interactive behavior of the chart will be preserved. This requires that all the data that participates in interactions be included in the resulting spec rather than being pre-transformed. If False, then all possible data transformations are applied even if they break the original interactive behavior of the chart.

  • inline_datasets – A dict from dataset names to pandas DataFrames or pyarrow Tables. Inline datasets may be referenced by the input specification using the following url syntax ‘vegafusion+dataset://{dataset_name}’ or ‘table://{dataset_name}’.

  • keep_signals –

    Signals from the input spec that must be included in the pre-transformed spec, even if they are no longer referenced. A list with elements that are either:

    • The name of a top-level signal as a string

    • A two-element tuple where the first element is the name of a signal as a string and the second element is the nested scope of the dataset as a list of integers

  • keep_datasets –

    Datasets from the input spec that must be included in the pre-transformed spec even if they are no longer referenced. A list with elements that are either:

    • The name of a top-level dataset as a string

    • A two-element tuple where the first element is the name of a dataset as a string and the second element is the nested scope of the dataset as a list of integers

Returns:

Two-element tuple of

  • The Vega specification as a dict with pre-transformed datasets included inline

  • A list of warnings as dictionaries. Each warning dict has a 'type' key indicating the warning type, and a 'message' key containing a description of the warning. Potential warning types include:

    • 'RowLimitExceeded': Some datasets in resulting Vega specification have been truncated to the provided row limit

    • 'BrokenInteractivity': Some interactive features may have been broken in the resulting Vega specification

    • 'Unsupported': No transforms in the provided Vega specification were eligible for pre-transforming

Return type:

tuple[dict[str, Any], list[PreTransformWarning]]

Example: See pre_transform_spec.py for a complete example.

Rust#

See pre_transform_spec.rs for a complete example.