Skip to main content

mgplot

Description

mgplot is an open-source Python frontend for matplotlib designed for time-series chart creation with PeriodIndex data. It simplifies common economic and financial plots while:

  1. producing time-series charts that can be tricky to create directly,
  2. finalising (or publishing) charts with titles, labels, annotations, etc.,
  3. minimising code duplication, and maintaining a consistent style.

Installation

pip install mgplot

Or using uv:

uv add mgplot

Requirements: Python 3.10+, pandas, matplotlib, numpy

Import

import mgplot as mg

Quick Example

import pandas as pd
import mgplot as mg

# Create sample data with PeriodIndex
data = pd.Series(
    [100, 102, 105, 103, 108],
    index=pd.period_range("2024Q1", periods=5, freq="Q")
)

# Plot and finalise in one step
mg.line_plot_finalise(data, title="Quarterly Data", ylabel="Value")

Plot Functions

All plot functions take a pandas Series or DataFrame with a PeriodIndex as the first argument and return a matplotlib Axes object. Keyword arguments control styling and behavior:

  • bar_plot() -- bar plot (grouped or stacked) with intelligent PeriodIndex labeling; horizontal=True plots categorical data as horizontal bars (categories on the y-axis, values along the x-axis)
  • fill_between_plot() -- shaded region between two bounds (requires 2-column DataFrame)
  • growth_plot() -- plots annual and periodic growth rates (requires 2-column DataFrame with pre-calculated growth)
  • line_plot() -- one or more lines with optional annotations
  • postcovid_plot() -- data as a line with pre-COVID linear projection
  • revision_plot() -- designed to plot ABS-style data revisions
  • run_plot() -- line plot with background highlighting for monotonic increasing/decreasing runs
  • seastrend_plot() -- seasonal and trend components on one plot
  • series_growth_plot() -- calculates and plots annual (line) and periodic (bars) growth from a single Series
  • summary_plot() -- latest data point against historical range with z-score visualization

For ranked-category charts (states, industries, expenditure classes), use horizontal=True with a string-indexed Series or DataFrame:

vacancies = vacancies.sort_values()  # smallest at the bottom
mg.bar_plot_finalise(
    vacancies,
    horizontal=True,
    annotate=True,     # value labels at the bar ends
    above=True,
    x0=True,           # zero line on the value axis
    title="Job vacancies by industry",
    xlabel="'000",
)

horizontal=True is for categorical data: with a PeriodIndex it warns and falls back to a vertical plot.

Finalising Plots

Once a plot is generated, finalise it with titles, labels, and save to file:

ax = mg.line_plot(data)
mg.finalise_plot(ax, title="My Chart", ylabel="Units", tag="my_chart")

Axis Tick Labels

For PeriodIndex data, x-axis tick labels are generated contextually: the tick density is chosen to fit within max_ticks, and labels show the period with years marked at transitions (e.g. a monthly axis shows Feb Mar ... 2024 ... Feb, a quarterly axis shows Q2 Q3 2025 Q2).

Contextual labels cover yearly, quarterly, monthly, weekly, daily and intraday (minute, multi-minute such as 5min, and hourly) frequencies. Weekly ticks are labelled by each week's start day, or fall on the first week of a month or year for longer spans. Intraday axes show times with the date at each new day (12:00 / 19 Nov 2026, 15:00, ... 00:00 / 20 Nov), or days, months or years for longer spans. Points sit at their period ordinals, so gaps in the data (closed market hours, weekends) take their real width on the axis.

Three keyword arguments control the labels on the period-indexed plot functions (line_plot, bar_plot, growth_plot, fill_between_plot, run_plot, and their *_finalise variants):

  • max_ticks -- the maximum number of ticks (suggestive, not exact). The global default is mg.get_setting("max_ticks").
  • tick_relabel -- a callable applied to each generated label string, after the contextual labelling has run. Use it to restyle labels without losing the transition logic.
  • label_rotation -- (bar_plot only) rotates the x-axis tick labels.

For example, to convert 4-digit year labels to 2-digit years:

import re

def two_digit_years(label: str) -> str:
    """Shorten 4-digit years to 2 digits (e.g. 2024 -> 24)."""
    return re.sub(r"\b(?:19|20)(\d{2})\b", r"\1", label)

# default labels:           2010  2012  2014  ...  2024  2026
# with tick_relabel:          10    12    14  ...    24    26
mg.line_plot_finalise(data, title="My Chart", tick_relabel=two_digit_years)

Because tick_relabel operates on the label strings, this works unchanged on quarterly or monthly axes too: a label such as 2024 marking a year transition becomes 24, while the Q2/Mar labels between transitions pass through untouched.

These options are stashed on the matplotlib Axes when the plot is drawn, and finalise_plot() honours them when it refreshes the tick labels just before saving. Editing tick labels directly on the Axes (e.g. with set_xticklabels()) does not survive that refresh -- use tick_relabel instead.

Multi-Panel Figures

finalise_plot() works on a single Axes. For a figure with several panels, finalise each panel with axes_only=True (axes-level styling only: titles, labels, legends), then make the last call a normal finalise_plot() carrying the figure-level arguments (suptitle, lfooter, rfooter, figsize, ...), which also saves and closes the figure:

fig, (ax_left, ax_right) = plt.subplots(1, 2)
mg.line_plot(left_data, ax=ax_left)
mg.line_plot(right_data, ax=ax_right)
mg.finalise_plot(ax_left, title="Left Panel", ylabel="Index", axes_only=True)
mg.finalise_plot(
    ax_right,
    title="Right Panel",
    ylabel="Index",
    suptitle="Both Panels Together",  # also used for the filename
    lfooter="Australia. Seasonally adjusted.",
    rfooter="Source: ABS",
    figsize=(9, 4.5),
)

Convenience Finalisers

For every plot function, there is a *_finalise() variant that combines the plot and finalise steps:

  • bar_plot_finalise()
  • fill_between_plot_finalise()
  • growth_plot_finalise()
  • line_plot_finalise()
  • postcovid_plot_finalise()
  • revision_plot_finalise()
  • run_plot_finalise()
  • scatter_plot_finalise()
  • seastrend_plot_finalise()
  • series_growth_plot_finalise()
  • summary_plot_finalise()

Multi-Plot Chaining

Chain plotting operations together for batch processing:

  • plot_then_finalise() -- chains a plot function with finalise_plot()
  • multi_start() -- creates multiple plots with different start dates
  • multi_column() -- creates separate plots for each DataFrame column

Settings and Configuration

Manage global defaults for figure size, colors, output directory, etc.:

mg.set_setting("figsize", (10, 5))
mg.set_setting("dpi", 150)
mg.set_chart_dir("./charts")

# Get current setting
current_dpi = mg.get_setting("dpi")

Color Utilities

Built-in support for Australian state/territory and political party colors:

mg.get_color("NSW")           # Returns 'deepskyblue'
mg.get_color("Labor")         # Returns Labor party color
mg.colorise_list(["NSW", "VIC", "QLD"])  # Returns list of colors

Documentation

API documentation is generated from docstrings using pdoc. To view locally:

# Generate and serve docs
uv run pdoc src/mgplot

# Or open the pre-built docs
open docs/mgplot.html

Development

# Install dependencies
uv sync

# Run type checking
uv run pyright src/

# Run linting
uv run ruff check src/
uv run ruff format src/

License

MIT License - see LICENSE file for details.


Metadata

Release files for mgplot 0.3.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mgplot 0.3.5
File Size Uploaded Provenance Actions
mgplot-0.3.5.tar.gz 2.8 MB Without provenance Details for mgplot-0.3.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mgplot 0.3.5
File Interpreter ABI Platform Actions
mgplot-0.3.5-py3-none-any.whl Python 3 none any Details for mgplot-0.3.5-py3-none-any.whl

Total release size: 2.8 MB

Release files / mgplot-0.3.5.tar.gz

Download URL mgplot-0.3.5.tar.gz
Size 2.8 MB
Tags Source
SHA-256 checksum
How to use checksums
de6c79243cca6240ea8b726a603e73434b3befa05a8297d1746c7a3bc41f9cf0
BLAKE2b-256 checksum
How to use checksums
d90bc36dd515c3329b5cc98446298f194609129bbdb1b68c6756813b53d8018e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / mgplot-0.3.5-py3-none-any.whl

Download URL mgplot-0.3.5-py3-none-any.whl
Size 68.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
28cda064ccf6d683d54423bce895802cabe964cca35dbb441120388609937d1a
BLAKE2b-256 checksum
How to use checksums
12b46ac248319ac30623ae9f2819b2c7a7527047701c65e44d5d646be457aea8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for mgplot 0.3.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.5 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page