| Copyright | (c) Dominik Schrempf 2020 |
|---|---|
| License | GPL-3.0-or-later |
| Maintainer | dominik.schrempf@gmail.com |
| Stability | unstable |
| Portability | portable |
| Safe Haskell | None |
| Language | Haskell2010 |
ELynx.Tools
Contents
Description
Creation date: Sat Mar 21 13:56:03 2020.
A large collection of tools.
Synopsis
- alignRightWith :: Char -> Int -> ByteString -> ByteString
- alignRight :: Int -> ByteString -> ByteString
- alignLeftWith :: Char -> Int -> ByteString -> ByteString
- alignLeft :: Int -> ByteString -> ByteString
- splitGen :: PrimMonad m => Int -> Gen (PrimState m) -> m [Gen (PrimState m)]
- getChunks :: Int -> Int -> [Int]
- eps :: Double
- precision :: Int
- allEqual :: Eq a => [a] -> Bool
- allNearlyEqualWith :: Double -> [Double] -> Bool
- allNearlyEqual :: [Double] -> Bool
- nearlyEqWith :: Double -> Double -> Double -> Bool
- eps :: Double
- nearlyEq :: Double -> Double -> Bool
- (=~=) :: Double -> Double -> Bool
- nearlyEqListWith :: Double -> [Double] -> [Double] -> Bool
- nearlyEqList :: [Double] -> [Double] -> Bool
- nearlyEqVecWith :: Double -> Vector R -> Vector R -> Bool
- nearlyEqVec :: Vector R -> Vector R -> Bool
- nearlyEqMatWith :: Double -> Matrix R -> Matrix R -> Bool
- nearlyEqMat :: Matrix R -> Matrix R -> Bool
- getOutFilePath :: forall a. Reproducible a => String -> ELynx a (Maybe FilePath)
- openFile' :: Force -> FilePath -> IOMode -> IO Handle
- readGZFile :: FilePath -> IO ByteString
- writeGZFile :: Force -> FilePath -> ByteString -> IO ()
- out :: Reproducible a => String -> ByteString -> String -> ELynx a ()
- outHandle :: Reproducible a => String -> String -> ELynx a Handle
- runParserOnFile :: Parser a -> FilePath -> IO (Either String a)
- parseFileWith :: Parser a -> FilePath -> IO a
- parseIOWith :: Parser a -> IO a
- parseFileOrIOWith :: Parser a -> Maybe FilePath -> IO a
- parseStringWith :: Parser a -> String -> a
- parseByteStringWith :: Parser a -> ByteString -> a
- matrixSeparateSymSkew :: Matrix R -> (Matrix R, Matrix R)
- matrixSetDiagToZero :: Matrix R -> Matrix R
- dispv :: Int -> Vector R -> String
- dispm :: Int -> Matrix R -> String
- dispmi :: Int -> Int -> Matrix R -> String
- sortListWithIndices :: Ord a => [a] -> [(a, Int)]
- randomInsertList :: PrimMonad m => a -> [a] -> Gen (PrimState m) -> m [a]
- shuffle :: PrimMonad m => [a] -> Gen (PrimState m) -> m [a]
- shuffleN :: [a] -> Int -> GenIO -> IO [[a]]
- grabble :: PrimMonad m => [a] -> Int -> Int -> Gen (PrimState m) -> m [[a]]
- logNewSection :: MonadLogger m => Text -> m ()
- eLynxWrapper :: forall a b. (Eq a, Show a, Reproducible a, ToJSON a) => Arguments a -> (Arguments a -> Arguments b) -> ELynx b () -> IO ()
- compose :: [a -> a] -> a -> a
- allValues :: (Bounded a, Enum a) => [a]
- horizontalConcat :: [[[a]]] -> [[a]]
- harmonic :: Int -> Double
- roundN :: Int -> Double -> Double
- logHeader :: String -> [String] -> IO String
- logFooter :: IO String
- data Verbosity
- toLogLevel :: Verbosity -> LogLevel
- newtype Force = Force Bool
- forceOpt :: Parser Force
- data GlobalArguments = GlobalArguments {}
- globalArguments :: Parser GlobalArguments
- data Seed
- seedOpt :: Parser Seed
- data Arguments a = Arguments {
- global :: GlobalArguments
- local :: a
- parseArguments :: forall a. Reproducible a => IO (Arguments a)
- type ELynx a = ReaderT (Arguments a) (LoggingT IO)
- class Reproducible a where
- getReproductionHash :: forall a. Reproducible a => Reproduction a -> String
- data Reproduction a = Reproduction {}
- writeReproduction :: forall a. (Eq a, Show a, Reproducible a, ToJSON a) => String -> a -> IO ()
- hashFile :: FilePath -> IO ByteString
- createCommandReproducible :: forall a b. Reproducible a => (a -> b) -> Mod CommandFields b
- createCommand :: String -> [String] -> [String] -> Parser a -> (a -> b) -> Mod CommandFields b
- elynxParserInfo :: [String] -> [String] -> Parser a -> ParserInfo a
- class Generic a
- class FromJSON a
- class ToJSON a
- tShow :: Show a => a -> Text
- fromBs :: ByteString -> Text
ByteString handling
alignRightWith :: Char -> Int -> ByteString -> ByteString Source #
For a given width, align string to the right; use given fill character; trim on the left if string is longer.
alignRight :: Int -> ByteString -> ByteString Source #
For a given width, align string to the right; trim on the left if string is longer.
alignLeftWith :: Char -> Int -> ByteString -> ByteString Source #
For a given width, align string to the left; use given fill character; trim on the right if string is longer.
alignLeft :: Int -> ByteString -> ByteString Source #
For a given width, align string to the left; trim on the right if string is longer.
MWC
splitGen :: PrimMonad m => Int -> Gen (PrimState m) -> m [Gen (PrimState m)] Source #
Split a generator.
Concurrent calculations
getChunks :: Int -> Int -> [Int] Source #
For a given number of capabilities and number of calculations, get chunk sizes. The chunk sizes will be as evenly distributed as possible and sum up to the number of calculations.
Definitions
Equality
allEqual :: Eq a => [a] -> Bool Source #
Test if all elements of a list are equal; returns True for empty list.
allNearlyEqualWith :: Double -> [Double] -> Bool Source #
Test if all elements of a list are nearly equal; returns True for empty list.
allNearlyEqual :: [Double] -> Bool Source #
Test if all elements of a list are nearly equal; returns True for empty list.
nearlyEqWith :: Double -> Double -> Double -> Bool Source #
Test for equality with given tolerance (needed because of machine precision).
nearlyEq :: Double -> Double -> Bool Source #
Test for equality with predefined tolerance eps (needed because of
machine precision).
nearlyEqListWith :: Double -> [Double] -> [Double] -> Bool Source #
Test if two lists are nearly equal.
nearlyEqList :: [Double] -> [Double] -> Bool Source #
Test if two lists are nearly equal; use tolerance eps.
nearlyEqVecWith :: Double -> Vector R -> Vector R -> Bool Source #
Test if two vectors are nearly equal.
nearlyEqVec :: Vector R -> Vector R -> Bool Source #
Test if two vectors are nearly equal; use tolerance eps.
nearlyEqMatWith :: Double -> Matrix R -> Matrix R -> Bool Source #
Test if two vectors are nearly equal.
nearlyEqMat :: Matrix R -> Matrix R -> Bool Source #
Test if two vectors are nearly equal; use tolerance eps.
Input, output
getOutFilePath :: forall a. Reproducible a => String -> ELynx a (Maybe FilePath) Source #
Get out file path with extension.
openFile' :: Force -> FilePath -> IOMode -> IO Handle Source #
Open existing files only if Force is true.
readGZFile :: FilePath -> IO ByteString Source #
Read file. If file path ends with ".gz", assume gzipped file and decompress before read.
writeGZFile :: Force -> FilePath -> ByteString -> IO () Source #
Write file. If file path ends with ".gz", assume gzipped file and compress before write.
out :: Reproducible a => String -> ByteString -> String -> ELynx a () Source #
Write a result with a given name to file with given extension or standard output. Supports compression.
outHandle :: Reproducible a => String -> String -> ELynx a Handle Source #
Get an output handle, does not support compression. The handle has to be closed after use!
Parsing
runParserOnFile :: Parser a -> FilePath -> IO (Either String a) Source #
Parse a possibly gzipped file.
parseFileWith :: Parser a -> FilePath -> IO a Source #
Parse a possibly gzipped file and extract the result.
parseIOWith :: Parser a -> IO a Source #
Parse standard input.
parseFileOrIOWith :: Parser a -> Maybe FilePath -> IO a Source #
Parse a possibly gzipped file, or standard input, and extract the result.
parseByteStringWith :: Parser a -> ByteString -> a Source #
Parse a ByteString and extract the result.
Linear Algebra
matrixSeparateSymSkew :: Matrix R -> (Matrix R, Matrix R) Source #
Separate a square matrix into a symmetric and a skew-symmetric matrix.
dispmi :: Int -> Int -> Matrix R -> String Source #
Display a matrix with given precision and indent.
Lists
sortListWithIndices :: Ord a => [a] -> [(a, Int)] Source #
Sort a list and also return original indices.
randomInsertList :: PrimMonad m => a -> [a] -> Gen (PrimState m) -> m [a] Source #
Insert element into random position of list.
grabble :: PrimMonad m => [a] -> Int -> Int -> Gen (PrimState m) -> m [[a]] Source #
grabble xs m n is O(m*n'), where n' = min n (length xs). Choose n'
elements from xs, without replacement, and that m times.
Logger
logNewSection :: MonadLogger m => Text -> m () Source #
Unified way of creating a new section in the log.
eLynxWrapper :: forall a b. (Eq a, Show a, Reproducible a, ToJSON a) => Arguments a -> (Arguments a -> Arguments b) -> ELynx b () -> IO () Source #
Weird stuff
compose :: [a -> a] -> a -> a Source #
Chain a list of functions together. See https://wiki.haskell.org/Compose.
horizontalConcat :: [[[a]]] -> [[a]] Source #
A brain f***. As an example, let xss be a list of alignments (i.e., a
list of a list of a list of alleles). This function horizontally concatenates
the sites. The number of species needs to be same in each alignment. No
checks are performed!
Numeric
Log file
logHeader :: String -> [String] -> IO String Source #
Short, globally usable string preceding all logs with obligatory description.
Options
Verbosity levels.
Instances
toLogLevel :: Verbosity -> LogLevel Source #
Conert verbosity option to log level.
Exit when output exists, or overwrite.
data GlobalArguments Source #
A set of global arguments used by all programs. The idea is to provide a common framework for shared arguments.
Constructors
| GlobalArguments | |
Fields | |
Instances
globalArguments :: Parser GlobalArguments Source #
See GlobalArguments, parser function.
Random or fixed seed.
Instances
| Eq Seed Source # | Upon equality check, a random seed is not different from a fixed one. |
| Show Seed Source # | |
| Generic Seed Source # | |
| ToJSON Seed Source # | |
Defined in ELynx.Tools.Reproduction | |
| FromJSON Seed Source # | |
| type Rep Seed Source # | |
Defined in ELynx.Tools.Reproduction type Rep Seed = D1 (MetaData "Seed" "ELynx.Tools.Reproduction" "elynx-tools-0.3.4-28pXPI2ZtMgDLoTfpzJ7BX" False) (C1 (MetaCons "Random" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Fixed" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Vector Word32)))) | |
Argument skeleton to be used with all commands.
Constructors
| Arguments | |
Fields
| |
Instances
| Eq a => Eq (Arguments a) Source # | |
| Show a => Show (Arguments a) Source # | |
| Generic (Arguments a) Source # | |
| ToJSON a => ToJSON (Arguments a) Source # | |
Defined in ELynx.Tools.Reproduction | |
| FromJSON a => FromJSON (Arguments a) Source # | |
| Reproducible a => Reproducible (Arguments a) Source # | |
| type Rep (Arguments a) Source # | |
Defined in ELynx.Tools.Reproduction type Rep (Arguments a) = D1 (MetaData "Arguments" "ELynx.Tools.Reproduction" "elynx-tools-0.3.4-28pXPI2ZtMgDLoTfpzJ7BX" False) (C1 (MetaCons "Arguments" PrefixI True) (S1 (MetaSel (Just "global") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 GlobalArguments) :*: S1 (MetaSel (Just "local") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a))) | |
parseArguments :: forall a. Reproducible a => IO (Arguments a) Source #
Parse arguments. Provide a global description, header, footer, and so on. Custom additional description (first argument) and footer (second argument) can be provided. print help if needed.
Reproduction
type ELynx a = ReaderT (Arguments a) (LoggingT IO) Source #
Logging transformer to be used with all executables.
class Reproducible a where Source #
Reproducible commands have - a set of input files to be checked for consistency, - a set of output suffixes which define output files to be checked for consistency, - a function to get the seed, if available, - a function to set the seed, if applicable, - a parser to read the command line, - a nice program name, description, and footer.
Methods
inFiles :: a -> [FilePath] Source #
outSuffixes :: a -> [String] Source #
getSeed :: a -> Maybe Seed Source #
Instances
| Reproducible a => Reproducible (Arguments a) Source # | |
getReproductionHash :: forall a. Reproducible a => Reproduction a -> String Source #
A unique hash of the reproduction data type.
data Reproduction a Source #
Necessary information for a reproducible run. Notably, the input files are checked for consistency!
Constructors
| Reproduction | |
Fields | |
Instances
writeReproduction :: forall a. (Eq a, Show a, Reproducible a, ToJSON a) => String -> a -> IO () Source #
Write an ELynx reproduction file.
Misc
createCommandReproducible :: forall a b. Reproducible a => (a -> b) -> Mod CommandFields b Source #
Create a command; convenience function.
createCommand :: String -> [String] -> [String] -> Parser a -> (a -> b) -> Mod CommandFields b Source #
Create a command; convenience function.
elynxParserInfo :: [String] -> [String] -> Parser a -> ParserInfo a Source #
ELynx parser info; convenience function.
Re-exports
Representable types of kind *.
This class is derivable in GHC with the DeriveGeneric flag on.
A Generic instance must satisfy the following laws:
from.to≡idto.from≡id
Instances
A type that can be converted from JSON, with the possibility of failure.
In many cases, you can get the compiler to generate parsing code for you (see below). To begin, let's cover writing an instance by hand.
There are various reasons a conversion could fail. For example, an
Object could be missing a required key, an Array could be of
the wrong size, or a value could be of an incompatible type.
The basic ways to signal a failed conversion are as follows:
failyields a custom error message: it is the recommended way of reporting a failure;empty(ormzero) is uninformative: use it when the error is meant to be caught by some(;<|>)typeMismatchcan be used to report a failure when the encountered value is not of the expected JSON type;unexpectedis an appropriate alternative when more than one type may be expected, or to keep the expected type implicit.
prependFailure (or modifyFailure) add more information to a parser's
error messages.
An example type and instance using typeMismatch and prependFailure:
-- Allow ourselves to writeTextliterals. {-# LANGUAGE OverloadedStrings #-} data Coord = Coord { x :: Double, y :: Double } instanceFromJSONCoord whereparseJSON(Objectv) = Coord<$>v.:"x"<*>v.:"y" -- We do not expect a non-Objectvalue here. -- We could useemptyto fail, buttypeMismatch-- gives a much more informative error message.parseJSONinvalid =prependFailure"parsing Coord failed, " (typeMismatch"Object" invalid)
For this common case of only being concerned with a single
type of JSON value, the functions withObject, withScientific, etc.
are provided. Their use is to be preferred when possible, since
they are more terse. Using withObject, we can rewrite the above instance
(assuming the same language extension and data type) as:
instanceFromJSONCoord whereparseJSON=withObject"Coord" $ \v -> Coord<$>v.:"x"<*>v.:"y"
Instead of manually writing your FromJSON instance, there are two options
to do it automatically:
- Data.Aeson.TH provides Template Haskell functions which will derive an instance at compile time. The generated instance is optimized for your type so it will probably be more efficient than the following option.
- The compiler can provide a default generic implementation for
parseJSON.
To use the second, simply add a deriving clause to your
datatype and declare a GenericFromJSON instance for your datatype without giving
a definition for parseJSON.
For example, the previous example can be simplified to just:
{-# LANGUAGE DeriveGeneric #-}
import GHC.Generics
data Coord = Coord { x :: Double, y :: Double } deriving Generic
instance FromJSON Coord
The default implementation will be equivalent to
parseJSON = ; if you need different
options, you can customize the generic decoding by defining:genericParseJSON defaultOptions
customOptions =defaultOptions{fieldLabelModifier=maptoUpper} instanceFromJSONCoord whereparseJSON=genericParseJSONcustomOptions
Instances
A type that can be converted to JSON.
Instances in general must specify toJSON and should (but don't need
to) specify toEncoding.
An example type and instance:
-- Allow ourselves to writeTextliterals. {-# LANGUAGE OverloadedStrings #-} data Coord = Coord { x :: Double, y :: Double } instanceToJSONCoord wheretoJSON(Coord x y) =object["x".=x, "y".=y]toEncoding(Coord x y) =pairs("x".=x<>"y".=y)
Instead of manually writing your ToJSON instance, there are two options
to do it automatically:
- Data.Aeson.TH provides Template Haskell functions which will derive an instance at compile time. The generated instance is optimized for your type so it will probably be more efficient than the following option.
- The compiler can provide a default generic implementation for
toJSON.
To use the second, simply add a deriving clause to your
datatype and declare a GenericToJSON instance. If you require nothing other than
defaultOptions, it is sufficient to write (and this is the only
alternative where the default toJSON implementation is sufficient):
{-# LANGUAGE DeriveGeneric #-}
import GHC.Generics
data Coord = Coord { x :: Double, y :: Double } deriving Generic
instance ToJSON Coord where
toEncoding = genericToEncoding defaultOptions
If on the other hand you wish to customize the generic decoding, you have to implement both methods:
customOptions =defaultOptions{fieldLabelModifier=maptoUpper} instanceToJSONCoord wheretoJSON=genericToJSONcustomOptionstoEncoding=genericToEncodingcustomOptions
Previous versions of this library only had the toJSON method. Adding
toEncoding had two reasons:
- toEncoding is more efficient for the common case that the output of
toJSONis directly serialized to aByteString. Further, expressing either method in terms of the other would be non-optimal. - The choice of defaults allows a smooth transition for existing users:
Existing instances that do not define
toEncodingstill compile and have the correct semantics. This is ensured by making the default implementation oftoEncodingusetoJSON. This produces correct results, but since it performs an intermediate conversion to aValue, it will be less efficient than directly emitting anEncoding. (this also means that specifying nothing more thaninstance ToJSON Coordwould be sufficient as a generically decoding instance, but there probably exists no good reason to not specifytoEncodingin new instances.)