pip install msds-comms-plotter==0.1.1

Released: Jul 31, 2026

Interactive Altair charts and a matplotlib/Altair styling toolkit for the 2022 FIFA World Cup (MSDS 610 example).

Ad

Navigation

Verified details

Unverified details

  • License: GNU GENERAL PUBLIC LICENSE
  • Author: Tom Sasser
  • Tags altair , visualization , matplotlib , football , world-cup , statsbomb
  • Requires: Python >=3.9
  • Provides-Extra: png
  • Intended Audience Education
  • Education
  • Operating System OS Independent
  • OS Independent
  • Programming Language Python :: 3 Python :: 3.9 Python :: 3.10 Python :: 3.11 Python :: 3.12
  • Python :: 3
  • Python :: 3.9
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Topic Scientific/Engineering :: Visualization
  • Scientific/Engineering :: Visualization

Project description

A small teaching library for the MSDS 610 (Communications for Analytics) coursework. It bundles a tiny pandas data layer, a World Cup 2022 example dataset with matplotlib figures, and chartkit — a styling toolkit that gives matplotlib and Altair one shared visual identity.

General

The package ships three things:

About chartkit

matplotlib and Altair are independent renderers: matplotlib draws static figures in Python, while Altair emits Vega-Lite JSON that renders in a browser. You can't stack one on the other. What chartkit does instead is give both the same visual identity so a static matplotlib figure and an interactive Altair chart look like siblings:

Ad
  • One typeface — JetBrains Mono, with a monospace fallback stack.
  • One palette — a calm, colorblind-aware 8-color categorical set, plus a sequential (viridis) and diverging (redblue) scheme for magnitude and polarity data.
  • Matching minimal chrome — left-aligned bold titles, quiet horizontal-only gridlines, no top/right spines, tickless axes.
Font note: JetBrains Mono must be installed for matplotlib to use it, and available to the browser (e.g. via a webfont) for Altair. Both fall back to a generic monospace stack otherwise — nothing breaks, the type just changes. Get the font at https://www.jetbrains.com/lp/mono/.

Installation

Requires Python ≥ 3.9.

Just want to use it? Inside an activated virtual environment (see below), the package installs straight from PyPI — the World Cup sample data is bundled, so the charts work with no extra downloads:

The rest of this section covers a full editable/dev install from a clone. Either way, install into a virtual environment (venv). This is the recommended (and on many systems, required) approach: a modern Python — including the Homebrew Python on macOS — is "externally managed" and will refuse a plain pip install with an error: externally-managed-environment (PEP 668). A venv sidesteps that entirely by giving the project its own isolated Python and pip, so you never touch the system install.

Ad

1. Get the code

2. Create the venv

Run this once, from the repo root. It makes a .venv/ folder holding a private copy of Python (.venv/ is already covered by .gitignore).

3. Activate it

You must activate the venv in each new terminal session before installing or running anything. Pick the line for your shell:

Once active, your prompt is prefixed with (.venv). Confirm pip now points inside the venv (not the system Python):

Ad

4. Install the package

With the venv active, upgrade pip and install this project in editable mode (-e, so your source edits take effect without reinstalling). Because you're inside the venv, no --break-system-packages or --user flag is needed:

This pulls in every dependency automatically (see the table below).

5. Verify

Expected output: chartkit OK 8 colors.

6. When you're done

Leave the venv with:

Next time you work on the project, just re-activate (step 3) — you don't need to recreate the venv or reinstall.

Note — do not use --break-system-packages. That flag (or a global pip install outside a venv) writes into the system/Homebrew Python and can corrupt it. The venv above is the safe, standard fix for the externally-managed-environment error.

Requirements

Installing the package pulls these in automatically (declared in pyproject.toml):

chartkit imports matplotlib and Altair lazily, inside the functions that need them — so importing chartkit never fails just because one renderer is missing. Use the matplotlib half without Altair installed, or vice versa.

Optional — static PNG export. Altair charts save as interactive .html out of the box. To also write .png files, install the extra:

To register the JetBrains Mono font without a system-wide install, see register_font in the API below.

API

Import it from the package:

Design tokens (module constants)

These are the shared values every function draws from. Read them, or reuse them directly in your own plotting code.

matplotlib functions

apply_matplotlib_theme() -> dict

Applies the chartkit look to matplotlib globally via rcParams (font, palette cycle, figure size/DPI, spines, grid, ticks, legend). Call once, near the top of your script or notebook. Returns the dict of rcParams it set.

style_axes(ax, title=None, xlabel=None, ylabel=None, ygrid_only=True) -> Axes

Per-axes finishing touches the global rcParams can't express: left-aligned title, axis labels, hidden tick marks (labels kept), and horizontal-only grid when ygrid_only=True. Returns the same ax for chaining.

ensure_font(name="JetBrains Mono") -> bool

Returns True if the font is available to matplotlib; otherwise emits a UserWarning explaining the fallback and returns False. Handy as a pre-flight check.

register_font(path) -> str

Registers a .ttf/.otf with matplotlib at runtime (no system install needed) and returns the resolved font family name.

Altair functions

altair_theme() -> dict

Returns the chartkit Vega-Lite config as a plain dict — useful if you want to merge or inspect it rather than register it.

enable_altair_theme(name="chartkit") -> str

Registers and enables the theme, transparently handling both the Altair ≥ 5.5 decorator API and the legacy alt.themes registry. Returns the theme name. Call once per session.

alt_line(data, x, y, color=None, title="") -> alt.Chart

alt_bar(data, x, y, color=None, title="") -> alt.Chart

alt_scatter(data, x, y, color=None, title="") -> alt.Chart

Thin styled chart builders. Channel arguments use Altair shorthand ("date:T", "price:Q", "symbol:N"). They return a normal alt.Chart, so you can keep chaining Altair methods (.properties(...), .interactive(), …).

Examples

matplotlib

If JetBrains Mono lives in a local file rather than a system install:

Altair

Both figures now share the same font, palette, and chrome.

Running the World Cup example charts

The package ships a worked example on real data: altair_charts explores the 2022 World Cup with the five most common Altair chart types (bar, line, scatter, histogram, heatmap) plus two linked-brush charts, a point-paths chart, and a horizon graph of shots-per-minute, and plots renders matplotlib figures of the same data.

Interactive — open the whole gallery in your browser (recommended). The example script examples/show_wc2022_charts.py builds every chart, stacks them into one page, and opens it in your default web browser. Every chart has hover tooltips; the line and scatter charts also support zoom and pan (scroll/drag) — the bar, histogram, and heatmap have categorical or binned axes where zoom isn't meaningful, so they're tooltip-only. The linked brush charts let you drag a box on a scatter so the bars below recount only the players you selected; the passing chart adds a player-name search box; and the point-paths chart adds a match-number slider, hover-to-trace team paths, and a team search box.

Two color pickers are pinned to the top of the gallery: a Category scheme (15 categorical schemes) that recolors every chart at once — including the single-hue bar/line/scatter/histogram, each taking a distinct slot of the scheme — and a Heatmap ramp (15 sequential schemes) for the heatmap.

The example uses the World Cup data bundled inside the installed package, so it works from any folder with no raw data and no network. It writes a self-contained HTML gallery to ./wc2022_altair_gallery.html in whatever directory you run it from (the Vega libraries are embedded, so it stays interactive offline — no server, no internet). Re-open that file any time without re-running. On a headless machine the script skips the browser and just prints the file path.

Two more drop-in example scripts ship alongside it:

Quickest — just look at the pre-rendered charts. Individual charts are committed in reports/figures/. Open any alt_*.html in a browser for the interactive version, or the matching .png for a static image:

Regenerate them yourself. With the package installed (steps above), run the module — it uses the bundled World Cup data, so no raw-data unpack is needed:

Both write to reports/figures/. (.html always; .png needs the [png] extra above.)

In a notebook, call any builder to display one chart inline — no need to run the whole module:

See the chart cookbook below for a picture and the core Altair code for each chart type, and docs/wc2022_data.md for the full chart list and the dataset columns.

Chart cookbook

One recipe per chart type used in this project: what it looks like, and the core Altair code to build it. The snippets are trimmed to the essential mark + encode so the technique is clear — the full themed, interactive versions live in msds_comms_plotter.altair_charts (call ac.bar_goals_by_team(), ac.line_cumulative_goals(), …). Every chart first picks up the shared look with:

Data comes from the bundled sample tables (worldcup.sample_goals(), worldcup.sample_player_match_stats(), worldcup.sample_shots()); see docs/wc2022_data.md for columns.

1. Bar chart — mark_bar

Magnitude across a category. One measure, one categorical axis, single hue; rank is carried by length and the sort order.

2. Line chart — mark_line

Change over time. Here goals are summed per match-day and accumulated into a monotone curve. point=True marks each observation.

3. Scatter plot — mark_point

Relationship between two continuous measures — one dot per record.

Add a y = x reference line by layering a second chart:

4. Histogram — mark_bar with bin

Distribution of a continuous variable: bin it, then count. A histogram is a bar chart whose x is binned.

5. Heatmap — mark_rect

Two categorical axes with a magnitude in each cell, shaded by a sequential color ramp.

6. Linked brush — selection_interval (crossfilter)

Altair's signature interaction: drag a box on the scatter and a second view re-aggregates to only the selected points; the rest fade to grey. One selection drives both marks.

The passing chart (ac.linked_scatter_passing) is the same pattern with a player-name search box and a live color-scheme dropdown added on top — see the one-call shortcut at the end of this cookbook.

7. Point paths on hover — mark_trail + hover selection

Each entity is a trajectory over an ordered dimension. Hovering one traces its whole path as a tapering trail; the rest stay dim. (Abbreviated — the full builder adds a match-number slider and a team search box.)

8. Horizon graph — layered clipped mark_area

Compresses a tall time series into a short band: fold it into N layers, each a clipped area of the amount spilling past its threshold, so busier values stack into darker color.

Saving a chart

Any chart is an alt.Chart; save it as interactive HTML or a static PNG:

To see them all together with the shared color pickers, run the gallery:

Shortcut: just call the library

You don't have to reproduce any of the code above. Each chart already has a one-call builder in altair_charts, and every builder defaults to the bundled World Cup data — so a plain call works right after pip install. For example, the full passing chart — brush, player-name search box, color-scheme dropdown, and the linked count-by-position bars — is one function call:

The same one-call pattern works for every chart — ac.bar_goals_by_team(), ac.horizon_shots_per_minute(), and so on. To use your own numbers, pass a DataFrame (ac.linked_scatter_passing(stats=my_df)) and you get the full themed, interactive chart back as an alt.Chart.

Project layout

Contributing

This is a course project, but if you're extending it:

  1. Keep the shared design tokens (PALETTE, INK, GRID, …) as the single source of truth — style through them rather than hard-coding colors.
  2. Keep renderer imports lazy (import matplotlib/altair inside functions) so the two halves stay independent.
  3. Run a quick import check before committing: python -c "from msds_comms_plotter import chartkit".

License

Project details

Verified details

Unverified details

  • License: GNU GENERAL PUBLIC LICENSE
  • Author: Tom Sasser
  • Tags altair , visualization , matplotlib , football , world-cup , statsbomb
  • Requires: Python >=3.9
  • Provides-Extra: png
  • Intended Audience Education
  • Education
  • Operating System OS Independent
  • OS Independent
  • Programming Language Python :: 3 Python :: 3.9 Python :: 3.10 Python :: 3.11 Python :: 3.12
  • Python :: 3
  • Python :: 3.9
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Topic Scientific/Engineering :: Visualization
  • Scientific/Engineering :: Visualization

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Uploaded Jul 31, 2026 Source

Built Distribution

Filter files by name, interpreter, ABI, and platform.

If you're not sure about the file name format, learn more about wheel file names.

Copy a direct link to the current filters

Uploaded Jul 31, 2026 Python 3

File details

Details for the file msds_comms_plotter-0.1.1.tar.gz.

File metadata

  • Download URL: msds_comms_plotter-0.1.1.tar.gz
  • Upload date: Jul 31, 2026
  • Size: 157.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.14.6

File hashes

See more details on using hashes here.

File details

Details for the file msds_comms_plotter-0.1.1-py3-none-any.whl.

File metadata

File hashes

See more details on using hashes here.

Source: Pypi.org