Type family which allows for higher-kinded record types in two forms:

• Single record type using Identity, where Column Identity a ~ a ;
• Record type whose elements are some other functor (usually Vector).

Types are created like regular record types, but each element must have the type Column f a instead of a. For example:

>>> :{
     data Student f
         = MkStudent { studentName      :: Column f String
                     , studentAge       :: Column f Int
                     , studentMathGrade :: Column f Char
                     }
         deriving (Generic, Frameable)
:}

Typeclass that endows any record type t with the ability to be packaged as a dataframe.

Under no circumstances should you write instances for Frameable; instead, simply derive an instance of Generic for t. For example:

>>> :set -XDeriveAnyClass
>>> :{
    data Store f
         = MkStore { storeName    :: Column f String
                   , storeId      :: Column f Int
                   , storeAddress :: Column f String
                   }
         deriving (Generic, Frameable)
:}

Type synonym for a record type with scalar elements

Type synonym for a record type whose elements are arrays (columns)

Build a dataframe from a container of rows.

For the inverse operation, see toRows.

Deconstruct a dataframe into its rows.

For the inverse operation, see fromRows.

Return the field names associated with a row or frame. This is useful to display frames via display.

Returns True if a dataframe has no rows.

Access the length of a dataframe, i.e. the number of rows.

Map a function over each row individually.

For mapping with a monadic action, see mapRowsM.

Map each element of a dataframe to a monadic action, evaluate these actions from left to right, and collect the result in a new dataframe.

For mapping without a monadic action, see mapRows.

Filter rows from a Frame t, only keeping the rows where the predicate is True.

Left-associative fold of a structure, with strict application of the operator.

Sort the rows of a frame using a custom comparison function.

Use the function on from Data.Function to easily create comparison functions. See the example below.

If you wish to prune rows with duplicates, see sortRowsByUnique. If your dataframe has an instance of Indexable, see sortRowsByKey.

For example, let's say we want to sort a dataframe of students by their first name:

>>> :{
     data Student f
         = MkStudent { studentName      :: Column f String
                     , studentAge       :: Column f Int
                     , studentMathGrade :: Column f Char
                     }
         deriving (Generic, Frameable)
     students = fromRows 
              [ MkStudent "Erika" 13 'D'
              , MkStudent "Beatrice" 13 'B'
              , MkStudent "David" 13 'A'
              , MkStudent "Albert" 12 'C'
              , MkStudent "Frank" 11 'C'
              , MkStudent "Clara" 12 'A'
              ]
:}

>>> import Data.Function (on)
>>> putStrLn $ display $ sortRowsBy (compare `on` studentName) students
studentName | studentAge | studentMathGrade
----------- | ---------- | ----------------
   "Albert" |         12 |              'C' 
 "Beatrice" |         13 |              'B'
    "Clara" |         12 |              'A'
    "David" |         13 |              'A'
    "Erika" |         13 |              'D'
    "Frank" |         11 |              'C'

The underlying sorting algorithm is timsort (via sortBy), which minimizes the number of comparisons used.

Sort the rows of a frame using a custom comparison function.

Use the function on from Data.Function to easily create comparison functions. See the example below.

If your dataframe has an instance of Indexable, see sortRowsByKey.

For example, let's say we want to sort a dataframe of students by their first name:

>>> :{
     data Student f
         = MkStudent { studentName      :: Column f String
                     , studentAge       :: Column f Int
                     , studentMathGrade :: Column f Char
                     }
         deriving (Generic, Frameable)
     students = fromRows 
              [ MkStudent "Erika" 13 'D'
              , MkStudent "Beatrice" 13 'B'
              , MkStudent "David" 13 'A'
              , MkStudent "Albert" 12 'C'
              , MkStudent "Frank" 11 'C'
              , MkStudent "Clara" 12 'A'
              ]
:}

>>> import Data.Function (on)
>>> putStrLn $ display $ sortRowsBy (compare `on` studentName) students
studentName | studentAge | studentMathGrade
----------- | ---------- | ----------------
   "Albert" |         12 |              'C' 
 "Beatrice" |         13 |              'B'
    "Clara" |         12 |              'A'
    "David" |         13 |              'A'
    "Erika" |         13 |              'D'
    "Frank" |         11 |              'C'

The underlying sorting algorithm is timsort (via sortBy), which minimizes the number of comparisons used.

Sort the rows of a frame using the index defined by the Indexable typeclass.

If your dataframe does not have an instance of Indexable, see sortRowsBy.

To prune rows with duplicate keys, see sortRowsByKeyUnique.

For example:

>>> :{
     data Student f
         = MkStudent { studentName      :: Column f String
                     , studentAge       :: Column f Int
                     , studentMathGrade :: Column f Char
                     }
         deriving (Generic, Frameable)
     instance Indexable Student where
         type Key Student = String
         index = studentName
     students = fromRows 
              [ MkStudent "Erika" 13 'D'
              , MkStudent "Beatrice" 13 'B'
              , MkStudent "David" 13 'A'
              , MkStudent "Albert" 12 'C'
              , MkStudent "Frank" 11 'C'
              , MkStudent "Clara" 12 'A'
              ]
:}

>>> import Data.Function (on)
>>> putStrLn $ display $ sortRowsByKey students
studentName | studentAge | studentMathGrade
----------- | ---------- | ----------------
   "Albert" |         12 |              'C' 
 "Beatrice" |         13 |              'B'
    "Clara" |         12 |              'A'
    "David" |         13 |              'A'
    "Erika" |         13 |              'D'
    "Frank" |         11 |              'C'

The underlying sorting algorithm is timsort (via sortBy), which minimizes the number of comparisons used.

Sort the rows of a frame using the index defined by the Indexable typeclass, but prune rows with duplicate keys.

The underlying sorting algorithm is timsort (via sortBy), which minimizes the number of comparisons used.

Sort the rows of a frame by mapping the index defined by the Indexable typeclass, to another key type k. Also prune rows with duplicate keys.

The underlying sorting algorithm is timsort (via sortBy), which minimizes the number of comparisons used.

Display a Frame t using default DisplayOptions.

Although this is up to you, we strongly recommend that the Show instance for Frame t be:

instance Show (Frame t) where show = display

Example:

>>> :{
     data Student f
         = MkStudent { studentName      :: Column f String
                     , studentAge       :: Column f Int
                     , studentMathGrade :: Column f Char
                     }
         deriving (Generic, Frameable)
:}

>>> students = fromRows $ Vector.fromList [MkStudent "Albert" 12 'C', MkStudent "Beatrice" 13 'B', MkStudent "Clara" 12 'A']
>>> putStrLn (display students)
studentName | studentAge | studentMathGrade
----------- | ---------- | ----------------
   "Albert" |         12 |              'C' 
 "Beatrice" |         13 |              'B'
    "Clara" |         12 |              'A'

Display a Frame t using custom DisplayOptions.

Example:

>>> :{
     data Student f
         = MkStudent { studentName      :: Column f String
                     , studentAge       :: Column f Int
                     , studentMathGrade :: Column f Char
                     }
         deriving (Generic, Frameable)
:}

>>> :{
    students = fromRows 
             $ Vector.fromList 
             [ MkStudent "Albert" 12 'C'
             , MkStudent "Beatrice" 13 'B'
             , MkStudent "Clara" 12 'A'
             , MkStudent "David" 13 'A'
             , MkStudent "Erika" 13 'D'
             , MkStudent "Frank" 11 'C'
             ]
:}

>>> putStrLn (displayWith (defaultDisplayOptions{maximumNumberOfRows=2}) students)
studentName | studentAge | studentMathGrade
----------- | ---------- | ----------------
   "Albert" |         12 |              'C' 
        ... |        ... |              ...
    "Frank" |         11 |              'C'

Control how displayWith behaves.

Default Frame t display options.

Access a row from a dataframe by its integer index. Indexing starts at 0, representing the first row.

If the index is larger than the number of rows, this function returns Nothing.

To access a specific row AND column, iat is much more efficient.

To lookup a row based on a non-integer index, see lookup.

Lookup an element of the frame by row index and column

This is much more efficient than looking up an entire row using ilookup, and then selecting a specific field from a row.

To lookup an element by row key instead, see at.

Typeclass for dataframes with an index, a column or set of columns that can be used to search through rows.

An index need not be unique, but the type of its keys must be an instance of Eq.

Look up a row in a data frame by key. The specific key is defined by the Indexable instance of type t.

The first row whose index matches the supplied key is returned. If no row has a matching key, returns Nothing.

If you need to look up a particular row and column, at is much more efficient.

To lookup a row based on an integer index, see ilookup.

Lookup an element of a frame by row and column.

This is much more efficient than looking up an entire row using lookup, and then selecting a specific field from a row.

To lookup an element by integer row index instead, see iat.

Zip two frames together using a combination function. Rows from each frame are matched in order; the resulting frame will only contain as many rows as the shortest of the two input frames

Merge two dataframes using a merging strategy, where the indexes of the dataframes have the same type. See mergeWithStrategyOn to merge dataframes with different indexes.

A merging strategy handles the possibility of rows missing in the left and/or right dataframes. Merge strategies can be user-defined, or you can use predefined strategies (e.g. matchedStrategy).

Note that (Key t1 ~ Key t2) means that the type of keys in in both dataframes must be the same.

In the example below, we have two dataframes: one containing store names, and one containing addresses. Both dataframes have use a unique identification number to relate their data to specific stores.

We want to build a summary of information about stores, containing each store's name and address.

>>> :{
     data Store f
         = MkStore { storeId   :: Column f Int
                   , storeName :: Column f String
                   }
         deriving (Generic, Frameable)
     instance Indexable Store where
         type Key Store = Int
         index = storeId
:}

>>> :{
     data Address f
         = MkAddress { addressStoreId     :: Column f Int
                     , addressCivicNumber :: Column f Int
                     , addressStreetName  :: Column f String
                     }
         deriving (Generic, Frameable)
     instance Show (Row Address) where
         show (MkAddress _ civicNum streetName) = mconcat [show civicNum, " ", streetName]
     instance Indexable Address where
         type Key Address = Int
         index = addressStoreId
:}

>>> :{
     data StoreSummary f
         = MkStoreSummary { storeSummaryName    :: Column f String
                          , storeSummaryAddress :: Column f (Row Address)
                          }
         deriving (Generic, Frameable)
     deriving instance Show (Row StoreSummary)
:}

>>> :{
    stores = fromRows 
             [ MkStore 1 "Maxi"
             , MkStore 2 "Metro"
             , MkStore 3 "Sobeys"
             , MkStore 4 "Loblaws"
             ]
:}

>>> :{
    addresses = fromRows
                [ MkAddress 1 1982 "14th Avenue"
                , MkAddress 2 10   "Main Street"
                , MkAddress 3 914  "Prima Street"
                -- Missing address for store id 4
                , MkAddress 5 1600 "Cosgrove Lane"
                ]
:}

>>> :{
     putStrLn
         $ display
             $ mergeWithStrategy 
                   (matchedStrategy (\_ store address -> MkStoreSummary (storeName store) address))
                   stores
                   addresses
:}
storeSummaryName | storeSummaryAddress
---------------- | -------------------
          "Maxi" |    1982 14th Avenue
         "Metro" |      10 Main Street
        "Sobeys" |    914 Prima Street

Merge two dataframes using a merging strategy, where the indexes of the dataframes are mapped to some key of type k.

See mergeWithStrategy for further notes and examples.

Merge strategy which only works if both the left and right rows are found.

If you are familiar with relational databases, matchedStrategy is an inner join.

The These type represents values with two non-exclusive possibilities.

This can be useful to represent combinations of two values, where the combination is defined if either input is. Algebraically, the type These A B represents (A + B + AB), which doesn't factor easily into sums and products--a type like Either A (B, Maybe A) is unclear and awkward to use.

These has straightforward instances of Functor, Monad, &c., and behaves like a hybrid error/writer monad, as would be expected.

For zipping and unzipping of structures with These values, see Data.Align.