#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""A basic histogram plotting routine using matplotlib"""

#-----------------------------------------------------------------------------
# Boilerplate
#-----------------------------------------------------------------------------
from __future__ import absolute_import, division, print_function, unicode_literals

#-----------------------------------------------------------------------------
# Imports
#-----------------------------------------------------------------------------
import scipy
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
from . set_style import set_plot_style
from .. pygeostat_parameters import Parameters

@set_plot_style
def histogram_plot(data, var=None, weights=None, cat=None, catdict=None, bins=None, icdf=False, lower=None,
                    upper=None, ax=None, figsize=None, xlim=None, ylim=None, title=None, xlabel=None,
                    stat_blk=None, stat_xy=None, stat_ha=None, roundstats=None, sigfigs=None, color=None,
                    edgecolor=None, edgeweights=None, grid=None, axis_xy=None, label_count=False,
                    rotateticks=None, plot_style=None, custom_style=None, output_file=None, out_kws=None,
                    stat_fontsize=None, stat_linespacing=None, logx=False, **kwargs):
    """
    Generates a matplotlib style histogram with summary statistics. Trimming is now only applied
    to NaN values (Pygeostat null standard).

    The only required required parameter is ``data``. If ``xlabel`` is left to its default value of
    ``None`` and the input data is contained in a pandas dataframe or series, the column
    information will be used to label the x-axis.

    Two statistics block sets are available: ``'all'`` and the default ``'minimal'``. The
    statistics block can be customized to a user defined list and order. Available statistics are
    as follows:

    >>> ['count', 'mean', 'stdev', 'cvar', 'max', 'upquart', 'median', 'lowquart', 'min',
    ...  'p10', 'p90']

    The way in which the values within the statistics block are rounded and displayed can be
    controlled using the parameters ``roundstats`` and ``sigfigs``.

    Please review the documentation of the :func:`gs.set_style()
    <pygeostat.plotting.set_style.set_style>` and :func:`gs.export_image()
    <pygeostat.plotting.export_image.export_image>` functions for details on their parameters so that
    their use in this function can be understood.

    Parameters:
        data (np.ndarray, pd.DataFrame/Series, or gs.DataFile): data array, which must be 1D
            unless var is provided. The exception being a DataFile, if data.variables
            is a single name.
        var (str): name of the variable in data, which is required if data is not 1D.
        weights (np.ndarray, pd.DataFrame/Series, or gs.DataFile or str): 1D array of declustering
             weights for the data. Alternatively the declustering weights name in var. If data
             is a DataFile, it may be string in data.columns, or True to use data.weights
             (if data.weights is not None).
        cat (bool or str): either a cat column in data.data, or if True uses data.cat if data.cat
            is not None
        catdict (dict or bool): overrides bins. If a categorical variable is being plotted, provide
            a dictionary where keys are numeric (categorical codes) and values are their associated
            labels (categorical names). The bins will be set so that the left edge (and associated
            label) of each bar is inclusive to each category. May also be set to True, if data is
            a DataFile and data.catdict is initialized.
        bins (int or list): Number of bins to use, or a list of bins
        icdf (bool): Indicator to plot a CDF or not
        lower (float): Lower limit for histogram
        upper (float): Upper limit for histogram
        ax (mpl.axis): Matplotlib axis to plot the figure
        figsize (tuple): Figure size (width, height)
        xlim (float tuple): Minimum and maximum limits of data along the x axis
        ylim (float tuple): Minimum and maximum limits of data along the y axis
        title (str): Title for the plot
        xlabel (str): X-axis label
        stat_blk (bool): Indicate if statistics are plotted or not
        stat_xy (float tuple): X, Y coordinates of the annotated statistics in figure
            space. Based on Parameters['plotting.histogram_plot.stat_xy'] if a histogram and
            Parameters['plotting.histogram_plot.stat_xy'] if a CDF, which defaults to the top right when
            a PDF is plotted and the bottom right if a CDF is plotted.
        stat_ha (str): Horizontal alignment parameter for the annotated statistics. Can be
            ``'right'``, ``'left'``, or ``'center'``. If None, based on
            Parameters['plotting.stat_ha']
        stat_fontsize (float): the fontsize for the statistics block. If None, based on
            Parameters['plotting.stat_fontsize']. If less than 1, it is the fraction of the
            matplotlib.rcParams['font.size']. If greater than 1, it the absolute font size.
        roundstats (bool): Indicate if the statistics should be rounded to the number of digits or
            to a number of significant figures (e.g., 0.000 vs. 1.14e-5). The number of digits or
            figures used is set by the parameter ``sigfigs``. sigfigs (int): Number of significant
            figures or number of digits (depending on ``roundstats``) to display for the float
            statistics
        color (str or int or dict): Any permissible matplotlib color or a integer which is used to draw
            a color from the pygeostat color pallet ``pallet_pastel``> May also be a dictionary of colors,
            which are used for each bar (useful for categories). colors.keys() must align with bins[:-1]
            if a dictionary is passed. Drawn from Parameters['plotting.cmap_cat'] if catdict is used
            and their keys align.
        edgecolor (str): Any permissible matplotlib color for the edge of a histogram bar
        grid(bool): plots the major grid lines if True. Based on Parameters['plotting.grid']
            if None.
        axis_xy (bool): converts the axis to GSLIB-style axis visibility (only left and bottom
            visible) if axis_xy is True. Based on Parameters['plotting.axis_xy'] if None.
        label_count (bool): label the number of samples found for each category in catdict. Does
            nothing if no catdict is found
        rotateticks (bool tuple): Indicate if the axis tick labels should be rotated (x, y)
        plot_style (str): Use a predefined set of matplotlib plotting parameters as specified by
            :class:`gs.GridDef <pygeostat.data.grid_definition.GridDef>`. Use ``False`` or ``None``
            to turn it off
        custom_style (dict): Alter some of the predefined parameters in the ``plot_style`` selected.
        output_file (str): Output figure file name and location
        out_kws (dict): Optional dictionary of permissible keyword arguments to pass to
            :func:`gs.export_image() <pygeostat.plotting.export_image.export_image>`
        **kwargs: Optional permissible keyword arguments to pass to either: (1) matplotlib's hist
            function if a PDF is plotted or (2) matplotlib's plot function if a CDF is plotted.

    Returns:
        ax (ax): matplotlib Axes object with the histogram

    **Examples:**

    A simple call:

    .. plot::

        import pygeostat as gs
        # load some data
        dfl = gs.ExampleData("point3d_ind_mv")
        # plot the histogram_plot
        gs.histogram_plot(dfl, var="Phi", bins=30)

    |

    Change the colour, number of significant figures displayed in the statistics, and pass some
    keyword arguments to matplotlibs hist function:

    .. plot::

        import pygeostat as gs
        # load some data
        dfl = gs.ExampleData("point3d_ind_mv")
        # plot the histogram_plot
        gs.histogram_plot(dfl, var="Phi", color='#c2e1e5', sigfigs=5, log=True, density=True)

    |

    Plot a CDF while also displaying all available statistics, which have been shifted up:

    .. plot::

        import pygeostat as gs
        # load some data
        dfl = gs.ExampleData("point3d_ind_mv")
        # plot the histogram_plot
        gs.histogram_plot(dfl, var="Phi", icdf=True, stat_blk='all', stat_xy=(1, 0.75))
        # Change the CDF line colour by grabbing the 3rd colour from the color pallet
        # ``cat_vibrant`` and increase its width by passing a keyword argument to matplotlib's
        # plot function. Also define a custom statistics block:
        gs.histogram_plot(dfl, var="Phi", icdf=True, color=3, lw=3.5, stat_blk=['count','upquart'])

    |

    Generate histograms of Phi considering the categories:

    .. plot::

        import pygeostat as gs
        # load some data
        dfl = gs.ExampleData("point3d_ind_mv")
        cats = [1, 2, 3, 4, 5]
        colors = gs.catcmapfromcontinuous("Spectral", 5).colors
        # build the required cat dictionaries
        dfl.catdict = {c: "RT {:02d}".format(c) for c in cats}
        colordict =  {c: colors[i] for i, c in enumerate(cats)}
        # plot the histogram_plot
        f, axs = plt.subplots(2, 1, figsize=(8, 6))
        for var, ax in zip(["Phi", "Sw"], axs):
            gs.histogram_plot(dfl, var=var, cat=True, color=colordict, bins=40, figsize=(8, 4), ax=ax,
                       xlabel=False, title=var)

    |

    Generate cdf subplots considering the categories:

    .. plot::

        import pygeostat as gs
        # load some data
        dfl = gs.ExampleData("point3d_ind_mv")
        cats = [1, 2, 3, 4, 5]
        colors = gs.catcmapfromcontinuous("Spectral", 5).colors
        # build the required cat dictionaries
        dfl.catdict = {c: "RT {:02d}".format(c) for c in cats}
        colordict =  {c: colors[i] for i, c in enumerate(cats)}
        # plot the histogram_plot
        f, axs = plt.subplots(2, 2, figsize=(12, 9))
        axs=axs.flatten()
        for var, ax in zip(dfl.variables, axs):
            gs.histogram_plot(dfl, var=var, icdf=True, cat=True, color=colordict, ax=ax)

    Recreate the `Proportion` class plot

    .. plot::

        import pygeostat as gs
        # load some data
        dfl = gs.ExampleData("point3d_ind_mv")
        cats = [1, 2, 3, 4, 5]
        colors = gs.catcmapfromcontinuous("Spectral", 5).colors
        # build the required cat dictionaries
        dfl.catdict = {c: "RT {:02d}".format(c) for c in cats}
        colordict =  {c: colors[i] for i, c in enumerate(cats)}
        # plot the histogram_plot
        ax = gs.histogram_plot(dfl, cat=True, color=colordict, figsize=(7, 4), rotateticks=(45, 0),
                        label_count=True)

    """
    import pygeostat as gs
    from . utils import format_plot, _set_stat_fontsize, _format_grid, _format_tick_labels, setup_plot, catcmapfromcontinuous
    from . cmaps import _cat_pastel_data, _cat_vibrant_data
    import copy
    # Now converting to a numpy array, as encountering some odd pandas performance, and there's
    # no major disadvantagve to application of a numpy in this context to my knowledge - RMB
    # If a list is passed convert it to a series so that trimming can take place
    # weights
    if isinstance(weights, str):
        if isinstance(data, pd.DataFrame) or isinstance(data, gs.DataFile):
            weights = data[weights]
    elif isinstance(weights, bool):
        if weights:
            if isinstance(data, gs.DataFile):
                if data.weights is None:
                    raise ValueError('weights=True but data.weights is None!')
                elif isinstance(data.weights, list):
                    raise ValueError('weights=True but data.weights is a list!')
                weights = data[data.weights].values
            else:
                raise ValueError('weights=True is only valid if data is a DataFile!')
        else:
            weights = None
    if isinstance(weights, pd.Series) or isinstance(weights, pd.DataFrame):
        weights = weights.values
    # cats for continuous histogram_plots
    if isinstance(cat, str):
        if isinstance(data, pd.DataFrame) or isinstance(data, gs.DataFile):
            cat = data[cat]
    elif isinstance(cat, bool):
        if cat:
            if isinstance(data, gs.DataFile):
                if data.cat is None:
                    raise ValueError('cat=True but data.cat is None!')
                cat = data[data.cat].values
                if catdict is None and data.catdict is None:
                    raise ValueError("pass a `catdict` when setting `cat`")
                else:
                    catdict = data.catdict
            else:
                raise ValueError('cat=True is only valid if data is a DataFile!')
        else:
            cat = None
    if isinstance(cat, pd.Series) or isinstance(cat, pd.DataFrame):
        cat = cat.values
    # Handle categorical dictionary
    if isinstance(catdict, bool):
        if catdict:
            if not isinstance(data, gs.DataFile):
                raise ValueError('catdict as a bool is only valid if data is a DataFile!')
            if data.catdict is None:
                raise ValueError('catdict as a bool is only valid if data is not None!')
            catdict = data.catdict
    # Variable
    # Handle data that is 2-D and/or a DataFile
    if isinstance(var, str):
        if isinstance(data, pd.DataFrame) or isinstance(data, gs.DataFile):
            if isinstance(cat, str):
                cat = data[cat]
            data = data[var]
        else:
            raise ValueError('var as a string is only valid if data is a DataFile or DataFrame!')
    elif isinstance(data, gs.DataFile):
        if isinstance(data.variables, str):
            data = data[data.variables]
        elif cat is not None:
            if isinstance(cat, str):
                data = data[cat]
            elif var is None and isinstance(cat, (np.ndarray, list)):
                data = cat
        elif len(data.columns) == 1:
            data = data.data
        else:
            raise ValueError('Could not coerce data (DataFile) into a 1D dataset!')
    # Get the xlabel if possible before converting to a numpy array
    if isinstance(data, pd.Series) or isinstance(data, pd.DataFrame):
        if xlabel is None:
            xlabel = gs.get_label(data)
        data = data.values
    elif isinstance(data, list):
        data = np.array(data)
    if isinstance(cat, (pd.Series, pd.DataFrame)):
        cat = cat.values
    # Should be numpy by now...
    if data.ndim > 1:
        if data.shape[1] > 1:
            raise ValueError('Could not coerce data into a 1D dataset!')
        else:
            data = data.flatten()
    # Handle Null values if needed
    idx = np.isnan(data)
    nullcnt = np.sum(idx)
    if nullcnt > 0:
        data = data[~idx]
        if weights is not None:
            weights = weights[~idx]
        if cat is not None:
            cat = cat[~idx]
    # Handle dictionary defaults
    if out_kws is None:
        out_kws = dict()
    # Set-up plot if no axis is supplied
    _, ax, _ = setup_plot(ax, figsize=figsize, aspect=False)
    # Infer some default parameters
    if weights is None:
        weights = np.ones(len(data)) / len(data)
    else:
        weights = weights / np.sum(weights)
    # Some quick error checks
    assert(np.all(weights) >= 0.0), 'weights less than 0 not valid'
    # Categories
    if isinstance(catdict, dict) and var is None:
        if not all([isinstance(float(i), float) for i in catdict.keys()]):
            raise ValueError('if catdict is dict., all keys should be an int/float!')
        # The bins are set to begin at the start of each category
        # bins go from 0.5 to (icat + 1) + 0.5
        # label is centered at (icat + 1)
        bins = np.arange(len(catdict) + 1) + 0.5
    if color is None and isinstance(catdict, dict):
        # Color each bin by the category color?
        if isinstance(Parameters['plotting.cmap_cat'], dict):
            temp = Parameters['plotting.cmap_cat']
            if list(sorted(temp.keys())) == list(sorted(catdict.keys())):
                color = temp
        else:
            color = catcmapfromcontinuous(Parameters["plotting.cmap"], len(catdict)).colors
    if isinstance(color, dict):
        if list(sorted(color.keys())) != list(sorted(catdict.keys())):
            raise ValueError(('if color is a dictionary, keys must align with '
                              'bins[:-1]! Consider using a single color.'))
        temp = color
        color = []
        for _, v in sorted(temp.items()):
            color.append(v)
    # Color setup
    if isinstance(color, int):
        # Grab a color from ``cat_vibrant`` if an integer is passed
        color = _cat_pastel_data[color % len(_cat_vibrant_data)]
    if not icdf:
        if color is None:
            color = Parameters['plotting.histogram_plot.facecolor']
        if edgecolor is None:
            edgecolor = Parameters['plotting.histogram_plot.edgecolor']
        if edgeweights is None:
            if "lw" in kwargs:
                edgeweights = kwargs.pop("lw")
            else:
                edgeweights = Parameters["plotting.histogram_plot.edgeweight"]
    else:
        if color is None and icdf:
            color = Parameters['plotting.histogram_plot.cdfcolor']
    plotdata = copy.deepcopy(data)
    plotweights = copy.deepcopy(weights)
    if xlim is not None:
        plotdata[data < xlim[0]] = xlim[0]
        plotdata[data > xlim[1]] = xlim[1]
    # Main plotting
    if icdf:

        def singlecdf(ax, data, weights, lower, upper, bins, color, label=None, **kwargs):
            """ local function to plot a single cdf """
            cdf_x, cdfvals = gs.cdf(data, weights=weights, lower=lower, upper=upper, bins=bins)
            # Matplotlib is a memory hog if to many points are used. Limit the number of points the CDF
            # is build with to 1000. The tails are given extra attention to make sure they are defined
            # nicely.
            if len(cdf_x) > 1000:
                cdfinterp = scipy.interpolate.interp1d(x=cdfvals, y=cdf_x)
                cdfvals = np.concatenate([np.arange(cdfvals.min(), 0.1, 0.001),
                                          np.arange(0.1, 0.9, 0.01),
                                          np.arange(0.9, cdfvals.max(), 0.001)])
                cdf_x = []
                for val in cdfvals:
                    cdf_x.append(cdfinterp(val))
                cdf_x = np.array(cdf_x)
            fig = ax.plot(cdf_x, cdfvals, color=color, label=label, **kwargs)
            return fig

        if catdict is not None:
            if var is not None:
                stat_blk = False
                for icat, c in enumerate(catdict):
                    clr = color[icat]
                    catidx = cat == c
                    fig = singlecdf(ax, plotdata[catidx], plotweights[catidx], lower, upper, bins, clr,
                                    label=catdict[c], **kwargs)
            else:
                raise ValueError("`icdf=True` and `catdict` only makes sense with a `var` defined")
        else:
            fig = singlecdf(ax, plotdata, plotweights, lower, upper, bins, color, **kwargs)
        if ylim is None:
            ylim = (0, 1.0)
    else:
        if bins is None:
            bins = Parameters['plotting.histogram_plot.histbins']
        label = kwargs.pop("label", None)
        if bins is None:
            if len(plotdata) < 200:
                bins = 20
            elif len(plotdata) < 500:
                bins = 25
            else:
                bins = 30
        if logx:
            if catdict is not None:
                raise ValueError('Cannot have logx with catdict!')
            if xlim is None:
                minv = np.log10(max(plotdata.min(), 1e-10))
                maxv = np.log10(plotdata.max())
            else:
                minv = np.log10(max(xlim[0], 1e-10))
                maxv = np.log10(xlim[1])
            if np.isnan([minv, maxv]).any():
                raise ValueError('ERROR converting your data to log base! are there negatives?')
            bins = np.logspace(minv, maxv, bins)
        if catdict is not None:
            if var is None:
                for icat, cat in enumerate(catdict):
                    plotdata[data == cat] = icat + 1
                histclr = None
            else:
                # generate lists of data per cat
                plotdata = [plotdata[cat == c] for c in catdict]
                plotweights = [weights[cat == c] for c in catdict]
                label = list(catdict.values())
                histtype = kwargs.pop("histtype", "stepfilled")
                stat_blk = False
                if "stacked" not in kwargs:
                    kwargs["stacked"] = True
                histclr = color
        histtype = kwargs.pop("histtype", "bar")
        if not isinstance(color, list):
            ax.hist(plotdata, bins, weights=plotweights, color=color, edgecolor=edgecolor,
                    histtype=histtype, label=label, lw=edgeweights, **kwargs)
        else:
            _, _, patches = ax.hist(plotdata, bins, weights=plotweights, histtype=histtype,
                                    color=histclr, edgecolor=edgecolor,
                                    label=label, lw=edgeweights, **kwargs)
            try:
                for patch, clr in zip(patches, color):
                    patch.set_facecolor(clr)
            except (AttributeError, ValueError):
                pass
        if catdict is not None and label_count:
            nd = len(data)
            for icat, cat in enumerate(catdict):
                count = np.count_nonzero(data == cat)
                pcat = (weights * (data == cat).astype(float)).sum()
                ax.text(icat + 1, pcat, count, ha="center", va="bottom")
    # Summary stats
    if stat_blk is None:
        stat_blk = Parameters['plotting.histogram_plot.stat_blk']
    if stat_xy is None:
        if icdf:
            stat_xy = Parameters['plotting.histogram_plot.stat_xy_cdf']
        else:
            stat_xy = Parameters['plotting.histogram_plot.stat_xy']
    if stat_blk:
        if sigfigs is None:
            sigfigs = Parameters['plotting.sigfigs']
        if roundstats is None:
            roundstats = Parameters['plotting.roundstats']
        if stat_ha is None:
            stat_ha = Parameters['plotting.stat_ha']
        if stat_linespacing is None:
            stat_linespacing = Parameters['plotting.stat_linespacing']
        if stat_linespacing is None:
            stat_linespacing = 1.0
        # Force no bins and upper/lower for median
        cdf_x, cdfvals = gs.cdf(data, weights=weights)
        # Currently defined statistics, possible to add more quite simply
        if np.mean(data) == 0:
            cdata = float("nan")
        elif roundstats:
            cdata = round((np.std(data) / np.mean(data)), sigfigs)
        else:
            cdata = gs.round_sigfig((np.std(data) / np.mean(data)), sigfigs)
        if roundstats:
            mean = round(gs.weighted_mean(data, weights), sigfigs)
            median = round(gs.percentile_from_cdf(cdf_x, cdfvals, 50.0), sigfigs)
            stdev = round(np.sqrt(gs.weighted_variance(data, weights)), sigfigs)
            minval = round(np.min(data), sigfigs)
            maxval = round(np.max(data), sigfigs)
            upquart = round(np.percentile(data, 75), sigfigs)
            lowquart = round(np.percentile(data, 25), sigfigs)
            p10 = round(np.percentile(data, 10), sigfigs)
            p90 = round(np.percentile(data, 90), sigfigs)
        else:
            mean = gs.round_sigfig(gs.weighted_mean(data, weights), sigfigs)
            median = gs.round_sigfig(gs.percentile_from_cdf(cdf_x, cdfvals, 50.0), sigfigs)
            stdev = gs.round_sigfig(np.sqrt(gs.weighted_variance(data, weights)), sigfigs)
            minval = gs.round_sigfig(np.min(data), sigfigs)
            maxval = gs.round_sigfig(np.max(data), sigfigs)
            upquart = gs.round_sigfig(np.percentile(data, 75), sigfigs)
            lowquart = gs.round_sigfig(np.percentile(data, 25), sigfigs)
            p10 = gs.round_sigfig(np.percentile(data, 10), sigfigs)
            p90 = gs.round_sigfig(np.percentile(data, 90), sigfigs)
        statistics = {'mean': (r'$m = %g$' % mean),
                      'median': (r'$x_{{50}} = %g$' % median),
                      'count': ('$n = %i$' % len(data)),
                      'count_trimmed': ('$n_{trim} = %i$' % nullcnt),
                      'stdev': (r'$\sigma = %g$' % stdev),
                      'cvar': ('$CV = %g$' % cdata),
                      'min': ('$x_{{min}} = %g$' % minval),
                      'max': ('$x_{{max}} = %g$' % maxval),
                      'upquart': ('$x_{{75}} = %g$' % upquart),
                      'lowquart': ('$x_{{25}} = %g$' % lowquart),
                      'p10': ('$x_{{10}} = %g$' % p10),
                      'p90': ('$x_{{90}} = %g$' % p90)}
        # Default statistic sets
        if stat_blk == 'varlabel' and 'label' in kwargs:
            statistics['varlabel'] = kwargs['label']
        statsets = {'minimal': ['count', 'mean', 'median', 'stdev'],
                    'all': ['count', 'mean', 'stdev', 'cvar', 'max', 'upquart', 'median',
                            'lowquart', 'min'],
                    'varlabel': ['varlabel', 'count', 'mean', 'stdev', 'cvar', 'max', 'upquart',
                                 'median', 'lowquart', 'min'],
                    'none': None}
        # Use a default statistic set
        if isinstance(stat_blk, bool) and stat_blk:
            stat_blk = 'all'
        if isinstance(stat_blk, str):
            if stat_blk in statsets:
                stat_blk = statsets[stat_blk]
            else:
                print('WARNING: stats value of: "' + stat_blk + '" does not exist - '
                      'default to no stats')
                stat_blk = None
        # Use a supplied statistic set, but check for bad ones
        else:
            badstats = [s for s in stat_blk if s not in statistics]
            stat_blk = [s for s in stat_blk if s in statistics]
            for badstat in badstats:
                print('WARNING: stats value of: "' + badstat + '" does not exist - '
                      'It was removed from summary statistics list')
        # Form the stats string
        if stat_blk:
            if nullcnt != 0:
                stat_blk.insert(stat_blk.index('count') + 1, 'count_trimmed')
            stat_blk = [statistics[s] for s in stat_blk]
            txtstats = '\n'.join(stat_blk)
            if len(np.unique(weights)) > 1:
                txtstats = txtstats + '\n\nweights used'
            if stat_xy[1] > 0.5:
                va = 'top'
            else:
                va = 'bottom'
            # Set the stat_fontsize
            stat_fontsize = _set_stat_fontsize(stat_fontsize)
            ax.text(stat_xy[0], stat_xy[1], txtstats, va=va, ha=stat_ha, transform=ax.transAxes,
                    fontsize=stat_fontsize, linespacing=stat_linespacing)
    # Label as required
    if icdf:
        ylabel = 'Cumulative Distribution Function'
    elif 'density' in kwargs:
        ylabel = 'Probability Density Function (PDF)'
    else:
        ylabel = 'Frequency'
    ax = format_plot(ax, xlabel, ylabel, title, axis_xy=axis_xy, xlim=xlim, ylim=ylim, logx=logx)
    if catdict is not None and var is None:
        ticlocs = [i + 1 for i in range(len(catdict.keys()))]
        ax.set_xticks(ticlocs)
        ax.set_xticklabels(catdict.values())
        ax.set_xlim(0.25, len(catdict) + 0.75)
    elif catdict is not None and var is not None:
        ax.legend()
    _format_tick_labels(ax, rotateticks)
    # format_plot doesn't handle some specialized axis_xy and grid requirements
    # for histogram_plot...
    if icdf:
        # Ensure that we have top spline, in case it was removed above
        ax.spines['top'].set_visible(True)
        _format_grid(ax, grid, below=False)
    else:
        # The grid should be below for a histogram
        _format_grid(ax, grid, below=True)
    # Export figure
    if output_file or ('pdfpages' in out_kws):
        gs.export_image(output_file, **out_kws)
    return ax
