Skip to main content

P(i/y)thon h(i/y)stograms.

Project description

physt Physt logo

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.

ReadTheDocs Join the chat at https://gitter.im/physt/Lobby PyPI downloads PyPI version Anaconda-Server Badge Anaconda-Server Badge Code style: black

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

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

Heights plot

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);

Iris 2D plot

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")

Directional 3D plot

See more in docstring's and notebooks:

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, beta, 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.9+
  • 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) uproot - I/O
  • (optional) astropy - additional binning algorithms
  • (optional) folium - map plotting
  • (optional) vega3 - for vega in-line in IPython notebook (note that to generate vega JSON, this is not necessary)
  • (optional) xtermcolor - for ASCII color maps
  • (testing) pytest
  • (docs) sphinx, sphinx_rtd_theme, ipython

Publicity

Talk at PyData Berlin 2018:

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:

Patches:

Alternatives and inspirations

Project details


Release history Release notifications | RSS feed

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.8.4.tar.gz (117.4 kB view details)

Uploaded Source

Built Distribution

physt-0.8.4-py2.py3-none-any.whl (106.0 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file physt-0.8.4.tar.gz.

File metadata

  • Download URL: physt-0.8.4.tar.gz
  • Upload date:
  • Size: 117.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.4.20

File hashes

Hashes for physt-0.8.4.tar.gz
Algorithm Hash digest
SHA256 f16c00489c3bde56c98f6bb7de92fb6aa13d6f213f8cf9bced885e5f028d0a39
MD5 d31278ce2e9dee2b70af72ebe81077e2
BLAKE2b-256 8e8a2e7331f5e9b7fe8299e9c7dd9cd1c08c9d8de64de8c009380e73229aef13

See more details on using hashes here.

File details

Details for the file physt-0.8.4-py2.py3-none-any.whl.

File metadata

  • Download URL: physt-0.8.4-py2.py3-none-any.whl
  • Upload date:
  • Size: 106.0 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.4.20

File hashes

Hashes for physt-0.8.4-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 a9c4dc417c74d7e3d89d16bf30627505e9c7872cb087d4dcffca2176de853602
MD5 da910776a517736463fd7b7f79bfcebf
BLAKE2b-256 d5a650956a96535c69931639b16030c74b479d4a3c4d800e47529bc58114bab5

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page