Fill tables with values that are linked to references¶

About¶

This Sphinx extension (named “sphinx-filltableref”, parsed as “fill table ref”) enables creating “summary” tables of data that link to other pages which contain “source” tables that specify where the data is from (the reference) and can also describe the data values in more detail.

The extension defines two Sphinx directives: The tblrender directive is used to specify what the summary table looks like (row and column labels and titles), but not the referenced data values. The tbldata directive is used to specify the data values along with the source (reference). When a document is processed, information specified in both types of directives are combined: data values from one or more tbldata directives are used to fill in the summary table specified in a tblrender directive. The values filled-in link to the “source” tables specified by the tbldata directive that display the citation for the values.

This extension requires extension: sphinxcontrib-bibtexpdflink. The reason for this requrement is that, in order to generate the citations and references, this extension requires extensions: sphinxcontrib-bibtex and sphinxcontrib-bibtex2, and both of those are installed automatically by sphinxcontrib-bibtexpdflink. Also sphinxcontrib-bibtexpdflink allows having a link to a PDF file and notes for each reference, which can be quite useful.

Installation¶

Install the extension with:

$ pip install --index-url https://test.pypi.org/simple/ sphinxcontrib-filltableref

(This installs from Test PyPI).

The package is not yet on the real PyPI, but when it is, the installation command will be:

$ pip install sphinxcontrib-filltableref

Configuring¶

Add the extension to the Sphinx conf.py file (along with extensions sphinxcontrib.bibtexpdflink, sphinxcontrib.bibtex, and sphinxcontrib.bibtex2):

extensions = [
    "sphinxcontrib.bibtex",
    "sphinxcontrib.bibtex2",
    "sphinxcontrib.bibtexpdflink",
    "sphinxcontrib.filltableref"
    ]

If it’s desired to allow the citations to include links to PDF files and note files (which is the purpose of the sphinxcontrib-bibtexpdflink extension), add the locations of the PDF and notes file directories to the conf.py fileusing config variables bibtexpdflink_note_dir and bibtexpdflink_pdf_dir as describe in the documentation for sphinxcontrib-bibtexpdflink.

Usage¶

As described in About, the extension works using two directives: tblrender specifies what a summary table looks like (but without referenced values), and the tbldata directive specifies the values used to fill in the summary table) along with citations to publications.

These directives are described in the following sections:

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
Source cell	Cell count	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]					-

tbldata¶

The tbldata directive (abbreviation for “table data”) is used to specify data values that are included in to the summary table (defined by the tblrender directive) along with citation(s) to publications from which the values were found. There can be multiple tbldata directives for each tblrender directive (each tbldata directive specifying additional data values). The tbldata directive has the following format:

.. tbldata:: <table_name>
   :id_prefix: <id_prefix>

   <row title>   | <expanded col title>   | Value       | Reference
   <row label-a> | <col label a>          | <value a>   | <reference a>
   <row label-b> | <col label b>          | <value b>   | <reference b>
   <row label-c> | <col label c>          | <value c>   | <reference c>
       .               .                       .             .
       .               .                       .             .
       .               .                       .             .


Text describing the data (optional)


.. footbibliography::

The entities in angle brackets are:

<table_name>: Name of the summary table (used in the tblrender directive).
<id_prefix>: A short prefix (for example ‘a’, ‘b’, ‘gr’) which will be used to make an id (e.g. a1, a2, a3 …) associated with the row in the table. It will be displayed as the link after the data value in the summary table and link to the source table. The prefix should be unique for each source table.
<row title>: The row title specified in the tblrender directive.
<expanded col title>: Either the <expanded_col_title> or the <col title> specified in the tblrender directive. (Either one is allowed, whatever seems most understandable should be used).
<row label-a>: A <row label> in the summary table.
<col label a>: A <col label> in the summary table.
<value a>: A value to be inserted into the summary table for the specified <row label-a> and <col label a>.
<reference a>: A reference (bibtex citation id) or a list of references, seperated by spaces or commas.

An example is shown below:

.. tbldata:: table_loebner_fig2a
   :id_prefix: b

   Source cell | Cell count or Target cell   | Value       | Reference
   basket      | Cell count                  | 7.5x10^6    | LoebnerEE-1989
   basket      | purkinje                    | 9, 7.5x10^6 | LoebnerEE-1989

Some text describing basket cells.

.. footbibliography::

This is combined with the Example tblrender directive on the previous page to generate:

Data for table Cells and connections in cat

The following table has data and references for table Cells and connections in cat. 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).

Id	Source cell	Cell count or Target cell	Value	Reference
b1	basket	Cell count	7.5x10^6	[LoebnerEE-1989] 1
b2	basket	purkinje	9, 7.5x10^6	[LoebnerEE-1989] 1

Some text describing basket cells.

1(1,2): EE Loebner. Intelligent network management and functional cerebellum synthesis. In Raugh MR, editor, Cerebellar Models of Associative Memory: Three papers from IEEE COMPCON SPRING ‘89, pages 14–19. Research Institute for Advanced Computer Science, NASA Ames Research Center, 1989. PDF: LoebnerEE-1989.pdf, Notes: LoebnerEE-1989.html.

Notes¶

The notes listed here are in the notes directory. Links to these note files are added to the references that have the same citation key as the note file name by the sphinxcontrib-bibtexpdflink Sphinx extension.

The following notes are available:

JaeckelLA-1989a¶

Notes about [JaeckelLA-1989a] 1 .

This paper describes the “selected-coordinate design” of the Sparce Distributed Memory (SDM). The design was the subject of a patent application filed in 1998.

1: LA Jaeckel. An alternative design for a sparse distributed memory. Technical Report 89.28, NASA Ames Research Center, 1989. PDF: JaeckelLA-1989a.pdf, Notes: JaeckelLA-1989a.html (this file).

LiK+MalikJ-2017¶

Notes about [LiK+MalikJ-2017] 1 .

This paper describes an effecient algorithm for searching for k-nearest neighbours. It states that the algorithm is reduces the number of distance evaluations by a factor of 14 to 116 and the memory consumption by a factor of 21 compared to prior methods.

1: K Li and J Malik. Fast k-nearest neighbour search via dynamic continuous indexing. 2017. URL: https://arxiv.org/abs/1512.00442, PDF: LiK+MalikJ-2017.pdf, Notes: LiK+MalikJ-2017.html (this file).

LoebnerEE-1989¶

Notes about [LoebnerEE-1989] 1 .

Figure 2 in the paper provides data about the number of cells of different types in the cat cerebellum.

The number of cells of each type given in the figure is:

Cell type	Number of cells
basket	7.5x10^6
golgi	4.2x10^5
granule	2.2x10^9
purkinje	1.3x10^6
stellate	2.1x10^7

This data is included in the example summary table using the following tbldata directive. (The basket cell data is not included because it is provided in the other example tbldata directive.)

.. tbldata:: table_loebner_fig2a
   :id_prefix: n

   Source cell | Cell count or Target cell   | Value       | Reference
   golgi       | Cell count                  | 4.2x10^5    | LoebnerEE-1989
   granule     | Cell count                  | 2.2x10^9    | LoebnerEE-1989
   purkinje    | Cell count                  | 1.3x10^6    | LoebnerEE-1989
   stellate    | Cell count                  | 2.1x10^7    | LoebnerEE-1989


.. footbibliography::

It is rendered as:

Data for table Cells and connections in cat

The following table has data and references for table Cells and connections in cat. 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).

Id	Source cell	Cell count or Target cell	Value	Reference
n1	golgi	Cell count	4.2x10^5	[LoebnerEE-1989] 1
n2	granule	Cell count	2.2x10^9	[LoebnerEE-1989] 1
n3	purkinje	Cell count	1.3x10^6	[LoebnerEE-1989] 1
n4	stellate	Cell count	2.1x10^7	[LoebnerEE-1989] 1

1(1,2,3,4,5): EE Loebner. Intelligent network management and functional cerebellum synthesis. In Raugh MR, editor, Cerebellar Models of Associative Memory: Three papers from IEEE COMPCON SPRING ‘89, pages 14–19. Research Institute for Advanced Computer Science, NASA Ames Research Center, 1989. PDF: LoebnerEE-1989.pdf, Notes: LoebnerEE-1989.html (this file).

References¶

The sample references here are generated by the sphinxcontrib-bibtexpdflink extension which builds on the the sphinxcontrib-bibtex extension by adding links to included PDF and Notes files to the references.

JaeckelLA-1989b: LA Jaeckel. A class of designs for a sparse distributed memory. Technical Report 89.29, NASA Ames Research Center, 1989. URL: https://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/19920002426.pdf.
JaeckelLA-1989a: LA Jaeckel. An alternative design for a sparse distributed memory. Technical Report 89.28, NASA Ames Research Center, 1989. PDF: JaeckelLA-1989a.pdf, Notes: JaeckelLA-1989a.html.
LiK+MalikJ-2017: K Li and J Malik. Fast k-nearest neighbour search via dynamic continuous indexing. 2017. URL: https://arxiv.org/abs/1512.00442, PDF: LiK+MalikJ-2017.pdf, Notes: LiK+MalikJ-2017.html.
LoebnerEE-1989: EE Loebner. Intelligent network management and functional cerebellum synthesis. In Raugh MR, editor, Cerebellar Models of Associative Memory: Three papers from IEEE COMPCON SPRING ‘89, pages 14–19. Research Institute for Advanced Computer Science, NASA Ames Research Center, 1989. PDF: LoebnerEE-1989.pdf, Notes: LoebnerEE-1989.html.