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


-- | Modules for parsing, generating and manipulating AB1 files.
--   
--   This library provides functionality for parsing, modifying, writing
--   and generating ABIF files
--   
--   Any AB1 file conforming to the standard at
--   <a>http://www6.appliedbiosystems.com/support/software_community/ABIF_File_Format.pdf</a>
--   should be supported.
--   
--   This library also support generating a minimal ABIF file from a FASTA
--   input sequence.
--   
--   A basic terminal application that can dump and generate AB1s is
--   included. See
--   <a>https://github.com/hyraxbio/hyraxAbif/blob/master/app/Main.hs</a>
--   
--   See
--   
--   <ul>
--   <li><a>Hyrax.Abif.Generate</a> for generate ABIF files from FASTA
--   inputs</li>
--   <li><a>Hyrax.Abif.Read</a> for parsing ABIF files</li>
--   <li><a>Hyrax.Abif.Write</a> for creating/updating ABIF files</li>
--   <li><a>Hyrax.Abif</a> for the core types</li>
--   <li><a>Examples</a> for examples</li>
--   </ul>
@package hyraxAbif
@version 0.2.3.10


-- | Simple examples showing how to use this library Also see
--   <a>Hyrax.Abif.Generate</a> to see how a minimal AB1, that recall and
--   phred can read, is generated
--   
--   <ul>
--   <li><a>Examples.ReadAb1</a></li>
--   <li><a>Examples.AddComment</a></li>
--   <li><a>Examples.RemoveComments</a></li>
--   </ul>
module Examples


-- | This module contains the core types for working with AB1 files.
--   
--   See
--   
--   <ul>
--   <li><a>Source code on github</a></li>
--   <li><a>The ABIF spec</a></li>
--   </ul>
module Hyrax.Abif

-- | A single ABIF
data Abif
Abif :: !Header -> !Directory -> ![Directory] -> Abif
[aHeader] :: Abif -> !Header
[aRootDir] :: Abif -> !Directory
[aDirs] :: Abif -> ![Directory]

-- | ABIF header
data Header
Header :: !Text -> !Int -> Header
[hName] :: Header -> !Text
[hVersion] :: Header -> !Int

-- | ABIF directory entry. The <a>dData</a> field contains the data for the
--   entry
data Directory
Directory :: !Text -> !Int -> !ElemType -> !Int -> !Text -> !Int -> !Int -> !Int -> !Int -> !ByteString -> ![Text] -> Directory

-- | Tag name
[dTagName] :: Directory -> !Text

-- | Tag number, see e.g. how DATA entries use this
[dTagNum] :: Directory -> !Int

-- | Type of an element
[dElemType] :: Directory -> !ElemType

-- | Integer value of <a>dElemType</a>
[dElemTypeCode] :: Directory -> !Int

-- | Description of <a>dElemType</a>
[dElemTypeDesc] :: Directory -> !Text

-- | Size in bytes of each element
[dElemSize] :: Directory -> !Int

-- | Number of elements in the data. See the spec per data type. E.g. for a
--   string this is the number of characters
[dElemNum] :: Directory -> !Int

-- | Number of bytes in the data
[dDataSize] :: Directory -> !Int

-- | Offset of this directory entry's data in the file. For data that is
--   four bytes or less, the data itself is stored in this field. This
--   value will be recalculated when writing an ABIF so you do not need to
--   manually set it.
[dDataOffset] :: Directory -> !Int

-- | The entry's data
[dData] :: Directory -> !ByteString

-- | Optinal debug data, populated by <a>getDebug</a> when a ABIF is parsed
[dDataDebug] :: Directory -> ![Text]

-- | Type of the elements in a directory entry. See the spec for details on
--   each type if required.
data ElemType
ElemUnknown :: ElemType
ElemCustom :: ElemType
ElemByte :: ElemType
ElemChar :: ElemType
ElemWord :: ElemType
ElemShort :: ElemType
ElemLong :: ElemType
ElemFloat :: ElemType
ElemDouble :: ElemType
ElemDate :: ElemType
ElemTime :: ElemType
ElemPString :: ElemType
ElemCString :: ElemType
ElemThumb :: ElemType
ElemBool :: ElemType
ElemRationalUnsupported :: ElemType
ElemBCDUnsupported :: ElemType
ElemPointUnsupported :: ElemType
ElemRectUnsupported :: ElemType
ElemVPointUnsupported :: ElemType
ElemVRectUnsupported :: ElemType
ElemTagUnsupported :: ElemType
ElemDeltaCompUnsupported :: ElemType
ElemLZWCompUnsupported :: ElemType
ElemCompressedDataUnsupported :: ElemType
ElemRoot :: ElemType

-- | Get an <a>ElemType</a> from a elem type code
getElemType :: Int -> ElemType

-- | Get the description for an <a>ElemType</a>
describeElemType :: Int -> (ElemType, Text)
instance GHC.Classes.Eq Hyrax.Abif.Abif
instance GHC.Show.Show Hyrax.Abif.Abif
instance GHC.Classes.Eq Hyrax.Abif.Directory
instance GHC.Show.Show Hyrax.Abif.Directory
instance GHC.Classes.Eq Hyrax.Abif.ElemType
instance GHC.Show.Show Hyrax.Abif.ElemType
instance GHC.Classes.Eq Hyrax.Abif.Header
instance GHC.Show.Show Hyrax.Abif.Header


-- | Functionality for reading FASTA files
module Hyrax.Abif.Fasta

-- | FASTA data
data Fasta
Fasta :: !Text -> !Text -> Fasta

-- | Name
[fastaName] :: Fasta -> !Text

-- | Data
[fastaRead] :: Fasta -> !Text

-- | Parse the data for a single FASTA into a list of <a>Fasta</a> values.
--   Single and multi-line FASTAs are supported. Used by
--   <a>Hyrax.Abif.Generate</a> to read weighted-FASTAs
parseFasta :: Text -> Either Text [Fasta]
instance GHC.Classes.Eq Hyrax.Abif.Fasta.Fasta
instance GHC.Show.Show Hyrax.Abif.Fasta.Fasta


-- | Functionality for reading and parsing AB1 files
--   
--   e.g.
--   
--   <pre>
--   abif' &lt;- readAbif "example.ab1"
--   
--   case abif' of
--     Left e -&gt; putStrLn $ "error reading ABIF: " &lt;&gt; e
--     Right abif -&gt; print $ clearAbif abif
--   </pre>
module Hyrax.Abif.Read

-- | Read and parse an AB1 file
readAbif :: FilePath -> IO (Either Text Abif)

-- | Parse an AB1 from a <a>ByteString</a>
getAbif :: ByteString -> Either Text Abif

-- | Removes all data from a directory entry. This will probably only be
--   useful when trying to show an ABIF value
clear :: Directory -> Directory

-- | Removes all data from the ABIF's directories
clearAbif :: Abif -> Abif

-- | Populate the directory entry with debug data (into <a>dDataDebug</a>).
--   This is done for selected types only, e.g. for strings so that
--   printing the structure will display readable/meaningfull info
getDebug :: Directory -> Directory

-- | Parse a <a>ElemPString</a>
getPString :: Get Text

-- | Parse a <a>ElemCString</a>
getCString :: Int -> Get Text

-- | Parse the ABIF <a>Header</a>
getHeader :: Get Header

-- | Parse the root (<a>Header</a> and <a>Directory</a>)
getRoot :: ByteString -> Get (Header, Directory)

-- | Parse all the directoy entries
getDirectories :: ByteString -> [Directory] -> Int -> Get [Directory]

-- | Parse a single <a>Directory</a> entry and read its data
getDirectory :: ByteString -> Get Directory


-- | Example of reading a ABIF file. See other examples in <a>Examples</a>
module Examples.ReadAb1

-- | Read and print a ABIF file
readAbif :: IO ()


-- | Functionality for writing AB1 files. See <a>generateAb1</a> for an
--   example of how to create an <tt>Ab1</tt>
module Hyrax.Abif.Write

-- | Write an <a>Abif</a> to a <a>ByteString</a>
createAbifBytes :: Abif -> ByteString

-- | Write an <a>Abif</a> to a file
writeAbif :: FilePath -> Abif -> IO ()

-- | Create the <a>Abif</a> using <a>Data.Binary</a>
putAbif :: Abif -> Put

-- | Write <a>Text</a>
putTextStr :: Text -> Put

-- | Write a <a>Header</a>
putHeader :: Header -> Put

-- | Write a <a>Directory</a>
putDirectory :: Int -> Directory -> Put

-- | Create a <a>Header</a>
mkHeader :: Header

-- | Create the root <a>Directory</a> entry
mkRoot :: Directory

-- | Create a data (DATA) <a>Directory</a> entry and array of
--   <a>ElemShort</a> data
mkData :: Int -> [Int16] -> Directory

-- | Create a comment <a>Directory</a> entry and <a>ElemPString</a> data
mkComment :: Text -> Directory

-- | Create a sample name (SMPL) <a>Directory</a> entry and
--   <a>ElemPString</a> data
mkSampleName :: Text -> Directory

-- | Create a base order (FWO_) <a>Directory</a> entry data
mkBaseOrder :: Base -> Base -> Base -> Base -> Directory

-- | Create a lane (LANE) <a>Directory</a> entry and data
mkLane :: Int16 -> Directory

-- | Create a called bases (PBAS) <a>Directory</a> entry and data
mkCalledBases :: Text -> Directory

-- | Create a mobility file name (PDMF) <a>Directory</a> entry and
--   <a>ElemPString</a> data
mkMobilityFileName :: Int -> Text -> Directory

-- | Create a signal strength (S/N%) <a>Directory</a> entry and data
mkDyeSignalStrength :: Int16 -> Int16 -> Int16 -> Int16 -> Directory

-- | Create a peak locations (PLOC) <a>Directory</a> entry and array of
--   <a>ElemShort</a> data
mkPeakLocations :: [Int16] -> Directory

-- | Add a directory to an <a>Abif</a>
addDirectory :: Abif -> Directory -> Abif

-- | Used to specify the base order for the FWO directry entry, see
--   <a>mkBaseOrder</a>
data Base
BaseA :: Base
BaseC :: Base
BaseG :: Base
BaseT :: Base


-- | Functionality for generating AB1 files from an input FASTA. These AB1s
--   are supported by both PHRED and recall, if you are using other
--   software you may need to add additional required sections.
--   
--   <h1>Weighted reads</h1>
--   
--   The input FASTA files have "weighted" reads. The name for each read is
--   an value between 0 and 1 which specifies the height of the peak
--   relative to a full peak.
--   
--   <h2>Single read</h2>
--   
--   The most simple example is a single FASTA with a single read with a
--   weight of 1
--   
--   <pre>
--   &gt; 1
--   ACTG
--   </pre>
--   
--   
--   The chromatogram for this AB1 shows perfect traces for the input
--   <tt>ACTG</tt> nucleotides with a full height peak.
--   
--   <h2>Mixes &amp; multiple reads </h2>
--   
--   The source FASTA can have multiple reads, which results in a
--   chromatogram with mixes
--   
--   <pre>
--   &gt; 1
--   ACAG
--   &gt; 0.3
--   ACTG
--   </pre>
--   
--   
--   There is an <tt>AT</tt> mix at the third nucleotide. The first read
--   has a weight of 1 and the second a weight of 0.3. The chromatogram
--   shows the mix and the <tt>T</tt> with a lower peak (30% of the
--   <tt>A</tt> peak)
--   
--   <h2>Summing weights</h2>
--   
--   <ul>
--   <li>The weigh of a read specifies the intensity of the peak from 0 to
--   1.</li>
--   <li>Weights for each position are added to a maximum of 1 per
--   nucleotide</li>
--   <li>You can use `_` as a "blank" nucleotide, in which only the
--   nucleotides from other reads will be considered</li>
--   </ul>
--   
--   E.g.
--   
--   <pre>
--   &gt; 1
--   ACAG
--   &gt; 0.3
--   _GT
--   &gt; 0.2
--   _G
--   </pre>
--   
--   
--   <h2>Reverse reads</h2>
--   
--   A weighted FASTA can represent a reverse read. To do this add a
--   <tt>R</tt> suffix to the weight. The data you enter should be entered
--   as if it was a forward read. This data will be complemented and
--   reversed before writing to the ABIF
--   
--   E.g.
--   
--   <pre>
--   &gt; 1R
--   ACAG
--   </pre>
--   
--   See README.md for additional details and examples
module Hyrax.Abif.Generate

-- | Generate a set of AB1s. One for every FASTA found in the source
--   directory
generateAb1s :: FilePath -> FilePath -> IO ()

-- | Create the <a>ByteString</a> data for an AB1 given the data from a
--   weighted FASTA (see <a>readWeightedFasta</a>)
generateAb1 :: (Text, [(Double, Text)]) -> ByteString

-- | Read a weighted FASTA file. See the module documentation for details
--   on the format of the weighted FASTA Reads with a weight followed by an
--   <tt>R</tt> are reverse reads, and the AB1 generated will contain the
--   complemeted sequence.
--   
--   e.g. weighted FASTA
--   
--   <pre>
--   &gt; 1
--   ACAG
--   &gt; 0.3
--   _GT
--   &gt; 0.2
--   _G
--   </pre>
--   
--   The result data has the type
--   
--   <pre>
--   [(<a>Double</a>, <a>Text</a>)]
--     ^        ^
--     |        |
--     |        +---- read 
--     | 
--     +---- weight
--   </pre>
readWeightedFasta :: ByteString -> Either Text [(Double, Text)]

-- | Given a set of nucleotides get the IUPAC ambiguity code
iupac :: [[Char]] -> [Char]

-- | Convert a IUPAC ambiguity code to the set of nucleotides it represents
unIupac :: Char -> [Char]

-- | Return the complement of a nucelotide string
complementNucleotides :: Text -> Text
instance GHC.Show.Show Hyrax.Abif.Generate.TraceData


-- | Example showing how to remove all comments from an ABIF file. See
--   other examples in <a>Examples</a>
module Examples.RemoveComments

-- | Remove all comments from an existing file
removeComments :: IO ()


-- | Example showing how to add a comment to an existing AB1 file. See
--   other examples in <a>Examples</a>
module Examples.AddComment

-- | Add a comment to an existing AB1 file
addComment :: IO ()
