ipyvizzu Documentation

When changing multiple dimensions simultaneously (adding and removing dimensions), you can control how markers transition between the current state and the target state using the regroupStrategy parameter in chart.animate().

Available strategies:

• Default (Implicit): Markers are aggregated to the common base of the two states, then drilled down to the target state.
• drilldown: The chart drills down to the union of the two states, then aggregates to the target state.
• fade: The chart fades the markers between the two states.

# Example using 'drilldown' strategy
chart.animate(
    Config(
        {
            "channels": {
                "x": {
                    "detach": ["Genres"],
                    "attach": ["Kinds"],
                },
            }
        }
    ),
    regroupStrategy="drilldown",
)

# Example using 'fade' strategy
chart.animate(
    Config(
        {
            "channels": {
                "x": {
                    "detach": ["Kinds"],
                    "attach": ["Genres"],
                },
            }
        }
    ),
    regroupStrategy="fade",
)

When initializing a Chart, you can specify how and when animations are displayed using the display parameter with DisplayTarget values.

Note: For DisplayTarget.MANUAL, you must switch from the default DataCamp editor to the JupyterLab-style editor for ipyvizzu to work.

Supported DisplayTarget options in DataCamp:

• DisplayTarget.BEGIN: Automatically display all animations after the first cell.
• DisplayTarget.ACTUAL: Automatically display all animations after the currently running cell.
• DisplayTarget.END: Automatically display all animations after the last running cell.
• DisplayTarget.MANUAL: Display animations only after calling the .show() method or when the _repr_html_ method is triggered (requires JupyterLab-style editor).

When using any target other than DisplayTarget.MANUAL, you can rerun any cell without needing to rerun the first cell.

from ipyvizzu import Chart, DisplayTarget

# Example initialization with a specific display target
chart = Chart(width="640px", height="360px", display=DisplayTarget.BEGIN)

The store functionality allows you to capture the current state of a chart or a specific animation to a variable, which can then be reused later without re-defining the entire configuration.

Storing a Chart State (Snapshot)

To save the current visual state of a chart (e.g., its current alignment or configuration), call chart.store(). You can return to this state later by passing the stored object to chart.animate().

Storing an Animation

To save a specific animation sequence, call chart.control.store(). This captures the animation itself. You can replay this animation later by passing the stored object to chart.animate().

Reusing Stored Objects

Once stored, pass the variable directly into chart.animate() to apply the snapshot or replay the animation.

# 1. Save a chart state (snapshot)
snapshot = chart.store()

# 2. Save an animation
chart.animate(Config({"align": "stretch"}))
animation = chart.control.store()

# 3. Reuse them
chart.animate(animation)
chart.animate(snapshot)

The Chart object accepts a display parameter which determines when animations are triggered and how the chart interacts with the notebook execution flow.

Available DisplayTarget options:

• DisplayTarget.MANUAL: Animations are displayed only after the _repr_html_ method is called (e.g., by simply typing the chart object at the end of a cell). This mode allows you to rerun any cell without rerunning the first cell.
• DisplayTarget.BEGIN: Automatically display all animations after the first cell.
• DisplayTarget.ACTUAL: Automatically display all animations after the currently running cell.
• DisplayTarget.END: Automatically display all animations after the last running cell.

Supported features in Mode include changing the vizzu URL, width, height, and enabling scroll_into_view=True.

from ipyvizzu import Chart, DisplayTarget

chart = Chart(width="640px", height="360px", display=DisplayTarget.MANUAL)

If you are not using DataFrames, you can manually construct data using several methods:

1. Specify data by series

Use add_series(name, values, type="dimension" | "measure") to add columns one by one.

2. Specify data by records

Use add_record(list) for a single row, or add_records(list_of_lists | list_of_dicts) for multiple rows. Records must be in first normal form.

3. Using data cube form

This is useful for dense data where you define dimensions and then a matrix of measures.

• Use add_dimension(name, values) for each dimension.
• Use add_measure(name, matrix) where the matrix is a list of lists representing the values for each combination of dimensions.

4. Using JSON

Load data directly from a JSON file using the class method Data.from_json(path).

from ipyvizzu import Data

# Data Cube Example
data = Data()
data.add_dimension("Genres", ["Pop", "Rock"])
data.add_dimension("Kinds", ["Hard", "Smooth"])
data.add_measure("Popularity", [[114, 96], [56, 36]])

# JSON Example
data = Data.from_json("path/to/data.json")