[Orgmode] [babel] RFC: column and row names in babel tables

[Dan Davison]

If others would like to comment on this proposal that would be really
helpful (warning: probably not fun reading):

The question is: how do we map between org tables with hline separators
and tabular data structures in babel languages (some of which have
internal concepts of "column names" and "row names")? In particular, one
might commonly use an hline in org to form "column names":

| column | names    |
|--------+----------|
| table  | contents |

* Example tables
#+tblname: A
| a | b | c |
| d | e | f |
| g | h | i |

#+tblname: B
| a | b | c |
|---+---+---|
| d | e | f |
| g | h | i |

#+tblname: C
| a | b | c |
|---+---+---|
| d | e | f |
|---+---+---|
| g | h | i |


- Terminology ::

  - Table B above has "column names" and therefore one "hline". Table
    A has neither. Table C has "column names" and two "hlines".

  - For the purposes of this discussion, there are no such things as
    "row names" in an Org table.

- What will we do with hlines ::

  Currently, all languages other than R fail with hlines present.

  New behaviour: by default all languages will *drop all hlines* from
  tables in input. We shall make no attempt to reinstate hlines in the
  output[1] *Do we want some way for the user to control hlines in the
  output?*
  
  This means that if a table has column names, those column names will
  be passed to the language as an ordinary first row of the table.

  This example shows loss of all hlines by default:

#+begin_src python :var tab=C
tab
#+end_src

#+results:
| a | b | c |
| d | e | f |
| g | h | i |

  
- :colnames header argument ::
  
  This argument will be used to say: "The first row of this input
  table contains column names." There are two cases:

  In both cases, to start off with we *drop all hlines* and *omit the
  first row*. Therefore, row i in the org table will be row i-1 in the
  language. The difference is:

  1. Language does not support column names for tabular data
     structures (most languages)

     When we output a table we reinstate the first row as column names
     with an hline, *if* the output number of columns is the same as
     the input. *Do you agree?*

  2. Language supports column names (R)
  
     The input R object is created with the first row as column names,
     and the column names of the output object are exported back to
     org, and an hline is reinstated.

This example shows preservation of colnames and loss of second hline:

#+begin_src python :var tab=C :colnames yes
tab
#+end_src

#+results:
| a | b | c |
|---+---+---|
| d | e | f |
| g | h | i |

- :rownames header argument ::
  
  This is analogous to :colnames
  
  This argument will be used to say: "The first column of this input
  table contains row names." There are two cases. In both cases we
  *omit the first column*, therefore column j in the org table will be
  column j-1 in the language.
  
  1. Language does not support row names for tabular data structures
     (most languages)

     We attempt to *reinstate row names* if number of output rows is
     the same as input.

  2. Language supports rownames (R)
     
     The first column is used as the object rownames. The output
     object rownames are exported to Org and become the first column
     of the output org table.

     This is largely implemented already by a patch by Julien Barnier.

Dan

* Footnotes

[1] Because the output table is not necessarily "the same table" as
the input table.