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)

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:

  1. a 2D numpy array, where each row is one data set;

  2. a 1D numpy array, containing only one set of data;

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

  4. 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.

• bins (int, list, numpy.ndarray, or pandas.Series) –

  Bin specifications. Can be:

  1. An integer, which indicates number of bins;

  2. 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 not None) will override this parameter.

• dpi (float) – Figure resolution. The dpi of fig (if not None) 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) of X.

• 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. If None, 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