histoprint

2.6.0 · active · verified Sat Apr 11

histoprint is a Python library that provides pretty-printing of NumPy (and other compatible) histograms directly to the console. It leverages terminal color codes and Unicode characters to create visually appealing histogram representations. Currently at version 2.6.0, it follows a regular release cadence with updates typically adding features, improving compatibility, and addressing minor issues.

Warnings

breaking Version 2.0.0 dropped support for Python 2.7 and Python 3.5. Ensure your environment uses Python 3.6 or newer (Python 3.8+ recommended for v2.6.0+).
Fix: Upgrade your Python environment to 3.8 or later.
breaking The optional extra dependency 'root' was renamed to 'uproot' in version 2.3.0. If you were installing with `pip install histoprint[root]`, you must now use `pip install histoprint[uproot]`.
Fix: Change install command from `histoprint[root]` to `histoprint[uproot]`.
breaking Version 2.6.0 and later explicitly require Python 3.8+. Previous versions supported Python 3.6+.
Fix: Ensure your Python environment is version 3.8 or higher.
gotcha Some terminals may not correctly display Unicode combining characters used by histoprint for overlaying histograms. If output appears garbled, you may need to constrain the character set.
Fix: Consult histoprint documentation for options to disable or limit Unicode combining characters, such as `symbols` argument in `print_hist` or specific configuration settings if available.
gotcha While `text_hist` accepts raw data, `print_hist` expects a tuple of `(counts, bin_edges)` similar to the output of `numpy.histogram` or a compatible `PlottableHistogram` object (e.g., from `boost-histogram` or `Hist` library).
Fix: Always pass pre-computed histogram data (counts and bin edges) to `print_hist` or ensure the object adheres to the `PlottableProtocol`.

Install

pip install histoprint Standard Install
pip install histoprint[uproot] With Uproot support
pip install histoprint[rich] With Rich integration

Imports

text_hist
```
from histoprint import text_hist
```
print_hist
```
from histoprint import print_hist
```

Quickstart

This quickstart demonstrates how to generate sample data using NumPy and then visualize it as histograms in the console using `histoprint.text_hist` for single-array input and `histoprint.print_hist` for displaying multiple or pre-computed NumPy histograms, including stacked visualizations.

import numpy as np
from histoprint import text_hist, print_hist

# Create some sample data
A = np.random.randn(1000) - 2
B = np.random.randn(1000)
C = np.random.randn(1000) + 2

# Use text_hist for a single array (wraps numpy.histogram)
print('--- Single Histogram (text_hist) ---')
text_hist(B, bins=[-5, -3, -2, -1, -0.5, 0, 0.5, 1, 2, 3, 5], title="Variable bin widths")

# Create NumPy histograms manually for print_hist
histA = np.histogram(A, bins=15, range=(-5, 5))
histB = np.histogram(B, bins=15, range=(-5, 5))
histC = np.histogram(C, bins=15, range=(-5, 5))

# print_hist can print multiple histograms at once
print('\n--- Overlapping Histograms (print_hist) ---')
print_hist(([histA[0], histB[0], histC[0]], histA[1]), title="Overlays", labels="ABC")

print('\n--- Stacked Histograms (print_hist) ---')
print_hist(([histA[0], histB[0], histC[0]], histA[1]), title="Stacks", stack=True, labels="ABC", bg_colors="rgb")

view raw JSON →