DOCSEARCHbyAlgolia
Submit Docs

sjvisualizer Python Library

repository·main·Indexed 42 days ago

https://github.com/sjoerdtilmans/sjvisualizer

A Python library for animating time-series data using pandas and Tkinter. It enables the creation of combined visualizations including bar races, bubble charts, and regional contour maps on a single canvas for live playback or MP4 video recording via OpenCV.

Tokens
6.5K
Snippets
22
Records
33
Agent score
53%

What's inside sjvisualizer

  3. Data requirements for animations

    main

    When providing data for animated charts, follow these rules:

    • Structure: Rows represent animation frames; columns represent categories.
    • Sorting: Frames must be sorted, unique, and contain no missing values.
    • Indexing:
      • Numeric indices require exact lookups.
      • Datetime indices use the nearest available row.
    • Missing Values: Numeric missing or infinite values are treated as zero (except in Maps, where they use missing_color).
    • Stacked Bars: Do not use negative values in stacked bar datasets.
    • Caching: Numeric data is cached at construction. If you edit your data, you must construct a new chart instance.

  4. Build API documentation locally

    main

    To generate the HTML API documentation from the Sphinx source files, follow these steps:

    1. Install documentation requirements:
      python -m pip install -r docs/requirements.txt
    2. Build the HTML:
      python -m sphinx -b html docs docs/_build/html
    3. Open the output in your browser: docs/_build/html/index.html
    python -m sphinx -b html docs docs/_build/html

  5. Verify chart implementations and package integrity

    main

    To verify your changes, first compile the package and example sources to check for syntax errors. Then, run the smoke test suite to ensure basic rendering functionality across the 24 numbered examples.

    python -m compileall -q sjvisualizer scripts Examples
python scripts/smoke_examples.py

  7. Record animations to video

    main

    To record your animation as an MP4 file, use the record=True and file_name arguments in the cv.play() method.

    Important Requirements:

    • Recording uses OpenCV and screen capture, so the canvas must remain visible and unobscured.
    • Capture dimensions default to the canvas size.
    • Recording will automatically close the Tk window when finished; therefore, you should omit cv.tk.mainloop() when recording.
    • Playback is synchronous.
    cv.play(df=df, fps=30, record=True, file_name="output.mp4")

  9. Rebuild map assets from source data

    main

    If you need to regenerate the packaged map files (Africa, North America, US states, Europe, or Asia) from raw source files, use the provided build scripts. These scripts do not require additional Python dependencies.

    Build US States, Africa, and North America: Use scripts/build_map_assets.py with a path to the US Census Bureau 2024 Cartographic Boundary File ZIP.

    Build High-Resolution Europe and Asia: Use scripts/build_highres_maps.py with a path to the Natural Earth ne_10m_admin_0_countries.geojson file.

    Important: After regenerating assets, restart your Python environment to clear the geometry cache.

    # Build Africa, North America, and US states
python scripts/build_map_assets.py --states-zip path/to/cb_2024_us_state_20m.zip

# Build Europe and Asia from Natural Earth GeoJSON
python scripts/build_highres_maps.py --countries-geojson path/to/ne_10m_admin_0_countries.geojson

  10. Quick start with sjvisualizer

    main

    To create an animation, use Canvas.canvas to initialize the workspace, add charts using specific chart classes (like BarRace.bar_race), and use cv.play() to run the animation.

    Note that cv.tk provides access to the underlying Tkinter object, allowing you to set attributes like -fullscreen.

    import numpy as np
import pandas as pd
from sjvisualizer import Canvas, BarRace

frames = 180
index = pd.date_range("2000-01-01", "2025-01-01", periods=frames)
df = pd.DataFrame({"Solar": np.linspace(10, 90, frames),
                   "Wind": np.linspace(70, 40, frames)}, index=index)

cv = Canvas.canvas(width=1200, height=800, include_logo=False)
cv.tk.attributes("-fullscreen", False)
cv.add_title("Energy production")
chart = BarRace.bar_race(canvas=cv, df=df, x_pos=100, y_pos=150,
                         width=900, height=450, number_of_bars=2, unit=" GWh")
cv.add_sub_plot(chart)
cv.add_time(df, time_indicator="year")
cv.play(df=df, fps=30)
cv.tk.mainloop()

  11. Install sjvisualizer

    main

    To install the refactored version from source, use a Python 3.9 or newer environment with Tkinter installed. On Linux, you may need to install your distribution's Tk package (e.g., python3-tk).

    Local Development Setup

    1. Create a virtual environment:
      python -m venv .venv
    2. Activate the environment:
      • Windows PowerShell: .venv\Scripts\Activate.ps1
      • macOS/Linux: source .venv/bin/activate
    3. Install in editable mode:
      python -m pip install -e .

    Published Package

    You can also install the published version via pip:

    python -m pip install sjvisualizer
    python -m pip install sjvisualizer