Skip to content

Add plot_custom to sinter python API #1035

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Strilanc merged 3 commits into from
Feb 4, 2026
Merged

Add plot_custom to sinter python API #1035

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4a214fe
Add plot_custom to sinter python API
m-mcewen Jan 29, 2026
16c9718
regen docs
m-mcewen Feb 2, 2026
94291ef
Merge branch 'main' into sinter_plot_custom
Strilanc Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions doc/sinter_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ API references for stable versions are kept on the [stim github wiki](https://gi
- [`sinter.iter_collect`](#sinter.iter_collect)
- [`sinter.log_binomial`](#sinter.log_binomial)
- [`sinter.log_factorial`](#sinter.log_factorial)
- [`sinter.plot_custom`](#sinter.plot_custom)
- [`sinter.plot_discard_rate`](#sinter.plot_discard_rate)
- [`sinter.plot_error_rate`](#sinter.plot_error_rate)
- [`sinter.post_selection_mask_from_4th_coord`](#sinter.post_selection_mask_from_4th_coord)
Expand Down Expand Up @@ -1452,6 +1453,70 @@ def log_factorial(
"""
```

<a name="sinter.plot_custom"></a>
```python
# sinter.plot_custom

# (at top-level in the sinter module)
def plot_custom(
*,
ax: 'plt.Axes',
stats: 'Iterable[sinter.TaskStats]',
x_func: Callable[[sinter.TaskStats], Any],
y_func: Callable[[sinter.TaskStats], Union[sinter.Fit, float, int]],
group_func: Callable[[sinter.TaskStats], ~TCurveId] = lambda _: None,
point_label_func: Callable[[sinter.TaskStats], Any] = lambda _: None,
filter_func: Callable[[sinter.TaskStats], Any] = lambda _: True,
plot_args_func: Callable[[int, ~TCurveId, List[sinter.TaskStats]], Dict[str, Any]] = lambda index, group_key, group_stats: dict(),
line_fits: Optional[Tuple[Literal['linear', 'log', 'sqrt'], Literal['linear', 'log', 'sqrt']]] = None,
) -> None:
"""Plots error rates in curves with uncertainty highlights.

Args:
ax: The plt.Axes to plot onto. For example, the `ax` value from `fig, ax = plt.subplots(1, 1)`.
stats: The collected statistics to plot.
x_func: The X coordinate to use for each stat's data point. For example, this could be
`x_func=lambda stat: stat.json_metadata['physical_error_rate']`.
y_func: The Y value to use for each stat's data point. This can be a float or it can be a
sinter.Fit value, in which case the curve will follow the fit.best value and a
highlighted area will be shown from fit.low to fit.high.
group_func: Optional. When specified, multiple curves will be plotted instead of one curve.
The statistics are grouped into curves based on whether or not they get the same result
out of this function. For example, this could be `group_func=lambda stat: stat.decoder`.
If the result of the function is a dictionary, then optional keys in the dictionary will
also control the plotting of each curve. Available keys are:
'label': the label added to the legend for the curve
'color': the color used for plotting the curve
'marker': the marker used for the curve
'linestyle': the linestyle used for the curve
'sort': the order in which the curves will be plotted and added to the legend
e.g. if two curves (with different resulting dictionaries from group_func) share the same
value for key 'marker', they will be plotted with the same marker.
Colors, markers and linestyles are assigned in order, sorted by the values for those keys.
point_label_func: Optional. Specifies text to draw next to data points.
filter_func: Optional. When specified, some curves will not be plotted.
The statistics are filtered and only plotted if filter_func(stat) returns True.
For example, `filter_func=lambda s: s.json_metadata['basis'] == 'x'` would plot only stats
where the saved metadata indicates the basis was 'x'.
plot_args_func: Optional. Specifies additional arguments to give the underlying calls to
`plot` and `fill_between` used to do the actual plotting. For example, this can be used
to specify markers and colors. Takes the index of the curve in sorted order and also a
curve_id (these will be 0 and None respectively if group_func is not specified). For example,
this could be:

plot_args_func=lambda index, group_key, group_stats: {
'color': (
'red'
if group_key == 'decoder=pymatching p=0.001'
else 'blue'
),
}
line_fits: Defaults to None. Set this to a tuple (x_scale, y_scale) to include a dashed line
fit to every curve. The scales determine how to transform the coordinates before
performing the fit, and can be set to 'linear', 'sqrt', or 'log'.
"""
```

<a name="sinter.plot_discard_rate"></a>
```python
# sinter.plot_discard_rate
Expand Down
1 change: 1 addition & 0 deletions glue/sample/src/sinter/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
better_sorted_str_terms,
plot_discard_rate,
plot_error_rate,
plot_custom,
group_by,
)
from sinter._predict import (
Expand Down
Loading