    [NAME]
    ALL.module.core.dataframe

    [TITLE]
    Data Frame

    [DESCRIPTION]

    A data frame is a matrix-like data structure that organizes data values into table(s).
    But unlike a matrix, a data frame can contain any types of values, though the values of
    the same column are required to be the same. Also, the rows and columns can be attached
    with arbitrary sets of labels, and such labels can be used to retrieve the rows or
    columns.

    Dao data frame supports both 2D and 3D data frames. A 2D data frame contains only one
    data table, with data items indexed by row and column indices or labels. A 3D data frame
    contains multiple data tables, where each table is indexed by a depth index or multiple
    depth labels.

    Here is a simple example to create and print a data frame:

       1  load DataFrame
       2
       3  matrix = [ [ -1.0D : -1 : 4] : 1.5 : 5 ]
       4  dframe = DataFrame( matrix )
       5  io.writeln( dframe );

    which will print something like the following:

       1  DataFrame[0x7f82f34a1700]
       2  Dimensions: Rows=5; Cols=4; Deps=1;
       3  Depth: 0;
       4  | Columns from 0 to 3:
       5  |       0     1     2     3
       6  |--------------------------|
       7  0:   -1.0  -2.0  -3.0  -4.0
       8  1:    0.5  -0.5  -1.5  -2.5
       9  2:    2.0   1.0   0.0  -1.0
      10  3:    3.5   2.5   1.5   0.5
      11  4:    5.0   4.0   3.0   2.0

    More on data frame creation:

       1  # Create a 2D matrix:
       2  matrix = [ [ -1.0D : -1 : 8] : 1.51 : 16 ]
       3
       4  # Create a 2D dataframe from the matrix:
       5  dframe2d = DataFrame( matrix )
       6
       7  # Create a 3D matrix:
       8  matrix3d = [ matrix : 1 : 3 ]
       9  matrix3d.permute( [ 2, 1, 0 ] )
      10
      11  # Create 3D dataframe:
      12  dframe3d = DataFrame( matrix3d )

    Attaching labels to data frames:

       1  # Add row labels:
       2  dframe2d.AddLabels( $row, { 'RR1' => 0, 'R2' => 1, 'RRRR5' => 5 } )
       3  dframe2d.AddLabels( $row, { 'RR1' => 0, 'R2' => 1, 'RRRR5' => 6 } )
       4
       5  # Add column labels:
       6  dframe2d.AddLabels( $column, { 'CC1' => 0, 'C2' => 1, 'CCCCCCCCC3' => 4 } )

    Adding additional columns:

       1  # Add string column:
       2  dframe2d.AddColumn( { 'ABC', 'DEF', 'SSSS', 'Hello\t world!' }, 'String' )
       3
       4  # Add column of arbitrary type:
       5  dframe2d.AddColumn( { {'ABC'}, {'DEF', 'SSSS'}, 'Hello\n world!' }, 'Any' )
       6
       7  # Add integer column:
       8  dframe2d.AddColumn( [ 123, 456, 7890], 'Number' )

    Operation on data frame:

       1  # Update one cell:
       2  dframe2d[0,1] = 1000000.23
       3
       4  # Update one column:
       5  dframe2d[:,2] += [[0]:100:9]
       6
       7  # Add the first column to the second:
       8  dframe2d[:,1] += dframe2d[:,0]

    Using code section methods of data frame:

       1  # Scan cells:
       2  dframe2d[1:5,:3].ScanCells { [value,row,column]
       3      io.writeln( row, column, value )
       4  }
       5
       6  # Scan rows:
       7  dframe2d[1:5,:3].ScanRows { [value,row]
       8      io.writeln( row, value )
       9  }
      10
      11  # Scan columns:
      12  dframe2d[1:5,:3].ScanColumns { [value,column]
      13      io.writeln( column, value )
      14  }