-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Easily create histograms of your data
@package Histogram
@version 0.1


-- | This package easily lets you create high quality histogram plots from
--   your data in Haskell. It automatically bins your data using whichever
--   binning strategy you'd like, then plots the data. It uses the gnuplot
--   package to do all the actual graphing, so any options that work for
--   making gnuplot pretty will also work here.
--   
--   Here's a brief example that should get you going:
--   
--   <pre>
--   import qualified Graphics.Gnuplot.Frame.OptionSet as Opts
--   
--   input = [1,0.2,0.23,0.15,0.1,0.88,0.89,0.33,0.05,0.33,0.45,0.99,0.01,0.01,0.5]
--   
--   simple = do
--       let hist = histogram binSturges input
--       plot "simple.png" hist
--   
--   advanced = do
--       let hist = histogram binSqrt input
--       let opts = Opts.title "I'm a histogram!" $ 
--                  Opts.yLabel "Why?" $ 
--                  Opts.xLabel "Because!" $ 
--                  defOpts hist
--       plotAdv "advanced.eps" opts hist
--   </pre>
module Graphics.Histogram

-- | Creates a histogram that's ready for plotting. Call it with one of the
--   binning strategies that is appropriate to the type of data you have.
--   If you don't know, then try using binSturges.
histogram :: BinningStrat -> [Double] -> Histogram

-- | Create a histogram by specifying the exact bin size. You probably
--   don't want to use this function, and should use histogram with an
--   appropriate binning strategy.
histogramBinSize :: Double -> [Double] -> Histogram

-- | Create a histogram by specifying the exact number of bins You probably
--   don't want to use this function, and should use histogram with an
--   appropriate binning strategy.
histogramNumBins :: Int -> [Double] -> Histogram

-- | Sturges' binning strategy is the least computational work, but
--   recommended for only normal data
binSturges :: BinningStrat

-- | Doane's binning strategy extends Sturges' for non-normal data. It
--   takes a little more time because it must calculate the kurtosis
--   (peakkiness) of the distribution
binDoane :: BinningStrat

-- | Using the sqrt of the number of samples is not supported by any
--   theory, but is commonly used by excell and other histogram making
--   software
binSqrt :: BinningStrat

-- | Scott's rule is the optimal solution for normal data, but requires
--   more computation than Spurges'
binScott :: BinningStrat

-- | The Freedman-Diaconis rule is less susceptible to outliers than
--   Scott's and is also used on "normalish" data
binFreedmanDiaconis :: BinningStrat

-- | Options for a plot, as specified in the gnuplot library
type PlotOptions = T (T Int Double)

-- | Plots your histogram. If the filename is empty, then it will open a
--   window and display the histogram on screen. Otherwise, the filetype is
--   automatically determined by the extension. Supported file types are
--   .png, .svg (vector graphics), and .eps (PostScript).
plot :: String -> Histogram -> IO ExitCode

-- | Just like <a>plot</a>, except you may specify additional options from
--   the gnuplot library. For example, you could add labels and a title.
plotAdv :: String -> PlotOptions -> Histogram -> IO ExitCode

-- | Default plot display parameters
defOpts :: Histogram -> PlotOptions