physt.plotting package

Submodules

physt.plotting.ascii module

ASCII plots (experimental).

The plots are printed directly to standard output.

physt.plotting.ascii.hbar(h1, width=80, show_values=False)

physt.plotting.common module

Functions that are shared by several (all) plotting backends.

class physt.plotting.common.TimeTickHandler(level: str = None)

Bases: object

Callable that creates ticks and labels corresponding to “sane” time values.

Note: This class is very experimental and subject to change or disappear.

LEVELS = {'day': 86400, 'hour': 3600, 'min': 60, 'sec': 1}
LevelType = typing.Tuple[str, typing.Union[float, int]]
classmethod deduce_level(h1: physt.histogram1d.Histogram1D, min_: float, max_: float) → Tuple[str, Union[float, int]]
format_time_ticks(ticks: List[float], level: Tuple[str, Union[float, int]]) → List[str]
get_time_ticks(h1: physt.histogram1d.Histogram1D, level: Tuple[str, Union[float, int]], min_: float, max_: float) → List[float]
classmethod parse_level(value: Union[Tuple[str, Union[float, int]], float, str, datetime.timedelta]) → Tuple[str, Union[float, int]]
classmethod split_hms(value) → Tuple[bool, int, int, Union[int, float]]
physt.plotting.common.check_ndim(ndim: Union[int, Tuple[int, ...]])

Decorator checking proper histogram dimension.

physt.plotting.common.get_data(histogram: physt.histogram_base.HistogramBase, density: bool = False, cumulative: bool = False, flatten: bool = False) → numpy.ndarray

Get histogram data based on plotting parameters.

Parameters:
  • density (Whether to divide bin contents by bin size) –
  • cumulative (Whether to return cumulative sums instead of individual) –
  • flatten (Whether to flatten multidimensional bins) –
physt.plotting.common.get_err_data(histogram: physt.histogram_base.HistogramBase, density: bool = False, cumulative: bool = False, flatten: bool = False) → numpy.ndarray

Get histogram error data based on plotting parameters.

Parameters:
  • density (Whether to divide bin contents by bin size) –
  • cumulative (Whether to return cumulative sums instead of individual) –
  • flatten (Whether to flatten multidimensional bins) –
physt.plotting.common.get_value_format(value_format: Union[Callable[[float], str], str, None]) → Callable[[float], str]

Create a formatting function from a generic value_format argument.

physt.plotting.common.pop_kwargs_with_prefix(prefix: str, kwargs: dict) → dict

Pop all items from a dictionary that have keys beginning with a prefix.

Parameters:
  • prefix (str) –
  • kwargs (dict) –
Returns:

kwargs – Items popped from the original directory, with prefix removed.
Return type:

dict

physt.plotting.folium module

physt.plotting.matplotlib module

physt.plotting.plotly module

physt.plotting.vega module

Vega3 backend for plotting in physt.

The JSON can be produced without any external dependency, the ability to show plots in-line in IPython requires ‘vega3’ library.

Implementation note: Values passed to JSON cannot be of type np.int64 (solution: explicit cast to float)

Common parameters

See the enable_inline_view wrapper.

physt.plotting.vega.bar(h1: physt.histogram1d.Histogram1D, **kwargs) → dict

Bar plot of 1D histogram.

Parameters:
  • lw (float) – Width of the line between bars
  • alpha (float) – Opacity of the bars
  • hover_alpha (float) – Opacity of the bars when hover on
physt.plotting.vega.display_vega(vega_data: dict, display: bool = True) → Union[Vega, dict]

Optionally display vega dictionary.

Parameters:
  • vega_data (Valid vega data as dictionary) –
  • display (Whether to try in-line display in IPython) –
physt.plotting.vega.enable_inline_view(f)

Decorator to enable in-line viewing in Python and saving to external file.

It adds several parameters to each decorated plotted function:

Parameters:
  • write_to (str (optional)) – Path to write vega JSON/HTML to.
  • write_format ("auto" | "json" | "html") – Whether to create a JSON data file or a full-fledged HTML page.
  • display ("auto" | True | False) – Whether to try in-line display in IPython
  • indent (int) – Indentation of JSON
physt.plotting.vega.line(h1: physt.histogram1d.Histogram1D, **kwargs) → dict

Line plot of 1D histogram values.

Points are horizontally placed in bin centers.

Parameters:h1 (physt.histogram1d.Histogram1D) – Dimensionality of histogram for which it is applicable
physt.plotting.vega.map(h2: physt.histogram_nd.Histogram2D, *, show_zero: bool = True, show_values: bool = False, **kwargs) → dict

Heat-map of two-dimensional histogram.

physt.plotting.vega.map_with_slider(h3: physt.histogram_nd.HistogramND, *, show_zero: bool = True, show_values: bool = False, **kwargs) → dict

Heatmap showing slice in first two dimensions, third dimension represented as a slider.

physt.plotting.vega.scatter(h1: physt.histogram1d.Histogram1D, **kwargs) → dict

Scatter plot of 1D histogram values.

Points are horizontally placed in bin centers.

Parameters:shape (str) –
physt.plotting.vega.write_vega(vega_data, *, title: Optional[str], write_to: str, write_format: str = 'auto', indent: int = 2)

Write vega dictionary to an external file.

Parameters:
  • vega_data (Valid vega data as dictionary) –
  • write_to (Path to write vega JSON/HTML to.) –
  • write_format ("auto" | "json" | "html") – Whether to create a JSON data file or a full-fledged HTML page.
  • indent (Indentation of JSON) –

Module contents

Plotting for physt histograms.

Available backends

  • matplotlib
  • vega
  • plotly (simple wrapper around matplotlib for 1D histograms)
  • folium (just for the geographical histograms)

Calling the plotting functions

Common parameters

There are several backends (and user-defined may be added) and several plotting functions for each - we try to keep a consistent set of parameters to which all implementations should try to stick (with exceptions).

All histograms

write_to : str (optional)
Path to file where the output will be stored
title : str (optional)
String to be displayed as plot title (defaults to h.title)
xlabel : str (optional)
String to be displayed as x-axis label (defaults to corr. axis name)
ylabel : str (optional)
String to be displayed as y-axis label (defaults to corr. axis name)
xscale : str (optional)
If “log”, x axis will be scaled logarithmically
yscale : str (optional)
If “log”, y axis will be scaled logarithmically

xlim : tuple | “auto” | “keep”

ylim : tuple | “auto” | “keep”

invert_y : bool
If True, the y axis points downwards
ticks : {“center”, “edge”}, optional
If set, each bin will have a tick (either central or edge)
alpha : float (optional)
The alpha of the whole plot (default: 1)
cmap : str or list
Name of the palette or list of colors or something that the respective backend can interpret as colourmap.

cmap_normalize : {“log”}, optional

cmap_min :

cmap_max :

show_values : bool
If True, show values next to (or inside) the bins
value_format : str or Callable
How bin values (if to be displayed) are rendered.

zorder : int (optional)

text_color : text_alpha : text_* :

Other options that are passed to the formatting of values without the prefix

1D histograms

cumulative : bool
If True, show CDF instead of bin heights
density : bool
If True, does not show bin contents but contents divided by width
errors : bool
Whether to show error bars (if available)
show_stats : bool
If True, display a small box with statistical info

2D heatmaps

show_zero : bool
Whether to show bins that have 0 frequency
grid_color :
Colour of line between bins
show_colorbar : bool
Whether to display a colorbar next to the plot itself

Line plots

lw (or linewidth) : int
Width of the lines
class physt.plotting.PlottingProxy(h: Union[physt.histogram_base.HistogramBase, physt.histogram_collection.HistogramCollection])

Bases: object

Proxy enabling to call plotting methods on histogram objects.

It can be used both as a method or as an object containing methods. In any case, it only forwards the call to the universal plot() function.

The __dir__ method should offer all plotting methods supported by the currently selected backend.

Example

plotter = histogram.plot plotter(…) # Plots using defaults plotter.bar(…) # Plots as a specified plot type (“bar”)

Note

Inspiration taken from the way how pandas deals with this.

physt.plotting.get_default_backend() → Optional[str]

The backend that will be used by default with the plot function.

physt.plotting.plot(histogram: Union[physt.histogram_base.HistogramBase, physt.histogram_collection.HistogramCollection], kind: Optional[str] = None, backend: Optional[str] = None, **kwargs)

Universal plotting function.

All keyword arguments are passed to the plotting methods.

Parameters:kind (Type of the plot (like "scatter", "line", ..), similar to pandas) –
physt.plotting.set_default_backend(name: str) → None

Choose a default backend.