[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  }