# 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

    Returns

    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.

    Returns

    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

    Returns

    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.

    Returns

    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

      - rows – table data in row orientation

      - header – table header

      - 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

    Returns

    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

    Returns

    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

    Returns

    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.