statprocon 2.0.0

A Python helper library for generating Process Behaviour Charts

statprocon

statprocon is a Python helper library for generating data for use in Statistical Process Control charts. SPC charts are also known as Process Behaviour Charts, Control charts or Shewhart charts.

SPC Charts help answer questions like:

• How do I know a change has occurred in a process?
• What is the expected variation in a process?
• Is a process stable or unpredictable?

Installation

pip install statprocon

To use the built-in plotting helpers (x_plot() / mr_plot()), install the optional plot extra, which pulls in matplotlib and pandas:

pip install statprocon[plot]

Usage

from statprocon import XmR

counts = [10, 50, 40, 30]

xmr = XmR(counts)
moving_ranges = xmr.moving_ranges()
unpl = xmr.upper_natural_process_limit()[0]  # 85.7
lnpl = xmr.lower_natural_process_limit()[0]  # -20.7
x_cl = xmr.x_central_line()[0]  # 32.5

url = xmr.upper_range_limit()[0]  # 65.36
mr_cl = xmr.mr_central_line()[0]  # 20

Currently, this library only supports the data for generating an XmR chart. An XmR chart is the most universal way of using process behaviour charts. XmR is short for individual values (X) and a moving range (mR). More chart data options can be added via pull requests.

For more information, please read Making Sense of Data by Donald Wheeler.

pandas

Visualize XmR charts using Jupyter Notebooks and pandas

import pandas as pd
from statprocon import XmR

xmr = XmR(counts)

pd.DataFrame(xmr.x_to_dict()).astype(float).plot()
pd.DataFrame(xmr.mr_to_dict()).astype(float).plot()

Charts can display X-axis labels by using the following code:

labels = ['0', '1', '2', '3']
pd.DataFrame(xmr.x_to_dict(), index=labels).astype(float).plot()

Or use built-in methods to generate charts that highlight detection points. These require the optional plotting dependencies (pip install statprocon[plot]):

labels = ['J', 'F', 'M', ...]
xmr = XmR(counts)
xmr.x_plot(labels)
xmr.mr_plot(labels)

Data points that meet detection rules are marked by the following colours:

Rule	Colour
Rule 1	Red
Rule 2	Green
Rule 3	Orange

If one data point meets the criteria for multiple detection rules, the lower numbered detection rule will take priority and be marked. For example, if a data point meets all detection rules, it will be displayed in red. If a data point meets rule 2 and rule 3, it will be displayed in green.

CSV

Generate a CSV of all the data needed to create XmR charts.

print(xmr.to_csv())

Google Sheets Charts

Generate XmR Charts in Google Sheets

https://github.com/mattmccormick/statprocon/assets/436801/0de1a9f3-a8ad-4047-8c9d-0f890e0bf453

1. Make a copy of the statprocon XmR Template sheet
2. Paste the CSV output from above into cell A1
3. Click Data -> Split Text to Columns

The X and MR charts will appear on the right.

Note that the Lower Natural Process Limit may not make sense if your count data could not possibly go negative. If LNPL is not needed, remove it with the following steps:

1. Double-click on the X Chart
2. Click the Setup tab
3. Under Series, find LNPL
4. Click the 3 dot menu on the right next to LNPL
5. Click Remove

The LNPL line will be removed from the X Chart.

Advanced Usage

Halfway Lines

Halfway lines between the X central line and the Upper and Lower Natural Process Limits can be returned by using the include_halfway_lines argument:

xmr.x_to_dict(include_halfway_lines=True)

When the process is predictable, approximately 85% of the X values fall between the Upper and Lower halfway lines.

Trending Limits

With data points that trend upwards or downwards over time, use Trending Limits to calculate a sloping X central line, Upper Natural Process Limits and Lower Natural Process Limits.

from statprocon import XmRTrending

counts = [...]  # data from TrendingTestCase.test_trending_limits

source = XmR(counts)
trending = XmRTrending(source)
pd.DataFrame(trending.x_to_dict()).astype(float).plot()

Use the Median Moving Range

If your data contains extreme outliers, it may be better to compute the limits using the median moving range.

xmr = XmR(counts, moving_range_uses='median')

Use the Median for the X Central Line

xmr = XmR(counts, x_central_line_uses='median')

Note: It's assumed that by using the median for the X central line that the median moving range should also be used. For example, you cannot do the following:

xmr = XmR(counts, x_central_line_uses='median', moving_range_uses='average')

Calculate Limits from Subset of Counts

The central lines and limits calculations can be restricted to a subset of the count data. Use the subset_start_index and subset_end_index parameters when instantiating the XmR object:

xmr = XmR(counts, subset_start_index=10, subset_end_index=34)  # 24 points of data starting at index 10

When one or both of these optional arguments are provided, the the X and MR central line calculations will be modified to only use the data from subset_start_index up to, but not including, subset_end_index. When these optional arguments are not provided, subset_start_index defaults to 0 and subset_end_index defaults to the length of counts.

Dependencies

There are a few other Python libraries for generating SPC charts but they all contain large dependencies in order to include the ability to graph the chart. This package will remain small and light: the core package has no required dependencies, and the data can be converted into charts on your own. The plotting helpers (x_plot() / mr_plot()) are optional and only pull in matplotlib and pandas when you install the plot extra (pip install statprocon[plot]).

This package also contains extensive tests for verifying the integrity of the calculated data.

---

Development

This project uses uv for dependency management and packaging. Install it by following the installation guide.

Create the virtual environment and install all dependencies (including dev tools):

uv sync

To build the distribution locally:

uv build

Releasing

Releases are published to PyPI automatically by the release workflow when a version tag is pushed:

1. Bump version in pyproject.toml and add a matching section to CHANGELOG.md.

2. Merge to main.

3. Tag the release and push the tag:

   git tag v2.0.1
   git push origin v2.0.1
   

The workflow verifies the tag matches the package version, builds the distribution, publishes to PyPI via trusted publishing (no API tokens), and creates a GitHub Release from the CHANGELOG entry. Publishing waits for manual approval on the protected pypi environment.

Testing

Run tests

uv run python -m unittest discover

Run type checking

uv run mypy statprocon tests