VegaFusion

https://vegafusion.io/
Admin
VegaFusion provides Rust, Python, and JavaScript libraries for analyzing, accelerating, and scaling...
Tokens:27,144
Snippets:350
Trust Score:7.4
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install VegaFusion Server

Source: https://vegafusion.io/_sources/features/grpc.md.txt

Install the VegaFusion server executable from source using Cargo.

```bash
cargo install vegafusion-server
```

--------------------------------

### Install VegaFusion Server

Source: https://vegafusion.io/features/grpc.html

Install the VegaFusion server executable using cargo. This command compiles and installs the vegafusion-server binary.

```bash
cargo install vegafusion-server

```

--------------------------------

### Launch VegaFusion Server

Source: https://vegafusion.io/_sources/features/grpc.md.txt

Start the server instance on a specified port.

```bash
vegafusion-server --port 50051
```

--------------------------------

### Install VegaFusion Jupyter package

Source: https://vegafusion.io/_sources/posts/2022/2022-01-27_ProjectAnnouncement.md.txt

Install the necessary package and datasets to enable VegaFusion in Jupyter.

```bash
$ pip install "vegafusion-jupyter[embed]" vega-datasets
```

--------------------------------

### Install VegaFusion with embed extras

Source: https://vegafusion.io/_sources/posts/2023/2023-01-21_Release_1.0.0.md.txt

Install the package using pip to enable the mime renderer functionality.

```bash
pip install -U "vegafusion[embed]"
```

--------------------------------

### Install VegaFusion via pip

Source: https://vegafusion.io/index.html

Use this command to install the VegaFusion package in a standard Python environment.

```bash
pip install vegafusion
```

--------------------------------

### Full Example: Altair Chart with DuckDB Table

Source: https://vegafusion.io/_sources/posts/2023/2023-03-25_Release_1.1.0.md.txt

Demonstrates setting up a DuckDB connection, registering a table, and creating an Altair chart that references the DuckDB table using the 'table://' prefix.

```python
import duckdb
import vegafusion as vf
import pandas as pd
import altair as alt

# Create DuckDB connection
conn = duckdb.connect()

# Pass DuckDB connection to VegaFusion's set_connection method
vf.runtime.set_connection(conn)

# Enable Mime Renderer
vf.enable()

# Read parquet file using the DuckDB connection
relation = conn.read_parquet(
    "https://vegafusion-datasets.s3.amazonaws.com/vega/movies_201k.parquet"
)

# Filter NULL values and register the result as a table named "movies"
relation.query("tbl", """
    SELECT * FROM tbl 
    WHERE Rotten_Tomatoes_Rating IS NOT NULL AND Imdb_Rating IS NOT NULL
""").to_table("movies")

# Create an Altair chart that references the registered DuckDB table
chart = alt.Chart("table://movies").mark_rect().encode(
    alt.X('IMDB_Rating:Q', bin=alt.Bin(maxbins=60)),
    alt.Y('Rotten_Tomatoes_Rating:Q', bin=alt.Bin(maxbins=40)),
    alt.Color('count():Q', scale=alt.Scale(scheme='greenblue'))
)
chart
```

--------------------------------

### Install VegaFusion via conda

Source: https://vegafusion.io/index.html

Use this command to install the VegaFusion package from the conda-forge channel.

```bash
conda install -c conda-forge vegafusion
```

--------------------------------

### Create a Compound Altair Chart

Source: https://vegafusion.io/posts/2023/2023-06-10_Release_1.3.0.html

This example demonstrates creating a compound chart by combining a bar mark and a rule mark. Compound charts are now supported by `vf.transformed_data`.

```python
source = data.movies.url

base = alt.Chart(source)

bar = base.mark_bar().encode(
    alt.X('IMDB_Rating:Q').bin().axis(None),
    y='count()'
)

rule = base.mark_rule(color='red').encode(
    x='mean(IMDB_Rating):Q',
    size=alt.value(5)
)

chart = bar + rule
chart
```

--------------------------------

### Load Data Source with Altair

Source: https://vegafusion.io/_sources/posts/2023/2023-01-21_Release_1.0.0.md.txt

Initializes an Altair chart with a data source URL. This is the starting point for many vegafusion data transformations.

```python
import altair as alt
import vegafusion as vf

source = "https://cdn.jsdelivr.net/npm/vega-datasets@v1.29.0/data/movies.json"
chart = alt.Chart(source)
```

--------------------------------

### Create an Altair histogram with large dataset

Source: https://vegafusion.io/_sources/posts/2023/2023-01-21_Release_1.0.0.md.txt

Example of loading a large dataset and attempting to plot it with Altair, which triggers a MaxRowsError.

```python
import pandas as pd
import altair as alt

flights = pd.read_parquet(
    "https://vegafusion-datasets.s3.amazonaws.com/vega/flights_1m.parquet"
)

delay_hist = alt.Chart(flights).mark_bar().encode(
    alt.X("delay", bin=alt.Bin(maxbins=30)),
    alt.Y("count()")
)
delay_hist
```

--------------------------------

### Load Data and Create Scatter Plot

Source: https://vegafusion.io/posts/2023/2023-04-12_Release_1.2.0.html

Loads the movies dataset and creates a scatter plot using Altair. This example demonstrates saving unaggregated charts with VegaFusion.

```python
import vegafusion as vf
import altair as alt
from vega_datasets import data

source = data.movies()

scatter_chart = alt.Chart(source).mark_point().encode(
    alt.X("IMDB_Rating:Q"),
    alt.Y("Rotten_Tomatoes_Rating:Q"),
)
scatter_chart
```

--------------------------------

### Define Inline Dataset in Vega Specification

Source: https://vegafusion.io/_sources/features/inline_datasets.md.txt

Example of referencing an inline dataset named 'movies' within a Vega specification using the vegafusion+dataset:// protocol.

```json
{
  ...
  "data": [
    {
      "name": "source0",
      "url": "vegafusion+dataset://movies",
      "transform": [
        ...
      ]
    }
  ],
  ...
}
```

--------------------------------

### Construct a VegaFusionWidget

Source: https://vegafusion.io/_sources/features/jupyter_widget.md.txt

Initialize a widget by passing a Vega specification dictionary. Ensure the input is a valid Vega spec, as Vega-Lite is not supported.

```python
import vegafusion as vf
import json
from vegafusion.jupyter import VegaFusionWidget

vega_spec = json.loads(r"""
{
  "$schema": "https://vega.github.io/schema/vega/v5.json",
  "description": "A binned scatter plot example showing aggregate counts per binned cell.",
  "width": 200,
  "height": 200,
  "padding": 5,
  "autosize": "pad",

  "data": [
    {
      "name": "source",
      "url": "data/cars.json",
      "transform": [
        {
          "type": "filter",
          "expr": "datum['Horsepower'] != null && datum['Miles_per_Gallon'] != null && datum['Acceleration'] != null"
        }
      ]
    },
    {
      "name": "summary",
      "source": "source",
      "transform": [
        {
          "type": "extent", "field": "Horsepower",
          "signal": "hp_extent"
        },
        {
          "type": "bin", "field": "Horsepower", "maxbins": 10,
          "extent": {"signal": "hp_extent"},
          "as": ["hp0", "hp1"]
        },
        {
          "type": "extent", "field": "Miles_per_Gallon",
          "signal": "mpg_extent"
        },
        {
          "type": "bin", "field": "Miles_per_Gallon", "maxbins": 10,
          "extent": {"signal": "mpg_extent"},
          "as": ["mpg0", "mpg1"]
        },
        {
          "type": "aggregate",
          "groupby": ["hp0", "hp1", "mpg0", "mpg1"]
        }
      ]
    }
  ],

  "scales": [
    {
      "name": "x",
      "type": "linear",
      "round": true,
      "nice": true,
      "zero": true,
      "domain": {"data": "source", "field": "Horsepower"},
      "range": "width"
    },
    {
      "name": "y",
      "type": "linear",
      "round": true,
      "nice": true,
      "zero": true,
      "domain": {"data": "source", "field": "Miles_per_Gallon"},
      "range": "height"
    },
    {
      "name": "size",
      "type": "linear",
      "zero": true,
      "domain": {"data": "summary", "field": "count"},
      "range": [0,360]
    }
  ],

  "axes": [
    {
      "scale": "x",
      "grid": true,
      "domain": false,
      "orient": "bottom",
      "tickCount": 5,
      "title": "Horsepower"
    },
    {
      "scale": "y",
      "grid": true,
      "domain": false,
      "orient": "left",
      "titlePadding": 5,
      "title": "Miles_per_Gallon"
    }
  ],

  "legends": [
    {
      "size": "size",
      "title": "Count",
      "format": "s",
      "symbolFillColor": "#4682b4",
      "symbolStrokeColor": "transparent",
      "symbolType": "circle"
    }
  ],

  "marks": [
    {
      "name": "marks",
      "type": "symbol",
      "from": {"data": "summary"},
      "encode": {
        "update": {
          "x": {"scale": "x", "signal": "(datum.hp0 + datum.hp1) / 2"},
          "y": {"scale": "y", "signal": "(datum.mpg0 + datum.mpg1) / 2"},
          "size": {"scale": "size", "field": "count"},
          "shape": {"value": "circle"},
          "fill": {"value": "#4682b4"}
        }
      }
    }
  ]
}
""")
VegaFusionWidget(vega_spec)
```

--------------------------------

### Initialize DuckDB Connection for VegaFusion

Source: https://vegafusion.io/_sources/posts/2023/2023-03-25_Release_1.1.0.md.txt

Import the duckdb library and create a new connection. This connection will be passed to VegaFusion to enable access to DuckDB tables.

```python
import duckdb
conn = duckdb.connect()
```

--------------------------------

### VegaFusion with External DuckDB Connection and Altair Chart

Source: https://vegafusion.io/posts/2023/2023-03-25_Release_1.1.0.html

Demonstrates setting up VegaFusion with an external DuckDB connection and creating an Altair chart that references a DuckDB table. The chart will use the filtered data from the 'movies' table.

```python
import duckdb
import vegafusion as vf
import pandas as pd
import altair as alt

# Create DuckDB connection
conn = duckdb.connect()

# Pass DuckDB connection to VegaFusion's set_connection method
vf.runtime.set_connection(conn)

```

--------------------------------

### VegaFusionWidget Construction

Source: https://vegafusion.io/features/jupyter_widget.html

Initializes a new VegaFusionWidget instance using a Vega specification dictionary.

```APIDOC
## VegaFusionWidget Constructor

### Description
Constructs a new VegaFusionWidget instance to render a Vega specification. Note that this widget is compatible only with Vega specifications, not Vega-Lite.

### Parameters
- **vega_spec** (dict) - Required - A dictionary representing a valid Vega specification.

### Request Example
```python
from vegafusion.jupyter import VegaFusionWidget
import json

vega_spec = json.loads("{...}")
widget = VegaFusionWidget(vega_spec)
```
```

--------------------------------

### Connect Python Client to Server

Source: https://vegafusion.io/_sources/features/grpc.md.txt

Establish a connection from the Python client to a running VegaFusion Server instance.

```python
import vegafusion as vf
vf.runtime.grpc_connect("http://127.0.0.1:50051")
```

--------------------------------

### Preview Transformed Data

Source: https://vegafusion.io/_sources/posts/2023/2023-01-21_Release_1.0.0.md.txt

Uses `vf.transformed_data()` to get a preview of the data available at the chart's source URL. The `row_limit` argument controls the number of rows returned, and `.T` transposes the DataFrame for easier reading.

```python
vf.transformed_data(chart, row_limit=3).T
```

--------------------------------

### Configure DuckDB for Vega Transforms

Source: https://vegafusion.io/_sources/posts/2023/2023-03-25_Release_1.1.0.md.txt

Sets the runtime connection to DuckDB and demonstrates creating an Altair chart that utilizes DuckDB for binning and aggregation.

```python
import vegafusion as vf
import pandas as pd
import altair as alt

# Configure DuckDB connection
vf.runtime.set_connection("duckdb")

# Enable Mime Renderer
vf.enable()

# Load 201k row version of the Vega movies dataset with pandas
movies = pd.read_parquet(
    "https://vegafusion-datasets.s3.amazonaws.com/vega/movies_201k.parquet"
)

# Create an Altair chart from the pandas DataFrame as usual.
# Binning and aggregation will be evaluated against the DataFrame with DuckDB
chart = alt.Chart(movies).mark_rect().encode(
    alt.X('IMDB_Rating:Q', bin=alt.Bin(maxbins=60)),
    alt.Y('Rotten_Tomatoes_Rating:Q', bin=alt.Bin(maxbins=40)),
    alt.Color('count():Q', scale=alt.Scale(scheme='greenblue'))
)
chart
```

--------------------------------

### Create DuckDB Connection

Source: https://vegafusion.io/posts/2023/2023-03-25_Release_1.1.0.html

Initializes a DuckDB connection object. This connection can then be passed to VegaFusion.

```python
import duckdb
conn = duckdb.connect()

```

--------------------------------

### Enable VegaFusion renderer

Source: https://vegafusion.io/_sources/posts/2022/2022-01-27_ProjectAnnouncement.md.txt

Import and enable the VegaFusion renderer for Altair within a Jupyter notebook.

```python
import vegafusion as vf
vf.jupyter.enable()
```

--------------------------------

### Constants

Source: https://vegafusion.io/vega_coverage/optimized_expressions.html

Overview of optimization support for mathematical and numerical constants.

```APIDOC
## Constants

This section details the optimization support for various constants available in Vega-Lite expressions.

### Constant Support

| Constant | Status | Details |
|---|---|---|
| `NaN` | ✅ | |
| `E` | ✅ | |
| `LN2` | ✅ | |
| `LN10` | ✅ | |
| `LOG2E` | ✅ | |
| `LOG10E` | ✅ | |
| `MAX_VALUE` | ✅ | |
| `MIN_VALUE` | ✅ | |
| `PI` | ✅ | |
| `SQRT1_2` | ✅ | |
| `SQRT2` | ✅ | |
```

--------------------------------

### Enable VegaFusion mime renderer

Source: https://vegafusion.io/_sources/posts/2023/2023-01-21_Release_1.0.0.md.txt

Import and enable the VegaFusion renderer to bypass Altair's default row limits.

```python
import vegafusion as vf
vf.enable()
```

--------------------------------

### Enable VegaFusion for Altair Charts

Source: https://vegafusion.io/posts/2023/2023-06-10_Release_1.3.0.html

Call `vf.enable()` to enable VegaFusion processing for Altair charts. This should be done before creating charts that will utilize VegaFusion.

```python
import altair as alt
import vegafusion as vf
from vega_datasets import data

vf.enable()
```

--------------------------------

### Enable VegaFusion and Create Bar Chart

Source: https://vegafusion.io/_sources/posts/2023/2023-01-21_Release_1.0.0.md.txt

Enables VegaFusion and creates a bar chart showing the mean worldwide gross by director, ranking the top directors and grouping others. Requires the vega-datasets and vegafusion libraries.

```python
import altair as alt
import vegafusion as vf

vf.enable()

source = "https://cdn.jsdelivr.net/npm/vega-datasets@v1.29.0/data/movies.json"
chart = (
    alt.Chart(source)
    .transform_aggregate(
        aggregate_gross='mean(Worldwide_Gross)',
        groupby=["Director"],
    ).transform_window(
        rank='row_number()',
        sort=[alt.SortField("aggregate_gross", order="descending")],
    ).transform_calculate(
        ranked_director="datum.rank < 10 ? datum.Director : 'All Others'"
    ).mark_bar().encode(
        x=alt.X("aggregate_gross:Q", aggregate="mean", title=None),
        y=alt.Y(
            "ranked_director:N",
            sort=alt.Sort(op="mean", field="aggregate_gross", order="descending"),
            title=None,
        ),
    )
)
chart
```

--------------------------------

### Math Functions

Source: https://vegafusion.io/vega_coverage/optimized_expressions.html

Overview of optimization support for various mathematical functions.

```APIDOC
## Math Functions

This section details the optimization support for mathematical functions in Vega-Lite expressions.

### Function Support

| Function | Status | Details |
|---|---|---|
| `isNaN(value)` | ✅ | |
| `isFinite(value)` | ✅ | |
| `abs(value)` | ✅ | |
| `acos(value)` | ✅ | |
| `asin(value)` | ✅ | |
| `atan(value)` | ✅ | |
| `atan2(dy, dx)` | ❌ | |
| `ceil(value)` | ✅ | |
| `clamp(value, min, max)` | ❌ | |
| `cos(value)` | ✅ | |
| `exp(exponent)` | ✅ | |
| `floor(value)` | ✅ | |
| `hypot(value)` | ❌ | |
| `log(value)` | ✅ | |
| `max(value1, value2, …)` | ❌ | |
| `min(value1, value2, …)` | ❌ | |
| `pow(value, exponent)` | ✅ | |
| `random()` | ❌ | |
| `round(value)` | ✅ | |
| `sin(value)` | ✅ | |
| `sqrt(value)` | ✅ | |
| `tan(value)` | ✅ | |
```

--------------------------------

### Enable VegaFusion Mime Renderer

Source: https://vegafusion.io/_sources/posts/2023/2023-04-12_Release_1.2.0.md.txt

Enable the VegaFusion Mime Renderer for improved chart performance. This is typically done at the beginning of your script.

```python
import pandas as pd
import altair as alt
import vegafusion as vf
vf.enable()
```

--------------------------------

### Date-Time Functions

Source: https://vegafusion.io/vega_coverage/optimized_expressions.html

Overview of optimization support for date and time manipulation functions.

```APIDOC
## Date-Time Functions

This section details the optimization support for date and time functions in Vega-Lite expressions.

### Function Support

| Function | Status | Details |
|---|---|---|
| `now()` | ❌ | |
| `datetime(year, month[, day, hour, min, sec, millisec])` | ✅ | |
| `date(datetime)` | ✅ | |
| `day(datetime)` | ✅ | |
| `dayofyear(datetime)` | ✅ | |
| `year(datetime)` | ✅ | |
| `quarter(datetime)` | ✅ | |
| `month(datetime)` | ✅ | |
| `week(datetime)` | ❌ | |
| `hours(datetime)` | ✅ | |
| `minutes(datetime)` | ✅ | |
| `seconds(datetime)` | ✅ | |
| `milliseconds(datetime)` | ✅ | |
| `time(datetime)` | ✅ | |
| `timezoneoffset(datetime)` | ❌ | |
| `timeOffset(unit, date[, step])` | ✅ | |
| `timeSequence(unit, start, stop[, step])` | ❌ | |
| `utc(year, month[, day, hour, min, sec, millisec])` | ✅ | |
| `utcdate(datetime)` | ✅ | |
| `utcday(datetime)` | ✅ | |
| `utcdayofyear(datetime)` | ✅ | |
| `utcyear(datetime)` | ✅ | |
| `utcquarter(datetime)` | ✅ | |
| `utcmonth(datetime)` | ✅ | |
| `utcweek(datetime)` | ❌ | |
| `utchours(datetime)` | ✅ | |
| `utcminutes(datetime)` | ✅ | |
| `utcseconds(datetime)` | ✅ | |
| `utcmilliseconds(datetime)` | ✅ | |
| `utcOffset(unit, date[, step])` | ❌ | |
| `utcSequence(unit, start, stop[, step])` | ❌ | |
```

--------------------------------

### Create an accelerated Altair chart

Source: https://vegafusion.io/_sources/posts/2022/2022-01-27_ProjectAnnouncement.md.txt

Define an interactive Altair chart that utilizes VegaFusion for server-side processing.

```python
import altair as alt
from vega_datasets import data

source = data.seattle_weather()
brush = alt.selection(type='interval', encodings=['x'])

bars = alt.Chart().mark_bar().encode(
    x='month(date):O',
    y='mean(precipitation):Q',
    opacity=alt.condition(brush, alt.OpacityValue(1), alt.OpacityValue(0.7)),
).add_selection(
    brush
)

line = alt.Chart().mark_rule(color='firebrick').encode(
    y='mean(precipitation):Q',
    size=alt.SizeValue(3)
).transform_filter(
    brush
)

chart = alt.layer(bars, line, data=source)
chart
```

--------------------------------

### Construct a new ChartState object

Source: https://vegafusion.io/features/chart_state.html

Initializes a ChartState instance with a Vega specification and optional configuration for timezones, row limits, and inline datasets.

```python
VegaFusionRuntime.new_chart_state(_spec : dict[str, Any] | str_, _local_tz : str | None = None_, _default_input_tz : str | None = None_, _row_limit : int | None = None_, _inline_datasets : dict[str, Any] | None = None_) → ChartState
```

--------------------------------

### Create Histogram Chart

Source: https://vegafusion.io/_sources/posts/2023/2023-04-12_Release_1.2.0.md.txt

Create a histogram chart using Altair, visualizing the distribution of flight delays from a large dataset.

```python
delay_hist = alt.Chart(flights).mark_bar().encode(
    alt.X("delay", bin=alt.Bin(maxbins=30)),
    alt.Y("count()")
)
```

--------------------------------

### Basic Transforms

Source: https://vegafusion.io/_sources/vega_coverage/optimized_transforms.md.txt

Overview of basic transforms, their support status, and specific details regarding their implementation.

```APIDOC
## Basic Transforms

This section details the basic transforms available in Vega-Lite, their support status, and specific implementation notes.

### aggregate

- **Status**: Partially Supported (🟡)
- **Details**: Supported aggregate `ops`: `count`, `valid`, `missing`, `distinct`, `sum`, `mean` or `average`, `variance`, `variancep`, `stdev`, `stdevp`, `median`, `q1`, `q3`, `min`, `max`. Unsupported aggregate `ops`: `product`, `ci0`, `ci1`, `stderr`, `argmin`, `argmax`. The `cross`, `drop`, and `key` options are not yet supported.

### formula

- **Status**: Supported (✅)
- **Details**: See [optimized expressions](./optimized_expressions.md) for details on supported expression features that may be used in the `expr` field.

### window

- **Status**: Partially Supported (🟡)
- **Details**: Supported window operations: Ranking operations (`row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`), Value operations (`first_value`, `last_value`), and all supported aggregate transform ops. Not yet supported: `ntile`, `lag`/`lead`, `nth_value`, `prev_value`/`next_value`. All frame specifications and peer handling options are supported.

### lookup

- **Status**: Unsupported (❌)

### bin

- **Status**: Supported (✅)
- **Details**: `interval` option ignored and both bin edges are always included.

### collect

- **Status**: Supported (✅)

### extent

- **Status**: Supported (✅)

### filter

- **Status**: Supported (✅)
- **Details**: See [optimized expressions](./optimized_expressions.md) for details on supported expression features that may be used in the `expr` field.

### flatten

- **Status**: Unsupported (❌)
- **Details**: May be possible in the future with DataFusion's [unnest](https://github.com/apache/datafusion/pull/10044) transform.

### fold

- **Status**: Supported (✅)

### project

- **Status**: Supported (✅)

### sequence

- **Status**: Supported (✅)

### timeunit

- **Status**: Partially Supported (🟡)
- **Details**: `interval` option ignored and both bin edges are always included. `step`, `extent`, and `maxbins` options are not supported, so `units` must be provided.

### countpattern

- **Status**: Unsupported (❌)

### cross

- **Status**: Unsupported (❌)

### density

- **Status**: Unsupported (❌)

### dotbin

- **Status**: Unsupported (❌)

### identifier

- **Status**: Supported (✅)

### impute

- **Status**: Partially Supported (🟡)
- **Details**: Supported: `field` (Field to impute), `key` (Unique identifier field), `value` (Custom value for imputation), `groupby` (Group-based imputation). Unsupported: `method` parameter with options other than `value`, `keyvals` array for custom key values.

### kde

- **Status**: Unsupported (❌)

### loess

- **Status**: Unsupported (❌)

### pivot

- **Status**: Supported (✅)

### quantile

- **Status**: Unsupported (❌)

### regression

- **Status**: Unsupported (❌)

### sample

- **Status**: Unsupported (❌)

```

--------------------------------

### Display the chart after enabling VegaFusion

Source: https://vegafusion.io/posts/2023/2023-01-21_Release_1.0.0.html

Render the previously defined chart after the VegaFusion renderer is enabled.

```python
delay_hist
```

--------------------------------

### pre_transform_datasets (Python)

Source: https://vegafusion.io/_sources/features/transform_data.md.txt

Evaluates datasets in a Vega specification and returns them as Arrow tables or DataFrames.

```APIDOC
## Python: pre_transform_datasets

### Description
Evaluates datasets in a Vega spec and returns them as arrow tables or DataFrames.

### Method
Method call: vegafusion.runtime.VegaFusionRuntime.pre_transform_datasets
```

--------------------------------

### Selection Functions

Source: https://vegafusion.io/_sources/vega_coverage/optimized_expressions.md.txt

Private functions used by Vega-Lite for implementing selections.

```APIDOC
## Selection Functions

### `vlSelectionTest`

**Status**: ✅

### `vlSelectionResolve`

**Status**: ✅
```

--------------------------------

### Core Language Features

Source: https://vegafusion.io/vega_coverage/optimized_expressions.html

Details on the optimization support for core arithmetic, logical, and structural expression features.

```APIDOC
## Core Language Features

This section details the optimization support for core language features in Vega-Lite expressions.

### Feature Support

| Feature | Status | Details |
|---|---|---|
| `a + b` | ✅ | |
| `a - b` | ✅ | |
| `a * b` | ✅ | |
| `a / b` | ✅ | |
| `a % b` | ✅ | |
| `-a` | ✅ | |
| `+a` | ✅ | |
| `a == b` | ✅ | |
| `a != b` | ✅ | |
| `a < b` | ✅ | |
| `a > b` | ✅ | |
| `a <= b` | ✅ | |
| `a >= b` | ✅ | |
| `a && b` | ✅ | |
| `a || b` | ✅ | |
| `!a` | ✅ | |
| `a ? b : c` | ✅ | |
| `{a: 1, b: 2}` | ✅ | |
| `[1, 2, 3]` | ✅ | |
| `a.b` | ✅ | |
| `a["b"]` | ✅ | |
```

--------------------------------

### Connect Python Client to VegaFusion Server

Source: https://vegafusion.io/features/grpc.html

Connect a Python client to a running VegaFusion Server instance. This method dispatches all VegaFusion runtime operations to the server.

```python
import vegafusion as vf
vf.runtime.grpc_connect("http://127.0.0.1:50051")

```

--------------------------------

### Statistical Functions

Source: https://vegafusion.io/vega_coverage/optimized_expressions.html

Information on optimization support for statistical functions, including normal and uniform distributions.

```APIDOC
## Statistical Functions

This section details the optimization support for statistical functions in Vega-Lite expressions.

### Function Support

| Function | Status | Details |
|---|---|---|
| `sampleNormal([mean, stdev])` | ❌ | |
| `cumulativeNormal(value[, mean, stdev])` | ❌ | |
| `densityNormal(value[, mean, stdev])` | ❌ | |
| `quantileNormal(probability[, mean, stdev])` | ❌ | |
| `sampleLogNormal([mean, stdev])` | ❌ | |
| `cumulativeLogNormal(value[, mean, stdev])` | ❌ | |
| `densityLogNormal(value[, mean, stdev])` | ❌ | |
| `quantileLogNormal(probability[, mean, stdev])` | ❌ | |
| `sampleUniform([min, max])` | ❌ | |
| `cumulativeUniform(value[, min, max])` | ❌ | |
| `densityUniform(value[, min, max])` | ❌ | |
| `quantileUniform(probability[, min, max])` | ❌ | |
```

--------------------------------

### Configure DuckDB Connection for VegaFusion

Source: https://vegafusion.io/posts/2023/2023-03-25_Release_1.1.0.html

Use this to enable DuckDB for evaluating Vega transforms on pandas DataFrames. Ensure VegaFusion Mime Renderer is enabled for performance benefits.

```python
import vegafusion as vf
import pandas as pd
import altair as alt

# Configure DuckDB connection
vf.runtime.set_connection("duckdb")

# Enable Mime Renderer
vf.enable()

# Load 201k row version of the Vega movies dataset with pandas
movies = pd.read_parquet(
    "https://vegafusion-datasets.s3.amazonaws.com/vega/movies_201k.parquet"
)

# Create an Altair chart from the pandas DataFrame as usual.
# Binning and aggregation will be evaluated against the DataFrame with DuckDB
chart = alt.Chart(movies).mark_rect().encode(
    alt.X('IMDB_Rating:Q', bin=alt.Bin(maxbins=60)),
    alt.Y('Rotten_Tomatoes_Rating:Q', bin=alt.Bin(maxbins=40)),
    alt.Color('count():Q', scale=alt.Scale(scheme='greenblue'))
)
chart

```

--------------------------------

### Create Boxplot with Vega-Altair

Source: https://vegafusion.io/_sources/posts/2023/2023-08-21_Release_1.4.0.md.txt

Generates a boxplot using Vega-Altair, demonstrating support for q1/q3 aggregation functions. Ensure vegafusion is enabled.

```python
import altair as alt
from vega_datasets import data
import vegafusion as vf
vf.enable()

source = data.cars()

chart = alt.Chart(source).mark_boxplot(extent="min-max").encode(
    alt.X("Miles_per_Gallon:Q").scale(zero=False),
    alt.Y("Origin:N"),
)
chart
```

--------------------------------

### Enable Mime Renderer with DuckDB

Source: https://vegafusion.io/posts/2023/2023-03-25_Release_1.1.0.html

Enables the Mime Renderer and reads a parquet file using a DuckDB connection. Filters NULL values and registers the result as a table named 'movies'.

```python
vf.enable()

# Read parquet file using the DuckDB connection
relation = conn.read_parquet(
    "https://vegafusion-datasets.s3.amazonaws.com/vega/movies_201k.parquet"
)

# Filter NULL values and register the result as a table named "movies"
relation.query("tbl", """
    SELECT * FROM tbl 
    WHERE Rotten_Tomatoes_Rating IS NOT NULL AND Imdb_Rating IS NOT NULL
""").to_table("movies")

# Create an Altair chart that references the registered DuckDB table
chart = alt.Chart("table://movies").mark_rect().encode(
    alt.X('IMDB_Rating:Q', bin=alt.Bin(maxbins=60)),
    alt.Y('Rotten_Tomatoes_Rating:Q', bin=alt.Bin(maxbins=40)),
    alt.Color('count():Q', scale=alt.Scale(scheme='greenblue'))
)
chart
```

--------------------------------

### Set DuckDB Connection in VegaFusion

Source: https://vegafusion.io/_sources/posts/2023/2023-03-25_Release_1.1.0.md.txt

Pass the created DuckDB connection object to `vegafusion.runtime.set_connection` to configure VegaFusion to use this connection.

```python
vf.runtime.set_connection(conn)
```

--------------------------------

### Enable VegaFusion Mime Renderer

Source: https://vegafusion.io/posts/2023/2023-04-12_Release_1.2.0.html

Enable the VegaFusion Mime Renderer for Altair charts. This is a prerequisite for using VegaFusion's optimized saving functions.

```python
import pandas as pd
import altair as alt
import vegafusion as vf
vf.enable()

flights = pd.read_parquet(
    "https://vegafusion-datasets.s3.amazonaws.com/vega/flights_1m.parquet"
)

delay_hist = alt.Chart(flights).mark_bar().encode(
    alt.X("delay", bin=alt.Bin(maxbins=30)),
    alt.Y("count()")
)
delay_hist
```

--------------------------------

### Array Functions

Source: https://vegafusion.io/vega_coverage/optimized_expressions.html

Information on optimization support for array manipulation functions.

```APIDOC
## Array Functions

This section details the optimization support for array functions in Vega-Lite expressions.

### Function Support

| Function | Status | Details |
|---|---|---|
| `extent(array)` | ❌ | |
| `clampRange(range, min, max)` | ❌ | |
| `indexof(array, value)` | ✅ | |
| `inrange(value, range)` | ❌ | |
| `join(array[, separator])` | ❌ | |
| `lastindexof(array, value)` | ❌ | |
| `length(array)` | ✅ | |
| `lerp(array, fraction)` | ❌ | |
| `peek(array)` | ❌ | |
| `pluck(array, field)` | ❌ | |
| `reverse(array)` | ❌ | |
| `sequence([start, ]stop[, step])` | ❌ | |
| `slice(array, start[, end])` | ❌ | |
| `sort(array)` | ❌ | |
| `span(array)` | ✅ | |
```

--------------------------------

### Bound Variables

Source: https://vegafusion.io/vega_coverage/optimized_expressions.html

Information on the optimization support for various bound variables within expressions.

```APIDOC
## Bound Variables

This section details the optimization support for bound variables available within Vega-Lite expressions.

### Variable Support

| Variable | Status | Details |
|---|---|---|
| `datum` | ✅ | |
| `event` | ❌ | |
| `item` | ❌ | |
| `parent` | ❌ | |
| Signal Names | ✅ | |
```

--------------------------------

### Load Movies Dataset

Source: https://vegafusion.io/_sources/posts/2023/2023-04-12_Release_1.2.0.md.txt

Load the movies dataset from vega_datasets, which contains 3201 rows and 16 columns. This dataset is used for demonstrating scatter plot performance.

```python
import vegafusion as vf
import altair as alt
from vega_datasets import data

source = data.movies()
```

--------------------------------

### Python: VegaFusionRuntime.pre_transform_spec

Source: https://vegafusion.io/features/transform_spec.html

Evaluates supported transforms in an input Vega specification and returns a new specification with pre-transformed datasets included inline.

```APIDOC
## POST VegaFusionRuntime.pre_transform_spec

### Description
Evaluates supported transforms in an input Vega specification, producing a new specification with pre-transformed datasets included inline.

### Parameters
#### Request Body
- **spec** (dict[str, Any] | str) - Required - A Vega specification dict or JSON string.
- **local_tz** (str) - Optional - Name of timezone to be considered local.
- **default_input_tz** (str) - Optional - Name of timezone that naive datetime strings should be interpreted in.
- **row_limit** (int) - Optional - Maximum number of dataset rows to include.
- **preserve_interactivity** (bool) - Optional - If True, preserves interactive behavior of the chart.
- **inline_datasets** (dict[str, Any]) - Optional - A dict from dataset names to pandas DataFrames or pyarrow Tables.
- **keep_signals** (list[str | tuple[str, list[int]]]) - Optional - Signals from the input spec to include.
- **keep_datasets** (list[str | tuple[str, list[int]]]) - Optional - Datasets from the input spec to include.

### Response
#### Success Response (200)
- **result** (tuple[dict[str, Any], list[PreTransformWarning]]) - A tuple containing the transformed Vega specification and a list of warnings.
```

--------------------------------

### VegaFusionWidget Planner Properties

Source: https://vegafusion.io/_sources/features/jupyter_widget.md.txt

The VegaFusionWidget provides several properties to inspect the results of the Vega-Lite planning process. These properties allow developers to understand how the original specification was transformed and partitioned between the client and server.

```APIDOC
## VegaFusionWidget Planner Properties

### Description
Access properties of the `VegaFusionWidget` to view the results of the planner.

### Properties
- `widget.spec` (object) - The original Vega specification provided to the widget.
- `widget.transformed_spec` (object) - The initial Vega specification after being transformed by VegaFusion.
- `widget.server_spec` (object) - The portion of the Vega specification planned to be executed on the server (e.g., Python kernel).
- `widget.client_spec` (object) - The portion of the Vega specification planned to be executed on the client using the Vega JavaScript Library.
- `widget.comm_plan` (object) - The specification detailing which signals and datasets need to be transferred between the client and server to maintain interactive behavior.
```

--------------------------------

### new_chart_state

Source: https://vegafusion.io/_sources/features/chart_state.md.txt

Initializes a new chart state for managing interactive data transformations.

```APIDOC
## new_chart_state

### Description
Creates a new chart state instance within the VegaFusion runtime to support interactive chart updates and transform re-evaluation.

### Method
Python Method

### Endpoint
vegafusion.runtime.VegaFusionRuntime.new_chart_state
```

--------------------------------

### Type Checking Functions

Source: https://vegafusion.io/vega_coverage/optimized_expressions.html

Details on which type-checking functions are supported for optimization.

```APIDOC
## Type Checking Functions

This section details the optimization support for type-checking functions in Vega-Lite expressions.

### Function Support

| Function | Status | Details |
|---|---|---|
| `isArray(value)` | ❌ | |
| `isBoolean(value)` | ❌ | |
| `isDate(value)` | ✅ | |
| `isDefined(value)` | ❌ | |
| `isNumber(value)` | ❌ | |
| `isObject(value)` | ❌ | |
| `isRegExp(value)` | ❌ | |
| `isString(value)` | ❌ | |
| `isValid(value)` | ✅ | |
```

--------------------------------

### Build Altair Chart and Retrieve Transformed Data

Source: https://vegafusion.io/_sources/posts/2023/2023-03-25_Release_1.1.0.md.txt

Construct an Altair chart with aggregations and window transformations, then use VegaFusion to extract the transformed data into a Polars DataFrame. This is useful for inspecting intermediate results or further data processing.

```python
chart = (
    alt.Chart(source)
    .transform_aggregate(
        aggregate_gross='mean(Worldwide_Gross)',
        groupby=["Director"],
    ).transform_window(
        rank='row_number()',
        sort=[alt.SortField("aggregate_gross", order="descending")],
    ).transform_calculate(
        ranked_director="datum.rank < 10 ? datum.Director : 'All Others'"
    ).mark_bar().encode(
        x=alt.X("aggregate_gross:Q", aggregate="mean", title=None),
        y=alt.Y(
            "ranked_director:N",
            sort=alt.Sort(op="mean", field="aggregate_gross", order="descending"),
            title=None,
        ),
    )
).properties(
    title="Top Directors by Average Worldwide Gross",
)
chart
```

```python
transformed = vf.transformed_data(chart)
print(type(transformed))
transformed
```
Tokens:
Raw