core.table.Table

core.table.Table(
    header=None,
    data=None,
    index_name=None,
    title='',
    legend='',
    digits=4,
    space=4,
    max_width=int(1e+100),
    column_templates=None,
    format_name='simple',
    missing_data='',
    **kwargs,
)

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

Attributes

Name	Description
format	the str display format
index_name	column name whose values can be used to index table rows

Methods

Name	Description
appended	Concatenates an arbitrary number of tables together
count	Returns number of rows for which the provided callback
count_unique	count occurrences of unique combinations of columns
cross_join	cross join, or full outer join, of self with other
distinct_values	returns the set of distinct values for the named column(s)
filtered	Returns a table with rows satisfying the provided callback function.
filtered_by_column	Returns a table with columns identified by callback
format_column	Provide a formatting template for a named column.
get_columns	select columns from self with index_name unless excluded
get_row_indices	returns boolean array of callback values given columns
group_by	Group table rows by one or more columns.
head	displays top nrows
inner_join	inner join of self with other
joined	returns a new table containing the join of this table and
normalized	returns a table with elements expressed as a fraction according
set_repr_policy	specify policy for repr(self)
sorted	Returns a new table sorted according to columns order.
sum_columns	return sum of indicated columns
sum_rows	return sum of indicated rows
summed	returns the sum of numerical values for column(s)/row(s)
tail	displays bottom nrows
to_categorical	construct object that can be used for statistical tests
to_csv	return table formatted as comma separated values
to_html	construct html table
to_latex	Returns the text a LaTeX table.
to_list	Returns raw data as a list
to_markdown	returns markdown formatted table
to_pandas	returns pandas DataFrame instance
to_plotly	returns a Plotly Table
to_rst	returns rst formatted table
to_string	Return the table as a formatted string.
to_tsv	return table formatted as tab separated values
transposed	returns the transposed table.
with_new_column	Returns new table with an additional column, computed using callback.
with_new_header	returns a new Table with old header labels replaced by new
write	Write table to filename in the specified format.

appended

core.table.Table.appended(new_column, *tables, **kwargs)

Concatenates an arbitrary number of tables together

Parameters

Name	Type	Description	Default
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.	required
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.

count

core.table.Table.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

Name	Type	Description	Default
columns		the columns whose values determine whether a row is to be included.	`None`
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.	required

count_unique

core.table.Table.count_unique(columns=None)

count occurrences of unique combinations of columns

Parameters

Name	Type	Description	Default
columns		name of one or more columns. If None, all columns are used	`None`

Returns

Name	Type	Description
	CategoryCounter instance

cross_join

core.table.Table.cross_join(other, col_prefix='right_', **kwargs)

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

Parameters

Name	Type	Description	Default
other		A table object which will be joined with this table. other must have a title.	required
col_prefix		ensure columns are unique by prepending col_prefix	`'right_'`

distinct_values

core.table.Table.distinct_values(columns)

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

filtered

core.table.Table.filtered(callback, columns=None, **kwargs)

Returns a table with rows satisfying the provided callback function.

Parameters

Name	Type	Description	Default
columns		the columns whose values determine whether a row is to be included.	`None`
callback		Can be a function, which takes rows and returns True/False, or a string representing valid python code to be evaluated.	required

Notes

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

filtered_by_column

core.table.Table.filtered_by_column(callback, **kwargs)

Returns a table with columns identified by callback

Parameters

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

format_column

core.table.Table.format_column(column_head, format_template)

Provide a formatting template for a named column.

Parameters

Name	Type	Description	Default
column_head	str	the column label.	required
format_template	Callable[[typing.Any], str]	string formatting template or a function that will handle the formatting.	required

get_columns

core.table.Table.get_columns(columns, with_index=True)

select columns from self with index_name unless excluded

Parameters

Name	Type	Description	Default
columns	string or sequence of strings	names of columns	required
with_index	bool	If index_name is set, includes with columns.	`True`

Returns

Name	Type	Description
	Table

get_row_indices

core.table.Table.get_row_indices(callback, columns, negate=False)

returns boolean array of callback values given columns

group_by

core.table.Table.group_by(columns)

Group table rows by one or more columns.

Parameters

Name	Type	Description	Default
columns	str \| list[str]	column name or list of column names to group by	required

Returns

Name	Type	Description
	GroupBy instance supporting aggregation via `.agg()`,
	`.count()`, `.sum()`, etc.

head

core.table.Table.head(nrows=5)

displays top nrows

inner_join

core.table.Table.inner_join(
    other,
    columns_self=None,
    columns_other=None,
    use_index=True,
    col_prefix='right_',
    **kwargs,
)

inner join of self with other

Parameters

Name	Description	Default
other	A table object which will be joined with this table. other must have a title.	required
columns_self	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	`None`
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	`None`
use_index	if no columns specified and both self and other have a nominated index_name, this will be used.	`True`
col_prefix	ensure columns are unique by prepending col_prefix	`'right_'`

joined

core.table.Table.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

normalized

core.table.Table.normalized(by_row=True, denominator_func=None, **kwargs)

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

Parameters

Name	Type	Description	Default
by_row		normalisation done by row	`True`
denominator_func		a callback function that takes an array and returns a value to be used as the denominator. Default is sum.	`None`

set_repr_policy

core.table.Table.set_repr_policy(
    head=None,
    tail=None,
    random=0,
    show_shape=True,
)

specify policy for repr(self)

Parameters

Name	Type	Description	Default
head	int	number of top rows to included in represented display	`None`
tail	int	number of bottom rows to included in represented display	`None`
random	int	number of rows to sample randomly (supercedes head/tail)	`0`
show_shape	bool	boolean to determine if table shape info is displayed	`True`

sorted

core.table.Table.sorted(columns=None, reverse=None, **kwargs)

Returns a new table sorted according to columns order.

Parameters

Name	Type	Description	Default
columns	Iterable[str] \| str \| None	column headings, their order determines the sort order.	`None`
reverse	Iterable[str] \| str \| None	column headings, these columns will be reverse sorted.	`None`

Notes

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

sum_columns

core.table.Table.sum_columns(columns=None, strict=True)

return sum of indicated columns

Parameters

Name	Type	Description	Default
columns		column name(s) or indices	`None`
strict		if False, ignores cells with non column/row.	`True`

sum_rows

core.table.Table.sum_rows(indices=None, strict=True)

return sum of indicated rows

Parameters

Name	Type	Description	Default
indices		row indices	`None`
strict		if False, ignores cells with non numeric values.	`True`

summed

core.table.Table.summed(indices=None, col_sum=True, strict=True)

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

Parameters

Name	Description	Default
indices	column name(s) or indices or row indices	`None`
col_sum	sums values in the indicated column, the default. If False, returns the row sum.	`True`
strict	if False, ignores cells with non column/row.	`True`

tail

core.table.Table.tail(nrows=5)

displays bottom nrows

to_categorical

core.table.Table.to_categorical(columns=None, index_name=None)

construct object that can be used for statistical tests

Parameters

Name	Type	Description	Default
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.	`None`

Returns

Name	Type	Description
	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

core.table.Table.to_csv(with_title=False, with_legend=False)

return table formatted as comma separated values

Parameters

Name	Type	Description	Default
with_title	bool	include the table title	`False`
with_legend	bool	include table legend	`False`

to_html

core.table.Table.to_html(column_alignment=None)

construct html table

Parameters

Name	Type	Description	Default
column_alignment	dict	{col_name: alignment character, …} where alignment character can be one of ‘l’, ‘c’, ‘r’. Defaults to ‘r’ for numeric columns, ‘l’ for text columns.	`None`

Notes

Placed within c3table div element, embeds CSS style.

to_latex

core.table.Table.to_latex(
    concat_title_legend=True,
    justify=None,
    label=None,
    position=None,
    with_title=True,
    with_legend=True,
)

Returns the text a LaTeX table.

Parameters

Name	Type	Description	Default
concat_title_legend	bool	the table caption is formed by concatenating the table title and legend	`True`
justify	str \| None	latex character for column justification (e.g. ‘c’), default is right aligned.	`None`
label	str \| None	for cross referencing	`None`
position	str \| None	table page position, default is here, top separate page	`None`
with_title	bool	include the table title	`True`
with_legend	bool	include the table legend	`True`

Notes

The

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

to_list

core.table.Table.to_list(columns=None)

Returns raw data as a list

Parameters

Name	Type	Description	Default
columns	str \| list[str] \| None	if None, all data are returned	`None`

Notes

If one column, a 1D list is returned.

to_markdown

core.table.Table.to_markdown(space=1, justify=None)

returns markdown formatted table

Parameters

Name	Type	Description	Default
space	int	number of spaces surrounding the cell contents, must be >= 1	`1`
justify	str \| None		`None`
characters			required
center			required
right			required

Returns

Name	Type	Description
	str

to_pandas

core.table.Table.to_pandas(categories=None)

returns pandas DataFrame instance

Parameters

Name	Type	Description	Default
categories		converts these columns to category dtype in the data frame. Note, categories are not ordered.	`None`

to_plotly

core.table.Table.to_plotly(width=500, font_size=12, layout=None, **kwargs)

returns a Plotly Table

to_rst

core.table.Table.to_rst(csv_table=False, with_title=True, with_legend=True)

returns rst formatted table

Parameters

Name	Type	Description	Default
csv_table	bool	use csv-directive, grid table otherwise	`False`
with_title	bool	include the table title	`True`
with_legend	bool	include the table legend	`True`

to_string

core.table.Table.to_string(
    format_name=None,
    borders=True,
    sep=None,
    center=False,
    concat_title_legend=True,
    with_title=None,
    with_legend=None,
    **kwargs,
)

Return the table as a formatted string.

Parameters

Name	Type	Description	Default
format_name	str \| None	possible formats are ‘rest’/‘rst’, ‘markdown’/‘md’, ‘latex’, ‘html’, ‘phylip’, ‘bedgraph’, ‘csv’, ‘tsv’, or ‘simple’ (default).	`None`
sep	str \| None	A string separator for delineating columns, e.g. ‘,’ or ’ ’. Overrides format.	`None`
center	bool	content is centered in the column, default is right justified	`False`
concat_title_legend	bool	Concat the title and legend.	`True`
with_title	bool \| None	include the table title. If None, uses each format’s default (shown for simple, rst and latex, omitted for csv and tsv). Ignored by formats without a title.	`None`
with_legend	bool \| None	include the table legend. If None, uses each format’s default (shown for simple, rst and latex, omitted for csv and tsv). Ignored by formats without a legend.	`None`

Notes

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

to_tsv

core.table.Table.to_tsv(with_title=False, with_legend=False)

return table formatted as tab separated values

Parameters

Name	Type	Description	Default
with_title	bool	include the table title	`False`
with_legend	bool	include table legend	`False`

transposed

core.table.Table.transposed(new_column_name, select_as_header=None, **kwargs)

returns the transposed table.

Parameters

Name	Type	Description	Default
new_column_name		the existing header will become a column with this name	required
select_as_header		current column name containing data to be used as the header. Defaults to the first column.	`None`

with_new_column

core.table.Table.with_new_column(
    new_column,
    callback,
    columns=None,
    dtype=None,
    **kwargs,
)

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

Parameters

Name	Type	Description	Default
new_column	str	new column heading	required
columns	str \| tuple[str, …] \| None	the columns whose values determine whether a row is to be included.	`None`
callback	typing.Callable[[numpy.ndarray], typing.Iterable] \| str	Can be a function, which takes the subtable by columns and returns True/False, or a string representing valid python code to be evaluated.	required
dtype	numpy.dtype \| None	numpy type of result	`None`

with_new_header

core.table.Table.with_new_header(old, new, **kwargs)

returns a new Table with old header labels replaced by new

Parameters

Name	Type	Description	Default
old		the old column header(s). Can be a string or series of them.	required
new		the new column header(s). Can be a string or series of them.	required

write

core.table.Table.write(
    filename,
    mode=None,
    writer=None,
    format_name=None,
    sep=None,
    compress=None,
    with_title=True,
    with_legend=True,
    **kwargs,
)

Write table to filename in the specified format.

Parameters

Name	Type	Description	Default
mode	str \| None	file opening mode	`None`
format_name	str \| None	Valid formats are those of the to_string method plus pickle. Will try and guess from filename if not specified.	`None`
writer	typing.Callable \| None	a function for formatting the data for output.	`None`
sep	str \| None	a character delimiter for fields.	`None`
compress	bool \| None	if True, gzips the file and appends .gz to the filename (if not already added).	`None`
with_title	bool	include the table title, ignored by formats without a title	`True`
with_legend	bool	include the table legend, ignored by formats without a legend	`True`

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.