fix #676 : implemented ExcelReport class which generates an Excel file with multiple graphs

moved _positive_integer() from util/options.py to util/misc.py

added get_example_templates_dir() function

Author: alixdamman

MANIFEST.in

@@ -1,2 +1,3 @@
 include COPYING
-recursive-include larray/tests/data *.csv *.xlsx *.h5
+recursive-include larray/tests/data *.csv *.xlsx *.h5
+recursive-include larray/tests/excel_template *.crtx

doc/source/api.rst

@@ -675,6 +675,22 @@ Excel
    Workbook.close
    Workbook.app
 
+ExcelReport
+===========
+
+.. autosummary::
+   :toctree: _generated/
+
+   ExcelReport
+   ExcelReport.set_template_dir
+   ExcelReport.set_graph_template
+   ExcelReport.set_item_default_size
+   ExcelReport.set_sheet
+   ExcelReport.newline
+   ExcelReport.add_title
+   ExcelReport.add_graph
+   ExcelReport.to_excel
+
 .. _api-misc:
 
 Miscellaneous
@@ -687,6 +703,7 @@ Miscellaneous
    from_frame
    from_series
    get_example_filepath
+   get_example_templates_dir
    set_options
    get_options
    labels_array

larray/__init__.py

@@ -30,6 +30,7 @@
 from larray.inout.sas import read_sas
 from larray.inout.stata import read_stata
 from larray.inout.xw_excel import open_excel, Workbook
+from larray.inout.xw_reporting import ExcelReport
 
 # just make sure handlers for .pkl and .pickle are initialized
 import larray.inout.pickle as _pkl
@@ -41,7 +42,7 @@
 
 from larray.extra.ipfp import ipfp
 
-from larray.example import get_example_filepath, load_example_data
+from larray.example import get_example_filepath, load_example_data, get_example_templates_dir
 
 import larray.random
 
@@ -75,15 +76,16 @@
     'real_if_close', 'interp', 'isnan', 'isinf', 'inverse',
     # inout
     'from_lists', 'from_string', 'from_frame', 'from_series', 'read_csv', 'read_tsv',
-    'read_eurostat', 'read_excel', 'read_hdf', 'read_sas', 'read_stata', 'open_excel', 'Workbook',
+    'read_eurostat', 'read_excel', 'read_hdf', 'read_sas', 'read_stata',
+    'open_excel', 'Workbook', 'ExcelReport',
     # utils
     'get_options', 'set_options',
     # viewer
     'view', 'edit', 'compare',
     # ipfp
     'ipfp',
     # example
-    'get_example_filepath', 'load_example_data',
+    'get_example_filepath', 'load_example_data', 'get_example_templates_dir',
 ]
 
 

larray/example.py

@@ -2,12 +2,18 @@
 import larray as la
 
 
-EXAMPLE_FILES_DIR = os.path.dirname(__file__) + '/tests/data/'
+_TEST_DIR = os.path.join(os.path.dirname(__file__), 'tests')
+
+EXAMPLE_FILES_DIR = os.path.join(_TEST_DIR, 'data')
+# TODO : replace 'demography.h5' by 'population_session.h5' and remove 'demo' ?
 AVAILABLE_EXAMPLE_DATA = {
+    'demo': os.path.join(EXAMPLE_FILES_DIR, 'population_session.h5'),
     'demography': os.path.join(EXAMPLE_FILES_DIR, 'demography.h5')
 }
 AVAILABLE_EXAMPLE_FILES = os.listdir(EXAMPLE_FILES_DIR)
 
+EXAMPLE_EXCEL_TEMPLATES_DIR = os.path.join(_TEST_DIR, 'excel_template')
+
 
 def get_example_filepath(fname):
     """Return absolute path to an example file if exist.
@@ -77,3 +83,32 @@ def load_example_data(name):
     if name not in AVAILABLE_EXAMPLE_DATA.keys():
         raise ValueError("example_data must be chosen from list {}".format(list(AVAILABLE_EXAMPLE_DATA.keys())))
     return la.Session(AVAILABLE_EXAMPLE_DATA[name])
+
+
+def get_example_templates_dir():
+    """
+    Return the path the directory containing example Excel template files.
+
+    Examples
+    --------
+    >>> tmpl_dir = get_example_templates_dir()
+
+    >>> # list of all available example templates
+    >>> for template_file in sorted(os.listdir(tmpl_dir)):
+    ...     print(template_file)
+    Area.crtx
+    Area_100Stacked.crtx
+    Area_Stacked.crtx
+    Bar_100Stacked.crtx
+    Bar_Clustered.crtx
+    Bar_Stacked.crtx
+    Line.crtx
+    Line_Comp_Proj.crtx
+    Line_Marker.crtx
+    Line_Marker_Comp_Proj.crtx
+    Line_Marker_Proj.crtx
+    Line_proj.crtx
+    Pie.crtx
+    Scat.crtx
+    """
+    return EXAMPLE_EXCEL_TEMPLATES_DIR