Coverage for src/thunderlab/tabledata.py: 88%
1570 statements
« prev ^ index » next coverage.py v7.7.0, created at 2025-03-18 22:36 +0000
1"""
2Tables with hierarchical headers and units
4## Classes
6- `class TableData`: tables with a rich hierarchical header
7 including units and column-specific formats. Kind of similar to a
8 pandas data frame, but with intuitive numpy-style indexing and nicely
9 formatted output to csv, html, and latex.
12## Helper functions
14- `write()`: shortcut for constructing and writing a TableData.
15- `latex_unit()`: translate unit string into SIunit LaTeX code.
16- `index2aa()`: convert an integer into an alphabetical representation.
17- `aa2index()`: convert an alphabetical representation to an index.
20## Configuration
22- `add_write_table_config()`: add parameter specifying how to write a table to a file as a new section to a configuration.
23- `write_table_args()`: translates a configuration to the respective parameter names for writing a table to a file.
24"""
26import sys
27import os
28import re
29import math as m
30import numpy as np
31from io import StringIO
32try:
33 import pandas as pd
34 has_pandas = True
35except ImportError:
36 has_pandas = False
39__pdoc__ = {}
40__pdoc__['TableData.__contains__'] = True
41__pdoc__['TableData.__len__'] = True
42__pdoc__['TableData.__iter__'] = True
43__pdoc__['TableData.__next__'] = True
44__pdoc__['TableData.__setupkey__'] = True
45__pdoc__['TableData.__call__'] = True
46__pdoc__['TableData.__getitem__'] = True
47__pdoc__['TableData.__setitem__'] = True
48__pdoc__['TableData.__delitem__'] = True
49__pdoc__['TableData.__str__'] = True
52default_missing_str = '-'
53"""Default string indicating nan data elements when outputting data."""
55default_missing_inputs = ['na', 'NA', 'nan', 'NAN', '-']
56"""Default strings that are translated to nan when loading table data."""
59class TableData(object):
60 """Table with numpy-style indexing and a rich hierarchical header including units and formats.
62 Parameters
63 ----------
64 data: str, stream, ndarray
65 - a filename: load table from file with name `data`.
66 - a stream/file handle: load table from that stream.
67 - 1-D or 2-D ndarray of data: the data of the table.
68 Requires als a specified `header`.
69 header: list of str
70 Header labels for each column.
71 units: list of str, optional
72 Unit strings for each column.
73 formats: str or list of str, optional
74 Format strings for each column. If only a single format string is
75 given, then all columns are initialized with this format string.
76 missing: list of str
77 Missing data are indicated by one of these strings.
79 Manipulate table header
80 -----------------------
82 Each column of the table has a label (the name of the column), a
83 unit, and a format specifier. Sections group columns into a hierarchy.
85 - `__init__()`: initialize a TableData from data or a file.
86 - `append()`: append column to the table.
87 - `insert()`: insert a table column at a given position.
88 - `remove()`: remove columns from the table.
89 - `section()`: the section name of a specified column.
90 - `set_section()`: set a section name.
91 - `append_section()`: add sections to the table header.
92 - `insert_section()`: insert a section at a given position of the table header.
93 - `label()`: the name of a column.
94 - `set_label()`: set the name of a column.
95 - `unit()`: the unit of a column.
96 - `set_unit()`: set the unit of a column.
97 - `set_units()`: set the units of all columns.
98 - `format()`: the format string of the column.
99 - `set_format()`: set the format string of a column.
100 - `set_formats()`: set the format strings of all columns.
102 For example:
103 ```
104 tf = TableData('data.csv')
105 ```
106 loads a table directly from a file. See `load()` for details.
107 ```
108 tf = TableData(np.random.randn(4,3), header=['aaa', 'bbb', 'ccc'], units=['m', 's', 'g'], formats='%.2f')
109 ```
110 results in
111 ``` plain
112 aaa bbb ccc
113 m s g
114 1.45 0.01 0.16
115 -0.74 -0.58 -1.34
116 -2.06 0.08 1.47
117 -0.43 0.60 1.38
118 ```
120 A more elaborate way to construct a table is:
121 ```
122 df = TableData()
123 # first column with section names and 3 data values:
124 df.append(["data", "partial information", "size"], "m", "%6.2f",
125 [2.34, 56.7, 8.9])
126 # next columns with single data values:
127 df.append("full weight", "kg", "%.0f", 122.8)
128 df.append_section("complete reaction")
129 df.append("speed", "m/s", "%.3g", 98.7)
130 df.append("median jitter", "mm", "%.1f", 23)
131 df.append("size", "g", "%.2e", 1.234)
132 # add a missing value to the second column:
133 df.append_data(np.nan, 1)
134 # fill up the remaining columns of the row:
135 df.append_data((0.543, 45, 1.235e2))
136 # append data to the next row starting at the second column:
137 df.append_data((43.21, 6789.1, 3405, 1.235e-4), 1) # next row
138 ```
139 results in
140 ``` plain
141 data
142 partial information complete reaction
143 size full weight speed median jitter size
144 m kg m/s mm g
145 2.34 123 98.7 23.0 1.23e+00
146 56.70 - 0.543 45.0 1.24e+02
147 8.90 43 6.79e+03 3405.0 1.23e-04
148 ```
150 Table columns
151 -------------
153 Columns can be specified by an index or by the name of a column. In
154 table headers with sections the colum can be specified by the
155 section names and the column name separated by '>'.
157 - `index()`: the index of a column.
158 - `__contains__()`: check for existence of a column.
159 - `find_col()`: find the start and end index of a column specification.
160 - `column_spec()`: full specification of a column with all its section names.
161 - `column_head()`: the name, unit, and format of a column.
162 - `table_header()`: the header of the table without content.
164 For example:
165 ```
166 df.index('complete reaction>size) # returns 4
167 'speed' in df # is True
168 ```
170 Iterating over columns
171 ----------------------
173 A table behaves like an ordered dictionary with column names as
174 keys and the data of each column as values.
175 Iterating over a table goes over columns.
177 - `keys()`: list of unique column keys for all available columns.
178 - `values()`: list of column data corresponding to keys().
179 - `items()`: list of tuples with unique column specifications and the corresponding data.
180 - `__len__()`: the number of columns.
181 - `__iter__()`: initialize iteration over data columns.
182 - `__next__()`: return data of next column as a list.
183 - `data`: the table data as a list over columns each containing a list of data elements.
185 For example:
186 ```
187 print('column specifications:')
188 for c in range(df.columns()):
189 print(df.column_spec(c))
190 print('keys():')
191 for c, k in enumerate(df.keys()):
192 print('%d: %s' % (c, k))
193 print('values():')
194 for c, v in enumerate(df.values()):
195 print(v)
196 print('iterating over the table:')
197 for v in df:
198 print(v)
199 ```
200 results in
201 ``` plain
202 column specifications:
203 data>partial information>size
204 data>partial information>full weight
205 data>complete reaction>speed
206 data>complete reaction>median jitter
207 data>complete reaction>size
208 keys():
209 0: data>partial information>size
210 1: data>partial information>full weight
211 2: data>complete reaction>speed
212 3: data>complete reaction>median jitter
213 4: data>complete reaction>size
214 values():
215 [2.34, 56.7, 8.9]
216 [122.8, nan, 43.21]
217 [98.7, 0.543, 6789.1]
218 [23, 45, 3405]
219 [1.234, 123.5, 0.0001235]
220 iterating over the table:
221 [2.34, 56.7, 8.9]
222 [122.8, nan, 43.21]
223 [98.7, 0.543, 6789.1]
224 [23, 45, 3405]
225 [1.234, 123.5, 0.0001235]
226 ```
228 Accessing data
229 --------------
231 In contrast to the iterator functions the [] operator treats the
232 table as a 2D-array where the first index indicates the row and
233 the second index the column.
235 Like a numpy aray the table can be sliced, and logical indexing can
236 be used to select specific parts of the table.
238 As for any function, columns can be specified as indices or strings.
240 - `rows()`: the number of rows.
241 - `columns()`: the number of columns.
242 - `shape`: number of rows and columns.
243 - `row()`: a single row of the table as TableData.
244 - `row_dict()`: a single row of the table as dictionary.
245 - `col()`: a single column of the table as TableData.
246 - `__call__()`: a single column of the table as ndarray.
247 - `__getitem__()`: data elements specified by slice.
248 - `__setitem__()`: assign values to data elements specified by slice.
249 - `__delitem__()`: delete data elements or whole columns or rows.
250 - `array()`: the table data as a ndarray.
251 - `data_frame()`: the table data as a pandas DataFrame.
252 - `dicts()`: the table as a list of dictionaries.
253 - `dict()`: the table as a dictionary.
254 - `append_data()`: append data elements to successive columns.
255 - `append_data_column()`: append data elements to a column.
256 - `set_column()`: set the column where to add data.
257 - `fill_data()`: fill up all columns with missing data.
258 - `clear_data()`: clear content of the table but keep header.
259 - `key_value()`: a data element returned as a key-value pair.
261 - `sort()`: sort the table rows in place.
262 - `statistics()`: descriptive statistics of each column.
264 For example:
265 ```
266 # single column:
267 df('size') # data of 'size' column as ndarray
268 df[:,'size'] # data of 'size' column as ndarray
269 df.col('size') # table with the single column 'size'
271 # single row:
272 df[2,:] # table with data of only the third row
273 df.row(2) # table with data of only the third row
275 # slices:
276 df[2:5,['size','jitter']] # sub-table
277 df[2:5,['size','jitter']].array() # ndarray with data only
279 # logical indexing:
280 df[df('speed') > 100.0, 'size'] = 0.0 # set size to 0 if speed is > 100
282 # delete:
283 del df[3:6, 'weight'] # delete rows 3-6 from column 'weight'
284 del df[3:5,:] # delete rows 3-5 completeley
285 del df[:,'speed'] # remove column 'speed' from table
286 df.remove('weight') # remove column 'weigth' from table
288 # sort and statistics:
289 df.sort(['weight', 'jitter'])
290 df.statistics()
291 ```
292 statistics() returns a table with standard descriptive statistics:
293 ``` plain
294 statistics data
295 - partial information complete reaction
296 - size full weight speed median jitter size
297 - m kg m/s mm g
298 mean 22.65 83 2.3e+03 1157.7 4.16e+01
299 std 24.23 40 3.18e+03 1589.1 5.79e+01
300 min 2.34 43 0.543 23.0 1.23e-04
301 quartile1 5.62 83 49.6 34.0 6.17e-01
302 median 8.90 123 98.7 45.0 1.23e+00
303 quartile3 32.80 - 3.44e+03 1725.0 6.24e+01
304 max 56.70 123 6.79e+03 3405.0 1.24e+02
305 count 3.00 2 3 3.0 3.00e+00
306 ```
308 Write and load tables
309 ---------------------
311 Table data can be written to a variety of text-based formats
312 including comma separated values, latex and html files. Which
313 columns are written can be controlled by the hide() and show()
314 functions. TableData can be loaded from all the written file formats
315 (except html), also directly via the constructor.
317 - `hide()`: hide a column or a range of columns.
318 - `hide_all()`: hide all columns.
319 - `hide_empty_columns()`: hide all columns that do not contain data.
320 - `show()`: show a column or a range of columns.
321 - `write()`: write table to a file or stream.
322 - `write_file_stream()`: write table to file or stream and return appropriate file name.
323 - `__str__()`: write table to a string.
324 - `load()`: load table from file or stream.
325 - `formats`: list of supported file formats for writing.
326 - `descriptions`: dictionary with descriptions of the supported file formats.
327 - `extensions`: dictionary with default filename extensions for each of the file formats.
328 - `ext_formats`: dictionary mapping filename extensions to file formats.
330 See documentation of the `write()` function for examples of the supported file formats.
332 """
334 formats = ['dat', 'ascii', 'csv', 'rtai', 'md', 'tex', 'html']
335 """list of strings: Supported output formats."""
336 descriptions = {'dat': 'data text file', 'ascii': 'ascii-art table',
337 'csv': 'comma separated values', 'rtai': 'rtai-style table',
338 'md': 'markdown', 'tex': 'latex tabular',
339 'html': 'html markup'}
340 """dict: Decription of output formats corresponding to `formats`."""
341 extensions = {'dat': 'dat', 'ascii': 'txt', 'csv': 'csv', 'rtai': 'dat',
342 'md': 'md', 'tex': 'tex', 'html': 'html'}
343 """dict: Default file extensions for the output `formats`. """
344 ext_formats = {'dat': 'dat', 'DAT': 'dat', 'txt': 'dat', 'TXT': 'dat',
345 'csv': 'csv', 'CSV': 'csv', 'md': 'md', 'MD': 'md',
346 'tex': 'tex', 'TEX': 'tex', 'html': 'html', 'HTML': 'html'}
347 """dict: Mapping of file extensions to the output formats."""
349 def __init__(self, data=None, header=None, units=None, formats=None,
350 missing=default_missing_inputs, stop=None):
351 self.data = []
352 self.shape = (0, 0)
353 self.header = []
354 self.nsecs = 0
355 self.units = []
356 self.formats = []
357 self.hidden = []
358 self.setcol = 0
359 self.addcol = 0
360 if header is not None:
361 if units is None:
362 units = ['']*len(header)
363 if formats is None:
364 formats = ['%g']*len(header)
365 elif not isinstance(formats, (list, tuple, np.ndarray)):
366 formats = [formats]*len(header)
367 for h, u, f in zip(header, units, formats):
368 self.append(h, u, f)
369 if data is not None:
370 if isinstance(data, TableData):
371 self.shape = data.shape
372 self.nsecs = data.nsecs
373 self.setcol = data.setcol
374 self.addcol = data.addcol
375 for c in range(data.columns()):
376 self.header.append([])
377 for h in data.header[c]:
378 self.header[c].append(h)
379 self.units.append(data.units[c])
380 self.formats.append(data.formats[c])
381 self.hidden.append(data.hidden[c])
382 self.data.append([])
383 for d in data.data[c]:
384 self.data[c].append(d)
385 elif has_pandas and isinstance(data, pd.DataFrame):
386 for k in data.keys():
387 values = data[k].tolist()
388 f = '%s' if isinstance(values[0], str) else '%g'
389 self.append(k, '', f, value=values)
390 elif isinstance(data, (list, tuple, np.ndarray)):
391 if isinstance(data[0], (list, tuple, np.ndarray)):
392 # 2D list, rows first:
393 for row in data:
394 for c, val in enumerate(row):
395 self.data[c].append(val)
396 else:
397 # 1D list:
398 for c, val in enumerate(data):
399 self.data[c].append(val)
400 else:
401 self.load(data, missing, stop)
403 def append(self, label, unit=None, formats=None, value=None,
404 fac=None, key=None):
405 """Append column to the table.
407 Parameters
408 ----------
409 label: str or list of str
410 Optional section titles and the name of the column.
411 unit: str or None
412 The unit of the column contents.
413 formats: str or None
414 The C-style format string used for printing out the column content, e.g.
415 '%g', '%.2f', '%s', etc.
416 If None, the format is set to '%g'.
417 value: None, float, int, str, etc. or list thereof, or list of dict
418 If not None, data for the column.
419 If list of dictionaries, extract from each dictionary in the list
420 the value specified by `key`. If `key` is `None` use `label` as
421 the key.
422 fac: float
423 If not None, multiply the data values by this number.
424 key: None or key of a dictionary
425 If not None and `value` is a list of dictionaries,
426 extract from each dictionary in the list the value specified
427 by `key` and assign the resulting list as data to the column.
429 Returns
430 -------
431 index: int
432 The index of the new column.
433 """
434 if self.addcol >= len(self.data):
435 if isinstance(label, (list, tuple, np.ndarray)):
436 self.header.append(list(reversed(label)))
437 label = label[-1]
438 else:
439 self.header.append([label])
440 self.formats.append(formats or '%g')
441 self.units.append(unit or '')
442 self.hidden.append(False)
443 self.data.append([])
444 if self.nsecs < len(self.header[-1])-1:
445 self.nsecs = len(self.header[-1])-1
446 else:
447 if isinstance(label, (list, tuple, np.ndarray)):
448 self.header[self.addcol] = list(reversed(label)) + self.header[self.addcol]
449 label = label[-1]
450 else:
451 self.header[self.addcol] = [label] + self.header[self.addcol]
452 self.units[self.addcol] = unit or ''
453 self.formats[self.addcol] = formats or '%g'
454 if self.nsecs < len(self.header[self.addcol])-1:
455 self.nsecs = len(self.header[self.addcol])-1
456 if not key:
457 key = label
458 if value is not None:
459 if isinstance(value, (list, tuple, np.ndarray)):
460 if key and len(value) > 0 and isinstance(value[0], dict):
461 value = [d[key] if key in d else float('nan') for d in value]
462 self.data[-1].extend(value)
463 else:
464 self.data[-1].append(value)
465 if fac:
466 for k in range(len(self.data[-1])):
467 self.data[-1][k] *= fac
468 self.addcol = len(self.data)
469 self.shape = (self.rows(), self.columns())
470 return self.addcol-1
472 def insert(self, column, label, unit=None, formats=None, value=None):
473 """Insert a table column at a given position.
475 .. WARNING::
476 If no `value` is given, the inserted column is an empty list.
478 Parameters
479 ----------
480 columns int or str
481 Column before which to insert the new column.
482 Column can be specified by index or name,
483 see `index()` for details.
484 label: str or list of str
485 Optional section titles and the name of the column.
486 unit: str or None
487 The unit of the column contents.
488 formats: str or None
489 The C-style format string used for printing out the column content, e.g.
490 '%g', '%.2f', '%s', etc.
491 If None, the format is set to '%g'.
492 value: None, float, int, str, etc. or list thereof
493 If not None, data for the column.
495 Returns
496 -------
497 index: int
498 The index of the inserted column.
500 Raises
501 ------
502 IndexError:
503 If an invalid column was specified.
504 """
505 col = self.index(column)
506 if col is None:
507 if isinstance(column, (np.integer, int)):
508 column = '%d' % column
509 raise IndexError('Cannot insert before non-existing column ' + column)
510 if isinstance(label, (list, tuple, np.ndarray)):
511 self.header.insert(col, list(reversed(label)))
512 else:
513 self.header.insert(col, [label])
514 self.formats.insert(col, formats or '%g')
515 self.units.insert(col, unit or '')
516 self.hidden.insert(col, False)
517 self.data.insert(col, [])
518 if self.nsecs < len(self.header[col])-1:
519 self.nsecs = len(self.header[col])-1
520 if value is not None:
521 if isinstance(value, (list, tuple, np.ndarray)):
522 self.data[col].extend(value)
523 else:
524 self.data[col].append(value)
525 self.addcol = len(self.data)
526 self.shape = (self.rows(), self.columns())
527 return col
529 def remove(self, columns):
530 """Remove columns from the table.
532 Parameters
533 -----------
534 columns: int or str or list of int of str
535 Columns can be specified by index or name,
536 see `index()` for details.
538 Raises
539 ------
540 IndexError:
541 If an invalid column was specified.
542 """
543 # fix columns:
544 if not isinstance(columns, (list, tuple, np.ndarray)):
545 columns = [ columns ]
546 if not columns:
547 return
548 # remove:
549 for col in columns:
550 c = self.index(col)
551 if c is None:
552 if isinstance(col, (np.integer, int)):
553 col = '%d' % col
554 raise IndexError('Cannot remove non-existing column ' + col)
555 continue
556 if c+1 < len(self.header):
557 self.header[c+1].extend(self.header[c][len(self.header[c+1]):])
558 del self.header[c]
559 del self.units[c]
560 del self.formats[c]
561 del self.hidden[c]
562 del self.data[c]
563 if self.setcol >= len(self.data):
564 self.setcol = 0
565 self.shape = (self.rows(), self.columns())
567 def section(self, column, level):
568 """The section name of a specified column.
570 Parameters
571 ----------
572 column: None, int, or str
573 A specification of a column.
574 See self.index() for more information on how to specify a column.
575 level: int
576 The level of the section to be returned. The column label itself is level=0.
578 Returns
579 -------
580 name: str
581 The name of the section at the specified level containing
582 the column.
583 index: int
584 The column index that contains this section
585 (equal or smaller thant `column`).
587 Raises
588 ------
589 IndexError:
590 If `level` exceeds the maximum possible level.
591 """
592 if level < 0 or level > self.nsecs:
593 raise IndexError('Invalid section level')
594 column = self.index(column)
595 while len(self.header[column]) <= level:
596 column -= 1
597 return self.header[column][level], column
599 def set_section(self, label, column, level):
600 """Set a section name.
602 Parameters
603 ----------
604 label: str
605 The new name to be used for the section.
606 column: None, int, or str
607 A specification of a column.
608 See self.index() for more information on how to specify a column.
609 level: int
610 The level of the section to be set. The column label itself is level=0.
611 """
612 column = self.index(column)
613 self.header[column][level] = label
614 return column
616 def append_section(self, label):
617 """Add sections to the table header.
619 Each column of the table has a header label. Columns can be
620 grouped into sections. Sections can be nested arbitrarily.
622 Parameters
623 ----------
624 label: stri or list of str
625 The name(s) of the section(s).
627 Returns
628 -------
629 index: int
630 The column index where the section was appended.
631 """
632 if self.addcol >= len(self.data):
633 if isinstance(label, (list, tuple, np.ndarray)):
634 self.header.append(list(reversed(label)))
635 else:
636 self.header.append([label])
637 self.units.append('')
638 self.formats.append('')
639 self.hidden.append(False)
640 self.data.append([])
641 else:
642 if isinstance(label, (list, tuple, np.ndarray)):
643 self.header[self.addcol] = list(reversed(label)) + self.header[self.addcol]
644 else:
645 self.header[self.addcol] = [label] + self.header[self.addcol]
646 if self.nsecs < len(self.header[self.addcol]):
647 self.nsecs = len(self.header[self.addcol])
648 self.addcol = len(self.data)-1
649 self.shape = (self.rows(), self.columns())
650 return self.addcol
652 def insert_section(self, column, section):
653 """Insert a section at a given position of the table header.
655 Parameters
656 ----------
657 columns int or str
658 Column before which to insert the new section.
659 Column can be specified by index or name,
660 see `index()` for details.
661 section: str
662 The name of the section.
664 Returns
665 -------
666 index: int
667 The index of the column where the section was inserted.
669 Raises
670 ------
671 IndexError:
672 If an invalid column was specified.
673 """
674 col = self.index(column)
675 if col is None:
676 if isinstance(column, (np.integer, int)):
677 column = '%d' % column
678 raise IndexError('Cannot insert at non-existing column ' + column)
679 self.header[col].append(section)
680 if self.nsecs < len(self.header[col])-1:
681 self.nsecs = len(self.header[col])-1
682 return col
684 def label(self, column):
685 """The name of a column.
687 Parameters
688 ----------
689 column: None, int, or str
690 A specification of a column.
691 See self.index() for more information on how to specify a column.
693 Returns
694 -------
695 name: str
696 The column label.
697 """
698 column = self.index(column)
699 return self.header[column][0]
701 def set_label(self, label, column):
702 """Set the name of a column.
704 Parameters
705 ----------
706 label: str
707 The new name to be used for the column.
708 column: None, int, or str
709 A specification of a column.
710 See self.index() for more information on how to specify a column.
711 """
712 column = self.index(column)
713 self.header[column][0] = label
714 return column
716 def unit(self, column):
717 """The unit of a column.
719 Parameters
720 ----------
721 column: None, int, or str
722 A specification of a column.
723 See self.index() for more information on how to specify a column.
725 Returns
726 -------
727 unit: str
728 The unit.
729 """
730 column = self.index(column)
731 return self.units[column]
733 def set_unit(self, unit, column):
734 """Set the unit of a column.
736 Parameters
737 ----------
738 unit: str
739 The new unit to be used for the column.
740 column: None, int, or str
741 A specification of a column.
742 See self.index() for more information on how to specify a column.
743 """
744 column = self.index(column)
745 self.units[column] = unit
746 return column
748 def set_units(self, units):
749 """Set the units of all columns.
751 Parameters
752 ----------
753 units: list of str
754 The new units to be used.
755 """
756 for c, u in enumerate(units):
757 self.units[c] = u
759 def format(self, column):
760 """The format string of the column.
762 Parameters
763 ----------
764 column: None, int, or str
765 A specification of a column.
766 See self.index() for more information on how to specify a column.
768 Returns
769 -------
770 format: str
771 The format string.
772 """
773 column = self.index(column)
774 return self.formats[column]
776 def set_format(self, format, column):
777 """Set the format string of a column.
779 Parameters
780 ----------
781 format: str
782 The new format string to be used for the column.
783 column: None, int, or str
784 A specification of a column.
785 See self.index() for more information on how to specify a column.
786 """
787 column = self.index(column)
788 self.formats[column] = format
789 return column
791 def set_formats(self, formats):
792 """Set the format strings of all columns.
794 Parameters
795 ----------
796 formats: str or list of str
797 The new format strings to be used.
798 If only a single format is specified,
799 then all columns get the same format.
800 """
801 if isinstance(formats, (list, tuple, np.ndarray)):
802 for c, f in enumerate(formats):
803 self.formats[c] = f or '%g'
804 else:
805 for c in range(len(self.formats)):
806 self.formats[c] = formats or '%g'
808 def table_header(self):
809 """The header of the table without content.
811 Returns
812 -------
813 data: TableData
814 A TableData object with the same header but empty data.
815 """
816 data = TableData()
817 sec_indices = [-1] * self.nsecs
818 for c in range(self.columns()):
819 data.append(*self.column_head(c))
820 for l in range(self.nsecs):
821 s, i = self.section(c, l+1)
822 if i != sec_indices[l]:
823 data.header[-1].append(s)
824 sec_indices[l] = i
825 data.nsecs = self.nsecs
826 return data
828 def column_head(self, column):
829 """The name, unit, and format of a column.
831 Parameters
832 ----------
833 column: None, int, or str
834 A specification of a column.
835 See self.index() for more information on how to specify a column.
837 Returns
838 -------
839 name: str
840 The column label.
841 unit: str
842 The unit.
843 format: str
844 The format string.
845 """
846 column = self.index(column)
847 return self.header[column][0], self.units[column], self.formats[column]
849 def column_spec(self, column):
850 """Full specification of a column with all its section names.
852 Parameters
853 ----------
854 column: int or str
855 Specifies the column.
856 See self.index() for more information on how to specify a column.
858 Returns
859 -------
860 s: str
861 Full specification of the column by all its section names and its header name.
862 """
863 c = self.index(column)
864 fh = [self.header[c][0]]
865 for l in range(self.nsecs):
866 fh.append(self.section(c, l+1)[0])
867 return '>'.join(reversed(fh))
869 def find_col(self, column):
870 """Find the start and end index of a column specification.
872 Parameters
873 ----------
874 column: None, int, or str
875 A specification of a column.
876 See self.index() for more information on how to specify a column.
878 Returns
879 -------
880 c0: int or None
881 A valid column index or None that is specified by `column`.
882 c1: int or None
883 A valid column index or None of the column following the range specified
884 by `column`.
885 """
887 def find_column_indices(ss, si, minns, maxns, c0, strict=True):
888 if si >= len(ss):
889 return None, None, None, None
890 ns0 = 0
891 for ns in range(minns, maxns+1):
892 nsec = maxns-ns
893 if ss[si] == '':
894 si += 1
895 continue
896 for c in range(c0, len(self.header)):
897 if nsec < len(self.header[c]) and \
898 ( ( strict and self.header[c][nsec] == ss[si] ) or
899 ( not strict and ss[si] in self.header[c][nsec] ) ):
900 ns0 = ns
901 c0 = c
902 si += 1
903 if si >= len(ss):
904 c1 = len(self.header)
905 for c in range(c0+1, len(self.header)):
906 if nsec < len(self.header[c]):
907 c1 = c
908 break
909 return c0, c1, ns0, None
910 elif nsec > 0:
911 break
912 return None, c0, ns0, si
914 if column is None:
915 return None, None
916 if not isinstance(column, (np.integer, int)) and column.isdigit():
917 column = int(column)
918 if isinstance(column, (np.integer, int)):
919 if column >= 0 and column < len(self.header):
920 return column, column+1
921 else:
922 return None, None
923 # find column by header:
924 ss = column.rstrip('>').split('>')
925 maxns = self.nsecs
926 si0 = 0
927 while si0 < len(ss) and ss[si0] == '':
928 maxns -= 1
929 si0 += 1
930 if maxns < 0:
931 maxns = 0
932 c0, c1, ns, si = find_column_indices(ss, si0, 0, maxns, 0, True)
933 if c0 is None and c1 is not None:
934 c0, c1, ns, si = find_column_indices(ss, si, ns, maxns, c1, False)
935 return c0, c1
937 def index(self, column):
938 """The index of a column.
940 Parameters
941 ----------
942 column: None, int, or str
943 A specification of a column.
944 - None: no column is specified
945 - int: the index of the column (first column is zero), e.g. `index(2)`.
946 - a string representing an integer is converted into the column index,
947 e.g. `index('2')`
948 - a string specifying a column by its header.
949 Header names of descending hierarchy are separated by '>'.
951 Returns
952 -------
953 index: int or None
954 A valid column index or None.
955 """
956 c0, c1 = self.find_col(column)
957 return c0
959 def __contains__(self, column):
960 """Check for existence of a column.
962 Parameters
963 ----------
964 column: None, int, or str
965 The column to be checked.
966 See self.index() for more information on how to specify a column.
968 Returns
969 -------
970 contains: bool
971 True if `column` specifies an existing column key.
972 """
973 return self.index(column) is not None
975 def keys(self):
976 """List of unique column keys for all available columns.
978 Returns
979 -------
980 keys: list of str
981 List of unique column specifications.
982 """
983 return [self.column_spec(c) for c in range(self.columns())]
985 def values(self):
986 """List of column data corresponding to keys().
988 Returns
989 -------
990 data: list of list of values
991 The data of the table. First index is columns!
992 """
993 return self.data
995 def items(self):
996 """Column names and corresponding data.
998 Returns
999 -------
1000 items: list of tuples
1001 Unique column specifications and the corresponding data.
1002 """
1003 return [(self.column_spec(c), self.data[c]) for c in range(self.columns())]
1005 def __len__(self):
1006 """The number of columns.
1008 Returns
1009 -------
1010 columns: int
1011 The number of columns contained in the table.
1012 """
1013 return self.columns()
1015 def __iter__(self):
1016 """Initialize iteration over data columns.
1017 """
1018 self.iter_counter = -1
1019 return self
1021 def __next__(self):
1022 """Next column of data.
1024 Returns
1025 -------
1026 data: list of values
1027 Table data of next column.
1028 """
1029 self.iter_counter += 1
1030 if self.iter_counter >= self.columns():
1031 raise StopIteration
1032 else:
1033 return self.data[self.iter_counter]
1035 def next(self):
1036 """Return next data columns. (python2 syntax)
1038 See also:
1039 ---------
1040 `__next__()`
1041 """
1042 return self.__next__()
1044 def rows(self):
1045 """The number of rows.
1047 Returns
1048 -------
1049 rows: int
1050 The number of rows contained in the table.
1051 """
1052 return max(map(len, self.data)) if self.data else 0
1054 def columns(self):
1055 """The number of columns.
1057 Returns
1058 -------
1059 columns: int
1060 The number of columns contained in the table.
1061 """
1062 return len(self.header)
1064 def row(self, index):
1065 """A single row of the table.
1067 Parameters
1068 ----------
1069 index: int
1070 The index of the row to be returned.
1072 Returns
1073 -------
1074 data: TableData
1075 A TableData object with a single row.
1076 """
1077 data = TableData()
1078 sec_indices = [-1] * self.nsecs
1079 for c in range(self.columns()):
1080 data.append(*self.column_head(c))
1081 for l in range(self.nsecs):
1082 s, i = self.section(c, l+1)
1083 if i != sec_indices[l]:
1084 data.header[-1].append(s)
1085 sec_indices[l] = i
1086 data.data[-1] = [self.data[c][index]]
1087 data.nsecs = self.nsecs
1088 return data
1090 def row_dict(self, index):
1091 """A single row of the table.
1093 Parameters
1094 ----------
1095 index: int
1096 The index of the row to be returned.
1098 Returns
1099 -------
1100 data: dict
1101 A dictionary with column header as key and corresponding data value of row `index`
1102 as value.
1103 """
1104 data = {}
1105 for c in range(self.columns()):
1106 data[self.label(c)] = self.data[c][index]
1107 return data
1109 def col(self, column):
1110 """A single column of the table.
1112 Parameters
1113 ----------
1114 column: None, int, or str
1115 The column to be returned.
1116 See self.index() for more information on how to specify a column.
1118 Returns
1119 -------
1120 table: TableData
1121 A TableData object with a single column.
1122 """
1123 data = TableData()
1124 c = self.index(column)
1125 data.append(*self.column_head(c))
1126 data.data = [self.data[c]]
1127 data.nsecs = 0
1128 return data
1130 def __call__(self, column):
1131 """A single column of the table as a ndarray.
1133 Parameters
1134 ----------
1135 column: None, int, or str
1136 The column to be returned.
1137 See self.index() for more information on how to specify a column.
1139 Returns
1140 -------
1141 data: 1-D ndarray
1142 Content of the specified column as a ndarray.
1143 """
1144 c = self.index(column)
1145 return np.asarray(self.data[c])
1147 def __setupkey(self, key):
1148 """Helper function that turns a key into row and column indices.
1150 Returns
1151 -------
1152 rows: list of int, slice, None
1153 Indices of selected rows.
1154 cols: list of int
1155 Indices of selected columns.
1157 Raises
1158 ------
1159 IndexError:
1160 If an invalid column was specified.
1161 """
1162 if type(key) is not tuple:
1163 rows = key
1164 cols = range(self.columns())
1165 else:
1166 rows = key[0]
1167 cols = key[1]
1168 if isinstance(cols, slice):
1169 start = cols.start
1170 if start is not None:
1171 start = self.index(start)
1172 if start is None:
1173 raise IndexError('"%s" is not a valid column index' % cols.start)
1174 stop = cols.stop
1175 if stop is not None:
1176 stop = self.index(stop)
1177 if stop is None:
1178 raise IndexError('"%s" is not a valid column index' % cols.stop)
1179 cols = slice(start, stop, cols.step)
1180 cols = range(self.columns())[cols]
1181 else:
1182 if not isinstance(cols, (list, tuple, np.ndarray)):
1183 cols = [cols]
1184 c = [self.index(inx) for inx in cols]
1185 if None in c:
1186 raise IndexError('"%s" is not a valid column index' % cols[c.index(None)])
1187 cols = c
1188 if isinstance(rows, np.ndarray) and rows.dtype == np.dtype(bool):
1189 rows = np.where(rows)[0]
1190 if len(rows) == 0:
1191 rows = None
1192 return rows, cols
1194 def __getitem__(self, key):
1195 """Data elements specified by slice.
1197 Parameters
1198 -----------
1199 key:
1200 First key specifies row, (optional) second one the column.
1201 Columns can be specified by index or name,
1202 see `index()` for details.
1204 Returns
1205 -------
1206 data:
1207 - A single data value if a single row and a single column is specified.
1208 - A ndarray of data elements if a single single column is specified.
1209 - A TableData object for multiple columns.
1210 - None if no row is selected (e.g. by a logical index that nowhere is True)
1212 Raises
1213 ------
1214 IndexError:
1215 If an invalid column was specified.
1216 """
1217 rows, cols = self.__setupkey(key)
1218 if len(cols) == 1:
1219 if rows is None:
1220 return None
1221 elif isinstance(rows, slice):
1222 return np.asarray(self.data[cols[0]][rows])
1223 elif isinstance(rows, (list, tuple, np.ndarray)):
1224 return np.asarray([self.data[cols[0]][r] for r in rows])
1225 else:
1226 return self.data[cols[0]][rows]
1227 else:
1228 data = TableData()
1229 sec_indices = [-1] * self.nsecs
1230 for c in cols:
1231 data.append(*self.column_head(c))
1232 for l in range(self.nsecs):
1233 s, i = self.section(c, l+1)
1234 if i != sec_indices[l]:
1235 data.header[-1].append(s)
1236 sec_indices[l] = i
1237 if rows is None:
1238 continue
1239 if isinstance(rows, (list, tuple, np.ndarray)):
1240 for r in rows:
1241 data.data[-1].append(self.data[c][r])
1242 else:
1243 if isinstance(self.data[c][rows], (list, tuple, np.ndarray)):
1244 data.data[-1].extend(self.data[c][rows])
1245 else:
1246 data.data[-1].append(self.data[c][rows])
1247 data.nsecs = self.nsecs
1248 return data
1250 def __setitem__(self, key, value):
1251 """Assign values to data elements specified by slice.
1253 Parameters
1254 -----------
1255 key:
1256 First key specifies row, (optional) second one the column.
1257 Columns can be specified by index or name,
1258 see `index()` for details.
1259 value: TableData, list, ndarray, float, ...
1260 Value(s) used to assing to the table elements as specified by `key`.
1262 Raises
1263 ------
1264 IndexError:
1265 If an invalid column was specified.
1266 """
1267 rows, cols = self.__setupkey(key)
1268 if rows is None:
1269 return
1270 if isinstance(value, TableData):
1271 if isinstance(self.data[cols[0]][rows], (list, tuple, np.ndarray)):
1272 for k, c in enumerate(cols):
1273 self.data[c][rows] = value.data[k]
1274 else:
1275 for k, c in enumerate(cols):
1276 self.data[c][rows] = value.data[k][0]
1277 else:
1278 if len(cols) == 1:
1279 if isinstance(rows, (list, tuple, np.ndarray)):
1280 if len(rows) == 1:
1281 self.data[cols[0]][rows[0]] = value
1282 elif isinstance(value, (list, tuple, np.ndarray)):
1283 for k, r in enumerate(rows):
1284 self.data[cols[0]][r] = value[k]
1285 else:
1286 for r in rows:
1287 self.data[cols[0]][r] = value
1288 elif isinstance(value, (list, tuple, np.ndarray)):
1289 self.data[cols[0]][rows] = value
1290 elif isinstance(rows, (np.integer, int)):
1291 self.data[cols[0]][rows] = value
1292 else:
1293 n = len(self.data[cols[0]][rows])
1294 if n > 1:
1295 self.data[cols[0]][rows] = [value]*n
1296 else:
1297 self.data[cols[0]][rows] = value
1298 else:
1299 if isinstance(self.data[0][rows], (list, tuple, np.ndarray)):
1300 for k, c in enumerate(cols):
1301 self.data[c][rows] = value[:,k]
1302 elif isinstance(value, (list, tuple, np.ndarray)):
1303 for k, c in enumerate(cols):
1304 self.data[c][rows] = value[k]
1305 else:
1306 for k, c in enumerate(cols):
1307 self.data[c][rows] = value
1309 def __delitem__(self, key):
1310 """Delete data elements or whole columns or rows.
1312 Parameters
1313 -----------
1314 key:
1315 First key specifies row, (optional) second one the column.
1316 Columns can be specified by index or name,
1317 see `index()` for details.
1318 If all rows are selected, then the specified columns are removed from the table.
1319 Otherwise only data values are removed.
1320 If all columns are selected than entire rows of data values are removed.
1321 Otherwise only data values in the specified rows are removed.
1323 Raises
1324 ------
1325 IndexError:
1326 If an invalid column was specified.
1327 """
1328 rows, cols = self.__setupkey(key)
1329 if rows is None:
1330 return
1331 row_indices = np.arange(self.rows(), dtype=int)[rows]
1332 if isinstance(row_indices, np.ndarray):
1333 if len(row_indices) == self.rows():
1334 # delete whole columns:
1335 self.remove(cols)
1336 elif len(row_indices) > 0:
1337 for r in reversed(sorted(row_indices)):
1338 for c in cols:
1339 del self.data[c][r]
1340 self.shape = (self.rows(), self.columns())
1341 else:
1342 for c in cols:
1343 del self.data[c][row_indices]
1344 self.shape = (self.rows(), self.columns())
1346 def array(self, row=None):
1347 """The table data as a ndarray.
1349 Parameters
1350 ----------
1351 row: int or None
1352 If specified, a 1D ndarray of that row will be returned.
1354 Returns
1355 -------
1356 data: 2D or 1D ndarray
1357 If no row is specified, the data content of the entire table
1358 as a 2D ndarray (rows first).
1359 If a row is specified, a 1D ndarray of that row.
1360 """
1361 if row is None:
1362 return np.array(self.data).T
1363 else:
1364 return np.array([d[row] for d in self.data])
1366 def data_frame(self):
1367 """The table data as a pandas DataFrame.
1369 Returns
1370 -------
1371 data: pandas.DataFrame
1372 A pandas DataFrame of the whole table.
1373 """
1374 return pd.DataFrame(self.dict())
1376 def dicts(self, raw_values=True, missing=default_missing_str):
1377 """The table as a list of dictionaries.
1379 Parameters
1380 ----------
1381 raw_values: bool
1382 If True, use raw table values as values,
1383 else format the values and add unit string.
1384 missing: str
1385 String indicating non-existing data elements.
1387 Returns
1388 -------
1389 table: list of dict
1390 For each row of the table a dictionary with header as key.
1391 """
1392 table = []
1393 for row in range(self.rows()):
1394 data = {}
1395 for col in range(len(self.header)):
1396 if raw_values:
1397 v = self.data[col][row];
1398 else:
1399 if isinstance(self.data[col][row], (float, np.floating)) and m.isnan(self.data[col][row]):
1400 v = missing
1401 else:
1402 u = ''
1403 if not self.units[col] in '1-' and self.units[col] != 'a.u.':
1404 u = self.units[col]
1405 v = (self.formats[col] % self.data[col][row]) + u
1406 data[self.header[col][0]] = v
1407 table.append(data)
1408 return table
1410 def dict(self):
1411 """The table as a dictionary.
1413 Returns
1414 -------
1415 table: dict
1416 A dictionary with keys being the column headers and
1417 values the list of data elements of the corresponding column.
1418 """
1419 table = {k: v for k, v in self.items()}
1420 return table
1422 def append_data(self, data, column=None):
1423 """Append data elements to successive columns.
1425 The current column is set behid the added columns.
1427 Parameters
1428 ----------
1429 data: float, int, str, etc. or list thereof or list of list thereof or dict or list of dict
1430 Data values to be appended to successive columns:
1431 - A single value is simply appened to the specified column of the table.
1432 - A 1D-list of values is appended to successive columns of the table
1433 starting with the specified column.
1434 - The columns of a 2D-list of values (second index) are appended
1435 to successive columns of the table starting with the specified column.
1436 - Values or list of values of a dictionary are added to the
1437 columns specified by the keys. Does not affect the current column.
1438 - The values of dictionaries in a list are appended to the
1439 columns specified by the keys. Does not affect the current column.
1440 column: None, int, or str
1441 The first column to which the data should be appended,
1442 if `data` does not specify columns.
1443 If None, append to the current column.
1444 See self.index() for more information on how to specify a column.
1445 """
1446 column = self.index(column)
1447 if column is None:
1448 column = self.setcol
1449 if isinstance(data, (list, tuple, np.ndarray)):
1450 if isinstance(data[0], (list, tuple, np.ndarray)):
1451 # 2D list, rows first:
1452 for row in data:
1453 for i, val in enumerate(row):
1454 self.data[column+i].append(val)
1455 self.setcol = column + len(data[0])
1456 elif isinstance(data[0], dict):
1457 # list of dictionaries:
1458 for row in data:
1459 for key in row:
1460 column = self.index(k)
1461 self.data[column].append(data[k])
1462 else:
1463 # 1D list:
1464 for val in data:
1465 self.data[column].append(val)
1466 column += 1
1467 self.setcol = column
1468 elif isinstance(data, dict):
1469 # dictionary with values:
1470 for key in data:
1471 column = self.index(key)
1472 if isinstance(data[key], (list, tuple, np.ndarray)):
1473 self.data[column].extend(data[key])
1474 else:
1475 self.data[column].append(data[key])
1476 else:
1477 # single value:
1478 self.data[column].append(data)
1479 self.setcol = column + 1
1480 if self.setcol >= len(self.data):
1481 self.setcol = 0
1482 self.shape = (self.rows(), self.columns())
1484 def append_data_column(self, data, column=None):
1485 """Append data elements to a column.
1487 The current column is incremented by one.
1489 Parameters
1490 ----------
1491 data: float, int, str, etc. or list thereof
1492 Data values to be appended to a column.
1493 column: None, int, or str
1494 The column to which the data should be appended.
1495 If None, append to the current column.
1496 See self.index() for more information on how to specify a column.
1497 """
1498 column = self.index(column)
1499 if column is None:
1500 column = self.setcol
1501 if isinstance(data, (list, tuple, np.ndarray)):
1502 self.data[column].extend(data)
1503 column += 1
1504 self.setcol = column
1505 else:
1506 self.data[column].append(data)
1507 self.setcol = column+1
1508 if self.setcol >= len(self.data):
1509 self.setcol = 0
1510 self.shape = (self.rows(), self.columns())
1512 def set_column(self, column):
1513 """Set the column where to add data.
1515 Parameters
1516 ----------
1517 column: int or str
1518 The column to which data elements should be appended.
1519 See self.index() for more information on how to specify a column.
1521 Raises
1522 ------
1523 IndexError:
1524 If an invalid column was specified.
1525 """
1526 col = self.index(column)
1527 if col is None:
1528 if isinstance(column, (np.integer, int)):
1529 column = '%d' % column
1530 raise IndexError('column ' + column + ' not found or invalid')
1531 self.setcol = col
1532 return col
1534 def fill_data(self):
1535 """Fill up all columns with missing data to have the same number of
1536 data elements.
1537 """
1538 # maximum rows:
1539 maxr = self.rows()
1540 # fill up:
1541 for c in range(len(self.data)):
1542 while len(self.data[c]) < maxr:
1543 self.data[c].append(np.nan)
1544 self.setcol = 0
1545 self.shape = (self.rows(), self.columns())
1547 def clear_data(self):
1548 """Clear content of the table but keep header.
1549 """
1550 for c in range(len(self.data)):
1551 self.data[c] = []
1552 self.setcol = 0
1553 self.shape = (self.rows(), self.columns())
1555 def sort(self, columns, reverse=False):
1556 """Sort the table rows in place.
1558 Parameters
1559 ----------
1560 columns: int or str or list of int or str
1561 A column specifier or a list of column specifiers of the columns
1562 to be sorted.
1563 reverse: boolean
1564 If `True` sort in descending order.
1566 Raises
1567 ------
1568 IndexError:
1569 If an invalid column was specified.
1570 """
1571 # fix columns:
1572 if not isinstance(columns, (list, tuple, np.ndarray)):
1573 columns = [ columns ]
1574 if not columns:
1575 return
1576 cols = []
1577 for col in columns:
1578 c = self.index(col)
1579 if c is None:
1580 if isinstance(col, (np.integer, int)):
1581 col = '%d' % col
1582 raise IndexError('sort column ' + col + ' not found')
1583 continue
1584 cols.append(c)
1585 # get sorted row indices:
1586 row_inx = range(self.rows())
1587 row_inx = sorted(row_inx, key=lambda x : [float('-inf') if self.data[c][x] is np.nan \
1588 or self.data[c][x] != self.data[c][x] \
1589 else self.data[c][x] for c in cols], reverse=reverse)
1590 # sort table according to indices:
1591 for c in range(self.columns()):
1592 self.data[c] = [self.data[c][r] for r in row_inx]
1594 def statistics(self):
1595 """Descriptive statistics of each column.
1596 """
1597 ds = TableData()
1598 if self.nsecs > 0:
1599 ds.append_section('statistics')
1600 for l in range(1,self.nsecs):
1601 ds.append_section('-')
1602 ds.append('-', '-', '%-10s')
1603 else:
1604 ds.append('statistics', '-', '%-10s')
1605 ds.append_data('mean', 0)
1606 ds.append_data('std', 0)
1607 ds.append_data('min', 0)
1608 ds.append_data('quartile1', 0)
1609 ds.append_data('median', 0)
1610 ds.append_data('quartile3', 0)
1611 ds.append_data('max', 0)
1612 ds.append_data('count', 0)
1613 dc = 1
1614 for c in range(self.columns()):
1615 if len(self.data[c]) > 0 and isinstance(self.data[c][0], (float, int, np.floating, np.integer)):
1616 ds.hidden.append(False)
1617 ds.header.append(self.header[c])
1618 ds.units.append(self.units[c])
1619 # integer data still make floating point statistics:
1620 if isinstance(self.data[c][0], (float, np.floating)):
1621 f = self.formats[c]
1622 i0 = f.find('.')
1623 if i0 > 0:
1624 p = int(f[i0+1:-1])
1625 if p <= 0:
1626 f = '%.1f'
1627 ds.formats.append(f)
1628 else:
1629 ds.formats.append('%.1f')
1630 # remove nans:
1631 data = np.asarray(self.data[c], float)
1632 data = data[np.isfinite(data)]
1633 # compute statistics:
1634 ds.data.append([])
1635 ds.append_data(np.mean(data), dc)
1636 ds.append_data(np.std(data), dc)
1637 ds.append_data(np.min(data), dc)
1638 q1, m, q3 = np.percentile(data, [25., 50., 75.])
1639 ds.append_data(q1, dc)
1640 ds.append_data(m, dc)
1641 ds.append_data(q3, dc)
1642 ds.append_data(np.max(data), dc)
1643 ds.append_data(len(data), dc)
1644 dc += 1
1645 ds.nsecs = self.nsecs
1646 ds.shape = (ds.rows(), ds.columns())
1647 return ds
1649 def key_value(self, row, col, missing=default_missing_str):
1650 """A data element returned as a key-value pair.
1652 Parameters
1653 ----------
1654 row: int
1655 Specifies the row from which the data element should be retrieved.
1656 col: None, int, or str
1657 A specification of a column.
1658 See self.index() for more information on how to specify a column.
1659 missing: str
1660 String indicating non-existing data elements.
1662 Returns
1663 -------
1664 key: str
1665 Header label of the column
1666 value: str
1667 A textual representation of the data element according to the format
1668 of the column, followed by the unit of the column.
1669 """
1670 col = self.index(col)
1671 if col is None:
1672 return ''
1673 if isinstance(self.data[col][row], (float, np.floating)) and m.isnan(self.data[col][row]):
1674 v = missing
1675 else:
1676 u = ''
1677 if not self.units[col] in '1-' and self.units[col] != 'a.u.':
1678 u = self.units[col]
1679 v = (self.formats[col] % self.data[col][row]) + u
1680 return self.header[col][0], v
1682 def hide(self, column):
1683 """Hide a column or a range of columns.
1685 Hidden columns will not be printed out by the write() function.
1687 Parameters
1688 ----------
1689 column: int or str
1690 The column to be hidden.
1691 See self.index() for more information on how to specify a column.
1692 """
1693 c0, c1 = self.find_col(column)
1694 if c0 is not None:
1695 for c in range(c0, c1):
1696 self.hidden[c] = True
1698 def hide_all(self):
1699 """Hide all columns.
1701 Hidden columns will not be printed out by the write() function.
1702 """
1703 for c in range(len(self.hidden)):
1704 self.hidden[c] = True
1706 def hide_empty_columns(self, missing=default_missing_inputs):
1707 """Hide all columns that do not contain data.
1709 Hidden columns will not be printed out by the write() function.
1711 Parameters
1712 ----------
1713 missing: list of str
1714 Strings indicating missing data.
1715 """
1716 for c in range(len(self.data)):
1717 # check for empty column:
1718 isempty = True
1719 for v in self.data[c]:
1720 if isinstance(v, (float, np.floating)):
1721 if not m.isnan(v):
1722 isempty = False
1723 break
1724 else:
1725 if not v in missing:
1726 isempty = False
1727 break
1728 if isempty:
1729 self.hidden[c] = True
1731 def show(self, column):
1732 """Show a column or a range of columns.
1734 Undoes hiding of a column.
1736 Parameters
1737 ----------
1738 column: int or str
1739 The column to be shown.
1740 See self.index() for more information on how to specify a column.
1741 """
1742 c0, c1 = self.find_col(column)
1743 if c0 is not None:
1744 for c in range(c0, c1):
1745 self.hidden[c] = False
1747 def write(self, fh=sys.stdout, table_format=None, delimiter=None,
1748 unit_style=None, column_numbers=None, sections=None,
1749 align_columns=None, shrink_width=True,
1750 missing=default_missing_str, center_columns=False,
1751 latex_label_command='', latex_merge_std=False):
1752 """Write the table to a file or stream.
1754 Parameters
1755 ----------
1756 fh: filename or stream
1757 If not a stream, the file with name `fh` is opened.
1758 If `fh` does not have an extension,
1759 the `table_format` is appended as an extension.
1760 Otherwise `fh` is used as a stream for writing.
1761 table_format: None or str
1762 The format to be used for output.
1763 One of 'out', 'dat', 'ascii', 'csv', 'rtai', 'md', 'tex', 'html'.
1764 If None or 'auto' then the format is set to the extension of the filename given by `fh`.
1765 If `fh` is a stream the format is set to 'dat'.
1766 delimiter: str
1767 String or character separating columns, if supported by the `table_format`.
1768 If None or 'auto' use the default for the specified `table_format`.
1769 unit_style: None or str
1770 - None or 'auto': use default of the specified `table_format`.
1771 - 'row': write an extra row to the table header specifying the units of the columns.
1772 - 'header': add the units to the column headers.
1773 - 'none': do not specify the units.
1774 column_numbers: str or None
1775 Add a row specifying the column index:
1776 - 'index': indices are integers, first column is 0.
1777 - 'num': indices are integers, first column is 1.
1778 - 'aa': use 'a', 'b', 'c', ..., 'z', 'aa', 'ab', ... for indexing
1779 - 'aa': use 'A', 'B', 'C', ..., 'Z', 'AA', 'AB', ... for indexing
1780 - None or 'none': do not add a row with column indices
1781 TableData.column_numbering is a list with the supported styles.
1782 sections: None or int
1783 Number of section levels to be printed.
1784 If `None` or 'auto' use default of selected `table_format`.
1785 align_columns: boolean
1786 - `True`: set width of column formats to make them align.
1787 - `False`: set width of column formats to 0 - no unnecessary spaces.
1788 - None or 'auto': Use default of the selected `table_format`.
1789 shrink_width: boolean
1790 If `True` disregard width specified by the format strings,
1791 such that columns can become narrower.
1792 missing: str
1793 Indicate missing data by this string.
1794 center_columns: boolean
1795 If True center all columns (markdown, html, and latex).
1796 latex_label_command: str
1797 LaTeX command for formatting header labels.
1798 E.g. 'textbf' for making the header labels bold.
1799 latex_merge_std: str
1800 Merge header of columns with standard deviations with previous column
1801 (LaTeX tables only).
1803 Returns
1804 -------
1805 file_name: str or None
1806 The full name of the file into which the data were written.
1808 Supported file formats
1809 ----------------------
1811 ## `dat`: data text file
1812 ``` plain
1813 # info reaction
1814 # size weight delay jitter
1815 # m kg ms mm
1816 2.34 123 98.7 23
1817 56.70 3457 54.3 45
1818 8.90 43 67.9 345
1819 ```
1821 ## `ascii`: ascii-art table
1822 ``` plain
1823 |---------------------------------|
1824 | info | reaction |
1825 | size | weight | delay | jitter |
1826 | m | kg | ms | mm |
1827 |-------|--------|-------|--------|
1828 | 2.34 | 123 | 98.7 | 23 |
1829 | 56.70 | 3457 | 54.3 | 45 |
1830 | 8.90 | 43 | 67.9 | 345 |
1831 |---------------------------------|
1832 ```
1834 ## `csv`: comma separated values
1835 ``` plain
1836 size/m,weight/kg,delay/ms,jitter/mm
1837 2.34,123,98.7,23
1838 56.70,3457,54.3,45
1839 8.90,43,67.9,345
1840 ```
1842 ## `rtai`: rtai-style table
1843 ``` plain
1844 RTH| info | reaction
1845 RTH| size | weight| delay| jitter
1846 RTH| m | kg | ms | mm
1847 RTD| 2.34| 123| 98.7| 23
1848 RTD| 56.70| 3457| 54.3| 45
1849 RTD| 8.90| 43| 67.9| 345
1850 ```
1852 ## `md`: markdown
1853 ``` plain
1854 | size/m | weight/kg | delay/ms | jitter/mm |
1855 |------:|-------:|------:|-------:|
1856 | 2.34 | 123 | 98.7 | 23 |
1857 | 56.70 | 3457 | 54.3 | 45 |
1858 | 8.90 | 43 | 67.9 | 345 |
1859 ```
1861 ## `tex`: latex tabular
1862 ``` tex
1863 \\begin{tabular}{rrrr}
1864 \\hline
1865 \\multicolumn{2}{l}{info} & \\multicolumn{2}{l}{reaction} \\
1866 \\multicolumn{1}{l}{size} & \\multicolumn{1}{l}{weight} & \\multicolumn{1}{l}{delay} & \\multicolumn{1}{l}{jitter} \\
1867 \\multicolumn{1}{l}{m} & \\multicolumn{1}{l}{kg} & \\multicolumn{1}{l}{ms} & \\multicolumn{1}{l}{mm} \\
1868 \\hline
1869 2.34 & 123 & 98.7 & 23 \\
1870 56.70 & 3457 & 54.3 & 45 \\
1871 8.90 & 43 & 67.9 & 345 \\
1872 \\hline
1873 \\end{tabular}
1874 ```
1876 ## `html`: html
1877 ``` html
1878 <table>
1879 <thead>
1880 <tr class="header">
1881 <th align="left" colspan="2">info</th>
1882 <th align="left" colspan="2">reaction</th>
1883 </tr>
1884 <tr class="header">
1885 <th align="left">size</th>
1886 <th align="left">weight</th>
1887 <th align="left">delay</th>
1888 <th align="left">jitter</th>
1889 </tr>
1890 <tr class="header">
1891 <th align="left">m</th>
1892 <th align="left">kg</th>
1893 <th align="left">ms</th>
1894 <th align="left">mm</th>
1895 </tr>
1896 </thead>
1897 <tbody>
1898 <tr class"odd">
1899 <td align="right">2.34</td>
1900 <td align="right">123</td>
1901 <td align="right">98.7</td>
1902 <td align="right">23</td>
1903 </tr>
1904 <tr class"even">
1905 <td align="right">56.70</td>
1906 <td align="right">3457</td>
1907 <td align="right">54.3</td>
1908 <td align="right">45</td>
1909 </tr>
1910 <tr class"odd">
1911 <td align="right">8.90</td>
1912 <td align="right">43</td>
1913 <td align="right">67.9</td>
1914 <td align="right">345</td>
1915 </tr>
1916 </tbody>
1917 </table>
1918 ```
1919 """
1920 # fix parameter:
1921 if table_format == 'auto':
1922 table_format = None
1923 if delimiter == 'auto':
1924 delimiter = None
1925 if unit_style == 'auto':
1926 unit_style = None
1927 if column_numbers == 'none':
1928 column_numbers = None
1929 if sections == 'auto':
1930 sections = None
1931 if align_columns == 'auto':
1932 align_columns = None
1933 # open file:
1934 own_file = False
1935 file_name = None
1936 if not hasattr(fh, 'write'):
1937 _, ext = os.path.splitext(fh)
1938 if table_format is None:
1939 if len(ext) > 1 and ext[1:] in self.ext_formats:
1940 table_format = self.ext_formats[ext[1:]]
1941 elif not ext or not ext[1:].lower() in self.ext_formats:
1942 fh += '.' + self.extensions[table_format]
1943 file_name = fh
1944 fh = open(fh, 'w')
1945 own_file = True
1946 if table_format is None:
1947 table_format = 'dat'
1948 # set style:
1949 if table_format[0] == 'd':
1950 align_columns = True
1951 begin_str = ''
1952 end_str = ''
1953 header_start = '# '
1954 header_sep = ' '
1955 header_close = ''
1956 header_end = '\n'
1957 data_start = ' '
1958 data_sep = ' '
1959 data_close = ''
1960 data_end = '\n'
1961 top_line = False
1962 header_line = False
1963 bottom_line = False
1964 if delimiter is not None:
1965 header_sep = delimiter
1966 data_sep = delimiter
1967 if sections is None:
1968 sections = 1000
1969 elif table_format[0] == 'a':
1970 align_columns = True
1971 begin_str = ''
1972 end_str = ''
1973 header_start = '| '
1974 header_sep = ' | '
1975 header_close = ''
1976 header_end = ' |\n'
1977 data_start = '| '
1978 data_sep = ' | '
1979 data_close = ''
1980 data_end = ' |\n'
1981 top_line = True
1982 header_line = True
1983 bottom_line = True
1984 if delimiter is not None:
1985 header_sep = delimiter
1986 data_sep = delimiter
1987 if sections is None:
1988 sections = 1000
1989 elif table_format[0] == 'c':
1990 # csv according to http://www.ietf.org/rfc/rfc4180.txt :
1991 column_numbers=None
1992 if unit_style is None:
1993 unit_style = 'header'
1994 if align_columns is None:
1995 align_columns = False
1996 begin_str = ''
1997 end_str = ''
1998 header_start=''
1999 header_sep = ','
2000 header_close = ''
2001 header_end='\n'
2002 data_start=''
2003 data_sep = ','
2004 data_close = ''
2005 data_end='\n'
2006 top_line = False
2007 header_line = False
2008 bottom_line = False
2009 if delimiter is not None:
2010 header_sep = delimiter
2011 data_sep = delimiter
2012 if sections is None:
2013 sections = 0
2014 elif table_format[0] == 'r':
2015 align_columns = True
2016 begin_str = ''
2017 end_str = ''
2018 header_start = 'RTH| '
2019 header_sep = '| '
2020 header_close = ''
2021 header_end = '\n'
2022 data_start = 'RTD| '
2023 data_sep = '| '
2024 data_close = ''
2025 data_end = '\n'
2026 top_line = False
2027 header_line = False
2028 bottom_line = False
2029 if sections is None:
2030 sections = 1000
2031 elif table_format[0] == 'm':
2032 if unit_style is None or unit_style == 'row':
2033 unit_style = 'header'
2034 align_columns = True
2035 begin_str = ''
2036 end_str = ''
2037 header_start='| '
2038 header_sep = ' | '
2039 header_close = ''
2040 header_end=' |\n'
2041 data_start='| '
2042 data_sep = ' | '
2043 data_close = ''
2044 data_end=' |\n'
2045 top_line = False
2046 header_line = True
2047 bottom_line = False
2048 if sections is None:
2049 sections = 0
2050 elif table_format[0] == 'h':
2051 align_columns = False
2052 begin_str = '<table>\n<thead>\n'
2053 end_str = '</tbody>\n</table>\n'
2054 if center_columns:
2055 header_start=' <tr>\n <th align="center"'
2056 header_sep = '</th>\n <th align="center"'
2057 else:
2058 header_start=' <tr>\n <th align="left"'
2059 header_sep = '</th>\n <th align="left"'
2060 header_close = '>'
2061 header_end='</th>\n </tr>\n'
2062 data_start=' <tr>\n <td'
2063 data_sep = '</td>\n <td'
2064 data_close = '>'
2065 data_end='</td>\n </tr>\n'
2066 top_line = False
2067 header_line = False
2068 bottom_line = False
2069 if sections is None:
2070 sections = 1000
2071 elif table_format[0] == 't':
2072 if align_columns is None:
2073 align_columns = False
2074 begin_str = '\\begin{tabular}'
2075 end_str = '\\end{tabular}\n'
2076 header_start=' '
2077 header_sep = ' & '
2078 header_close = ''
2079 header_end=' \\\\\n'
2080 data_start=' '
2081 data_sep = ' & '
2082 data_close = ''
2083 data_end=' \\\\\n'
2084 top_line = True
2085 header_line = True
2086 bottom_line = True
2087 if sections is None:
2088 sections = 1000
2089 else:
2090 if align_columns is None:
2091 align_columns = True
2092 begin_str = ''
2093 end_str = ''
2094 header_start = ''
2095 header_sep = ' '
2096 header_close = ''
2097 header_end = '\n'
2098 data_start = ''
2099 data_sep = ' '
2100 data_close = ''
2101 data_end = '\n'
2102 top_line = False
2103 header_line = False
2104 bottom_line = False
2105 if sections is None:
2106 sections = 1000
2107 # check units:
2108 if unit_style is None:
2109 unit_style = 'row'
2110 have_units = False
2111 for u in self.units:
2112 if u and u != '1' and u != '-':
2113 have_units = True
2114 break
2115 if not have_units:
2116 unit_style = 'none'
2117 # find std columns:
2118 stdev_col = np.zeros(len(self.header), dtype=bool)
2119 for c in range(len(self.header)-1):
2120 if self.header[c+1][0].lower() in ['sd', 'std', 's.d.', 'stdev'] and \
2121 not self.hidden[c+1]:
2122 stdev_col[c] = True
2123 # begin table:
2124 fh.write(begin_str)
2125 if table_format[0] == 't':
2126 fh.write('{')
2127 merged = False
2128 for h, f, s in zip(self.hidden, self.formats, stdev_col):
2129 if merged:
2130 fh.write('l')
2131 merged = False
2132 continue
2133 if h:
2134 continue
2135 if latex_merge_std and s:
2136 fh.write('r@{$\\,\\pm\\,$}')
2137 merged = True
2138 elif center_columns:
2139 fh.write('c')
2140 elif f[1] == '-':
2141 fh.write('l')
2142 else:
2143 fh.write('r')
2144 fh.write('}\n')
2145 # retrieve column formats and widths:
2146 widths = []
2147 widths_pos = []
2148 for c, f in enumerate(self.formats):
2149 w = 0
2150 # position of width specification:
2151 i0 = 1
2152 if len(f) > 1 and f[1] == '-' :
2153 i0 = 2
2154 i1 = f.find('.')
2155 if not shrink_width:
2156 if f[i0:i1]:
2157 w = int(f[i0:i1])
2158 widths_pos.append((i0, i1))
2159 # adapt width to header label:
2160 hw = len(self.header[c][0])
2161 if unit_style == 'header' and self.units[c] and\
2162 self.units[c] != '1' and self.units[c] != '-':
2163 hw += 1 + len(self.units[c])
2164 if w < hw:
2165 w = hw
2166 # adapt width to data:
2167 if f[-1] == 's':
2168 for v in self.data[c]:
2169 if not isinstance(v, (float, np.floating)) and w < len(v):
2170 w = len(v)
2171 else:
2172 fs = f[:i0] + str(0) + f[i1:]
2173 for v in self.data[c]:
2174 if isinstance(v, (float, np.floating)) and m.isnan(v):
2175 s = missing
2176 else:
2177 try:
2178 s = fs % v
2179 except ValueError:
2180 s = missing
2181 except TypeError:
2182 s = str(v)
2183 if w < len(s):
2184 w = len(s)
2185 widths.append(w)
2186 # adapt width to sections:
2187 sec_indices = [0] * self.nsecs
2188 sec_widths = [0] * self.nsecs
2189 sec_columns = [0] * self.nsecs
2190 for c in range(len(self.header)):
2191 w = widths[c]
2192 for l in range(min(self.nsecs, sections)):
2193 if 1+l < len(self.header[c]):
2194 if c > 0 and sec_columns[l] > 0 and \
2195 1+l < len(self.header[sec_indices[l]]) and \
2196 len(self.header[sec_indices[l]][1+l]) > sec_widths[l]:
2197 dw = len(self.header[sec_indices[l]][1+l]) - sec_widths[l]
2198 nc = sec_columns[l]
2199 ddw = np.zeros(nc, dtype=int) + dw // nc
2200 ddw[:dw % nc] += 1
2201 wk = 0
2202 for ck in range(sec_indices[l], c):
2203 if not self.hidden[ck]:
2204 widths[ck] += ddw[wk]
2205 wk += 1
2206 sec_widths[l] = 0
2207 sec_indices[l] = c
2208 if not self.hidden[c]:
2209 if sec_widths[l] > 0:
2210 sec_widths[l] += len(header_sep)
2211 sec_widths[l] += w
2212 sec_columns[l] += 1
2213 # set width of format string:
2214 formats = []
2215 for c, (f, w) in enumerate(zip(self.formats, widths)):
2216 formats.append(f[:widths_pos[c][0]] + str(w) + f[widths_pos[c][1]:])
2217 # top line:
2218 if top_line:
2219 if table_format[0] == 't':
2220 fh.write(' \\hline \\\\[-2ex]\n')
2221 else:
2222 first = True
2223 fh.write(header_start.replace(' ', '-'))
2224 for c in range(len(self.header)):
2225 if self.hidden[c]:
2226 continue
2227 if not first:
2228 fh.write('-'*len(header_sep))
2229 first = False
2230 fh.write(header_close)
2231 w = widths[c]
2232 fh.write(w*'-')
2233 fh.write(header_end.replace(' ', '-'))
2234 # section and column headers:
2235 nsec0 = self.nsecs-sections
2236 if nsec0 < 0:
2237 nsec0 = 0
2238 for ns in range(nsec0, self.nsecs+1):
2239 nsec = self.nsecs-ns
2240 first = True
2241 last = False
2242 merged = False
2243 fh.write(header_start)
2244 for c in range(len(self.header)):
2245 if nsec < len(self.header[c]):
2246 # section width and column count:
2247 sw = -len(header_sep)
2248 columns = 0
2249 if not self.hidden[c]:
2250 sw = widths[c]
2251 columns = 1
2252 for k in range(c+1, len(self.header)):
2253 if nsec < len(self.header[k]):
2254 break
2255 if self.hidden[k]:
2256 continue
2257 sw += len(header_sep) + widths[k]
2258 columns += 1
2259 else:
2260 last = True
2261 if len(header_end.strip()) == 0:
2262 sw = 0 # last entry needs no width
2263 if columns == 0:
2264 continue
2265 if not first and not merged:
2266 fh.write(header_sep)
2267 first = False
2268 if table_format[0] == 'c':
2269 sw -= len(header_sep)*(columns-1)
2270 elif table_format[0] == 'h':
2271 if columns>1:
2272 fh.write(' colspan="%d"' % columns)
2273 elif table_format[0] == 't':
2274 if merged:
2275 merged = False
2276 continue
2277 if latex_merge_std and nsec == 0 and stdev_col[c]:
2278 merged = True
2279 fh.write('\\multicolumn{%d}{c}{' % (columns+1))
2280 elif center_columns:
2281 fh.write('\\multicolumn{%d}{c}{' % columns)
2282 else:
2283 fh.write('\\multicolumn{%d}{l}{' % columns)
2284 if latex_label_command:
2285 fh.write('\\%s{' % latex_label_command)
2286 fh.write(header_close)
2287 hs = self.header[c][nsec]
2288 if nsec == 0 and unit_style == 'header':
2289 if self.units[c] and self.units[c] != '1' and self.units[c] != '-':
2290 hs += '/' + self.units[c]
2291 if align_columns and not table_format[0] in 'th':
2292 f = '%%-%ds' % sw
2293 fh.write(f % hs)
2294 else:
2295 fh.write(hs)
2296 if table_format[0] == 'c':
2297 if not last:
2298 fh.write(header_sep*(columns-1))
2299 elif table_format[0] == 't':
2300 if latex_label_command:
2301 fh.write('}')
2302 fh.write('}')
2303 fh.write(header_end)
2304 # units:
2305 if unit_style == 'row':
2306 first = True
2307 merged = False
2308 fh.write(header_start)
2309 for c in range(len(self.header)):
2310 if self.hidden[c] or merged:
2311 merged = False
2312 continue
2313 if not first:
2314 fh.write(header_sep)
2315 first = False
2316 fh.write(header_close)
2317 unit = self.units[c]
2318 if not unit:
2319 unit = '-'
2320 if table_format[0] == 't':
2321 if latex_merge_std and stdev_col[c]:
2322 merged = True
2323 fh.write('\\multicolumn{2}{c}{%s}' % latex_unit(unit))
2324 elif center_columns:
2325 fh.write('\\multicolumn{1}{c}{%s}' % latex_unit(unit))
2326 else:
2327 fh.write('\\multicolumn{1}{l}{%s}' % latex_unit(unit))
2328 else:
2329 if align_columns and not table_format[0] in 'h':
2330 f = '%%-%ds' % widths[c]
2331 fh.write(f % unit)
2332 else:
2333 fh.write(unit)
2334 fh.write(header_end)
2335 # column numbers:
2336 if column_numbers is not None:
2337 first = True
2338 fh.write(header_start)
2339 for c in range(len(self.header)):
2340 if self.hidden[c]:
2341 continue
2342 if not first:
2343 fh.write(header_sep)
2344 first = False
2345 fh.write(header_close)
2346 i = c
2347 if column_numbers == 'num':
2348 i = c+1
2349 aa = index2aa(c, 'a')
2350 if column_numbers == 'AA':
2351 aa = index2aa(c, 'A')
2352 if table_format[0] == 't':
2353 if column_numbers == 'num' or column_numbers == 'index':
2354 fh.write('\\multicolumn{1}{l}{%d}' % i)
2355 else:
2356 fh.write('\\multicolumn{1}{l}{%s}' % aa)
2357 else:
2358 if column_numbers == 'num' or column_numbers == 'index':
2359 if align_columns:
2360 f = '%%%dd' % widths[c]
2361 fh.write(f % i)
2362 else:
2363 fh.write('%d' % i)
2364 else:
2365 if align_columns:
2366 f = '%%-%ds' % widths[c]
2367 fh.write(f % aa)
2368 else:
2369 fh.write(aa)
2370 fh.write(header_end)
2371 # header line:
2372 if header_line:
2373 if table_format[0] == 'm':
2374 fh.write('|')
2375 for c in range(len(self.header)):
2376 if self.hidden[c]:
2377 continue
2378 w = widths[c]+2
2379 if center_columns:
2380 fh.write(':' + (w-2)*'-' + ':|')
2381 elif formats[c][1] == '-':
2382 fh.write(w*'-' + '|')
2383 else:
2384 fh.write((w-1)*'-' + ':|')
2385 fh.write('\n')
2386 elif table_format[0] == 't':
2387 fh.write(' \\hline \\\\[-2ex]\n')
2388 else:
2389 first = True
2390 fh.write(header_start.replace(' ', '-'))
2391 for c in range(len(self.header)):
2392 if self.hidden[c]:
2393 continue
2394 if not first:
2395 fh.write(header_sep.replace(' ', '-'))
2396 first = False
2397 fh.write(header_close)
2398 w = widths[c]
2399 fh.write(w*'-')
2400 fh.write(header_end.replace(' ', '-'))
2401 # start table data:
2402 if table_format[0] == 'h':
2403 fh.write('</thead>\n<tbody>\n')
2404 # data:
2405 for k in range(self.rows()):
2406 first = True
2407 merged = False
2408 fh.write(data_start)
2409 for c, f in enumerate(formats):
2410 if self.hidden[c] or merged:
2411 merged = False
2412 continue
2413 if not first:
2414 fh.write(data_sep)
2415 first = False
2416 if table_format[0] == 'h':
2417 if center_columns:
2418 fh.write(' align="center"')
2419 elif f[1] == '-':
2420 fh.write(' align="left"')
2421 else:
2422 fh.write(' align="right"')
2423 fh.write(data_close)
2424 if k >= len(self.data[c]) or \
2425 (isinstance(self.data[c][k], (float, np.floating)) and m.isnan(self.data[c][k])):
2426 # missing data:
2427 if table_format[0] == 't' and latex_merge_std and stdev_col[c]:
2428 merged = True
2429 fh.write('\\multicolumn{2}{c}{%s}' % missing)
2430 elif align_columns:
2431 if f[1] == '-':
2432 fn = '%%-%ds' % widths[c]
2433 else:
2434 fn = '%%%ds' % widths[c]
2435 fh.write(fn % missing)
2436 else:
2437 fh.write(missing)
2438 else:
2439 # data value:
2440 try:
2441 ds = f % self.data[c][k]
2442 except ValueError:
2443 ds = missing
2444 except TypeError:
2445 ds = str(self.data[c][k])
2446 if not align_columns:
2447 ds = ds.strip()
2448 fh.write(ds)
2449 fh.write(data_end)
2450 # bottom line:
2451 if bottom_line:
2452 if table_format[0] == 't':
2453 fh.write(' \\hline\n')
2454 else:
2455 first = True
2456 fh.write(header_start.replace(' ', '-'))
2457 for c in range(len(self.header)):
2458 if self.hidden[c]:
2459 continue
2460 if not first:
2461 fh.write('-'*len(header_sep))
2462 first = False
2463 fh.write(header_close)
2464 w = widths[c]
2465 fh.write(w*'-')
2466 fh.write(header_end.replace(' ', '-'))
2467 # end table:
2468 fh.write(end_str)
2469 # close file:
2470 if own_file:
2471 fh.close()
2472 # return file name:
2473 return file_name
2476 def write_file_stream(self, basename, file_name, **kwargs):
2477 """Write table to file or stream and return appropriate file name.
2479 Parameters
2480 ----------
2481 basename: str or stream
2482 If str, path and basename of file.
2483 `file_name` and an extension are appended.
2484 If stream, write table data into this stream.
2485 file_name: str
2486 Name of file that is appended to a base path or `basename`.
2487 kwargs:
2488 Arguments passed on to `TableData.write()`.
2489 In particular, 'table_format' is used to the set the file extension
2490 that is appended to the returned `file_name`.
2492 Returns
2493 -------
2494 file_name: str
2495 Path and full name of the written file in case of `basename`
2496 being a string. Otherwise, the file name and extension that
2497 should be appended to a base path.
2498 """
2499 if hasattr(basename, 'write'):
2500 table_format = kwargs.get('table_format', None)
2501 if table_format is None or table_format == 'auto':
2502 table_format = 'csv'
2503 file_name += '.' + TableData.extensions[table_format]
2504 self.write(basename, **kwargs)
2505 return file_name
2506 else:
2507 file_name = self.write(basename + file_name, **kwargs)
2508 return file_name
2511 def __str__(self):
2512 """Write table to a string.
2513 """
2514 stream = StringIO()
2515 self.write(stream, table_format='out')
2516 return stream.getvalue()
2519 def load(self, fh, missing=default_missing_inputs, stop=None):
2520 """Load table from file or stream.
2522 File type and properties are automatically inferred.
2524 Parameters
2525 ----------
2526 fh: str or stream
2527 If not a stream, the file with name `fh` is opened for reading.
2528 missing: str or list of str
2529 Missing data are indicated by this string and
2530 are translated to np.nan.
2531 stop: str or None
2532 If the beginning of a line matches `stop`, then stop reading the file.
2534 Raises
2535 ------
2536 FileNotFoundError:
2537 If `fh` is a path that does not exist.
2538 """
2540 def read_key_line(line, sep, table_format):
2541 if sep is None:
2542 cols, indices = zip(*[(m.group(0), m.start()) for m in re.finditer(r'( ?[\S]+)+(?=[ ][ ]+|\Z)', line.strip())])
2543 elif table_format == 'csv':
2544 cols, indices = zip(*[(c.strip(), i) for i, c in enumerate(line.strip().split(sep)) if c.strip()])
2545 return cols, indices
2546 else:
2547 seps = r'[^'+re.escape(sep)+']+'
2548 cols, indices = zip(*[(m.group(0), m.start()) for m in re.finditer(seps, line.strip())])
2549 colss = []
2550 indicess = []
2551 if table_format == 'tex':
2552 i = 0
2553 for c in cols:
2554 if 'multicolumn' in c:
2555 fields = c.split('{')
2556 n = int(fields[1].strip().rstrip('}').rstrip())
2557 colss.append(fields[3].strip().rstrip('}').rstrip())
2558 indicess.append(i)
2559 i += n
2560 else:
2561 colss.append(c.strip())
2562 indicess.append(i)
2563 i += 1
2564 else:
2565 for k, (c, i) in enumerate(zip(cols, indices)):
2566 if k == 0:
2567 c = c.lstrip('|')
2568 if k == len(cols)-1:
2569 c = c.rstrip('|')
2570 cs = c.strip()
2571 colss.append(cs)
2572 indicess.append(i)
2573 return colss, indicess
2575 def read_data_line(line, sep, post, precd, alld, numc, exped,
2576 fixed, strf, missing, nans):
2577 # read line:
2578 cols = []
2579 if sep is None:
2580 cols = [m.group(0) for m in re.finditer(r'\S+', line.strip())]
2581 else:
2582 if sep.isspace():
2583 seps = r'[^'+re.escape(sep)+']+'
2584 cols = [m.group(0) for m in re.finditer(seps, line.strip())]
2585 else:
2586 cols = line.split(sep)
2587 if len(cols) > 0 and len(cols[0]) == 0:
2588 cols = cols[1:]
2589 if len(cols) > 0 and len(cols[-1]) == 0:
2590 cols = cols[:-1]
2591 if len(cols) > 0:
2592 cols[0] = cols[0].lstrip('|').lstrip()
2593 cols[-1] = cols[-1].rstrip('|').rstrip()
2594 cols = [c.strip() for c in cols if c != '|']
2595 # read columns:
2596 for k, c in enumerate(cols):
2597 try:
2598 v = float(c)
2599 ad = 0
2600 ve = c.split('e')
2601 if len(ve) <= 1:
2602 exped[k] = False
2603 else:
2604 ad = len(ve[1])+1
2605 vc = ve[0].split('.')
2606 ad += len(vc[0])
2607 prec = len(vc[0].lstrip('-').lstrip('+').lstrip('0'))
2608 if len(vc) == 2:
2609 if numc[k] and post[k] != len(vc[1]):
2610 fixed[k] = False
2611 if post[k] < len(vc[1]):
2612 post[k] = len(vc[1])
2613 ad += len(vc[1])+1
2614 prec += len(vc[1].rstrip('0'))
2615 if precd[k] < prec:
2616 precd[k] = prec
2617 if alld[k] < ad:
2618 alld[k] = ad
2619 numc[k] = True
2620 except ValueError:
2621 if c in missing:
2622 v = np.nan
2623 nans[k] = c
2624 else:
2625 strf[k] = True
2626 if alld[k] < len(c):
2627 alld[k] = len(c)
2628 v = c
2629 self.append_data(v, k)
2631 # initialize:
2632 if isinstance(missing, str):
2633 missing = [missing]
2634 self.data = []
2635 self.shape = (0, 0)
2636 self.header = []
2637 self.nsecs = 0
2638 self.units = []
2639 self.formats = []
2640 self.hidden = []
2641 self.setcol = 0
2642 self.addcol = 0
2643 # open file:
2644 own_file = False
2645 if not hasattr(fh, 'readline'):
2646 fh = open(fh, 'r')
2647 own_file = True
2648 # read inital lines of file:
2649 key = []
2650 data = []
2651 target = data
2652 comment = False
2653 table_format='dat'
2654 for line in fh:
2655 line = line.rstrip()
2656 if line == stop:
2657 break;
2658 if line:
2659 if r'\begin{tabular' in line:
2660 table_format='tex'
2661 target = key
2662 continue
2663 if table_format == 'tex':
2664 if r'\end{tabular' in line:
2665 break
2666 if r'\hline' in line:
2667 if key:
2668 target = data
2669 continue
2670 line = line.rstrip(r'\\')
2671 if line[0] == '#':
2672 comment = True
2673 table_format='dat'
2674 target = key
2675 line = line.lstrip('#')
2676 elif comment:
2677 target = data
2678 if line[0:3] == 'RTH':
2679 target = key
2680 line = line[3:]
2681 table_format='rtai'
2682 elif line[0:3] == 'RTD':
2683 target = data
2684 line = line[3:]
2685 table_format='rtai'
2686 if (line[0:3] == '|--' or line[0:3] == '|:-') and \
2687 (line[-3:] == '--|' or line[-3:] == '-:|'):
2688 if not data and not key:
2689 table_format='ascii'
2690 target = key
2691 continue
2692 elif not key:
2693 table_format='md'
2694 key = data
2695 data = []
2696 target = data
2697 continue
2698 elif not data:
2699 target = data
2700 continue
2701 else:
2702 break
2703 target.append(line)
2704 else:
2705 break
2706 if len(data) > 5:
2707 break
2708 # find column separator of data and number of columns:
2709 col_seps = ['|', ',', ';', ':', '\t', '&', None]
2710 colstd = np.zeros(len(col_seps))
2711 colnum = np.zeros(len(col_seps), dtype=int)
2712 for k, sep in enumerate(col_seps):
2713 cols = []
2714 s = 5 if len(data) >= 8 else len(data) - 3
2715 if s < 0 or key:
2716 s = 0
2717 for line in data[s:]:
2718 cs = line.strip().split(sep)
2719 if not cs[0]:
2720 cs = cs[1:]
2721 if cs and not cs[-1]:
2722 cs = cs[:-1]
2723 cols.append(len(cs))
2724 colstd[k] = np.std(cols)
2725 colnum[k] = np.median(cols)
2726 if np.max(colnum) < 2:
2727 sep = None
2728 colnum = 1
2729 else:
2730 ci = np.where(np.array(colnum)>1.5)[0]
2731 ci = ci[np.argmin(colstd[ci])]
2732 sep = col_seps[ci]
2733 colnum = int(colnum[ci])
2734 # fix key:
2735 if not key and sep is not None and sep in ',;:\t|':
2736 table_format = 'csv'
2737 # read key:
2738 key_cols = []
2739 key_indices = []
2740 for line in key:
2741 cols, indices = read_key_line(line, sep, table_format)
2742 key_cols.append(cols)
2743 key_indices.append(indices)
2744 if not key_cols:
2745 # no obviously marked table key:
2746 key_num = 0
2747 for line in data:
2748 cols, indices = read_key_line(line, sep, table_format)
2749 numbers = 0
2750 for c in cols:
2751 try:
2752 v = float(c)
2753 numbers += 1
2754 except ValueError:
2755 pass
2756 if numbers == 0:
2757 key_cols.append(cols)
2758 key_indices.append(indices)
2759 key_num += 1
2760 else:
2761 break
2762 data = data[key_num:]
2763 kr = len(key_cols)-1
2764 # check for key with column indices:
2765 if kr >= 0:
2766 cols = key_cols[kr]
2767 numrow = True
2768 try:
2769 pv = int(cols[0])
2770 for c in cols[1:]:
2771 v = int(c)
2772 if v != pv+1:
2773 numrow = False
2774 break
2775 pv = v
2776 except ValueError:
2777 try:
2778 pv = aa2index(cols[0])
2779 for c in cols[1:]:
2780 v = aa2index(c)
2781 if v != pv+1:
2782 numrow = False
2783 break
2784 pv = v
2785 except ValueError:
2786 numrow = False
2787 if numrow:
2788 kr -= 1
2789 # check for unit line:
2790 units = None
2791 if kr > 0 and len(key_cols[kr]) == len(key_cols[kr-1]):
2792 units = key_cols[kr]
2793 kr -= 1
2794 # column labels:
2795 if kr >= 0:
2796 if units is None:
2797 # units may be part of the label:
2798 labels = []
2799 units = []
2800 for c in key_cols[kr]:
2801 if c[-1] == ')':
2802 lu = c[:-1].split('(')
2803 if len(lu) >= 2:
2804 labels.append(lu[0].strip())
2805 units.append('('.join(lu[1:]).strip())
2806 continue
2807 lu = c.split('/')
2808 if len(lu) >= 2:
2809 labels.append(lu[0].strip())
2810 units.append('/'.join(lu[1:]).strip())
2811 else:
2812 labels.append(c)
2813 units.append('')
2814 else:
2815 labels = key_cols[kr]
2816 indices = key_indices[kr]
2817 # init table columns:
2818 for k in range(colnum):
2819 self.append(labels[k], units[k], '%g')
2820 # read in sections:
2821 while kr > 0:
2822 kr -= 1
2823 for sec_label, sec_inx in zip(key_cols[kr], key_indices[kr]):
2824 col_inx = indices.index(sec_inx)
2825 self.header[col_inx].append(sec_label)
2826 if self.nsecs < len(self.header[col_inx])-1:
2827 self.nsecs = len(self.header[col_inx])-1
2828 # read data:
2829 post = np.zeros(colnum)
2830 precd = np.zeros(colnum)
2831 alld = np.zeros(colnum)
2832 numc = [False] * colnum
2833 exped = [True] * colnum
2834 fixed = [True] * colnum
2835 strf = [False] * colnum
2836 nans = [None] * colnum
2837 for line in data:
2838 read_data_line(line, sep, post, precd, alld, numc, exped, fixed,
2839 strf, missing, nans)
2840 # read remaining data:
2841 for line in fh:
2842 line = line.rstrip()
2843 if line == stop:
2844 break;
2845 if table_format == 'tex':
2846 if r'\end{tabular' in line or r'\hline' in line:
2847 break
2848 line = line.rstrip(r'\\')
2849 if (line[0:3] == '|--' or line[0:3] == '|:-') and \
2850 (line[-3:] == '--|' or line[-3:] == '-:|'):
2851 break
2852 if line[0:3] == 'RTD':
2853 line = line[3:]
2854 read_data_line(line, sep, post, precd, alld, numc, exped, fixed,
2855 strf, missing, nans)
2856 # set formats:
2857 for k in range(len(alld)):
2858 if strf[k]:
2859 self.set_format('%%-%ds' % alld[k], k)
2860 # make sure all elements are strings:
2861 for i in range(len(self.data[k])):
2862 if self.data[k][i] is np.nan:
2863 self.data[k][i] = nans[k]
2864 else:
2865 self.data[k][i] = str(self.data[k][i])
2866 elif exped[k]:
2867 self.set_format('%%%d.%de' % (alld[k], post[k]), k)
2868 elif fixed[k]:
2869 self.set_format('%%%d.%df' % (alld[k], post[k]), k)
2870 else:
2871 self.set_format('%%%d.%dg' % (alld[k], precd[k]), k)
2872 # close file:
2873 if own_file:
2874 fh.close()
2877def write(fh, data, header, units=None, formats=None,
2878 table_format=None, delimiter=None, unit_style=None,
2879 column_numbers=None, sections=None, align_columns=None,
2880 shrink_width=True, missing=default_missing_str,
2881 center_columns=False, latex_label_command='',
2882 latex_merge_std=False):
2883 """Construct table and write to file.
2885 Parameters
2886 ----------
2887 fh: filename or stream
2888 If not a stream, the file with name `fh` is opened.
2889 If `fh` does not have an extension,
2890 the `table_format` is appended as an extension.
2891 Otherwise `fh` is used as a stream for writing.
2892 data: 1-D or 2-D ndarray of data
2893 The data of the table.
2894 header: list of str
2895 Header labels for each column.
2896 units: list of str, optional
2897 Unit strings for each column.
2898 formats: str or list of str, optional
2899 Format strings for each column. If only a single format string is
2900 given, then all columns are initialized with this format string.
2902 See `TableData.write()` for a description of all other parameters.
2904 Example
2905 -------
2906 ```
2907 write(sys.stdout, np.random.randn(4,3), ['aaa', 'bbb', 'ccc'], units=['m', 's', 'g'], formats='%.2f')
2908 ```
2909 """
2910 td = TableData(data, header, units, formats)
2911 td.write(fh, table_format=table_format, unit_style=unit_style,
2912 column_numbers=column_numbers, missing=missing,
2913 shrink_width=shrink_width, delimiter=delimiter,
2914 align_columns=align_columns, sections=sections,
2915 latex_label_command=latex_label_command,
2916 latex_merge_std=latex_merge_std)
2919def add_write_table_config(cfg, table_format=None, delimiter=None,
2920 unit_style=None, column_numbers=None,
2921 sections=None, align_columns=None,
2922 shrink_width=True, missing='-',
2923 center_columns=False,
2924 latex_label_command='',
2925 latex_merge_std=False):
2926 """Add parameter specifying how to write a table to a file as a new
2927section to a configuration.
2929 Parameters
2930 ----------
2931 cfg: ConfigFile
2932 The configuration.
2933 """
2935 cfg.add_section('File format for storing analysis results:')
2936 cfg.add('fileFormat', table_format or 'auto', '', 'Default file format used to store analysis results.\nOne of %s.' % ', '.join(TableData.formats))
2937 cfg.add('fileDelimiter', delimiter or 'auto', '', 'String used to separate columns or "auto".')
2938 cfg.add('fileUnitStyle', unit_style or 'auto', '', 'Add units as extra row ("row"), add units to header label separated by "/" ("header"), do not print out units ("none"), or "auto".')
2939 cfg.add('fileColumnNumbers', column_numbers or 'none', '', 'Add line with column indices ("index", "num", "aa", "AA", or "none")')
2940 cfg.add('fileSections', sections or 'auto', '', 'Maximum number of section levels or "auto"')
2941 cfg.add('fileAlignColumns', align_columns or 'auto', '', 'If True, write all data of a column using the same width, if False write the data without any white space, or "auto".')
2942 cfg.add('fileShrinkColumnWidth', shrink_width, '', 'Allow to make columns narrower than specified by the corresponding format strings.')
2943 cfg.add('fileMissing', missing, '', 'String used to indicate missing data values.')
2944 cfg.add('fileCenterColumns', center_columns, '', 'Center content of all columns instead of left align columns of strings and right align numbers (markdown, html, and latex).')
2945 cfg.add('fileLaTeXLabelCommand', latex_label_command, '', 'LaTeX command name for formatting column labels of the table header.')
2946 cfg.add('fileLaTeXMergeStd', latex_merge_std, '', 'Merge header of columns with standard deviations with previous column (LaTeX tables only).')
2949def write_table_args(cfg):
2950 """Translates a configuration to the respective parameter names for
2951writing a table to a file.
2953 The return value can then be passed as key-word arguments to TableData.write().
2955 Parameters
2956 ----------
2957 cfg: ConfigFile
2958 The configuration.
2960 Returns
2961 -------
2962 a: dict
2963 Dictionary with names of arguments of the `TableData.write` function
2964 and their values as supplied by `cfg`.
2965 """
2966 d = cfg.map({'table_format': 'fileFormat',
2967 'delimiter': 'fileDelimiter',
2968 'unit_style': 'fileUnitStyle',
2969 'column_numbers': 'fileColumnNumbers',
2970 'sections': 'fileSections',
2971 'align_columns': 'fileAlignColumns',
2972 'shrink_width': 'fileShrinkColumnWidth',
2973 'missing': 'fileMissing',
2974 'center_columns': 'fileCenterColumns',
2975 'latex_label_command': 'fileLaTeXLabelCommand',
2976 'latex_merge_std': 'fileLaTeXMergeStd'})
2977 if 'sections' in d:
2978 if d['sections'] != 'auto':
2979 d['sections'] = int(d['sections'])
2980 return d
2983def latex_unit(unit):
2984 """Translate unit string into SIunit LaTeX code.
2986 Parameters
2987 ----------
2988 unit: str
2989 String enoting a unit.
2991 Returns
2992 -------
2993 unit: str
2994 Unit string as valid LaTeX code.
2995 """
2996 si_prefixes = {'y': '\\yocto',
2997 'z': '\\zepto',
2998 'a': '\\atto',
2999 'f': '\\femto',
3000 'p': '\\pico',
3001 'n': '\\nano',
3002 'u': '\\micro',
3003 'm': '\\milli',
3004 'c': '\\centi',
3005 'd': '\\deci',
3006 'h': '\\hecto',
3007 'k': '\\kilo',
3008 'M': '\\mega',
3009 'G': '\\giga',
3010 'T': '\\tera',
3011 'P': '\\peta',
3012 'E': '\\exa',
3013 'Z': '\\zetta',
3014 'Y': '\\yotta' }
3015 si_units = {'m': '\\metre',
3016 'g': '\\gram',
3017 's': '\\second',
3018 'A': '\\ampere',
3019 'K': '\\kelvin',
3020 'mol': '\\mole',
3021 'cd': '\\candela',
3022 'Hz': '\\hertz',
3023 'N': '\\newton',
3024 'Pa': '\\pascal',
3025 'J': '\\joule',
3026 'W': '\\watt',
3027 'C': '\\coulomb',
3028 'V': '\\volt',
3029 'F': '\\farad',
3030 'O': '\\ohm',
3031 'S': '\\siemens',
3032 'Wb': '\\weber',
3033 'T': '\\tesla',
3034 'H': '\\henry',
3035 'C': '\\celsius',
3036 'lm': '\\lumen',
3037 'lx': '\\lux',
3038 'Bq': '\\becquerel',
3039 'Gv': '\\gray',
3040 'Sv': '\\sievert'}
3041 other_units = {"'": '\\arcminute',
3042 "''": '\\arcsecond',
3043 'a': '\\are',
3044 'd': '\\dday',
3045 'eV': '\\electronvolt',
3046 'ha': '\\hectare',
3047 'h': '\\hour',
3048 'L': '\\liter',
3049 'l': '\\litre',
3050 'min': '\\minute',
3051 'Np': '\\neper',
3052 'rad': '\\rad',
3053 't': '\\ton',
3054 '%': '\\%'}
3055 unit_powers = {'^2': '\\squared',
3056 '^3': '\\cubed',
3057 '/': '\\per',
3058 '^-1': '\\power{}{-1}',
3059 '^-2': '\\rpsquared',
3060 '^-3': '\\rpcubed'}
3061 if '\\' in unit: # this string is already translated!
3062 return unit
3063 units = ''
3064 j = len(unit)
3065 while j >= 0:
3066 for k in range(-3, 0):
3067 if j+k < 0:
3068 continue
3069 uss = unit[j+k:j]
3070 if uss in unit_powers:
3071 units = unit_powers[uss] + units
3072 break
3073 elif uss in other_units:
3074 units = other_units[uss] + units
3075 break
3076 elif uss in si_units:
3077 units = si_units[uss] + units
3078 j = j+k
3079 k = 0
3080 if j-1 >= 0:
3081 uss = unit[j-1:j]
3082 if uss in si_prefixes:
3083 units = si_prefixes[uss] + units
3084 k = -1
3085 break
3086 else:
3087 k = -1
3088 units = unit[j+k:j] + units
3089 j = j + k
3090 return units
3093def index2aa(n, a='a'):
3094 """Convert an integer into an alphabetical representation.
3096 The integer number is converted into 'a', 'b', 'c', ..., 'z',
3097 'aa', 'ab', 'ac', ..., 'az', 'ba', 'bb', ...
3099 Inspired by https://stackoverflow.com/a/37604105
3101 Parameters
3102 ----------
3103 n: int
3104 An integer to be converted into alphabetical representation.
3105 a: str ('a' or 'A')
3106 Use upper or lower case characters.
3108 Returns
3109 -------
3110 ns: str
3111 Alphabetical represtnation of an integer.
3112 """
3113 d, m = divmod(n, 26)
3114 bm = chr(ord(a)+m)
3115 return index2aa(d-1, a) + bm if d else bm
3118def aa2index(s):
3119 """Convert an alphabetical representation to an index.
3121 The alphabetical representation 'a', 'b', 'c', ..., 'z',
3122 'aa', 'ab', 'ac', ..., 'az', 'ba', 'bb', ...
3123 is converted to an index starting with 0.
3125 Parameters
3126 ----------
3127 s: str
3128 Alphabetical representation of an index.
3130 Returns
3131 -------
3132 index: int
3133 The corresponding index.
3135 Raises
3136 ------
3137 ValueError:
3138 Invalid character in input string.
3139 """
3140 index = 0
3141 maxc = ord('z') - ord('a') + 1
3142 for c in s.lower():
3143 index *= maxc
3144 if ord(c) < ord('a') or ord(c) > ord('z'):
3145 raise ValueError('invalid character "%s" in string.' % c)
3146 index += ord(c) - ord('a') + 1
3147 return index-1
3150class IndentStream(object):
3151 """Filter an output stream and start each newline with a number of
3152 spaces.
3153 """
3154 def __init__(self, stream, indent=4):
3155 self.stream = stream
3156 self.indent = indent
3157 self.pending = True
3159 def __getattr__(self, attr_name):
3160 return getattr(self.stream, attr_name)
3162 def write(self, data):
3163 if not data:
3164 return
3165 if self.pending:
3166 self.stream.write(' '*self.indent)
3167 self.pending = False
3168 substr = data.rstrip('\n')
3169 rn = len(data) - len(substr)
3170 if len(substr) > 0:
3171 self.stream.write(substr.replace('\n', '\n'+' '*self.indent))
3172 if rn > 0:
3173 self.stream.write('\n'*rn)
3174 self.pending = True
3176 def flush(self):
3177 self.stream.flush()
3180def main():
3181 # setup a table:
3182 df = TableData()
3183 df.append(["data", "partial information", "ID"], "", "%-s", list('ABCDEFGH'))
3184 df.append("size", "m", "%6.2f", [2.34, 56.7, 8.9])
3185 df.append("full weight", "kg", "%.0f", 122.8)
3186 df.append_section("complete reaction")
3187 df.append("speed", "m/s", "%.3g", 98.7)
3188 df.append("median jitter", "mm", "%.1f", 23)
3189 df.append("size", "g", "%.2e", 1.234)
3190 df.append_data(np.nan, 2) # single value
3191 df.append_data((0.543, 45, 1.235e2)) # remaining row
3192 df.append_data((43.21, 6789.1, 3405, 1.235e-4), 2) # next row
3193 a = 0.5*np.arange(1, 6)*np.random.randn(5, 5) + 10.0 + np.arange(5)
3194 df.append_data(a.T, 1) # rest of table
3195 df[3:6,'weight'] = [11.0]*3
3197 # write out in all formats:
3198 for tf in TableData.formats:
3199 print(' - `%s`: %s' % (tf, TableData.descriptions[tf]))
3200 print(' ```')
3201 iout = IndentStream(sys.stdout, 4+2)
3202 df.write(iout, table_format=tf)
3203 print(' ```')
3204 print('')
3207if __name__ == "__main__":
3208 main()