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.

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

Return type:

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:

  • columns (string or sequence of strings) – names of columns

  • with_index (bool) – If index_name is set, includes with columns.

Return type:

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 – 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

  • 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:

  • head (int) – number of top rows to included in represented display

  • tail (int) – number of bottom rows to included in represented display

  • random (int) – number of rows to sample randomly (supercedes head/tail)

  • show_shape (bool) – 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_title (bool) – include the table title

  • with_legend (bool) – include table legend

Return type:

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:

flatten (bool) – returns a 1D dictionary

to_html(column_alignment=None)

construct html table

Parameters:

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.

Return type:

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_legend (bool) – 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_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

Return type:

str

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_table (bool) – use csv-directive, grid table otherwise

Return type:

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.

  • center (bool) – content is centered in the column, default is right justified

  • concat_title_legend (bool) – 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_title (bool) – include the table title

  • with_legend (bool) – include table legend

Return type:

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.