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.