Tables¶

Tables provide a simple means to visualize tabular data. VaRA-TS comes with its own table abstraction that uses pandas or python-tabulate to render tables in different formats. Here, you can find detailed information about how tables work in VaRA-TS and how to implement your own tables. For an introduction on how to generate tables see this guide.

Table Architecture¶

Tables in VaRA-TS work analogous to plots as described here. This section applies to tables as well if you replace every occurrence of plot with table.

How to add a new table in VaRA-TS¶

To implement a new plot, you need to create at least one subclass of TableGenerator and one Table.

Each table class must override the abstract function tabulate() that returns a string of the rendered table. By convention, the returned string should be produced by python-tabulate’s tabulate() function using the provided table_format parameter. There exists also a helper function dataframe_to_table() that can automatically convert a pandas data frame into the appropriate string representation. The data for tables should be retrieved using our data storage abstraction.

For the table generator, you need to implement the method generate(). The generator’s generate function must return one or more instances of table classes that should be generated. There is no restriction to what tables can be instantiated, but each generator should typically restrict to generating instances of a single table type.

Table helper modules¶

Module: table¶

Base table module.

exception varats.table.table.TableDataEmpty[source]¶

Bases: Exception

Throw if there was no input for the table.

class varats.table.table.Table(table_config, **kwargs)[source]¶

Bases: object

An abstract base class for all tables generated by VaRA-TS.

NAME = 'Table'¶

TABLES: Dict[str, Type[Table]] = {}¶

format_filetypes = {TableFormat.GITHUB: 'md', TableFormat.HTML: 'html', TableFormat.LATEX: 'tex', TableFormat.LATEX_BOOKTABS: 'tex', TableFormat.LATEX_RAW: 'tex', TableFormat.RST: 'rst', TableFormat.UNSAFEHTML: 'html'}¶

static get_table_types_help_string()[source]¶

Generates help string for visualizing all available tables.

Return type:: str
Returns:: a help string that contains all available table names.

static get_class_for_table_type(table_type)[source]¶

Get the class for table from the table registry.

Parameters:: table_type (str) – The name of the table.
Return type:: Type[Table]

Returns: The class implementing the table.

property name: str¶

Name of the current table.

Test: >>> Table(TableConfig.from_kwargs(view=False)).name ‘Table’

property table_config: TableConfig¶: Table config for this table.

property table_kwargs: Any¶

Access the kwargs passed to the initial table.

Test: >>> p = Table(TableConfig.from_kwargs(view=False), foo=’bar’, baz=’bazzer’) >>> p.table_kwargs[‘foo’] ‘bar’ >>> p.table_kwargs[‘baz’] ‘bazzer’

static supports_stage_separation()[source]¶

True, if the table supports stage separation, i.e., the table can be drawn separating the different stages in a case study.

Return type:: bool

abstractmethod tabulate(table_format, wrap_table)[source]¶

Build the table using tabulate.

Parameters:

table_format (TableFormat) – the format to use for the table
wrap_table (bool) – whether to wrap the table in a separate document (latex only)

Return type:

str

table_file_name(table_format)[source]¶

Get the file name this table; will be stored to when calling save. Automatically deduces this tables’ filetype from its format.

Return type:: str
Returns:: the file name the table will be stored to

Test: >>> p = Table(TableConfig.from_kwargs(view=False), project=’bar’) >>> p.table_file_name(TableFormat.PLAIN) ‘bar_Table.txt’ >>> from varats.paper.case_study import CaseStudy >>> p = Table(TableConfig.from_kwargs(view=False), project=’bar’, case_study=CaseStudy(‘baz’, 42)) >>> p.table_file_name(TableFormat.LATEX_BOOKTABS) ‘baz_42_Table.tex’

show()[source]¶

Show the current table in console.

Return type:: None

save(path, table_format, wrap_table)[source]¶

Save the current table to a file.

Parameters:

path (Path) – the path where the file is stored (excluding file name)
table_format (TableFormat) – the format to use for the table
wrap_table (bool) – whether to wrap the table in a separate document (latex only)

Return type:

None

Module: tables¶

General tables module.

class varats.table.tables.TableFormat(*values)[source]¶

Bases: Enum

List of supported TableFormats.

value: str¶

PLAIN = 'plain'¶

SIMPLE = 'simple'¶

GITHUB = 'github'¶

GRID = 'grid'¶

FANCY_GRID = 'fancy_grid'¶

PIPE = 'pipe'¶

ORGTBL = 'orgtbl'¶

JIRA = 'jira'¶

PRESTO = 'presto'¶

PRETTY = 'pretty'¶

PSQL = 'psql'¶

RST = 'rst'¶

MEDIAWIKI = 'mediawiki'¶

MOINMOIN = 'moinmoin'¶

YOUTRACK = 'youtrack'¶

HTML = 'html'¶

UNSAFEHTML = 'unsafehtml'¶

LATEX = 'latex'¶

LATEX_RAW = 'latex_raw'¶

LATEX_BOOKTABS = 'latex_booktabs'¶

TEXTILE = 'textile'¶

is_latex()[source]¶

Return type:: bool

is_html()[source]¶

Return type:: bool

class varats.table.tables.CommonTableOptions(view, table_dir, table_format, wrap_table, dry_run)[source]¶

Bases: object

Options common to all tables.

These options are handled by the TableGenerator base class and are not passed down to specific table generators.

Parameters:

view (bool) – if True, view the table instead of writing it to a file
table_dir (Path) – directory to write tables to (relative to config value ‘tables/table_dir’)
table_format (TableFormat) – the format for the written table file
dry_run (bool) – if True, do not generate any files

static from_kwargs(**kwargs)[source]¶

Construct a CommonTableOptions object from a kwargs dict.

Return type:: CommonTableOptions

classmethod cli_options(command)[source]¶

Decorate a command with common table CLI options.

This function can be used as a decorator.

Parameters:: command (Any) – the command to decorate
Return type:: Any
Returns:: the decorated command

get_dict()[source]¶

Create a dict representation for this object.

It holds that options == CommonTableOptions.from_kwargs(**options.get_dict()).

Return type:: Dict[str, Any]
Returns:: a dict representation of this object

class varats.table.tables.TableConfig(view, *options)[source]¶

Bases: object

Class with parameters that influence a table’s appearance.

Instances should typically be created with the from_kwargs() function.

property fig_title: COGetter[str]¶

property font_size: COGetterV[int]¶

property line_width: COGetterV[float]¶

classmethod from_kwargs(view, **kwargs)[source]¶

Instantiate a TableConfig object with values from the given kwargs.

Parameters:: **kwargs (Any) – a dict containing values to be used by this config
Return type:: TableConfig
Returns:: a table config object with values from the kwargs

classmethod cli_options(command)[source]¶

Decorate a command with table config CLI options.

This function can be used as a decorator.

Parameters:: command (Any) – the command to decorate
Return type:: Any
Returns:: the decorated command

get_dict()[source]¶

Create a dict representation from this table config.

The dict only contains options for which values were explicitly set. It holds that config == TableConfig.from_kwargs(**config.get_dict()).

Return type:: Dict[str, Any]
Returns:: a dict representation of this table config

exception varats.table.tables.TableGeneratorFailed(message)[source]¶

Bases: Exception

Exception for table generator related errors.

class varats.table.tables.TableGenerator(table_config, **table_kwargs)[source]¶

Bases: ABC

Superclass for all table generators.

A table generator is responsible for generating one or more tables. Subclasses are automatically registered if they reside in the varats.tables package and must override the function generate() so that it returns one or more table instances that should be generated. The generation itself (i.e., saving or displaying tables) is handled by the call operator (which should not be overridden!).

Creating a table generator class requires to provide additional parameters in the class definition, e.g.:

class MyTableGenerator(
    TableGenerator,
    generator_name="my_generator",  # generator name as shown by CLI
    options=[]  # put CLI option declarations here
):
    ...

GENERATORS: Dict[str, Type[TableGenerator]] = {}¶: Registry for concrete table generators.

NAME: str¶: Name of the concrete generator class (set automatically).

OPTIONS: List[Callable[[Callable[[...], Any] | Command], Callable[[...], Any] | Command]]¶: Table generator CLI Options (set automatically).

static get_table_generator_types_help_string()[source]¶

Generates help string for visualizing all available tables.

Return type:: str
Returns:: a help string that contains all available table names.

static get_class_for_table_generator_type(table_generator_type_name)[source]¶

Get the class for table from the table registry.

Parameters:: table_generator_type_name (str) – name of the table generator
Return type:: Type[TableGenerator]
Returns:: the class for the table generator

property table_config: TableConfig¶: Options that influence a table’s appearance.

property table_kwargs: Dict[str, Any]¶: Table-specific options.

abstractmethod generate()[source]¶

Create the table instance(s) that should be generated.

Return type:: List[Table]

class varats.table.tables.TableArtefact(name, output_dir, table_generator_type, common_options, table_config, **kwargs)[source]¶

Bases: Artefact

An artefact defining a Table.

Parameters:

name (str) – name of this artefact
output_dir (Path) – output dir relative to config value ‘artefacts/artefacts_dir’
table_generator_type (str) – the type of table to use
kwargs (Any) – additional arguments that will be passed to the table class

property table_generator_type: str¶: The type of table generator used to generate this artefact.

property table_generator_class: Type[TableGenerator]¶: The class associated with table_generator_type().

property common_options: CommonTableOptions¶: Options that are available to all tables.

property table_config: TableConfig¶: Options that influence the visual representation of a table.

property table_kwargs: Any¶: Additional arguments that will be passed to the table.

get_dict()[source]¶

Create a dict representation for this object.

Return type:: Dict[str, Any]
Returns:: a dict representation of this object

static create_artefact(name, output_dir, **kwargs)[source]¶

Create an artefact instance from the given information.

Parameters:

name (str) – the name of the artefact
output_dir (Path) – the output directory for the artefact
**kwargs (Any) – artefact-specific arguments

Return type:

Artefact

Returns:

an artefact instance

ARTEFACT_TYPE = 'table'¶

ARTEFACT_TYPE_VERSION = 2¶

static from_generator(name, generator, common_options)[source]¶

Create a table artefact from a generator.

Parameters:

name (str) – name for the artefact
generator (TableGenerator) – generator class to use for the artefact
common_options (CommonTableOptions) – common table options

Return type:

TableArtefact

Returns:

an instantiated table artefact

generate_artefact(progress=None)[source]¶

Generate the specified table(s).

Return type:: None

get_artefact_file_infos()[source]¶

Retrieve information about files generated by this artefact.

Return type:: List[ArtefactFileInfo]
Returns:: a list of file info objects

Module: table_utils¶

Module for table related utility functionality.

varats.table.table_utils.wrap_table_in_latex_document(table, landscape=False, margin=1.5, document_decorator=<function <lambda>>)[source]¶

Wraps a table inside a proper latex document.

Uses \longtable instead of \tabular to fit data on multiple pages.

Parameters:

table (str) – table string to wrap the document around
landscape (bool) – whether to layout the table in landscape mode
margin (float) – margin around the table in cm

Return type:

str

Returns:

the resulting latex document as a string

varats.table.table_utils.dataframe_to_table(data, table_format, style=None, wrap_table=False, wrap_landscape=False, margin=1.5, document_decorator=<function <lambda>>, **kwargs)[source]¶

Convert a pandas DataFrame to a table.

Parameters:

data – the DataFrame to convert
table_format – the table format used for conversion
style – optional styler object; needs to be passed when custom styles are used
wrap_table – whether to wrap the table in a separate document (latex only)
wrap_landscape – whether to use landscape mode to wrap the table (latex only)
margin – margin around the table in cm
document_decorator – callable function to decorate the document with additional things (e.g., packages, macros, etc.)
**kwargs – kwargs that get passed to pandas’ conversion functions (DataFrame.to_latex or DataFrame.to_html)

Returns:

the table as a string