physt 
P(i/y)thon h(i/y)stograms. Inspired (and based on) numpy.histogram, but designed for humans(TM) on steroids(TM).
Create rich histogram objects from numpy or dask arrays, from pandas and polars series/dataframes, from xarray datasets and a few more types of objects. Manipulate them with ease, plot them with matplotlib, vega or plotly.
In short, whatever you want to do with histograms, physt aims to be on your side.
See it in action
With uv installed, you can run the following command without needing to install
anything to see some examples in action:
uv run --with "physt[terminal]>=0.8.3" -m physt.examples
Command-line interface (experimental)
You can run (and install) physt as a command-line application to quickly analyse
data files. This functionality is currently in development.
uv run physt h1 "src/physt/examples/munros.csv" -c height -p -n 10
For more information, use the --help flag.
Simple example
from physt import h1
# Create the sample
heights = [160, 155, 156, 198, 177, 168, 191, 183, 184, 179, 178, 172, 173, 175,
172, 177, 176, 175, 174, 173, 174, 175, 177, 169, 168, 164, 175, 188,
178, 174, 173, 181, 185, 166, 162, 163, 171, 165, 180, 189, 166, 163,
172, 173, 174, 183, 184, 161, 162, 168, 169, 174, 176, 170, 169, 165]
hist = h1(heights, 10) # <--- get the histogram data
hist << 190 # <--- add a forgotten value
hist.plot() # <--- and plot it
2D example
from physt import h2
import seaborn as sns
iris = sns.load_dataset('iris')
iris_hist = h2(iris["sepal_length"], iris["sepal_width"], "pretty", bin_count=[12, 7], name="Iris")
iris_hist.plot(show_zero=False, cmap="gray_r", show_values=True);
3D directional example
import numpy as np
from physt import special_histograms
# Generate some sample data
data = np.empty((1000, 3))
data[:,0] = np.random.normal(0, 1, 1000)
data[:,1] = np.random.normal(0, 1.3, 1000)
data[:,2] = np.random.normal(1, .6, 1000)
# Get histogram data (in spherical coordinates)
h = special_histograms.spherical(data)
# And plot its projection on a globe
h.projection("theta", "phi").plot.globe_map(density=True, figsize=(7, 7), cmap="rainbow")
See more in docstring's and notebooks:
- Basic tutorial: http://nbviewer.jupyter.org/github/janpipek/physt/blob/dev/docs/tutorial.ipynb
- Binning: http://nbviewer.jupyter.org/github/janpipek/physt/blob/dev/docs/binning.ipynb
- 2D histograms: http://nbviewer.jupyter.org/github/janpipek/physt/blob/dev/docs/2d_histograms.ipynb
- Special histograms (polar, spherical, cylindrical - beta): http://nbviewer.jupyter.org/github/janpipek/physt/blob/dev/docs/special_histograms.ipynb
- Adaptive histograms: http://nbviewer.jupyter.org/github/janpipek/physt/blob/dev/docs/adaptive_histogram.ipynb
- Use dask for large (not "big") data - alpha: http://nbviewer.jupyter.org/github/janpipek/physt/blob/dev/docs/dask.ipynb
- Geographical bins . alpha: http://nbviewer.jupyter.org/github/janpipek/physt/blob/dev/docs/geospatial.ipynb
...and others, see the
docsdirectory.
Installation
Using pip:
pip install physt
or conda:
conda install -c janpipek physt
Features
Implemented
- 1D histograms
- 2D histograms
- ND histograms
- Some special histograms
- 2D polar coordinates (with plotting)
- 3D spherical / cylindrical coordinates (beta)
- Adaptive rebinning for on-line filling of unknown data (beta)
- Non-consecutive bins
- Memory-effective histogramming of dask arrays (beta)
- Understands any numpy-array-like object
- Keep underflow / overflow / missed bins
- Basic numeric operations (* / + -)
- Items / slice selection (including mask arrays)
- Add new values (fill, fill_n)
- Cumulative values, densities
- Simple statistics for original data (mean, std, sem) - only for 1D histograms
- Plotting with several backends
- matplotlib (static plots with many options)
- vega (interactive plots, broken, help wanted!)
- folium (experimental for geo-data)
- plotly (very basic, help wanted!)
- ascii (experimental)
- Algorithms for optimized binning
- pretty (nice rounded bin edges)
- mathematical (statistical, quantile-based, geometrical, ...)
- IO, conversions
- I/O JSON
- I/O xarray.DataSet (experimental)
- O ROOT file (experimental)
- O pandas.DataFrame (basic)
Planned
- Rebinning
- using reference to original data?
- merging bins
- Statistics (based on original data)?
- Stacked histograms (with names)
- Potentially holoviews plotting backend (instead of the discontinued bokeh one)
Not planned
- Kernel density estimates - use your favourite statistics package (like
seaborn) - Rebinning using interpolation - it should be trivial to use
rebin(https://github.com/jhykes/rebin) with physt
Rationale (for both): physt is dumb, but precise.
Dependencies
- Python 3.10+
- Numpy 1.25+
- (optional) polars (1.0+), pandas (1.5+), dask, xarray - if you want to histogram those
- (optional) matplotlib - simple visualization
- (optional) xarray - I/O
- (optional) astropy - additional binning algorithms
- (optional) folium - map plotting
- (optional) rich - console output including plots
- (testing) pytest
- (docs) sphinx, sphinx_rtd_theme, ipython
Publicity
Talk at PyData Berlin 2018:
- https://janpipek.github.io/pydata2018-berlin/ - repository with slides and links
- https://www.youtube.com/watch?v=ZG-wH3-Up9Y - video of the talk
Contribution
I am looking for anyone interested in using / developing physt. You can contribute by reporting errors, implementing missing features and suggest new one.
Thanks to:
- Ryan Mackenzie White - https://github.com/ryanmackenziewhite for the protobuf idea and first implementation.
- Ben Greiner - https://github.com/bnavigator for the numpy>=2.0 PR though I implemented it in a different way eventually.
Patches:
- Matthieu Marinangeli - https://github.com/marinang
Alternatives and inspirations
- https://github.com/boostorg/histogram (C++, part of boost)
- https://github.com/scikit-hep/boost-histogram (Python wrapper around boost-histogram)
- https://github.com/ibab/matplotlib-hep
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
physt-0.10.0.tar.gz
(97.5 kB
view details)
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
physt-0.10.0-py3-none-any.whl
(107.4 kB
view details)
File details
Details for the file physt-0.10.0.tar.gz.
File metadata
- Download URL: physt-0.10.0.tar.gz
- Upload date:
- Size: 97.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Fedora Linux","version":"44","id":"","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
97447cb59570e3c3c027b05da3b727efaec0493314b97d737f411577f88d03f8
|
|
| MD5 |
0c78c45de4dfab09084cb65bacea9ece
|
|
| BLAKE2b-256 |
b4138c47be239e5d9a876921a3e640f901751950e23d8f2e795b09231a36aa0e
|
File details
Details for the file physt-0.10.0-py3-none-any.whl.
File metadata
- Download URL: physt-0.10.0-py3-none-any.whl
- Upload date:
- Size: 107.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Fedora Linux","version":"44","id":"","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7970042c6bedea463dece63ac5a3d4e112dde68e173b0dd52ab08a365293f5aa
|
|
| MD5 |
8d8385f4dca8e61ea034e8f7d403c59d
|
|
| BLAKE2b-256 |
2d65813da2b4a39e28f63cd8202cb93f68f6854c7eb15e0b322875a6a2fa32aa
|
