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


-- | Quantify the diversity of a population
--   
--   Find the diversity of a collection of entities, mainly for use with
--   fasta sequences.
@package diversity
@version 0.8.1.0


-- | Collection of functions pertaining statistics needed in the library
module Math.Diversity.Statistics

-- | Get the median, adapted from
--   <a>http://rosettacode.org/wiki/Averages/Median#Haskell</a>, but FIXED
--   due to zero indexing. Also made sure that it is sorted
median :: [Double] -> Maybe Double

-- | Get the median and median absolute deviation (MAD) of a list of
--   numbers
medmad :: [Double] -> Maybe (Double, Double)


-- | Collection of functions pertaining to getting random samples from - a
--   population
module Math.Diversity.RandomSampling

-- | Gets a random sampling by getting either the requested amount either
--   directly or through the inverse (for speed)
subsample :: (Eq a, Ord a) => Int -> Int -> StdGen -> [a] -> [a]

-- | Get the number of types of entities in a subsample
subsampleSpecies :: (Eq a, Ord a) => Int -> Int -> StdGen -> [a] -> Int

-- | Repeat the sampling to get a median and MAD value for the runs for the
--   expected species counts
subsampleES :: (Eq a, Ord a) => Int -> Int -> Int -> [a] -> IO (Maybe (Double, Double))


-- | Collects all application specific types.
module Math.Diversity.Types
type Fragment = String
type Sample = String
type Position = Int
type Diversity = Double
type Order = Double
type Label = String
type Window = Int
type FrequencyMap = Map (Sample, Fragment) Int

-- | At each position we have a collection of fragments to find the
--   diversity of
type PositionMap = Map Position FrequencyMap

-- | At each position we have a diversity
type DiversityMap = Map Position Diversity


-- | Collection of functions for the collection of fragments for the
--   diversity calculations.
module Math.Diversity.GenerateDiversity

-- | Generates fragment list from string of "win" length. This version
--   differs from normal as it takes a tuple with the position as the first
--   entry. Is in tail recursive form
fragmentPos :: Bool -> Int -> [(Position, Char)] -> [(Position, Fragment)]

-- | Generate the frequency from a FastaSequence
generatePositionMap :: Bool -> Bool -> Int -> Int -> Bool -> Window -> FastaSequence -> PositionMap


-- | Collection of functions pertaining to finding the diversity of
--   samples.
module Math.Diversity.Diversity

-- | Takes two strings, returns Hamming distance
hamming :: String -> String -> Int

-- | Returns the richness of the observed data
richness :: (Ord a, Ord b) => Map (a, b) c -> Int

-- | Returns the diversity of a list of things
diversity :: (Ord a) => Double -> [a] -> Double

-- | Returns the diversity of a map of the species and how many times it
--   appears
diversityOfMap :: (Ord a) => Double -> Map a Int -> Double

-- | Returns the diversity of a map of the species and how many times it
--   appears, along with the contribution of each species.
diversityOfMapWithContribution :: (Ord a) => Double -> Map a Int -> (Double, Map a Double)

-- | Returns the chao1 estimator of a map of the species and how many times
--   it appears
chao1 :: (Ord a) => Map a Int -> Double

-- | Returns the chao2 estimator of a map of the sample labeled species
--   (sample, species) and how many times it appears. This will calculate
--   the overlap for you, so if you don't have the number of times it
--   appears it does not matter, you can set it to 1 and get the same
--   result as it's all about overlapping samples.
chao2 :: (Ord a, Ord b) => Map (a, b) Int -> Double

-- | Returns the chao1 estimator variance of a map of the species and how
--   many times each one appears.
chao1Var :: (Ord a) => Map a Int -> Double

-- | Returns the chao2 estimator variance of a map of the sample labeled
--   species (sample, species) and how many times it appears.
chao2Var :: (Ord a, Ord b) => Map (a, b) Int -> Double

-- | Returns the rarefaction curve for each position in a list
rarefactionCurve :: Bool -> Int -> Integer -> Integer -> Integer -> Map (Sample, Fragment) Int -> IO [(Int, Maybe (Double, Double))]

-- | Returns the rarefaction curve for each position in a list
rarefactionSampleCurve :: Bool -> Int -> Int -> Int -> Map (Sample, Fragment) Int -> IO [(Int, Maybe (Double, Double))]

-- | Calculates the percent of the curve that is above 95% of height of the
--   curve
rarefactionViable :: [Double] -> Double

-- | Returns the number of individuals needed to get the proportion g of
--   the estimated total richness of the assemblage. Sobs / Sest &lt; g
--   &lt; 1
individualG :: Double -> Map (Sample, Fragment) Int -> Double

-- | Returns the number of samples needed to get the proportion g of the
--   estimated total richness of the assemblage. Sobs / Sest &lt; g &lt; 1
sampleG :: Double -> Map (Sample, Fragment) Int -> Double

-- | Returns the number of samples needed before a new sample returns less
--   than x new species. Warning, goes forever until threshold is met!
minRarefaction :: Bool -> Bool -> Int -> Map (Sample, Fragment) Int -> Double -> Int -> IO Int


-- | Collection of functions for the printing of data (converting data
--   structures into strings for use with writing to output files).
module Math.Diversity.Print
printDiversity :: Label -> Order -> Window -> PositionMap -> String
printRarefaction :: Bool -> Double -> Label -> Window -> PositionMap -> IO String
printRarefactionCurve :: Bool -> Bool -> Bool -> Int -> Int -> Int -> Int -> Label -> Window -> PositionMap -> IO String
