javelin-0.1.0.0: Labeled one-dimensional arrays
Safe HaskellSafe-Inferred
LanguageGHC2021

Data.Series.Generic

Synopsis

Definition

data Series v k a Source #

A Series v k a is a labeled array of type v filled with values of type a, indexed by keys of type k.

Like Map, they support efficient:

  • random access by key ( \(O(\log n)\) );
  • slice by key ( \(O(\log n)\) ).

Like Vector, they support efficient:

  • random access by index ( \(O(1)\) );
  • slice by index ( \(O(1)\) );
  • numerical operations.

Instances

Instances details
(forall a. Vector v a, Vector v k, Foldable v, Functor v) => FoldableWithIndex k (Series v k) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

ifoldMap :: Monoid m => (k -> a -> m) -> Series v k a -> m #

ifoldMap' :: Monoid m => (k -> a -> m) -> Series v k a -> m #

ifoldr :: (k -> a -> b -> b) -> b -> Series v k a -> b #

ifoldl :: (k -> b -> a -> b) -> b -> Series v k a -> b #

ifoldr' :: (k -> a -> b -> b) -> b -> Series v k a -> b #

ifoldl' :: (k -> b -> a -> b) -> b -> Series v k a -> b #

(forall a. Vector v a, Functor v) => FunctorWithIndex k (Series v k) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

imap :: (k -> a -> b) -> Series v k a -> Series v k b #

(forall a. Vector v a, Functor v, Foldable v, Ord k, Traversable v) => TraversableWithIndex k (Series v k) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

itraverse :: Applicative f => (k -> a -> f b) -> Series v k a -> f (Series v k b) #

Foldable v => Bifoldable (Series v) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

bifold :: Monoid m => Series v m m -> m #

bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> Series v a b -> m #

bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> Series v a b -> c #

bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> Series v a b -> c #

Foldable v => Foldable (Series v k) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

fold :: Monoid m => Series v k m -> m #

foldMap :: Monoid m => (a -> m) -> Series v k a -> m #

foldMap' :: Monoid m => (a -> m) -> Series v k a -> m #

foldr :: (a -> b -> b) -> b -> Series v k a -> b #

foldr' :: (a -> b -> b) -> b -> Series v k a -> b #

foldl :: (b -> a -> b) -> b -> Series v k a -> b #

foldl' :: (b -> a -> b) -> b -> Series v k a -> b #

foldr1 :: (a -> a -> a) -> Series v k a -> a #

foldl1 :: (a -> a -> a) -> Series v k a -> a #

toList :: Series v k a -> [a] #

null :: Series v k a -> Bool #

length :: Series v k a -> Int #

elem :: Eq a => a -> Series v k a -> Bool #

maximum :: Ord a => Series v k a -> a #

minimum :: Ord a => Series v k a -> a #

sum :: Num a => Series v k a -> a #

product :: Num a => Series v k a -> a #

Traversable v => Traversable (Series v k) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

traverse :: Applicative f => (a -> f b) -> Series v k a -> f (Series v k b) #

sequenceA :: Applicative f => Series v k (f a) -> f (Series v k a) #

mapM :: Monad m => (a -> m b) -> Series v k a -> m (Series v k b) #

sequence :: Monad m => Series v k (m a) -> m (Series v k a) #

Functor v => Functor (Series v k) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

fmap :: (a -> b) -> Series v k a -> Series v k b #

(<$) :: a -> Series v k b -> Series v k a #

(Vector v a, Ord k) => Monoid (Series v k a) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

mempty :: Series v k a #

mappend :: Series v k a -> Series v k a -> Series v k a #

mconcat :: [Series v k a] -> Series v k a #

(Vector v a, Ord k) => Semigroup (Series v k a) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

(<>) :: Series v k a -> Series v k a -> Series v k a #

sconcat :: NonEmpty (Series v k a) -> Series v k a #

stimes :: Integral b => b -> Series v k a -> Series v k a #

(Vector v a, Ord k, Show k, Show a) => Show (Series v k a) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

showsPrec :: Int -> Series v k a -> ShowS #

show :: Series v k a -> String #

showList :: [Series v k a] -> ShowS #

(NFData (v a), NFData k2) => NFData (Series v k2 a) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

rnf :: Series v k2 a -> () #

(Vector v a, Eq k, Eq a) => Eq (Series v k a) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

(==) :: Series v k a -> Series v k a -> Bool #

(/=) :: Series v k a -> Series v k a -> Bool #

(Vector v a, Ord (v a), Ord k, Ord a) => Ord (Series v k a) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

compare :: Series v k a -> Series v k a -> Ordering #

(<) :: Series v k a -> Series v k a -> Bool #

(<=) :: Series v k a -> Series v k a -> Bool #

(>) :: Series v k a -> Series v k a -> Bool #

(>=) :: Series v k a -> Series v k a -> Bool #

max :: Series v k a -> Series v k a -> Series v k a #

min :: Series v k a -> Series v k a -> Series v k a #

convert :: (Vector v1 a, Vector v2 a) => Series v1 k a -> Series v2 k a Source #

\(O(n)\) Convert between two types of Series.

Building/converting Series

singleton :: Vector v a => k -> a -> Series v k a Source #

\(O(1)\) Create a Series with a single element.

fromIndex :: Vector v a => (k -> a) -> Index k -> Series v k a Source #

\(O(n)\) Generate a Series by mapping every element of its index.

Lists

fromList :: (Vector v a, Ord k) => [(k, a)] -> Series v k a Source #

Construct a Series from a list of key-value pairs. There is no condition on the order of pairs. Duplicate keys are silently dropped. If you need to handle duplicate keys, see fromListDuplicates.

toList :: Vector v a => Series v k a -> [(k, a)] Source #

Construct a list from key-value pairs. The elements are in order sorted by key.

Vectors

fromVector :: (Ord k, Vector v k, Vector v a, Vector v (k, a)) => v (k, a) -> Series v k a Source #

Construct a Series from a Vector of key-value pairs. There is no condition on the order of pairs. Duplicate keys are silently dropped. If you need to handle duplicate keys, see fromVectorDuplicates.

Note that due to differences in sorting, fromList and fromVector . fromList may not be equivalent if the input list contains duplicate keys.

toVector :: (Vector v a, Vector v k, Vector v (k, a)) => Series v k a -> v (k, a) Source #

Construct a Vector of key-value pairs. The elements are in order sorted by key.

Handling duplicates

data Occurrence Source #

Integer-like, non-negative number that specifies how many occurrences of a key is present in a Series.

The easiest way to convert from an Occurrence to another integer-like type is the fromIntegral function.

Instances

Instances details
Enum Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

Num Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

Integral Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

Real Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

Show Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

Eq Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

Ord Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

Unbox Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

Vector Vector Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

MVector MVector Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

newtype Vector Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

newtype MVector s Occurrence Source # 
Instance details

Defined in Data.Series.Generic.Definition

fromListDuplicates :: (Vector v a, Ord k) => [(k, a)] -> Series v (k, Occurrence) a Source #

Construct a series from a list of key-value pairs. Contrary to fromList, values at duplicate keys are preserved. To keep each key unique, an Occurrence number counts up.

fromVectorDuplicates :: (Ord k, Vector v k, Vector v a, Vector v (k, a), Vector v (k, Occurrence)) => v (k, a) -> Series v (k, Occurrence) a Source #

Construct a Series from a Vector of key-value pairs, where there may be duplicate keys. There is no condition on the order of pairs.

Strict Maps

fromStrictMap :: Vector v a => Map k a -> Series v k a Source #

Construct a series from a strict Map.

toStrictMap :: Vector v a => Series v k a -> Map k a Source #

Convert a series into a strict Map.

Lazy Maps

fromLazyMap :: Vector v a => Map k a -> Series v k a Source #

Construct a series from a lazy Map.

toLazyMap :: Vector v a => Series v k a -> Map k a Source #

Ad-hoc conversion with other data structures

class IsSeries t v k a where Source #

The IsSeries typeclass allow for ad-hoc definition of conversion functions, converting to / from Series.

Methods

toSeries :: t -> Series v k a Source #

Construct a Series from some container of key-values pairs. There is no condition on the order of pairs. Duplicate keys are silently dropped. If you need to handle duplicate keys, see fromListDuplicates or fromVectorDuplicates.

fromSeries :: Series v k a -> t Source #

Construct a container from key-value pairs of a Series. The elements are returned in ascending order of keys.

Instances

Instances details
Vector v a => IsSeries (IntMap a) (v :: Type -> Type) Int (a :: Type) Source # 
Instance details

Defined in Data.Series.Generic.Definition

(Ord k, Vector v a) => IsSeries (Seq (k, a)) (v :: Type -> Type) k (a :: Type) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

toSeries :: Seq (k, a) -> Series v k a Source #

fromSeries :: Series v k a -> Seq (k, a) Source #

Vector v a => IsSeries (Set (k, a)) (v :: Type -> Type) k (a :: Type) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

toSeries :: Set (k, a) -> Series v k a Source #

fromSeries :: Series v k a -> Set (k, a) Source #

Ord k => IsSeries (Vector (k, a)) Vector k (a :: Type) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

toSeries :: Vector (k, a) -> Series Vector k a Source #

fromSeries :: Series Vector k a -> Vector (k, a) Source #

(Ord k, Unbox a, Unbox k) => IsSeries (Vector (k, a)) Vector k (a :: Type) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

toSeries :: Vector (k, a) -> Series Vector k a Source #

fromSeries :: Series Vector k a -> Vector (k, a) Source #

(Ord k, Vector v a) => IsSeries [(k, a)] (v :: Type -> Type) k (a :: Type) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

toSeries :: [(k, a)] -> Series v k a Source #

fromSeries :: Series v k a -> [(k, a)] Source #

Vector v a => IsSeries (Map k a) (v :: Type -> Type) k (a :: Type) Source # 
Instance details

Defined in Data.Series.Generic.Definition

Methods

toSeries :: Map k a -> Series v k a Source #

fromSeries :: Series v k a -> Map k a Source #

Mapping and filtering

map :: (Vector v a, Vector v b) => (a -> b) -> Series v k a -> Series v k b Source #

\(O(n)\) Map every element of a Series.

mapWithKey :: (Vector v a, Vector v b) => (k -> a -> b) -> Series v k a -> Series v k b Source #

\(O(n)\) Map every element of a Series, possibly using the key as well.

mapIndex :: (Vector v a, Ord k, Ord g) => Series v k a -> (k -> g) -> Series v g a Source #

\(O(n \log n)\). Map each key in the index to another value. Note that the resulting series may have less elements, because each key must be unique.

In case new keys are conflicting, the first element is kept.

concatMap :: (Vector v a, Vector v k, Vector v b, Vector v (k, a), Vector v (k, b), Ord k) => (a -> Series v k b) -> Series v k a -> Series v k b Source #

Map a function over all the elements of a Series and concatenate the result into a single Series.

filter :: (Vector v a, Vector v Int, Ord k) => (a -> Bool) -> Series v k a -> Series v k a Source #

Filter elements. Only elements for which the predicate is True are kept. Notice that the filtering is done on the values, not on the keys; see filterWithKey to filter while taking keys into account.

filterWithKey :: (Vector v a, Vector v Int, Vector v Bool, Ord k) => (k -> a -> Bool) -> Series v k a -> Series v k a Source #

Filter elements, taking into account the corresponding key. Only elements for which the predicate is True are kept.

take :: Vector v a => Int -> Series v k a -> Series v k a Source #

\(O(\log n)\) take n xs returns at most n elements of the Series xs.

takeWhile :: Vector v a => (a -> Bool) -> Series v k a -> Series v k a Source #

\(O(n)\) Returns the longest prefix (possibly empty) of the input Series that satisfy a predicate.

drop :: Vector v a => Int -> Series v k a -> Series v k a Source #

\(O(\log n)\) drop n xs drops at most n elements from the Series xs.

dropWhile :: Vector v a => (a -> Bool) -> Series v k a -> Series v k a Source #

\(O(n)\) Returns the complement of takeWhile.

Mapping with effects

mapWithKeyM :: (Vector v a, Vector v b, Monad m, Ord k) => (k -> a -> m b) -> Series v k a -> m (Series v k b) Source #

\(O(n)\) Apply the monadic action to every element of a series and its index, yielding a series of results.

mapWithKeyM_ :: (Vector v a, Monad m) => (k -> a -> m b) -> Series v k a -> m () Source #

\(O(n)\) Apply the monadic action to every element of a series and its index, discarding the results.

forWithKeyM :: (Vector v a, Vector v b, Monad m, Ord k) => Series v k a -> (k -> a -> m b) -> m (Series v k b) Source #

\(O(n)\) Apply the monadic action to all elements of the series and their associated keys, yielding a series of results.

forWithKeyM_ :: (Vector v a, Monad m) => Series v k a -> (k -> a -> m b) -> m () Source #

\(O(n)\) Apply the monadic action to all elements of the series and their associated keys, discarding the results.

traverseWithKey :: (Applicative t, Ord k, Traversable v, Vector v a, Vector v b, Vector v k, Vector v (k, a), Vector v (k, b)) => (k -> a -> t b) -> Series v k a -> t (Series v k b) Source #

\(O(n)\) Traverse a Series with an Applicative action, taking into account both keys and values.

Folding

fold :: Vector v a => Fold a b -> Series v k a -> b Source #

\(O(n)\) Execute a Fold over a Series.

See also foldM for monadic folds, and foldWithKey to take keys into account while folding.

foldM :: (Monad m, Vector v a) => FoldM m a b -> Series v k a -> m b Source #

\(O(n)\) Execute a monadic FoldM over a Series.

See also fold for pure folds, and foldMWithKey to take keys into account while folding.

foldWithKey :: (Vector v a, Vector v k, Vector v (k, a)) => Fold (k, a) b -> Series v k a -> b Source #

\(O(n)\) Execute a Fold over a Series, where the Fold takes keys into account.

foldMWithKey :: (Monad m, Vector v a, Vector v k, Vector v (k, a)) => FoldM m (k, a) b -> Series v k a -> m b Source #

\(O(n)\) Execute a monadic FoldM over a Series, where the FoldM takes keys into account.

foldMap :: (Monoid m, Vector v a) => (a -> m) -> Series v k a -> m Source #

\(O(n)\) Fold over elements in a Series.

foldMapWithKey :: (Monoid m, Vector v a, Vector v k, Vector v (k, a)) => (k -> a -> m) -> Series v k a -> m Source #

\(O(n)\) Fold over pairs of keys and elements in a Series. See also bifoldMap.

Specialized folds

mean :: Fractional a => Fold a a #

Compute a numerically stable arithmetic mean of all elements

variance :: Fractional a => Fold a a #

Compute a numerically stable (population) variance over all elements

std :: Floating a => Fold a a #

Compute a numerically stable (population) standard deviation over all elements

length :: Vector v a => Series v k a -> Int Source #

\(O(1)\) Extract the length of a Series.

null :: Vector v a => Series v k a -> Bool Source #

\(O(1)\) Test whether a Series is empty.

all :: Vector v a => (a -> Bool) -> Series v k a -> Bool Source #

\(O(n)\) Check if all elements satisfy the predicate.

any :: Vector v a => (a -> Bool) -> Series v k a -> Bool Source #

\(O(n)\) Check if any element satisfies the predicate.

and :: Vector v Bool => Series v k Bool -> Bool Source #

\(O(n)\) Check if all elements are True.

or :: Vector v Bool => Series v k Bool -> Bool Source #

\(O(n)\) Check if any element is True.

sum :: (Num a, Vector v a) => Series v k a -> a Source #

\(O(n)\) Compute the sum of the elements.

product :: (Num a, Vector v a) => Series v k a -> a Source #

\(O(n)\) Compute the product of the elements.

maximum :: (Ord a, Vector v a) => Series v k a -> Maybe a Source #

\(O(n)\) Yield the maximum element of the series. In case of a tie, the first occurrence wins.

maximumOn :: (Ord b, Vector v a) => (a -> b) -> Series v k a -> Maybe a Source #

\(O(n)\) maximumOn f xs teturns the maximum element of the series xs, as determined by the function f. In case of a tie, the first occurrence wins. If the Series is empty, Nothing is returned.

minimum :: (Ord a, Vector v a) => Series v k a -> Maybe a Source #

\(O(n)\) Yield the minimum element of the series. In case of a tie, the first occurrence wins. If the Series is empty, Nothing is returned.

minimumOn :: (Ord b, Vector v a) => (a -> b) -> Series v k a -> Maybe a Source #

\(O(n)\) minimumOn f xs teturns the minimum element of the series xs, as determined by the function f. In case of a tie, the first occurrence wins. If the Series is empty, Nothing is returned.

argmax :: (Ord a, Vector v a) => Series v k a -> Maybe k Source #

\(O(n)\) Find the index of the maximum element in the input series. If the input series is empty, Nothing is returned.

The index of the first occurrence of the maximum element is returned.

>>> import qualified Data.Series as Series
>>> :{
    let (xs :: Series.Series Int Int) 
         = Series.fromList [ (1, 0)
                           , (2, 1)
                           , (3, 2)
                           , (4, 7)
                           , (5, 4)
                           , (6, 5)
                           ]
    in argmax xs 
:}
Just 4

argmin :: (Ord a, Vector v a, Vector v (Down a)) => Series v k a -> Maybe k Source #

\(O(n)\) Find the index of the minimum element in the input series. If the input series is empty, Nothing is returned.

The index of the first occurrence of the minimum element is returned.

>>> import qualified Data.Series as Series
>>> :{
    let (xs :: Series.Series Int Int) 
         = Series.fromList [ (1, 1)
                           , (2, 1)
                           , (3, 2)
                           , (4, 0)
                           , (5, 4)
                           , (6, 5)
                           ]
    in argmin xs 
:}
Just 4

Scans

postscanl :: (Vector v a, Vector v b) => (a -> b -> a) -> a -> Series v k b -> Series v k a Source #

\(O(n)\) Left-to-right postscan.

>>> import qualified Data.Vector as V
>>> let xs = Series.fromList (zip [0..] [1,2,3,4]) :: Series V.Vector Int Int
>>> xs
index | values
----- | ------
    0 |      1
    1 |      2
    2 |      3
    3 |      4
>>> postscanl (+) 0 xs
index | values
----- | ------
    0 |      1
    1 |      3
    2 |      6
    3 |     10

prescanl :: (Vector v a, Vector v b) => (a -> b -> a) -> a -> Series v k b -> Series v k a Source #

\(O(n)\) Left-to-right prescan.

>>> import qualified Data.Vector as V
>>> let xs = Series.fromList (zip [0..] [1,2,3,4]) :: Series V.Vector Int Int
>>> xs
index | values
----- | ------
    0 |      1
    1 |      2
    2 |      3
    3 |      4
>>> prescanl (+) 0 xs
index | values
----- | ------
    0 |      0
    1 |      1
    2 |      3
    3 |      6

forwardFill Source #

Arguments

:: (Vector v a, Vector v (Maybe a)) 
=> a

Until the first non-Nothing is found, Nothing will be filled with this value.

-> Series v k (Maybe a) 
-> Series v k a 

\(O(n)\) Replace all instances of Nothing with the last previous value which was not Nothing.

>>> import qualified Data.Vector as V
>>> let xs = Series.fromList (zip [0..] [Just 1, Just 2,Nothing, Just 3]) :: Series V.Vector Int (Maybe Int)
>>> xs
index |  values
----- |  ------
    0 |  Just 1
    1 |  Just 2
    2 | Nothing
    3 |  Just 3
>>> forwardFill 0 xs
index | values
----- | ------
    0 |      1
    1 |      2
    2 |      2
    3 |      3

If the first entry of the series is missing, the first input to forwardFill will be used:

>>> let ys = Series.fromList (zip [0..] [Nothing, Just 2,Nothing, Just 3]) :: Series V.Vector Int (Maybe Int)
>>> ys
index |  values
----- |  ------
    0 | Nothing
    1 |  Just 2
    2 | Nothing
    3 |  Just 3
>>> forwardFill 0 ys
index | values
----- | ------
    0 |      0
    1 |      2
    2 |      2
    3 |      3

Combining series

zipWith :: (Vector v a, Vector v b, Vector v c, Vector v (Maybe c), Ord k) => (a -> b -> c) -> Series v k a -> Series v k b -> Series v k (Maybe c) Source #

Apply a function elementwise to two series, matching elements based on their keys. For keys present only in the left or right series, the value Nothing is returned.

>>> let xs = Series.fromList [ ("alpha", 0::Int), ("beta", 1), ("gamma", 2) ]
>>> let ys = Series.fromList [ ("alpha", 10::Int), ("beta", 11), ("delta", 13) ]
>>> zipWith (+) xs ys
  index |  values
  ----- |  ------
"alpha" | Just 10
 "beta" | Just 12
"delta" | Nothing
"gamma" | Nothing

To only combine elements where keys are in both series, see zipWithMatched

zipWithMatched :: (Vector v a, Vector v b, Vector v c, Ord k) => (a -> b -> c) -> Series v k a -> Series v k b -> Series v k c Source #

Apply a function elementwise to two series, matching elements based on their keys. Keys present only in the left or right series are dropped.

>>> let xs = Series.fromList [ ("alpha", 0::Int), ("beta", 1), ("gamma", 2) ]
>>> let ys = Series.fromList [ ("alpha", 10::Int), ("beta", 11), ("delta", 13) ]
>>> zipWithMatched (+) xs ys
  index | values
  ----- | ------
"alpha" |     10
 "beta" |     12

To combine elements where keys are in either series, see zipWith. To combine three series, see zipWithMatched3.

zipWithKey :: (Vector v a, Vector v b, Vector v c, Vector v k, Ord k) => (k -> a -> b -> c) -> Series v k a -> Series v k b -> Series v k c Source #

Apply a function elementwise to two series, matching elements based on their keys. Keys present only in the left or right series are dropped.

>>> let xs = Series.fromList [ ("alpha", 0::Int), ("beta", 1), ("gamma", 2) ]
>>> let ys = Series.fromList [ ("alpha", 10::Int), ("beta", 11), ("delta", 13) ]
>>> zipWithKey (\k x y -> length k + x + y) xs ys
  index | values
  ----- | ------
"alpha" |     15
 "beta" |     16

To combine elements where keys are in either series, see zipWith

zipWith3 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v (Maybe d), Ord k) => (a -> b -> c -> d) -> Series v k a -> Series v k b -> Series v k c -> Series v k (Maybe d) Source #

Apply a function elementwise to three series, matching elements based on their keys. For keys present only in the left or right series, the value Nothing is returned.

>>> let xs = Series.fromList [ ("alpha", 0::Int),  ("beta", 1),   ("gamma", 2) ]
>>> let ys = Series.fromList [ ("alpha", 10::Int), ("beta", 11),  ("delta", 13) ]
>>> let zs = Series.fromList [ ("alpha", 20::Int), ("delta", 13), ("epsilon", 6) ]
>>> zipWith3 (\x y z -> x + y + z) xs ys zs
    index |  values
    ----- |  ------
  "alpha" | Just 30
   "beta" | Nothing
  "delta" | Nothing
"epsilon" | Nothing
  "gamma" | Nothing

To only combine elements where keys are in all series, see zipWithMatched3

zipWithMatched3 :: (Vector v a, Vector v b, Vector v c, Vector v d, Ord k) => (a -> b -> c -> d) -> Series v k a -> Series v k b -> Series v k c -> Series v k d Source #

Apply a function elementwise to three series, matching elements based on their keys. Keys not present in all three series are dropped.

>>> let xs = Series.fromList [ ("alpha", 0::Int),  ("beta", 1),   ("gamma", 2) ]
>>> let ys = Series.fromList [ ("alpha", 10::Int), ("beta", 11),  ("delta", 13) ]
>>> let zs = Series.fromList [ ("alpha", 20::Int), ("delta", 13), ("epsilon", 6) ]
>>> zipWithMatched3 (\x y z -> x + y + z) xs ys zs
  index | values
  ----- | ------
"alpha" |     30

zipWithKey3 :: (Vector v a, Vector v b, Vector v c, Vector v d, Vector v k, Ord k) => (k -> a -> b -> c -> d) -> Series v k a -> Series v k b -> Series v k c -> Series v k d Source #

Apply a function elementwise to three series, matching elements based on their keys. Keys not present in all series are dropped.

>>> let xs = Series.fromList [ ("alpha", 0::Int), ("beta", 1), ("gamma", 2) ]
>>> let ys = Series.fromList [ ("alpha", 10::Int), ("beta", 11), ("delta", 13) ]
>>> let zs = Series.fromList [ ("alpha", 20::Int), ("beta", 7), ("delta", 5) ]
>>> zipWithKey3 (\k x y z -> length k + x + y + z) xs ys zs
  index | values
  ----- | ------
"alpha" |     35
 "beta" |     23

type ZipStrategy k a b = k -> a -> Maybe b Source #

A ZipStrategy is a function which is used to decide what to do when a key is missing from one of two Series being zipped together with zipWithStrategy.

If a ZipStrategy returns Nothing, the key is dropped. If a ZipStrategy returns Just v for key k, then the value v is inserted at key k.

For example, the most basic ZipStrategy is to skip over any key which is missing from the other series. Such a strategy can be written as skip key value = Nothing (see skipStrategy).

skipStrategy :: ZipStrategy k a b Source #

This ZipStrategy drops keys which are not present in both Series.

>>> let xs = Series.fromList [ ("alpha", 0::Int), ("beta", 1), ("gamma", 2) ]
>>> let ys = Series.fromList [ ("alpha", 10::Int), ("beta", 11), ("delta", 13) ]
>>> zipWithStrategy (+) skipStrategy skipStrategy xs ys
  index | values
  ----- | ------
"alpha" |     10
 "beta" |     12

mapStrategy :: (a -> b) -> ZipStrategy k a b Source #

This ZipStrategy sets the value at keys which are not present in both Series to the some mapping from the value present in one of the series. See the example below.

>>> let xs = Series.fromList [ ("alpha", 0::Int), ("beta", 1), ("gamma", 2) ]
>>> let ys = Series.fromList [ ("alpha", 5::Int), ("beta", 6), ("delta", 7) ]
>>> zipWithStrategy (+) (mapStrategy id) (mapStrategy (*10)) xs ys
  index | values
  ----- | ------
"alpha" |      5
 "beta" |      7
"delta" |     70
"gamma" |      2

constStrategy :: b -> ZipStrategy k a b Source #

This ZipStrategy sets a constant value at keys which are not present in both Series.

>>> let xs = Series.fromList [ ("alpha", 0::Int), ("beta", 1), ("gamma", 2) ]
>>> let ys = Series.fromList [ ("alpha", 10::Int), ("beta", 11), ("delta", 13) ]
>>> zipWith (+) xs ys
  index |  values
  ----- |  ------
"alpha" | Just 10
 "beta" | Just 12
"delta" | Nothing
"gamma" | Nothing
>>> zipWithStrategy (+) (constStrategy (-100)) (constStrategy 200)  xs ys
  index | values
  ----- | ------
"alpha" |     10
 "beta" |     12
"delta" |    200
"gamma" |   -100

zipWithStrategy Source #

Arguments

:: (Vector v a, Vector v b, Vector v c, Ord k) 
=> (a -> b -> c)

Function to combine values when present in both series

-> ZipStrategy k a c

Strategy for when the key is in the left series but not the right

-> ZipStrategy k b c

Strategy for when the key is in the right series but not the left

-> Series v k a 
-> Series v k b 
-> Series v k c 

Zip two Series with a combining function, applying a ZipStrategy when one key is present in one of the Series but not both.

Note that if you want to drop keys missing in either Series, it is faster to use zipWithMatched f than using zipWithStrategy f skipStrategy skipStrategy.

zipWithStrategy3 Source #

Arguments

:: (Vector v a, Vector v b, Vector v c, Vector v d, Ord k) 
=> (a -> b -> c -> d)

Function to combine values when present in all series

-> ZipStrategy k a d

Strategy for when the key is in the left series but not in all the others

-> ZipStrategy k b d

Strategy for when the key is in the center series but not in all the others

-> ZipStrategy k c d

Strategy for when the key is in the right series but not in all the others

-> Series v k a 
-> Series v k b 
-> Series v k c 
-> Series v k d 

Zip three Series with a combining function, applying a ZipStrategy when one key is present in one of the Series but not all of the others.

Note that if you want to drop keys missing in either Series, it is faster to use zipWithMatched3 f than using zipWithStrategy3 f skipStrategy skipStrategy skipStrategy.

zipWithMonoid :: (Monoid a, Monoid b, Vector v a, Vector v b, Vector v c, Ord k) => (a -> b -> c) -> Series v k a -> Series v k b -> Series v k c Source #

Zip two Series with a combining function. The value for keys which are missing from either Series is replaced with the appropriate mempty value.

>>> import Data.Monoid ( Sum(..) )
>>> let xs = Series.fromList [ ("2023-01-01", Sum (1::Int)), ("2023-01-02", Sum 2) ]
>>> let ys = Series.fromList [ ("2023-01-01", Sum (5::Int)), ("2023-01-03", Sum 7) ]
>>> zipWith (<>) xs ys
       index |                  values
       ----- |                  ------
"2023-01-01" | Just (Sum {getSum = 6})
"2023-01-02" |                 Nothing
"2023-01-03" |                 Nothing
>>> zipWithMonoid (<>) xs ys
       index |           values
       ----- |           ------
"2023-01-01" | Sum {getSum = 6}
"2023-01-02" | Sum {getSum = 2}
"2023-01-03" | Sum {getSum = 7}

esum :: (Ord k, Num a, Vector v a, Vector v (Sum a)) => Series v k a -> Series v k a -> Series v k a Source #

Elementwise sum of two Series. Elements missing in one or the other Series is considered 0.

>>> let xs = Series.fromList [ ("2023-01-01", (1::Int)), ("2023-01-02", 2) ]
>>> let ys = Series.fromList [ ("2023-01-01", (5::Int)), ("2023-01-03", 7) ]
>>> xs `esum` ys
       index | values
       ----- | ------
"2023-01-01" |      6
"2023-01-02" |      2
"2023-01-03" |      7

eproduct :: (Ord k, Num a, Vector v a, Vector v (Product a)) => Series v k a -> Series v k a -> Series v k a Source #

Elementwise product of two Series. Elements missing in one or the other Series is considered 1.

>>> let xs = Series.fromList [ ("2023-01-01", (2::Int)), ("2023-01-02", 3) ]
>>> let ys = Series.fromList [ ("2023-01-01", (5::Int)), ("2023-01-03", 7) ]
>>> xs `eproduct` ys
       index | values
       ----- | ------
"2023-01-01" |     10
"2023-01-02" |      3
"2023-01-03" |      7

unzip :: (Vector v a, Vector v b, Vector v (a, b)) => Series v k (a, b) -> (Series v k a, Series v k b) Source #

\(O(n)\) Unzip a Series of 2-tuples.

unzip3 :: (Vector v a, Vector v b, Vector v c, Vector v (a, b, c)) => Series v k (a, b, c) -> (Series v k a, Series v k b, Series v k c) Source #

\(O(n)\) Unzip a Series of 3-tuples.

Index manipulation

require :: (Vector v a, Vector v (Maybe a), Ord k) => Series v k a -> Index k -> Series v k (Maybe a) Source #

require a series with a new index. Contrary to select, all keys in Set k will be present in the re-indexed series.

requireWith Source #

Arguments

:: (Vector v a, Vector v b, Ord k) 
=> (k -> b)

Function to apply to keys which are missing from the input series, but required in the input index

-> (a -> b)

Function to apply to values which are in the input series and input index.

-> Series v k a 
-> Index k 
-> Series v k b 

Generalization of require, which maps missing keys to values. This is particularly useful for Vector instances which don't support Maybe, like Data.Vector.Unboxed.

catMaybes :: (Vector v a, Vector v (Maybe a), Vector v Int, Ord k) => Series v k (Maybe a) -> Series v k a Source #

\(O(n)\) Only keep elements which are Just v.

dropIndex :: Series v k a -> Series v Int a Source #

Drop the index of a series by replacing it with an Int-based index. Values will be indexed from 0.

Accessors

Bulk access

select :: (Selection s, Vector v a, Ord k) => Series v k a -> s k -> Series v k a infixl 1 Source #

Select a subseries. There are two main ways to do this.

The first way to do this is to select a sub-series based on keys:

>>> let xs = Series.fromList [('a', 10::Int), ('b', 20), ('c', 30), ('d', 40)]
>>> xs `select` Index.fromList ['a', 'd']
index | values
----- | ------
  'a' |     10
  'd' |     40

The second way to select a sub-series is to select all keys in a range:

>>> xs `select` 'b' `to` 'c'
index | values
----- | ------
  'b' |     20
  'c' |     30

Such ranges can also be unbounded. (i.e. all keys smaller or larger than some key), like so:

>>> xs `select` upto 'c'
index | values
----- | ------
  'a' |     10
  'b' |     20
  'c' |     30
>>> xs `select` from 'c'
index | values
----- | ------
  'c' |     30
  'd' |     40

Note that with select, you'll always get a sub-series; if you ask for a key which is not in the series, it'll be ignored:

>>> xs `select` Index.fromList ['a', 'd', 'e']
index | values
----- | ------
  'a' |     10
  'd' |     40

See require if you want to ensure that all keys are present.

selectWhere :: (Vector v a, Vector v Int, Vector v Bool, Ord k) => Series v k a -> Series v k Bool -> Series v k a Source #

Select a sub-series from a series matching a condition.

data Range k Source #

Datatype representing an inclusive range of keys, which can either be bounded or unbounded. The canonical ways to construct a Range are to use to, from, and upto:

>>> 'a' `to` 'z'
Range (from 'a' to 'z')
>>> from 'd'
Range (from 'd')
>>> upto 'q'
Range (up to 'q')

A Range can be used to efficiently select a sub-series with select.

Instances

Instances details
Selection Range Source #

Selecting a sub-series based on a Range is most performant. Constructing a Range is most convenient using the to function.

Instance details

Defined in Data.Series.Generic.View

Methods

select :: forall (v :: Type -> Type) a k. (Vector v a, Ord k) => Series v k a -> Range k -> Series v k a Source #

Show k => Show (Range k) Source # 
Instance details

Defined in Data.Series.Generic.View

Methods

showsPrec :: Int -> Range k -> ShowS #

show :: Range k -> String #

showList :: [Range k] -> ShowS #

Eq k => Eq (Range k) Source # 
Instance details

Defined in Data.Series.Generic.View

Methods

(==) :: Range k -> Range k -> Bool #

(/=) :: Range k -> Range k -> Bool #

to :: Ord k => k -> k -> Range k infixr 9 Source #

Create a bounded Range which can be used for slicing. This function is expected to be used in conjunction with select.

For unbound ranges, see from and upto.

from :: k -> Range k Source #

Create an unbounded Range which can be used for slicing. This function is expected to be used in conjunction with select.

For bound ranges, see to.

upto :: k -> Range k Source #

Create an unbounded Range which can be used for slicing. This function is expected to be used in conjunction with select.

For bound ranges, see to.

class Selection s Source #

Class for datatypes which can be used to select sub-series using select.

There are two use-cases for select:

  • Bulk random-access (selecting from an Index of keys);
  • Bulk ordered access (selecting from a Range of keys).

See the documentation for select.

Minimal complete definition

select

Instances

Instances details
Selection Set Source #

Selecting a sub-series from a Set is a convenience function. Internally, the Set is converted to an index first.

Instance details

Defined in Data.Series.Generic.View

Methods

select :: forall (v :: Type -> Type) a k. (Vector v a, Ord k) => Series v k a -> Set k -> Series v k a Source #

Selection Range Source #

Selecting a sub-series based on a Range is most performant. Constructing a Range is most convenient using the to function.

Instance details

Defined in Data.Series.Generic.View

Methods

select :: forall (v :: Type -> Type) a k. (Vector v a, Ord k) => Series v k a -> Range k -> Series v k a Source #

Selection Index Source # 
Instance details

Defined in Data.Series.Generic.View

Methods

select :: forall (v :: Type -> Type) a k. (Vector v a, Ord k) => Series v k a -> Index k -> Series v k a Source #

Selection List Source #

Selecting a sub-series from a list is a convenience function. Internally, the list is converted to an index first.

Instance details

Defined in Data.Series.Generic.View

Methods

select :: forall (v :: Type -> Type) a k. (Vector v a, Ord k) => Series v k a -> [k] -> Series v k a Source #

Single-element access

at :: (Vector v a, Ord k) => Series v k a -> k -> Maybe a Source #

\(O(\log n)\). Extract a single value from a series, by key.

iat :: Vector v a => Series v k a -> Int -> Maybe a Source #

\(O(1)\). Extract a single value from a series, by index.

Replacement

replace :: (Vector v a, Vector v Int, Ord k) => Series v k a -> Series v k a -> Series v k a Source #

Replace values from the right series with values from the left series at matching keys. Keys in the right series but not in the right series are unaffected.

(|->) :: (Vector v a, Vector v Int, Ord k) => Series v k a -> Series v k a -> Series v k a infix 6 Source #

Infix version of replace

(<-|) :: (Vector v a, Vector v Int, Ord k) => Series v k a -> Series v k a -> Series v k a infix 6 Source #

Flipped version of |->,

Grouping and windowing operations

groupBy Source #

Arguments

:: Series v k a

Input series

-> (k -> g)

Grouping function

-> Grouping k g v a

Grouped series

Group values in a Series by some grouping function (k -> g). The provided grouping function is guaranteed to operate on a non-empty Series.

This function is expected to be used in conjunction with aggregate:

>>> import Data.Maybe ( fromMaybe )
>>> type Date = (Int, String)
>>> month :: (Date -> String) = snd
>>> :{
    let xs = Series.fromList [ ((2020, "January") :: Date,  0 :: Int)
                             , ((2021, "January"), -5)
                             , ((2020, "June")   , 20)
                             , ((2021, "June")   , 25) 
                             ]
     in xs `groupBy` month `aggregateWith` (fromMaybe 0 . minimum)
:}
    index | values
    ----- | ------
"January" |     -5
   "June" |     20

data Grouping k g v a Source #

Representation of a Series being grouped.

aggregateWith :: (Ord g, Vector v a, Vector v b) => Grouping k g v a -> (Series v k a -> b) -> Series v g b Source #

Aggregate groups resulting from a call to groupBy:

>>> import Data.Maybe ( fromMaybe )
>>> type Date = (Int, String)
>>> month :: (Date -> String) = snd
>>> :{
    let xs = Series.fromList [ ((2020, "January") :: Date,  0 :: Int)
                             , ((2021, "January"), -5)
                             , ((2020, "June")   , 20)
                             , ((2021, "June")   , 25) 
                             ]
     in xs `groupBy` month `aggregateWith` (fromMaybe 0 . minimum)
:}
    index | values
    ----- | ------
"January" |     -5
   "June" |     20

If you want to aggregate groups using a binary function, see foldWith which may be much faster.

foldWith :: (Ord g, Vector v a) => Grouping k g v a -> (a -> a -> a) -> Series v g a Source #

Fold over each group in a Grouping using a binary function. While this is not as expressive as aggregateWith, users looking for maximum performance should use foldWith as much as possible.

>>> type Date = (Int, String)
>>> month :: (Date -> String) = snd
>>> :{
    let xs = Series.fromList [ ((2020, "January") :: Date,  0 :: Int)
                             , ((2021, "January"), -5)
                             , ((2020, "June")   , 20)
                             , ((2021, "June")   , 25) 
                             ]
     in xs `groupBy` month `foldWith` min
:}
    index | values
    ----- | ------
"January" |     -5
   "June" |     20

windowing :: (Ord k, Vector v a, Vector v b) => (k -> Range k) -> (Series v k a -> b) -> Series v k a -> Series v k b Source #

General-purpose window aggregation.

>>> import qualified Data.Series as Series
>>> import           Data.Series ( to )
>>> :{
    let (xs :: Series.Series Int Int) 
         = Series.fromList [ (1, 0)
                           , (2, 1)
                           , (3, 2)
                           , (4, 3)
                           , (5, 4)
                           , (6, 5)
                           ]
    in windowing (\k -> k `to` (k + 2)) sum xs
:}
index | values
----- | ------
    1 |      3
    2 |      6
    3 |      9
    4 |     12
    5 |      9
    6 |      5

expanding Source #

Arguments

:: (Vector v a, Vector v b) 
=> Series v k a

Series vector

-> (Series v k a -> b)

Aggregation function

-> Series v k b

Resulting vector

Expanding window aggregation.

>>> import qualified Data.Series as Series
>>> :{
    let (xs :: Series.Series Int Int) 
         = Series.fromList [ (1, 0)
                           , (2, 1)
                           , (3, 2)
                           , (4, 3)
                           , (5, 4)
                           , (6, 5)
                           ]
    in (xs `expanding` sum) :: Series.Series Int Int 
:}
index | values
----- | ------
    1 |      0
    2 |      1
    3 |      3
    4 |      6
    5 |     10
    6 |     15

Displaying Series

display :: (Vector v a, Show k, Show a) => Series v k a -> String Source #

Display a Series using default DisplayOptions.

displayWith :: Vector v a => DisplayOptions k a -> Series v k a -> String Source #

Display a Series using customizable DisplayOptions.

noLongerThan :: (a -> String) -> Int -> a -> String Source #

This function modifies existing functions to limit the width of its result.

>>> let limit7 = (show :: Int -> String) `noLongerThan` 7
>>> limit7 123456789
"123456..."

data DisplayOptions k a Source #

Options controlling how to display Series in the displayWith function. Default options are provided by defaultDisplayOptions.

To help with creating DisplayOptions, see noLongerThan.

Constructors

DisplayOptions 

Fields

defaultDisplayOptions :: (Show k, Show a) => DisplayOptions k a Source #

Default Series display options.