DataFrames can now import vertically organised data sets.

To use set the third parameter to true.

Author: sqonk

src/DataFrame.class.php

@@ -47,11 +47,11 @@ final class DataFrame implements \ArrayAccess, \Countable, \IteratorAggregate
     protected $showGenericIndexes = true;
 
 	/** 
-     *   Static equivilent of `new DataFrame()`.
+     *   Static equivilent of `new DataFrame`.
      */
-	static public function make(array $data, array $headers = null)
+	static public function make(array $data, array $headers = null, bool $isVerticalDataSet = false)
 	{
-		return new DataFrame($data, $headers);
+		return new DataFrame($data, $headers, $isVerticalDataSet);
 	}
 
     static public function empty_frames(): bool
@@ -115,14 +115,35 @@ public function __toString(): string
 	// ------- Main class methods
 
     /**
-     * Construct a new dataframe with the provided data. You may optionally provided the 
+     * Construct a new dataframe with the provided data. You may optionally provide the 
      * set of column headers in the second parameter. If you choose to do this then they 
      * should match the keys in the array.
      * 
-     * NOTE: The provided array must have at least one element/row and must also be 
-     * 2-dimensional in structure.
+     * -- parameters:
+     * @param $data The array of data. Unless `$isVerticalDataSet` is TRUE, the array should be an array of rows. Each row is an associative array where the keys correpsond to the headers of each column. 
+     * @param $headers An optional custom set of column headers.
+     * @param $isVerticalDataSet When set to TRUE the $data array is interpretted as a veritical series of columns instead of rows. Defaults to FALSE.
+     * 
+     * Standard data array format:
+     * 
+     * ``` php
+     * [
+     *     ['col 1' => value, 'col 2' => value ... 'col Nth' => value],
+     *     ['col 1' => value, 'col 2' => value ... 'col Nth' => value]
+     * ]
+     * ```
+     * 
+     * Data Array format for vertical data sets:
+     * 
+     * ``` php
+     * [
+     *     'col 1' => [... values],
+     *     'col 2' => [... values],
+     *     'col Nth' => [... values]
+     * ]
+     * ```
      */
-    public function __construct(?array $data = null, ?array $headers = null)
+    public function __construct(?array $data = null, ?array $headers = null, bool $isVerticalDataSet = false)
     {
         if ($data === null) {
             if (! self::empty_frames())
@@ -133,6 +154,17 @@ public function __construct(?array $data = null, ?array $headers = null)
         else if (! self::empty_frames() and count($data) == 0 and ($headers === null or count($headers) == 0))
             throw new \LengthException('A DataFrame needs at least one row of data.');
 
+        if ($isVerticalDataSet)
+        {
+            # data has been supplied as a keyed set of columns, translate to rows.
+            $headers = array_keys($data);
+            $rows = [];
+            foreach (arrays::zip(...array_values($data)) as $values) {
+                $rows[] = array_combine($headers, $values);
+            }
+            $data = &$rows;
+        }
+        
         $this->data = $data;
         $this->headers = $headers;
         if (! $this->headers and count($data) > 0) {

src/global_functions.php

@@ -48,9 +48,9 @@ function vector(...$items)
 /**
  * Create a new DataFrame with the supplied rows & columns.
  * 
- * @see DataFrame::__construct() for a proper description.
+ * @see [DataFrame::__construct()](DataFrame.md#__construct) for a proper description.
  */
-function dataframe(?array $data = null, array $headers = null)
+function dataframe(?array $data = null, array $headers = null, bool $isVerticalDataSet = false)
 {
-	return new \sqonk\phext\datakit\DataFrame($data, $headers);
+	return new \sqonk\phext\datakit\DataFrame($data, $headers, $isVerticalDataSet);
 }

tests/DataFrameTest.php

@@ -34,6 +34,23 @@ private function _loadFrame()
         return [$df, $data];
     }
 
+    public function testCreateFromVerticalDataset()
+    {
+        $data = [
+            'col 1' => range(1, 3),
+            'col 2' => ['a', 'b', 'c']
+        ];
+        $exp = [
+            ['col 1' => 1, 'col 2' => 'a'],
+            ['col 1' => 2, 'col 2' => 'b'],
+            ['col 1' => 3, 'col 2' => 'c']
+        ];
+
+        $df = dataframe($data, null, true);
+
+        $this->assertSame($exp, $df->data());
+    }
+    
     public function testRows()
     {
         [$df, $data] = $this->_loadFrame();