"""
Plotting functions.
"""

from __future__ import absolute_import
import matplotlib.pyplot as plt
import numpy as np


def hhist(items, title=None, axislabel=None, color=None, height=None, width=None, reverse=False):
    """
    Plots a horizontal histogram of values and frequencies.

    Arguments:
        items (iterable[any])     => A list of objects.
        title (Optional[str])     => A title for the resulting histogram.
        axislabel (Optional[str]) => A label for the y-axis that lists the unique items in 
                                     the parameter list.
        color (Optional[str])     => A matplotlib color value for coloring the histogram 
                                     (default: matplotlib's default plot color, a royal blue)
        height (Optional[int])    => A height for the plot (default: 10)
        width (Optional[int])     => A width for the plot (default: 20)
        reverse (Optional[bool])  => Whether or not the histogram should plot from top to bottom in 
                                     order of decreasing frequency or the reverse of that.

    Returns:
        Void, but a matplotlib figure should be produced (type=None).
    """

    # Parse the unique items and their counts.
    unique_items, item_counts = np.unique(items, return_counts=True)

    # Sort the items by frequency.
    item_counts, unique_items = zip(*sorted(zip(item_counts, unique_items), reverse=reverse))

    # Plot the frequencies.
    pos = np.arange(len(unique_items)) + 0.5
    plt.figure(figsize=((width or 20), (height or 10)))
    plt.barh(pos, item_counts, align='center', color=color)
    plt.yticks(pos, unique_items)
    plt.xlabel('Frequency')
    if axislabel:
        plt.ylabel(axislabel)
    if title:
        plt.title(title)

    plt.show()

