Table

class Table(header=None, data=None, index_name=None, title='', legend='', digits=4, space=4, max_width=1e+100, column_templates=None, format='simple', missing_data='', **kwargs)

Tabular data. iter operates over rows. Columns are available as an attribute.

Attributes
array
format

the str display format

header
index_name

column name whose values can be used to index table rows

legend
shape
space
title

Methods

appended(new_column, *tables, **kwargs)

Concatenates an arbitrary number of tables together

count(callback[, columns])

Returns number of rows for which the provided callback function returns True when passed row data from columns.

count_unique([columns])

count occurrences of unique combinations of columns

cross_join(other, **kwargs)

cross join, or full outer join, of self with other

distinct_values(columns)

returns the set of distinct values for the named column(s)

filtered(callback[, columns])

Returns a table with rows satisfying the provided callback function.

filtered_by_column(callback, **kwargs)

Returns a table with columns identified by callback

format_column(column_head, format_template)

Provide a formatting template for a named column.

get_columns(columns[, with_index])

select columns from self with index_name unless excluded

get_row_indices(callback, columns[, negate])

returns boolean array of callback values given columns

head([nrows])

displays top nrows

inner_join(other[, columns_self, …])

inner join of self with other

joined(other[, columns_self, columns_other, …])

returns a new table containing the join of this table and other.

normalized([by_row, denominator_func])

returns a table with elements expressed as a fraction according to the results from func

set_repr_policy([head, tail, random, show_shape])

specify policy for repr(self)

sorted([columns, reverse])

Returns a new table sorted according to columns order.

sum_columns([columns, strict])

return sum of indicated columns

sum_rows([indices, strict])

return sum of indicated rows

summed([indices, col_sum, strict])

returns the sum of numerical values for column(s)/row(s)

tail([nrows])

displays bottom nrows

to_categorical([columns])

construct object that can be used for statistical tests

to_csv([with_title, with_legend])

return table formatted as comma separated values

to_dataframe([categories])

returns pandas DataFrame instance

to_dict([flatten])

returns data as a dict

to_html([column_alignment])

construct html table

to_latex([concat_title_legend, justify, …])

Returns the text a LaTeX table.

to_markdown([space, justify])

returns markdown formatted table

to_plotly([width, font_size, layout])

returns a Plotly Table

to_rich_html([row_cell_func, …])

returns just the table as html.

to_rst([csv_table])

returns rst formatted table

to_string([format, borders, sep, center, …])

Return the table as a formatted string.

to_tsv([with_title, with_legend])

return table formatted as tab separated values

tolist([columns])

Returns raw data as a list

transposed(new_column_name[, select_as_header])

returns the transposed table.

with_new_column(new_column, callback[, …])

Returns new table with an additional column, computed using callback.

with_new_header(old, new, **kwargs)

returns a new Table with old header labels replaced by new

write(filename[, mode, writer, format, sep, …])

Write table to filename in the specified format.

to_json

to_rich_dict

appended(new_column, *tables, **kwargs)

Concatenates an arbitrary number of tables together

Parameters
new_column

provide a heading for the new column, each tables title will be placed in it. If value is false, the result is no additional column.

tables

series of Table instances

Notes

All tables must have the same columns. If a column dtype differs between tables, dtype for that column in result is determined by numpy.

property array
count(callback, columns=None, **kwargs)

Returns number of rows for which the provided callback function returns True when passed row data from columns. Row data is a 1D list if more than one column, raw row[col] value otherwise.

Parameters
columns

the columns whose values determine whether a row is to be included.

callback

Can be a function, which takes the sub by columns and returns True/False, or a string representing valid python code to be evaluated.

count_unique(columns=None)

count occurrences of unique combinations of columns

Parameters
columns

name of one or more columns. If None, all columns are used

Returns
CategoryCounter instance
cross_join(other, **kwargs)

cross join, or full outer join, of self with other

Notes

The column headers of the output are made unique by prepending other column headers with _, e.g. ‘Name’ becomes _Name’.

distinct_values(columns)

returns the set of distinct values for the named column(s)

filtered(callback, columns=None, **kwargs)

Returns a table with rows satisfying the provided callback function.

Parameters
columns

the columns whose values determine whether a row is to be included.

callback

Can be a function, which takes rows and returns True/False, or a string representing valid python code to be evaluated.

Notes

Row data provided to callback is a 1D list if more than one column, single value (row[col]) otherwise.

filtered_by_column(callback, **kwargs)

Returns a table with columns identified by callback

Parameters
callback

A function which takes the columns delimited by columns and returns True/False, or a string representing valid python code to be evaluated.

property format

the str display format

format_column(column_head, format_template)

Provide a formatting template for a named column.

Parameters
column_head

the column label.

format_template

string formatting template or a function that will handle the formatting.

get_columns(columns, with_index=True)

select columns from self with index_name unless excluded

Parameters
columnsstring or sequence of strings

names of columns

with_indexbool

If index_name is set, includes with columns.

Returns
Table
get_row_indices(callback, columns, negate=False)

returns boolean array of callback values given columns

head(nrows=5)

displays top nrows

property header
property index_name

column name whose values can be used to index table rows

inner_join(other, columns_self=None, columns_other=None, use_index=True, **kwargs)

inner join of self with other

Parameters
other

A table object which will be joined with this table. other must have a title.

columns_self, columns_other

indices of key columns that will be compared in the join operation. Can be either column index, or a string matching the column header. The order matters, and the dimensions of columns_self and columns_other have to match. A row will be included in the output iff self[row, columns_self]==other[row, columns_other] for all i

use_index

if no columns specified and both self and other have a nominated index_name, this will be used.

Notes

The column headers of the output are made unique by prepending other column headers with _, e.g. ‘Name’ becomes _Name’.

joined(other, columns_self=None, columns_other=None, inner_join=True, **kwargs)

returns a new table containing the join of this table and other. See docstring for inner_join, or cross_join

property legend
normalized(by_row=True, denominator_func=None, **kwargs)

returns a table with elements expressed as a fraction according to the results from func

Parameters
by_row

normalisation done by row

denominator_func

a callback function that takes an array and returns a value to be used as the denominator. Default is sum.

set_repr_policy(head=None, tail=None, random=0, show_shape=True)

specify policy for repr(self)

Parameters
headint

number of top rows to included in represented display

tailint

number of bottom rows to included in represented display

randomint

number of rows to sample randomly (supercedes head/tail)

show_shapebool

boolean to determine if table shape info is displayed

property shape
sorted(columns=None, reverse=None, **kwargs)

Returns a new table sorted according to columns order.

Parameters
columns

column headings, their order determines the sort order.

reverse

column headings, these columns will be reverse sorted.

Notes

Either can be provided as just a single string, or a series of strings. If only reverse is provided, that order is used.

property space
sum_columns(columns=None, strict=True)

return sum of indicated columns

Parameters
columns

column name(s) or indices

strict

if False, ignores cells with non column/row.

sum_rows(indices=None, strict=True)

return sum of indicated rows

Parameters
indices

row indices

strict

if False, ignores cells with non numeric values.

summed(indices=None, col_sum=True, strict=True)

returns the sum of numerical values for column(s)/row(s)

Parameters
indices

column name(s) or indices or row indices

col_sum

sums values in the indicated column, the default. If False, returns the row sum.

strict

if False, ignores cells with non column/row.

tail(nrows=5)

displays bottom nrows

property title
to_categorical(columns=None)

construct object that can be used for statistical tests

Parameters
columns

columns to include. These correspond to contingency column labels. The row labels come from values under the index_name column. Defaults to all columns.

Returns
CategoryCounts, an object for performing statistical tests on
contingency tables.

Notes

Only applies to cases where an index_name is defined. The selected columns must be int types and represent the counts of corresponding categories.

to_csv(with_title=False, with_legend=False)

return table formatted as comma separated values

Parameters
with_titlebool

include the table title

with_legendbool

include table legend

Returns
str
to_dataframe(categories=None)

returns pandas DataFrame instance

Parameters
categories

converts these columns to category dtype in the data frame. Note, categories are not ordered.

to_dict(flatten=False)

returns data as a dict

Parameters
flattenbool

returns a 1D dictionary

to_html(column_alignment=None)

construct html table

Parameters
column_alignmentdict

{col_name: alignment character, …} where alignment character can be one of ‘l’, ‘c’, ‘r’. Defaults to ‘r’ for numeric columns, ‘l’ for text columns.

Returns
string

Notes

Placed within c3table div element, embeds CSS style.

to_json()
to_latex(concat_title_legend=True, justify=None, label=None, position=None)

Returns the text a LaTeX table.

Parameters
concat_title_legendbool

the table caption is formed by concatenating the table title and legend

rows

table data in row orientation

header

table header

justify

column justification, default is right aligned.

label

for cross referencing

position

table page position, default is here, top separate page

Notes

The caption*{} command is provided with the caption package. See https://ctan.org/pkg/caption for more details.

to_markdown(space=1, justify=None)

returns markdown formatted table

Parameters
space

number of spaces surrounding the cell contents, must be >= 1

justify

characters indicating alignment of columns

Returns
str
to_plotly(width=500, font_size=12, layout=None, **kwargs)

returns a Plotly Table

to_rich_dict()
to_rich_html(row_cell_func=None, header_cell_func=None, element_formatters=None, merge_identical=False, compact=False)

returns just the table as html.

Parameters
row_cell_func

callback function that formats the row values. Must take the row value and coordinates (row index, column index).

header_cell_func

callback function that formats the column headings must take the header label value and coordinate

element_formatters

a dictionary of specific callback funcs for formatting individual html table elements. e.g. {‘table’: lambda x: ‘<table border=”1” class=”docutils”>’}

merge_identical

cells within a row are merged to one span.

to_rst(csv_table=False)

returns rst formatted table

Parameters
csv_tablebool

use csv-directive, grid table otherwise

Returns
str
to_string(format='', borders=True, sep=None, center=False, concat_title_legend=True, **kwargs)

Return the table as a formatted string.

Parameters
format

possible formats are ‘rest’/’rst’, ‘markdown’/’md’, ‘latex’, ‘html’, ‘phylip’, ‘bedgraph’, ‘csv’, ‘tsv’, or ‘simple’ (default).

sep

A string separator for delineating columns, e.g. ‘,’ or ‘ ‘. Overrides format.

centerbool

content is centered in the column, default is right justified

concat_title_legendbool

Concat the title and legend.

Notes

If format is bedgraph, assumes that column headers are chrom, start, end, value. In that order!

to_tsv(with_title=False, with_legend=False)

return table formatted as tab separated values

Parameters
with_titlebool

include the table title

with_legendbool

include table legend

Returns
str
tolist(columns=None)

Returns raw data as a list

Parameters
columns

if None, all data are returned

Notes

If one column, a 1D list is returned.

transposed(new_column_name, select_as_header=None, **kwargs)

returns the transposed table.

Parameters
new_column_name

the existing header will become a column with this name

select_as_header

current column name containing data to be used as the header. Defaults to the first column.

with_new_column(new_column, callback, columns=None, dtype=None, **kwargs)

Returns new table with an additional column, computed using callback.

Parameters
new_column

new column heading

columns

the columns whose values determine whether a row is to be included.

callback

Can be a function, which takes the subtable by columns and returns True/False, or a string representing valid python code to be evaluated.

dtype

numpy type of result

with_new_header(old, new, **kwargs)

returns a new Table with old header labels replaced by new

Parameters
old

the old column header(s). Can be a string or series of them.

new

the new column header(s). Can be a string or series of them.

write(filename, mode=None, writer=None, format=None, sep=None, compress=None, **kwargs)

Write table to filename in the specified format.

Parameters
mode

file opening mode

format

Valid formats are those of the to_string method plus pickle. Will try and guess from filename if not specified.

writer

a function for formatting the data for output.

sep

a character delimiter for fields.

compress

if True, gzips the file and appends .gz to the filename (if not already added).

Notes

If a format is not specified, it attempts to use a filename suffix. Unformatted numerical values are written to file in order to preserve numerical accuracy.