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[, col_prefix])

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, index_name])

construct object that can be used for statistical tests

to_csv([with_title, with_legend])

return table formatted as comma separated values

to_dataframe(**kwargs)

deprecated, use to_pandas()

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_list([columns])

Returns raw data as a list

to_markdown([space, justify])

returns markdown formatted table

to_pandas([categories])

returns pandas DataFrame instance

to_plotly([width, font_size, layout])

returns a Plotly Table

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(**kwargs)

deprecated, use to_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, col_prefix='right_', **kwargs)#

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

Parameters:
other

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

col_prefix

ensure <other> columns are unique by prepending col_prefix

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, col_prefix='right_', **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.

col_prefix

ensure <other> columns are unique by prepending col_prefix

joined(other, columns_self=None, columns_other=None, inner_join=True, col_prefix='right_', **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, index_name=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(**kwargs)#

deprecated, use to_pandas()

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

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_list(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.

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_pandas(categories=None)#

returns pandas DataFrame instance

Parameters:
categories

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

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

returns a Plotly Table

to_rich_dict()#
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(**kwargs)#

deprecated, use to_list

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.