add documentation to the major internal implementation of groupby methods

Author: steveoni

src/danfojs-base/aggregators/groupby.ts

@@ -39,7 +39,50 @@ export default class Groupby {
     this.colIndex = colIndex
 
   }
-
+  /**
+   * Generate group object data needed for group operations
+   * let data = [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 20, 30, 40 ], [ 39, 89, 78 ] ];
+   * let cols = [ "A", "B", "C" ];
+   * let df = new dfd.DataFrame(data, { columns: cols });
+   * let groupDf = df.groupby([ "A" ]);
+   * The following internal object is generated and save to this.colDict
+   * {
+   *  '1': { A: [ 1 ], B: [ 2 ], C: [ 3 ] },
+   *  '4': { A: [ 4 ], B: [ 5 ], C: [ 6 ] },
+   *  '20': { A: [ 20 ], B: [ 30 ], C: [ 40 ] },
+   *  '39': { A: [ 39 ], B: [ 89 ], C: [ 78 ] }
+   * }
+   * Since for groupby using more than one columns is index via '-'
+   * e.g for df.groupby(['A','B'])
+   * the result will look like this
+   * {
+   *  '1-2': {A: [ 1 ], B: [ 2 ], C: [ 3 ]},
+   *  '4-5': {A: [ 4 ], B: [ 5 ], C: [ 6 ]}
+   * }
+   * but in doing analysis on a specific column like this
+   * df.groupby(['A','B']).col(['C'])
+   * will have the following set of internal result
+   * {
+   *  '1-2': { C: [ 3 ]},
+   *  '4-5': {C: [ 6 ]}
+   * }
+   * In building our multindex type of DataFrame for this data,
+   * we've somehow loose track of value for column A and B.
+   * This could actually be generated by using split('-') on the object keys
+   * e.g '1-2'.split('-') will give us the value for A and B.
+   * But we might have weird case scenerio where A and B value has '-`
+   * e.g 
+   * {
+   *  '1--2-': { C: [ 3 ]},
+   *  '4--5-': {C: [ 6 ]}
+   * }
+   * using `.split('-') might not work well
+   * Hence we create a key-value `keyToValue` object to store index and their 
+   * associated value
+   * NOTE: In the previous implementation we made use of Graph representation
+   * for the group by data and Depth First search (DFS). But we decided to use key-value
+   * object in javascript as an hashmap to reduce search time compared to using Grpah and DFS
+   */
   group():  Groupby{
     const self = this
     let keyToValue:{
@@ -78,6 +121,24 @@ export default class Groupby {
     return this
   }
 
+  /**
+   * Generate new internal groupby data 
+   * group = df.groupby(['A', 'B']).col('C')
+   * This filter the colDict property as generated by `.group()`
+   * it filter each group to contain only column `C` in their internal object
+   * e.g
+   * {
+   *  '1-2': {A: [ 1 ], B: [ 2 ], C: [ 3 ]},
+   *  '4-5': {A: [ 4 ], B: [ 5 ], C: [ 6 ]}
+   * }
+   * to
+   * {
+   *  '1-2': { C: [ 3 ]},
+   *  '4-5': {C: [ 6 ]}
+   * } 
+   * @param colNames column names
+   * @return Groupby
+   */
   col(colNames: ArrayType1D | undefined): Groupby {
 
     if (typeof colNames === "undefined") {
@@ -114,7 +175,47 @@ export default class Groupby {
     return gp
   }
 
-  arithemetic(operation: {[key: string] : Array<string> | string} | string): { [key: string ]: {} } {
+  /**
+   * Perform all groupby arithmetic operations
+   * In the previous implementation all groups data are 
+   * stord as DataFrame, which involve lot of memory usage 
+   * Hence each groups are just pure javascrit object
+   * and all arithmetic operation is done directly on javascript 
+   * arrays.
+   * e.g 
+   * using this internal data 
+   * {
+   *  '1-2': {A: [ 1,3 ], B: [ 2,5 ], C: [ 3, 5 ]},
+   *  '4-5': {A: [ 4,1 ], B: [ 5,0 ], C: [ 6, 12 ]}
+   * }
+   * 1) using groupby(['A', 'B']).arithmetic("mean")
+   * result: * {
+   *  '1-2': {A_mean: [ 2 ], B_mean: [ 3.5 ], C_mean: [ 4 ]},
+   *  '4-5': {A_mean: [ 2.5 ], B: [ 2.5 ], C_mean: [ 9 ]}
+   * }
+   * 2) .arithmetic({
+   *    A: 'mean',
+   *    B: 'sum',
+   *    C: 'min'
+   * })
+   * result: 
+   * {
+   *  '1-2': {A_mean: [ 2 ], B_sum: [ 7 ], C_min: [ 3 ]},
+   *  '4-5': {A_mean: [ 2.5 ], B_sum: [ 5 ], C_min: [ 6 ]}
+   * }
+   * 3) .arithmetic({
+   *    A: 'mean',
+   *    B: 'sum',
+   *    C: ['min', 'max']
+   * })
+   * result:
+   * {
+   *  '1-2': {A_mean: [ 2 ], B_sum: [ 7 ], C_min: [ 3 ], C_max: [5]},
+   *  '4-5': {A_mean: [ 2.5 ], B_sum: [ 5 ], C_min: [ 6 ], C_max: [12]}
+   * }
+   * @param operation 
+   */
+  private arithemetic(operation: {[key: string] : Array<string> | string} | string): { [key: string ]: {} } {
 
     const opsName = [ "mean", "sum", "count", "mode", "std", "var", "cumsum", "cumprod",
     "cummax", "cummin", "median" , "min"];
@@ -173,7 +274,12 @@ export default class Groupby {
     return colDict
   }
 
-  groupMathLog(colVal: Array<number>, ops: string): Array<number>{
+  /**
+   * Peform all arithmetic logic
+   * @param colVal 
+   * @param ops 
+   */
+  private groupMathLog(colVal: Array<number>, ops: string): Array<number>{
     let data = []
     switch(ops) {
       case "max":
@@ -261,7 +367,12 @@ export default class Groupby {
     return data
   }
 
-  toDataFrame(colDict: { [key: string ]: {} }): DataFrame {
+  /**
+   * Takes in internal groupby internal data and convert
+   * them to a single data frame.
+   * @param colDict 
+   */
+  private toDataFrame(colDict: { [key: string ]: {} }): DataFrame {
     let data:  { [key: string ]: ArrayType1D } = {}
 
     for(let key of this.colKeyDict(colDict)) {
@@ -287,7 +398,7 @@ export default class Groupby {
     return new DataFrame(data)
   }
 
-  operations(ops: string): DataFrame {
+  private operations(ops: string): DataFrame {
     if (!this.groupColNames) {
       let colGroup = this.col(undefined)
       let colDict = colGroup.arithemetic(ops)