#+TITLE: rorg --- R and org-mode

* Objectives
** Send data to R from org
   Org-mode includes orgtbl-mode, an extremely convenient way of using
   tabular data in a plain text file.  Currently, spreadsheet
   functionality is available in org tables using the emacs package
   calc.  It would be a boon both to org users and R users to allow
   org tables to be manipulated with the R programming language.  Org
   tables give R users an easy way to enter and display data; R gives
   org users a powerful way to perform vector operations, statistical
   tests, and visualization on their tables.

*** Implementations
**** naive
     Naive implementation would be to use =(org-export-table "tmp.csv")=
     and =(ess-execute "read.csv('tmp.csv')")=.  
**** org-R
     org-R passes data to R from two sources: org tables, or csv
     files. Org tables are first exported to a temporary csv file
     using [[file:existing_tools/org-R.el::defun%20org%20R%20export%20to%20csv%20csv%20file%20options][org-R-export-to-csv]].
**** org-exp-blocks
**** RweaveOrg
     NA

** evaluate R code from org and deal with output appropriately
*** vector output
    When R code evaluation generates vectors and 2-dimensional arrays,
    this should be formatted appropriately in org buffers (orgtbl-mode) as well
    as in export targets (html, latex)
**** Implementations
***** org-R
     org-R converts R output (vectors, or matrices / 2d-arrays) to an
     org table and stores it in the org buffer, or in a separate org
     file (csv output would also be perfectly possible).
***** org-exp-blocks
***** RweaveOrg
*** graphical output
    R can generate graphical output on a screen graphics device
    (e.g. X11, quartz), and in various standard image file formats
    (png, jpg, ps, pdf, etc). When graphical output is generated by
    evaluation of R code in Org, at least the following two things are desirable:
    1. output to screen for immediate viewing is possible
    2. graphical output to file is linked to appropriately from the
     org file This should have the automatic consequence that it is
     included appropriately in subsequent export targets (html,
     latex).
**** Implementations
***** org-R
      org-R does (1) if no output file is specified and (2) otherwise
***** org-exp-blocks
***** RweaveOrg


* Notes
** Special editing and evaluation of source code in R blocks
   Unfortunately org-mode how two different block types, both useful.
   In developing RweaveOrg, a third was introduced.

   Eric is leaning towards using the =#+begin_src= blocks, as that is
   really what these blocks contain: source code.  Austin believes
   that specifying export options at the beginning of a block is
   useful functionality, to be preserved if possible.

   Note that upper and lower case are not relevant in block headings.

*** Source code blocks 
    Org has an extremely useful method of editing source code and
    examples in their native modes.  In the case of R code, we want to
    be able to use the full functionality of ESS mode, including
    interactive evaluation of code.

    Source code blocks look like the following and allow for the
    special editing of code inside of the block through
    `org-edit-special'.

#+BEGIN_SRC r

,## hit C-c ' within this block to enter a temporary buffer in r-mode.

,## while in the temporary buffer, hit C-c C-c on this comment to
,## evaluate this block
a <- 3
a

,## hit C-c ' to exit the temporary buffer
#+END_SRC     

*** dblocks
    dblocks are useful because org-mode will automatically call
    `org-dblock-write:dblock-type' where dblock-type is the string
    following the =#+BEGIN:= portion of the line.

    dblocks look like the following and allow for evaluation of the
    code inside of the block by calling =\C-c\C-c= on the header of
    the block.  

#+BEGIN: dblock-type
#+END:

*** R blocks
    In developing RweaveOrg, Austin created [[file:existing_tools/RweaveOrg/org-sweave.el][org-sweave.el]].  This
    allows for the kind of blocks shown in [[file:existing_tools/RweaveOrg/testing.Rorg][testing.Rorg]].  These blocks
    have the advantage of accepting options to the Sweave preprocessor
    following the #+BEGIN_R declaration.


* tasks

* buffer dictionary
 LocalWords:  DBlocks dblocks