Reports¶
The reportlib sub-module provides the Report class for generating text based time series reports.
The Report class¶
- class Report(*tseries, **kwargs)¶
Create a tabular TimeSeries report with dates in the left column. All parameters are optional and simply serve as the defaults when calling the report. Parameters for calling the report are the exact same as for initialization. When calling the report, new options specified will not be saved to the instance.
Parameters: *tseries : {TimeSeries objects}, optional
The time series objects to generate a report for. Must all be the same frequency, but do not need to be aligned.
dates : {DateArray}, optional
dates at which values of all the series will be output. If not specified, data will be output from the minimum start_date to the maximum end_date of all the time series objects
header_row : {list of strings}, optional
List of column headers. Specifying the header for the date column is optional.
header_char : {“-”, str}, optional
Character to be used for the row separator line between the header and first row of data. Specify None for no separator. This is ignored if header_row is not specified.
header_justify : {‘left’, ‘right’, ‘center’, list of these values}, optional
Determines how headers are justified. If not specified, all headers are left justified. If a single string is specified all headers will be justified the same way. If a list is specified, each header will be justified according to the specification for that header in the list. Specifying the justification for the date column header is optional.
row_char : {str}, optional
Character to be used for the row separator line between each row of data. By default, there is no separator between rows.
footer_func : {list of aggregation functions or single function}, optional
A function or list of functions for summarizing each data column in the report. For example, ma.sum to get the sum of the column. If a list of functions is provided there must be exactly one function for each column. Be careful to ensure that the function properly handles masked values. Do not specify a function for the Date column.
footer_char : {‘-‘, str}
Character to be used for the row separator line between the last row of data and the footer. Specify None for no separator. This is ignored if footer_func is not specified.
footer_label : {str}
label for the footer row. This goes at the end of the date column. This is ignored if footer_func is not specified.
justify : {‘left’, ‘right’, ‘center’, list of these values}, optional
Determines how data are justified in each column. If not specified, the date column and string columns are left justified, and everything else is right justified. If a single string is specified, all columns will be justified the same way. If a list is specified, each column will be justified according to the specification for that column in the list. Specifying the justification for the date column is optional.
prefix : {str}, optional
A string prepended to each printed row.
postfix`: {str}, optional
A string appended to each printed row.
mask_rep : {‘–’, str}, optional
String used to represent masked values in output
datefmt : {str}, optional
Formatting string used for displaying the. If not specified, the default format for the given frequency is used.
fmt_func : {list of functions or single function}, optional
A function or list of functions for formatting each data column in the report. If not specified, str() is simply called on each item. If a list of functions is provided, there must be exactly one function for each column. Do not specify a function for the Date column, that is handled by the datefmt argument.
wrap_func : {list of functions or single function}, optional
A function for wrapping text; each element in the column is first wrapped by this function. Instances of wrap_onspace, wrap_onspace_strict, and wrap_always (which are part of this module) work well for this. For example, wrap_func=wrap_onspace(10). If a list of functions is specified, each column will be wrapped according to the specification for that column in the list. Specify None for columns you do not wish to wrap. Specifying a function for the Date column is optional
col_width : {list of integers or single integer}, optional
Use this to specify a width for all columns (single integer), or each column individually (list of integers). The column will be at least as wide as col_width, but may be larger if cell contents exceed col_width. If specifying a list, you may optionally specify the width for the Date column as the first entry
output : {sys.stdout, file like object}, optional
file like object to send output to. Only requirement is that it has a write method that accepts a single string.
fixed_width : {True, False}, optional
If True, columns are fixed width (ie. cells will be padded with spaces to ensure all cells in a given column are the same width). If False, col_width will be ignored and cells will not be padded.
Methods
__call__(*tseries, **kwargs) generate a report. Parameter values are not saved to the Report instance. set_options(*tseries, **kwargs) set new options or modify options in the report
Examples¶
The following variables will be used throughout the examples
>>> import scikits.timeseries.lib.reportlib as rl
>>> ser1 = ts.time_series(np.random.uniform(-100,100,10),
... start_date=ts.now('b')-5)
>>> ser2 = ts.time_series(np.random.uniform(-100,100,10),
... start_date=ts.now('b'))
>>> strings = ['some string', 'another string',
... 'yet another, string', 'final string']
>>> ser3 = ts.time_series(strings,
... start_date=ts.now('b'),
... dtype=np.string_)
>>> dArray = ts.date_array(start_date=ts.now('b'), length=3)
Example 1: Basic report¶
>>> basicReport = rl.Report(ser1, ser2, ser3)
>>> basicReport()
29-Jan-2007 | -95.4554568525 | -- | --
30-Jan-2007 | 8.58356086571 | -- | --
31-Jan-2007 | 41.6353000447 | -- | --
01-Feb-2007 | -70.4674570816 | -- | --
02-Feb-2007 | 2.98803489327 | -- | --
05-Feb-2007 | -21.6474414786 | -77.750560056 | some string
06-Feb-2007 | 84.3212422071 | 56.2238118715 | another string
07-Feb-2007 | 23.5664556686 | 64.2491772743 | yet another, string
08-Feb-2007 | 34.8778728662 | -39.4734173695 | final string
09-Feb-2007 | -64.0545308092 | -83.7175337221 | --
12-Feb-2007 | -- | 52.4958419122 | --
13-Feb-2007 | -- | 7.1396171176 | --
14-Feb-2007 | -- | -57.7688749366 | --
15-Feb-2007 | -- | 71.2844695721 | --
16-Feb-2007 | -- | 87.1665936067 | --
Example 2: csv report for excel¶
>>> mycsv = open('mycsv.csv', 'w')
>>> strfmt = lambda x: '"'+str(x)+'"'
>>> fmt_func = [None, None, strfmt]
>>> csvReport = rl.Report(ser1, ser2, ser3, fmt_func=fmt_func,
... mask_rep='#N/A', delim=',',
... fixed_width=False)
>>> csvReport() # output to sys.stdout
29-Jan-2007,67.4086881661,#N/A,#N/A
30-Jan-2007,-78.8405461996,#N/A,#N/A
31-Jan-2007,10.0559754743,#N/A,#N/A
01-Feb-2007,-71.149716374,#N/A,#N/A
02-Feb-2007,-46.055865283,#N/A,#N/A
05-Feb-2007,35.9105419931,85.1744316431,"some string"
06-Feb-2007,2.93015788615,-87.0634270731,"another string"
07-Feb-2007,-49.0774248826,-91.4854233865,"yet another, string"
08-Feb-2007,94.8175754225,36.587114053,"final string"
09-Feb-2007,-88.9474880802,37.3563788938,#N/A
12-Feb-2007,#N/A,21.1325367724,#N/A
13-Feb-2007,#N/A,72.2437957896,#N/A
14-Feb-2007,#N/A,37.2619438419,#N/A
15-Feb-2007,#N/A,-87.1465826319,#N/A
16-Feb-2007,#N/A,63.5556895555,#N/A
>>> csvReport(output=mycsv) # output to file
Example 3: HTML report¶
>>> numfmt = lambda x: '%.2f' % x
>>> fmt_func = [numfmt, numfmt, None]
>>> footer_func = [ma.sum, ma.sum, None]
>>> footer_label = "Total"
>>> htmlReport = rl.Report(ser1, ser2, ser3)
>>> htmlReport.set_options(prefix='<tr><td>',
... delim='</td><td>',
... postfix='</td></tr>')
>>> htmlReport.set_options(wrap_func=rl.wrap_onspace(10,nls='<BR>'))
>>> htmlReport.set_options(fmt_func=fmt_func)
>>> htmlReport.set_options(footer_label=footer_label,
... footer_func=footer_func,
... footer_char='')
>>> htmlReport.set_options(dates=dArray)
>>> htmlReport() # output to sys.stdout
<tr><td>05-Feb-2007</td><td> 91.66</td><td>-99.21</td><td>some<BR>string </td></tr>
<tr><td>06-Feb-2007</td><td>-68.84</td><td> 30.50</td><td>another<BR>string </td></tr>
<tr><td>07-Feb-2007</td><td> 93.53</td><td> 90.46</td><td>yet<BR>another,<BR>string</td></tr>
<tr><td>Total </td><td>116.36</td><td> 21.75</td><td> </td></tr>
Example 4: Extra Options¶
>>> basicReport = rl.Report(ser1, ser2, ser3, dates=dArray)
Output report with a header¶
By default, a line of dashes will separate the header and the first row of data. Optionally, you can specify a label for the Date column as well (so a list with four entries instead of three like this example), If you wish to get rid of the separator line, or use a different character, specify: header_char=''
>>> basicReport(header_row=['col 1', 'col 2', 'col 3'])
| col 1 | col 2 | col 3
------------------------------------------------------------------
06-Feb-2007 | 2.59583929443 | -96.2110139217 | some string
07-Feb-2007 | -24.1064434097 | 86.0387977626 | another string
08-Feb-2007 | -21.6432010416 | 4.83754030508 | yet another, string
Change column justification for the report¶
You can specify a single string (‘right’, ‘left’, or ‘center’) and this will impact all columns, or you can specify a list of strings (optionally including the Date column, which is ‘left’ by default)
>>> basicReport(justify=['left', 'left', 'right'])
06-Feb-2007 | 2.59583929443 | -96.2110139217 | some string
07-Feb-2007 | -24.1064434097 | 86.0387977626 | another string
08-Feb-2007 | -21.6432010416 | 4.83754030508 | yet another, string
Change formatting of Date column¶
>>> basicReport(datefmt='%d')
06 | 2.59583929443 | -96.2110139217 | some string
07 | -24.1064434097 | 86.0387977626 | another string
08 | -21.6432010416 | 4.83754030508 | yet another, string
Add a separater line between each row¶
>>> basicReport(row_char='-')
06-Feb-2007 | 2.59583929443 | -96.2110139217 | some string
-------------------------------------------------------------------
07-Feb-2007 | -24.1064434097 | 86.0387977626 | another string
-------------------------------------------------------------------
08-Feb-2007 | -21.6432010416 | 4.83754030508 | yet another, string
Report different series¶
Notice that the other options set remain intact (ie. dates=dArray)
>>> basicReport(ser1)
06-Feb-2007 | 2.59583929443
07-Feb-2007 | -24.1064434097
08-Feb-2007 | -21.6432010416
Specify column widths¶
Just as in the header and justify options, you can specify a single value to affect all columns, or a list which optionally includes a specification for the Date column. Specify -1 to auto-size a column
>>> basicReport(col_width=[20, 20, -1])
06-Feb-2007 | 2.59583929443 | -96.2110139217 | some string
07-Feb-2007 | -24.1064434097 | 86.0387977626 | another string
08-Feb-2007 | -21.6432010416 | 4.83754030508 | yet another, string