tblrender¶
The tblrender directive (stands for “table render”) specifies what a summary table looks like (row and column titles and labels) but without including referenced values. (The referenced values are filled in when the document is created). The directive is used in the following way:
.. _<table_name>:
Title of table
--------------
Description of table (displayed only before rendered summary table, not before source
tables.
.. tblrender <table_name>
:description:
Description of table, displayed before each "source" table, which are
generated by "tbldata" directives.
<ptable specification> AND/OR <gridtable specification>
The last line above indicates that there is an choice for the remainder of the directive: either a <ptable specification> or a <gridtable specification> or both. These two specifications accomplish the same thing, which is to define the table layout, but do it in different ways. The <ptable specification> uses parameter values that list the table row and column titles and labels. The <gridtable specification> uses a graphical layout that includes the row and column titles and labels in a table. The <ptable specification> will usually be shorter to write, but not as intuitative to understand since it does not look like a table. The <gridtable specification> will be easier to understand (since it looks like the finished table), but will be more laborious to create since it is longer and must be created by drawing lines using characters that must align accross rows.
The only difference between the functionality of the two is that the <gridtable specification> allows including prefilled values in the cells, but this cannot be done with the <ptable specification>. Although only one of the specifications will normally be used in a single tblrender directive, it’s permissible to include both. If that’s done, they must specify exactly the same table (except for any prefilled values in the <gridtable specification>) or an error is generated. Also, if both specifications are present, the <gridtable specification> is used to create the table (which will include any prefilled values). Including both specifications in the same tblrender directive is useful for documentation describing the specifications (this document) since that shows explicitly the relationship between them.
<ptable specification>¶
<ptable specification> contains:
:rows: <row title>, <row labels>
:cols: <col title>, <col labels>
:expanded_col_title: <expanded_col_title>
:ct_offset: <ct_offset>
The entities in angle brackets are either strings (enclosed in single or double quotes), list of strings (each element in the list separated by a comma) or an integer. The entities are:
- <row title>
The title displayed in the top left cell of the table (above the <row labels> which are in the left-most column below the <row title>). Example: “City”.
- <row labels>
List of the row labels, each element seperated by a comma. These go in the first column, under the <row title>. Example: “New York”, “London”, “Chicago”, …
- <col title>
The title displayed above the <col labels> in the header of the table. Example: “Season” (for a table showning average temperaure during each season).
- <col labels>
List of the column labels, each element seperated by a comma. Example: “Population”, “Spring”, “Fall”, “Summer”, …
- <ct_offset>
A positive integer specifying the number of columns (counting left to right), for which the <col label> does not subcategorize the <col title>. If not specified, the default is one (since the first column contains the <row title>, which does not subcategorize the <col title>). A value greater than one specifies a table in which the header for some columns after the first column have a <col lable> that does not appear under the <col title>. This is used for creating the table header.
For example, with the previous example values, <ct_offset> would be 2, to indicate that the “Population” column label is not an instance of the <col title> (“Season”), and thus “Population” should not be under “Season” in the table header. e.g., the header (and table) would look like:
+----------+------------+-----------------------------------+ | | | Season | | | +--------+--------+--------+--------+ | City | Population | Fall | Winter | Spring | Summer | +==========+============+========+========+========+========+ | New York | | | | | | +----------+------------+--------+--------+--------+--------+ | London | | | | | | +----------+------------+--------+--------+--------+--------+ | Chicago | | | | | | +----------+------------+--------+--------+--------+--------+
- <expanded_col_title>
This is a string that can be used in place of the <col title> as the column title for the column containing values in the source tables (made by the tbldata directive). If the <gridtable specification> is used (in addition to the <ptable specification>), then the <expanded_col_title> must match a value that is derived from the <gridtable specification>. This value is formed by first parsing the gridtable to obtain the <col title>, <col labels> and <ct_offset>; then combining the first <ct_offset> <column labels> and the <col title> separated by ” or “. In other words, what is specified explicitly using the <ptable specification> must match the layout given in the <gridtable specification> if both are present.
Using the values in the above examples, if derived from a <gridtable specification>, <expanded_col_title> would be “Population or Season”.
The full <ptable specification> for the table shown above is:
:rows: "City", "New York", "London", "Chicago"
:cols: "Season", "Population", "Fall", "Winter", "Spring", "Summer"
:expanded_col_title: "Population or Season"
:ct_offset: 2
<gridtable specification>¶
<gridtable specification> contains a :gridLayout: parameter followed by a reStructuredText
grid table.
Pre-filled values can be included in the cells. The specification for the table shown earlier is
below. A prefilled value (population of New York) is included.
:gridLayout:
+----------+------------+-----------------------------------+
| | | Season |
| | +--------+--------+--------+--------+
| City | Population | Fall | Winter | Spring | Summer |
+==========+============+========+========+========+========+
| New York | 8 million | | | | |
+----------+------------+--------+--------+--------+--------+
| London | | | | | |
+----------+------------+--------+--------+--------+--------+
| Chicago | | | | | |
+----------+------------+--------+--------+--------+--------+
Example¶
An example including both types of specifications is below. The <gridtable specification> includes prefilled values (“-”) along a diagonal.
.. _table_loebner_fig2a:
Cells and connections in cat
----------------------------
The following table provides counts of cells and connections in the cat cerebellum.
The first two columns (*Source cell* and *Cell count*) are respectively a cell type
and the count (number) of cells of that type. The values in the rest of the table
give the number of connections from the Source cell to Target cells. These are
specified as a pair of numbers: FO,FI. FO is fan-out (number of target cells each
source cell contacts) and FI is fan-in (number of source cells going to each target
cell). The data is from Figure 2 in :cite:`LoebnerEE-1989`.
.. tblrender:: table_loebner_fig2a
:rows: "Source cell", "basket", "golgi", "granule", "purkinje", "stellate"
:cols: "Target cell", "Cell count", "basket", "golgi", "granule", "purkinje", "stellate"
:expanded_col_title: "Cell count or Target cell"
:ct_offset: 2
:description:
Values are either a Cell count, or FO,FI where FO is *fan-out* (number of target cells
each source cell contacts) and FI is *fan-in* (number of source cells going to each
target cell).
:gridLayout:
+-------------+----------+------------------------------------------------------------------+
| | | Target cell |
| Source | Cell +------------+------------+------------+-------------+-------------+
| cell | count | basket | golgi | granule | purkinje | stellate |
+=============+==========+============+============+============+=============+=============+
| basket | | - | | | | |
+-------------+----------+------------+------------+------------+-------------+-------------+
| golgi | | | - | | | |
+-------------+----------+------------+------------+------------+-------------+-------------+
| granule | | | | - | | |
+-------------+----------+------------+------------+------------+-------------+-------------+
| purkinje | | | | | - | |
+-------------+----------+------------+------------+------------+-------------+-------------+
| stellate | | | | | | - |
+-------------+----------+------------+------------+------------+-------------+-------------+
It is rendered as shown below. The values for some of the cells followed by links to the source of the value are fill-in during the rendering process. These values are specified in the “source” table given on the next page using the tbldata directive.
Cells and connections in cat¶
The following table provides counts of cells and connections in the cat cerebellum. The first two columns (Source cell and Cell count) are respectively a cell type and the count (number) of cells of that type. The values in the rest of the table give the number of connections from the Source cell to Target cells. These are specified as a pair of numbers: FO,FI. FO is fan-out (number of target cells each source cell contacts) and FI is fan-in (number of source cells going to each target cell). The data is from Figure 2 in [LoebnerEE-1989].
Values are either a Cell count, or FO,FI where FO is fan-out (number of target cells each source cell contacts) and FI is fan-in (number of source cells going to each target cell).
Source cell |
Cell count |
Target cell |
||||
|---|---|---|---|---|---|---|
basket |
golgi |
granule |
purkinje |
stellate |
||
basket |
7.5x10^6 [b1] |
- |
9, 7.5x10^6 [b2] |
|||
golgi |
4.2x10^5 [n1] |
- |
||||
granule |
2.2x10^9 [n2] |
- |
||||
purkinje |
1.3x10^6 [n3] |
- |
||||
stellate |
2.1x10^7 [n4] |
- |
||||