Skip to content

tablefill

Automatically update LaTeX, LyX, and Markdown tables using a placeholder system.

Quickstart

pip install git+https://github.com/mcaceresb/tablefill
tablefill --help

Documentation

tablefill is a program that uses a generic placeholder system to update LaTeX, LyX, and Markdown documents. While it's primary use is to fill in tables (hance the name) placeholders are replaced anywhere in a table environment or within commented-out tablefill tags.

  • Getting Started gives a basic example of how the system works, and guides the user through updating a template using Stata-generated input files (this example can be replicated with any programming language, however, not just Stata).

  • The usage section details the input required by tablefill, the format of the placeholders that are allowed, and documents the tablefill usage options.

  • Last, we provide examples of how to generate the type of input required by tablefill in the sample programs page.

Background

The original idea for this workflow comes from GSLab. The original tablefill in particular was made to automatically update LyX files with Stata output. However, I expanded this system to work with LaTeX and added several features. The workflow is as follows:

  1. Create a LaTeX, LyX, or Markdown document using placeholders. Label or tag each table appropriately.

  2. Print a matrix (or any array) into a tab-delimited text file. The output is preceded by the label or tag of the table you want to fill, and the matrix or array entries correspond to the placeholders.

  3. Run tablefill to update the placeholders in the template document.

The original tablefill only worked with LyX and assumed the tables came from Stata (or Matlab). This project initially aimed to extend the system to work with LaTeX, but over time it re-wrote the entire code base and added (several features)[#features]. For compatibility with scripts using GSLab's tablefill, the script can be run from the command line or imported as a python module.

Installation

pip install git+https://github.com/mcaceresb/tablefill
tablefill --help

This was created specifically to run in a server that only had Python 2.6 available. The function should be compatible with Python 2.6, Python 2.7, and Python 3.X without requiring the installation of any additional packages (the --numpy-syntax option is available if the function can successfully run import numpy; however, numpy is not required for normal use).

Features

As mentioned above, the original idea for tablefill comes from GSLab. However, this version has enough distinct features to merit calling itself a separate program. These include:

  • Ability to fill LaTeX and Markdown templates

    • There can be several placeholders in one line (however, there must be at most one table line per code line).
    • Labels in LaTeX can be anywhere in the table environment.
    • Placeholders can also be placed between commented-out tablefill tags, so updating is not restricted to literal tables.
    • Placeholders can be either # or \# (note the former is a special character in LaTeX so while the filled output will compile, the template will not).
    • Can have several matches of the pattern in the same line.
    • LaTeX tables can be filled inside Markdown documents.
    • The user can choose whether or not to fill in placeholders in commented-out lines.

  • Several error and consistency checks

    • Checks inputs are correct (names and type)
    • Checks if input files exist
    • Soft warning when placeholder outside proper environment
    • Soft warning when placeholder in environment with no label
    • Soft warning when placeholder in environment with unmatched label
    • Soft warning when more placeholders than table entries

  • Several new placeholder types:

    • Arbitrary python formatting via #{.*}# (note that in python 2.6 this must be #{0:.*}#).
    • #*# interprets the input as a p-value and replaces it with significance symbols (default is * 0.1, **0.05, ***0.01; however, anything that LaTeX, LyX, or Markdown will compile can be passed).
    • Modifier % reads the input as percentage (multiplies by 100).
    • Modifier || outputs the absolute value of the input.

  • The input tables can be generated by any program as long as they write missing values as blank, a dot, NA, or NaN.

  • tablefill can be run from the command line directly or imported to a python script.

  • Basic compilation support via the --compile and/or --bibtex flags.

  • XML-based ad-hoc table combination engine.

    • The user can combine arbitrary entries of existing tables in the provided templates to create new tables. This is useful if generating new tables is costly. It is also useful to quote table statistics in a summary elsewhere in the text (the LaTeX engine can parse the placeholders as long as they are in a table environment, which can be regular text).

Contributors

License

MIT