Outputting data in LaTeX format (pwkit.latex)

pwkit.latex - various helpers for the LaTeX typesetting system.

Classes

Referencer

Accumulate a numbered list of bibtex references, then output them.

TableBuilder

Create awesome deluxetables programmatically.

Functions

latexify_l3col

Format value in LaTeX, suitable for tables of limit values.

latexify_n2col

Format a number in LaTeX in 2-column decimal-aligned formed.

latexify_u3col

Format value in LaTeX, suitable for tables of uncertain values.

latexify

Format a value in LaTeX appropriately.

Helpers for TableBuilder

AlignedNumberFormatter

Format numbers, aligning them at the decimal point.

BasicFormatter

Base class for formatters.

BoolFormatter

Format a boolean; default is True -> bullet, False -> nothing.

LimitFormatter

Format measurements for a table of limits.

MaybeNumberFormatter

Format numbers with a fixed number of decimal places, or objects with __pk_latex__().

UncertFormatter

Format measurements for a table of detailed uncertainties.

WideHeader

Helper for multi-column headers.

XXX: Barely tested!

class pwkit.latex.AlignedNumberFormatter(nplaces=1)

Format numbers. Allows the number of decimal places to be specified, and aligns the numbers at the decimal point.

colinfo(builder)

Return (nlcol, colspec, headprefix), where:

nlcol - The number of LaTeX columns encompassed by this logical

column.

colspec - Its LaTeX column specification (None to force user to

specify).

headprefix - Prefix applied before heading items in {} (e.g.,

“colhead”).

class pwkit.latex.BasicFormatter

Base class for formatting table cells in a TableBuilder.

Generally a formatter will also provide methods for turning input data into fancified LaTeX output that can be used by the column’s “data function”.

colinfo(builder)

Return (nlcol, colspec, headprefix), where:

nlcol - The number of LaTeX columns encompassed by this logical

column.

colspec - Its LaTeX column specification (None to force user to

specify).

headprefix - Prefix applied before heading items in {} (e.g.,

“colhead”).

class pwkit.latex.BoolFormatter

Format booleans. Attributes truetext and falsetext set what shows up for true and false values, respectively.

colinfo(builder)

Return (nlcol, colspec, headprefix), where:

nlcol - The number of LaTeX columns encompassed by this logical

column.

colspec - Its LaTeX column specification (None to force user to

specify).

headprefix - Prefix applied before heading items in {} (e.g.,

“colhead”).

class pwkit.latex.LimitFormatter

Format measurements (cf pwkit.msmt) with nice-looking limit information. Specific uncertainty information is discarded. The default formats do not involve fancy subscripts or superscripts, so row struts are not needed … by default.

colinfo(builder)

Return (nlcol, colspec, headprefix), where:

nlcol - The number of LaTeX columns encompassed by this logical

column.

colspec - Its LaTeX column specification (None to force user to

specify).

headprefix - Prefix applied before heading items in {} (e.g.,

“colhead”).

class pwkit.latex.MaybeNumberFormatter(nplaces=1, align='c')

Format Python objects. If it’s a number, format it as such, without any fancy column alignment, but with a specifiable number of decimal places. Otherwise, call latexify() on it.

colinfo(builder)

Return (nlcol, colspec, headprefix), where:

nlcol - The number of LaTeX columns encompassed by this logical

column.

colspec - Its LaTeX column specification (None to force user to

specify).

headprefix - Prefix applied before heading items in {} (e.g.,

“colhead”).

class pwkit.latex.Referencer

Accumulate a numbered list of bibtex references. Methods:

refkey(bibkey)

Return a string that should be used to give a numbered reference to the given bibtex key. “thiswork” is handled specially.

dump()

Return a string with citet{} commands identifing all of the numbered references.

Attributes:

thisworktext

text referring to “this work”; defaults to that.

thisworkmarker

special symbol used to denote “this work”; defaults to star.

Bibtex keys beginning with asterisks have the rest of their value used for the citation text, rather than “citet{<key>}”.

class pwkit.latex.TableBuilder(label)

Build and then emit a nice deluxetable.

Methods:

addcol(headings, datafunc, formatter=None, colspec=None, numbering=’(%d)’)

Define a logical column.

addnote(key, text)

Define a table note that can appear in cells.

addhcline(headerrowix, logcolidx, latexdeltastart, latexdeltaend)

Add a horizontal line between columns.

notemark(key)

Return a tablenotemark{} command for the specified note key.

emit(stream, items)

Write the table, with one row for each thing in items, to the stream.

If an item has an attribute tb_row_preamble, that text is written verbatim before that corresponding row is output.

Attributes:

environment

The name of the latex environment to use, default “deluxetable”. You may want to specify “deluxetable*”, or “mydeluxetable” if using a hacked package.

label

The latex reference label of the table. Mandatory.

note

A note at the table footer (”tablecomments{}” in LaTeX).

preamble

Commands for table preamble. See below.

refs

Contents of the table References section.

title

Table title. Default “Untitled table”.

widthspec

Passed to tablewidth{}; default “0em” = auto-widen.

numbercols

If True, number each column. This can be disabled on a col-by-col basis by calling addcol with numbering set to False.

final_double_backslash

If True, end the final table row with a ‘’'’. AAStex6 requires this, giving an error about a misplaced ‘omit’ if you don’t provide one. On the other hand, classic TeX tables look worse if you do provide this.

Legal preamble commands are:

\rotate
\tablenum{<manual table identifier>}
\tabletypesize{<font size command>}

The commands tablecaption, tablecolumns, tablehead, and tablewidth are handled specially.

If tablewidth{} is not provided, the table is set at full width, not its natural width, which is a lame default. The default widthspec lets us auto-widen while providing a clear avenue to customizing the width.

addcol(headings, datafunc, formatter=None, colspec=None, numbering='(%d)')

Define a logical column. Arguments:

headings

A string, or list of strings and WideHeaders. The headings are stacked vertically in the table header section.

datafunc

Return LaTeX for this cell. Call spec should be (item, [formatter, [tablebuilder]]).

formatter

The formatter to use; defaults to a new BasicFormatter.

colspec

The LaTeX column specification letters to use; defaults to ‘c’s.

numbering

If non-False, a format for writing this column’s number; if False, no number is written.

addhcline(headerrowidx, logcolidx, latexdeltastart, latexdeltaend)

Adds a horizontal line below a limited range of columns in the header section. Arguments:

headerrowidx - The 0-based row number below which the line will be

drawn; i.e. 0 means that the line will be drawn below the first row of header cells.

logcolidx - The 0-based ‘logical’ column number relative to which

the line will be placed; i.e. 1 means that the line placement will be relative to the second column defined in an addcol() call.

latexdeltastart - The relative position at which to start drawing the

line relative to that logical column, in LaTeX columns; typically going to be zero.

latexdeltaend - The relative position at which to finish drawing the

line, in the standard Python noninclusive sense. I.e., if you want to underline two LaTeX columns, latexdeltaend = latexdeltastart + 2.

class pwkit.latex.UncertFormatter

Format measurements (cf. pwkit.msmt) with detailed uncertainty information, possibly including asymmetric uncertainties. Because of the latter possibility, table rows have to be made extra-high to maintain evenness.

colinfo(builder)

Return (nlcol, colspec, headprefix), where:

nlcol - The number of LaTeX columns encompassed by this logical

column.

colspec - Its LaTeX column specification (None to force user to

specify).

headprefix - Prefix applied before heading items in {} (e.g.,

“colhead”).

class pwkit.latex.WideHeader(nlogcols, content, align='c')

Information needed for constructing wide table headers.

nlogcols - Number of logical columns consumed by this header. content - The LaTeX to insert for this header’s content. align - The alignment of this header; default ‘c’.

Rendered as multicolumn{nlatex}{align}{content}, where nlatex is the number of LaTeX columns spanned by this header – which may be larger than nlogcols if certain logical columns span multiple LaTeX columns.

pwkit.latex.latexify(obj, **kwargs)

Render an object in LaTeX appropriately.

pwkit.latex.latexify_l3col(obj, **kwargs)

Convert an object to special LaTeX for limit tables.

This conversion is meant for limit values in a table. The return value should span three columns. The first column is the limit indicator: <, >, ~, etc. The second column is the whole part of the value, up until just before the decimal point. The third column is the decimal point and the fractional part of the value, if present. If the item being formatted does not fit this schema, it can be wrapped in something like ‘multicolumn{3}{c}{…}’.

pwkit.latex.latexify_n2col(x, nplaces=None, **kwargs)

Render a number into LaTeX in a 2-column format, where the columns split immediately to the left of the decimal point. This gives nice alignment of numbers in a table.

pwkit.latex.latexify_u3col(obj, **kwargs)

Convert an object to special LaTeX for uncertainty tables.

This conversion is meant for uncertain values in a table. The return value should span three columns. The first column ends just before the decimal point in the main number value, if it has one. It has no separation from the second column. The second column goes from the decimal point until just before the “plus-or-minus” indicator. The third column goes from the “plus-or-minus” until the end. If the item being formatted does not fit this schema, it can be wrapped in something like ‘multicolumn{3}{c}{…}’.