3D histograms
- plot_utils.histogram3d(X, bins=10, fig=None, ax=None, figsize=(8, 4), dpi=100, elev=30, azim=5, alpha=0.6, data_labels=None, plot_legend=True, plot_xlabel=False, color=None, dx_factor=0.4, dy_factor=0.8, ylabel='Data', zlabel='Counts', **legend_kwargs)[source]
Plot 3D histograms. 3D histograms are best used to compare the distribution of more than one set of data.
- Parameters:
X (numpy.ndarray, list<list<float>>, pandas.Series, pandas.DataFrame) –
- Input data.
X
can be: a 2D numpy array, where each row is one data set;
a 1D numpy array, containing only one set of data;
a list of lists, e.g., [[1,2,3],[2,3,4,5],[2,4]], where each element corresponds to a data set (can have different lengths);
a list of 1D numpy arrays. [Note: Robustness is not guaranteed for X being a list of
2D numpy arrays.]
(5) a pandas Series, which is treated as a 1D numpy array; (5) a pandas DataFrame, where each column is one data set.
- Input data.
bins (int, list, numpy.ndarray, or pandas.Series) –
- Bin specifications. Can be:
An integer, which indicates number of bins;
An array or list, which specifies bin edges. [Note: If an integer is used, the widths of bars across data
sets may be different. Thus array/list is recommended.]
fig (matplotlib.figure.Figure or
None
) – Figure object. If None, a new figure will be created.ax (matplotlib.axes._subplots.AxesSubplot or
None
) – Axes object. If None, a new axes will be created.figsize ((float, float)) – Figure size in inches, as a tuple of two numbers. The figure size of
fig
(if notNone
) will override this parameter.dpi (float) – Figure resolution. The dpi of
fig
(if notNone
) will override this parameter.elev (float) – Elevation of the 3D view point.
azim (float) – Azimuth angle of the 3D view point (unit: degree).
alpha (float) – Opacity of bars
data_labels (list of str) – Names of different datasets, e.g., [‘Simulation’, ‘Measurement’]. If not provided, generic names [‘Dataset #1’, ‘Dataset #2’, …] are used. The data_labels are only shown when either plot_legend or plot_xlabel is
True
. If not provided, and X is a pandas DataFrame/Series, data_labels will be overridden by the column names (or name) ofX
.plot_legend (bool) – Whether to show legends or not.
plot_xlabel (str) – Whether to show data_labels of each data set on their respective x axis position or not.
color (list<list>, or tuple<tuples>) – Colors of each distributions. Needs to be at least the same length as the number of data series in
X
. Can be RGB colors, HEX colors, or valid color names in Python. IfNone
, get_colors(N=N, color_scheme=’tab10’) will be queried.dx_factor (float) – Width factor of 3D bars in x direction.
dy_factor (float) – Width factor of 3D bars in y direction. For example, if
dy_factor
is 0.9, there will be a small gap between bars in y direction.ylabel (str) – Label of Y axes.
zlabel (str) – Labels of Z axes.
- Returns:
fig (matplotlib.figure.Figure) – The figure object being created or being passed into this function.
ax (matplotlib.axes._subplots.AxesSubplot) – The axes object being created or being passed into this function.
Notes
- x direction :
Across data sets (i.e., if we have three datasets, the bars will occupy three different x values).
- y direction :
Within dataset.
Illustration:
^ z | | | | | |--------------------> y / / / / V x