Table#

class Table(header: list[str] | None = None, data: list[list[Any]] | None = None, index_name: str | None = None, title: str = '', legend: str = '', digits: int = 4, space: int = 4, max_width: int = 10000000000000000159028911097599180468360808563945281389781327557747838772170381060813469985856815104, column_templates: dict[str, str] | None = None, format_name: str = 'simple', missing_data: str = '', **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_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_name, borders, sep, ...])	Return the table as a formatted string.
`to_tsv`([with_title, with_legend])	return table formatted as tab separated values
`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_name, ...])	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: str, format_template: Callable[[Any], str]) → None#

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) → None#: 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: int | None = None, tail: int | None = None, random: int = 0, show_shape: bool = True) → None#

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: Iterable[str] | str | None = None, reverse: Iterable[str] | str | None = None, **kwargs: Any)#

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) → None#: 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: bool = False, with_legend: bool = False) → str#

return table formatted as comma separated values

Parameters:

with_titlebool: include the table title
with_legendbool: include table legend

to_dict(flatten=False)#

returns data as a dict

Parameters:

flattenbool: returns a 1D dictionary

to_html(column_alignment: dict[str, str] | None = None) → str#

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.

Notes

Placed within c3table div element, embeds CSS style.

to_json()#

to_latex(concat_title_legend: bool = True, justify: str | None = None, label: str | None = None, position: str | None = None) → str#

Returns the text a LaTeX table.

Parameters:

concat_title_legendbool: the table caption is formed by concatenating the table title and legend
justify: latex character for column justification (e.g. ‘c’), 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: str | list[str] | None = None) → list#

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: int = 1, justify: str | None = None) → str#

returns markdown formatted table

Parameters:

space: number of spaces surrounding the cell contents, must be >= 1
justify
characters indicating alignment of columns, c, r or l for
center, right or left respectively.

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: bool = False) → str#

returns rst formatted table

Parameters:

csv_tablebool: use csv-directive, grid table otherwise

to_string(format_name: str | None = None, borders: bool = True, sep: str | None = None, center: bool = False, concat_title_legend: bool = True, **kwargs) → str#

Return the table as a formatted string.

Parameters:

format_name: 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: bool = False, with_legend: bool = False) → str#

return table formatted as tab separated values

Parameters:

with_title: include the table title
with_legend: include table legend

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: str, callback: Callable[[ndarray], Iterable] | str, columns: str | tuple[str, ...] | None = None, dtype: dtype | None = None, **kwargs) → Self#

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 table to filename in the specified format.

Parameters:

mode: file opening mode
format_name: 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.