fix #575 and fix #371 : renamed argument 'transpose' of to_csv as 'wide' + added argument 'wide' to to_excel

alixdamman · alixdamman · commit f6504dd322df · 2018-02-16T12:02:22.000+01:00
diff --git a/doc/source/changes/version_0_28.rst.inc b/doc/source/changes/version_0_28.rst.inc
@@ -211,7 +211,6 @@ Miscellaneous improvements
      a0   0   0
      a1   1   1
 
-
 * renamed argument `nb_index` of `read_csv`, `read_excel`, `read_sas`, `from_lists` and `from_string` functions
   as `nb_axes`. The relation between `nb_index` and `nb_axes` is given by `nb_axes = nb_index + 1`:
 
@@ -234,6 +233,40 @@ Miscellaneous improvements
 
   Closes :issue:`548`:
 
+* renamed argument `transpose` by `wide` in `to_csv` method.
+
+* added argument `wide` in `to_excel` method. When argument `wide` is set to False, the array is exported
+  in "narrow" format, i.e. one column per axis plus one value column:
+
+    >>> arr = ndtest((2, 3))
+    >>> arr
+    a\b  b0  b1  b2
+     a0   0   1   2
+     a1   3   4   5
+
+  Default behavior (`wide=True`):
+
+    >>> arr.to_excel('my_file.xlsx')
+
+    a\b  b0  b1  b2
+    a0    0   1   2
+    a1    3   4   5
+
+  With `wide=False`:
+
+    >>> arr.to_excel('my_file.xlsx', wide=False)
+
+     a   b  value
+    a0  b0      0
+    a0  b1      1
+    a0  b2      2
+    a1  b0      3
+    a1  b1      4
+    a1  b2      5
+
+  Argument `transpose` has a different purpose than `wide` and is mainly useful to allow multiple axes as header
+  when exporting arrays with more than 2 dimensions. Closes :issue:`575` and :issue:`371`.
+
 
 Fixes
 -----
diff --git a/larray/core/array.py b/larray/core/array.py
@@ -5816,23 +5816,25 @@ def clip(self, a_min, a_max, out=None):
         from larray.core.ufuncs import clip
         return clip(self, a_min, a_max, out)
 
-    def to_csv(self, filepath, sep=',', na_rep='', transpose=True, dropna=None, dialect='default', **kwargs):
+    @deprecate_kwarg('transpose', 'wide')
+    def to_csv(self, filepath, sep=',', na_rep='', wide=True, dropna=None, dialect='default', **kwargs):
         """
         Writes array to a csv file.
 
         Parameters
         ----------
         filepath : str
             path where the csv file has to be written.
-        sep : str
-            seperator for the csv file.
-        na_rep : str
-            replace NA values with na_rep.
-        transpose : boolean
-            transpose = True  => transpose over last axis.
-            transpose = False => no transpose.
-        dialect : 'default' | 'classic'
-            Whether or not to write the last axis name (using '\' )
+        sep : str, optional
+            separator for the csv file. Defaults to `,`.
+        na_rep : str, optional
+            replace NA values with na_rep. Defaults to ''.
+        wide : boolean, optional
+            Whether or not writing arrays in "wide" format. If True, arrays are exported with the last axis
+            represented horizontally. If False, arrays are exported in "narrow" format: one column per axis plus one
+            value column. Defaults to True.
+        dialect : 'default' | 'classic', optional
+            Whether or not to write the last axis name (using '\' ). Defaults to 'default'.
         dropna : None, 'all', 'any' or True, optional
             Drop lines if 'all' its values are NA, if 'any' value is NA or do not drop any line (default).
             True is equivalent to 'all'.
@@ -5852,7 +5854,7 @@ def to_csv(self, filepath, sep=',', na_rep='', transpose=True, dropna=None, dial
         nat\\sex,M,F
         BE,0,1
         FO,2,3
-        >>> a.to_csv(fname, sep=';', transpose=False)
+        >>> a.to_csv(fname, sep=';', wide=False)
         >>> with open(fname) as f:
         ...     print(f.read().strip())
         nat;sex;0
@@ -5868,7 +5870,7 @@ def to_csv(self, filepath, sep=',', na_rep='', transpose=True, dropna=None, dial
         FO,2,3
         """
         fold = dialect == 'default'
-        if transpose:
+        if wide:
             frame = self.to_frame(fold, dropna)
             frame.to_csv(filepath, sep=sep, na_rep=na_rep, **kwargs)
         else:
@@ -5900,7 +5902,7 @@ def to_hdf(self, filepath, key, *args, **kwargs):
         self.to_frame().to_hdf(filepath, key, *args, **kwargs)
 
     def to_excel(self, filepath=None, sheet_name=None, position='A1', overwrite_file=False, clear_sheet=False,
-                 header=True, transpose=False, engine=None, *args, **kwargs):
+                 header=True, transpose=False, wide=True, engine=None, *args, **kwargs):
         """
         Writes array in the specified sheet of specified excel workbook.
 
@@ -5923,8 +5925,12 @@ def to_excel(self, filepath=None, sheet_name=None, position='A1', overwrite_file
         header : bool, optional
             Whether or not to write a header (axes names and labels). Defaults to True.
         transpose : bool, optional
-            Whether or not to transpose the resulting array. This can be used, for example, for writing one dimensional
-            arrays vertically. Defaults to False.
+            Whether or not to transpose the array transpose over last axis.
+            This is equivalent to paste with option transpose in Excel. Defaults to False.
+        wide : boolean, optional
+            Whether or not writing arrays in "wide" format. If True, arrays are exported with the last axis
+            represented horizontally. If False, arrays are exported in "narrow" format: one column per axis plus one
+            value column. Defaults to True.
         engine : 'xlwings' | 'openpyxl' | 'xlsxwriter' | 'xlwt' | None, optional
             Engine to use to make the output. If None (default), it will use 'xlwings' by default if the module is
             installed and relies on Pandas default writer otherwise.
@@ -5943,7 +5949,11 @@ def to_excel(self, filepath=None, sheet_name=None, position='A1', overwrite_file
         """
         sheet_name = _translate_sheet_name(sheet_name)
 
-        df = self.to_frame(fold_last_axis_name=True)
+        if wide:
+            pd_obj = self.to_frame(fold_last_axis_name=True)
+        else:
+            pd_obj = self.to_series()
+
         if engine is None:
             engine = 'xlwings' if xw is not None else None
 
@@ -5977,7 +5987,7 @@ def to_excel(self, filepath=None, sheet_name=None, position='A1', overwrite_file
                 sheet = wb.sheets.add(sheet_name, after=wb.sheets[-1])
 
             options = dict(header=header, index=header, transpose=transpose)
-            sheet[position].options(**options).value = df
+            sheet[position].options(**options).value = pd_obj
             # TODO: implement transpose via/in dump
             # sheet[position] = self.dump(header=header, transpose=transpose)
             if close:
@@ -5988,7 +5998,7 @@ def to_excel(self, filepath=None, sheet_name=None, position='A1', overwrite_file
                 sheet_name = 'Sheet1'
             # TODO: implement position in this case
             # startrow, startcol
-            df.to_excel(filepath, sheet_name, *args, engine=engine, **kwargs)
+            pd_obj.to_excel(filepath, sheet_name, *args, engine=engine, **kwargs)
 
     def to_clipboard(self, *args, **kwargs):
         """Sends the content of the array to clipboard.
diff --git a/larray/tests/test_array.py b/larray/tests/test_array.py
@@ -3187,7 +3187,8 @@ def test_to_csv(self):
         with open(self.tmp_path('out.csv')) as f:
             self.assertEqual(f.readlines()[:3], result)
 
-        la.to_csv(self.tmp_path('out.csv'), transpose=False)
+        # stacked data (one column containing all the values and another column listing the context of the value)
+        la.to_csv(self.tmp_path('out.csv'), wide=False)
         result = ['arr,age,sex,nat,time,0\n',
                   '1,0,F,1,2007,3722\n',
                   '1,0,F,1,2010,3395\n']
@@ -3217,6 +3218,13 @@ def test_to_excel_xlsxwriter(self):
         res = read_excel(fpath, engine='xlrd')
         assert_array_equal(res, a1)
 
+        # fpath/Sheet1/A1
+        # stacked data (one column containing all the values and another column listing the context of the value)
+        a1.to_excel(fpath, wide=False, engine='xlsxwriter')
+        res = read_excel(fpath, engine='xlrd')
+        stacked_a1 = a1.reshape([a1.a, Axis([0])])
+        assert_array_equal(res, stacked_a1)
+
         # 2D
         a2 = ndtest((2, 3))
 
@@ -3270,6 +3278,13 @@ def test_to_excel_xlsxwriter(self):
         res = read_excel(fpath, engine='xlrd')
         assert_array_equal(res, a1)
 
+        # fpath/Sheet1/A1
+        # stacked data (one column containing all the values and another column listing the context of the value)
+        a1.to_excel(fpath, wide=False, engine='xlsxwriter')
+        res = read_excel(fpath, engine='xlrd')
+        stacked_a1 = a1.reshape([a1.a, Axis([0])])
+        assert_array_equal(res, stacked_a1)
+
         # 2D
         a2 = ndtest((2, 3))
 
@@ -3352,6 +3367,12 @@ def test_to_excel_xlwings(self):
         res = read_excel(fpath, engine='xlrd')
         assert_array_equal(res, a1)
 
+        # fpath/Sheet1/A1
+        # stacked data (one column containing all the values and another column listing the context of the value)
+        a1.to_excel(fpath, wide=False, engine='xlwings')
+        res = read_excel(fpath, engine='xlrd')
+        assert_array_equal(res, a1)
+
         # 2D
         a2 = ndtest((2, 3))
 
