removed R tutorial from FIXME

FIXME/ob-doc-R-extended.org

@@ -1,843 +0,0 @@
-#+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:t d:(HIDE) tags:not-in-toc
-#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate 
-#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
-#+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
-#+TITLE:    Org-mode and R: An Introduction
-#+AUTHOR:    Erik Iverson
-#+EMAIL:     eriki at ccbr dot umn dot edu
-#+LANGUAGE:   en
-#+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
-#+BABEL: :exports both
-
-This is an introduction to using R ([[http://www.R-project.org]]) source
-code within Emacs org-mode ([[http://orgmode.org]]). Org-mode files use
-headlines to organize information. Each top-level headline in this
-document starts with a single '*', like the "Introduction" headline
-below. While this is not an introduction to using org-mode, you will
-need to know one command to proceed: use the TAB key on a headline to
-open it. TAB will cycle through the possible visibility states of the
-information under the headline, and eventually TAB will collapse the
-headline back to how you see it now. One last command to note: C-c C-o
-opens links like those above in your web browser. I have tried to link
-to the appropriate documentation for each feature I describe.
-
-Since you are following along in org-mode, instead of reading this in
-an exported format like HTML or PDF, you will need org-mode 7.01 or
-greater to go interact with this tutorial. See [[http://orgmode.org/index.html#sec-3][here]] for instructions
-on how to download the latest version of org-mode. To see what version
-of org-mode you have installed, type M-x org-version, and hit
-<ENTER>. The result will be in the minibuffer. If the version is
-anything less than 7.01, you'll need to update to run the examples.
-If you have an older version of org-mode, and just want to read about
-the possibilities, you can continue on.
-
-* Introduction
-
-#+begin_html
-  <div id="subtitle" style="float: center; text-align: center;">
-  <p>
-  Org-mode support for
-  <a href="http://www.r-project.org/">R</a>
-  </p>
-  <p>
-  <a href="http://www.r-project.org/">
-  <img src="http://www.r-project.org/Rlogo.jpg"/>
-  </a>
-  </p>
-  </div>
-#+end_html
-
-Emacs org-mode 7.01 has an exciting new feature that lets you submit
-source code blocks within an org-mode document for evaluation. This
-lets you do things like insert the results of R code into an Emacs
-buffer, insert graphical and tabular material into a buffer, or pass
-the results of R code to other programming languages such as Python. R
-code and results can be included in your exported org-mode documents,
-opening up several interesting possibilities for automatically
-generating comprehensive documentation and advanced reports. You can
-also extract the source code portions of an org-mode document for
-further processing, through a process called tangling. This tutorial
-will get you started using these org-mode features together with the R
-programming language.
-
-If you are unfamiliar with org-mode itself, you can learn a lot more
-from the project's [[orgmode.org][website]]. There are many good tutorials available on
-org-mode already. The [[http://orgmode.org/guide/index.html][compact guide]] is a great place to start. This
-current document focuses on source code support. Note that while the
-features being demonstrated in this document were being developed, the
-project was known as org-babel. Thus, many of the variables and
-function names reference 'org-babel' in their names. Org-babel is now
-distributed with org-mode, so many of the previous configuration
-hurdles are now avoided. Keep this in mind as you read old mailing
-list posts and documentation. The authors of org-babel are Eric
-Schulte and Dan Davison. They have worked very hard creating this
-amazing system!
-
-Although you may be viewing this tutorial in an exported format like
-HTML or PDF, I wrote this tutorial in org-mode. You will benefit most
-from it by following along in org-mode. Only then can you
-interactively evaluate the examples to see org-mode in action. For
-this reason, I suggest you download the [[http://repo.or.cz/w/Worg.git/blob_plain/HEAD:/org-contrib/babel/languages/ob-doc-R-extended.org][actual org mode file]] that this
-document is based on, visit the file in Emacs, and follow along there.
-
-For those following along in an exported version, such as HTML, 
-in the actual org-mode file, source code blocks look like this:
-
-#+begin_example
-#+begin_src R 
-  # some R code 
-  square <- function(x) 
-  {
-    x * x
-  }
-    
-  square(1:10)
-#+end_src 
-#+end_example
-
-However, when they are /exported/ into documents like this they will
-look like:
-
-#+begin_src R :exports code
-  # some R code 
-  square <- function(x) 
-  {
-    x * x
-  }
-    
-  square(1:10)
-#+end_src 
-
-It's something to be aware of when following along from an exported
-version such as HTML, since I will be referencing source code block
-arguments that you will not be able to see.  That is another very good
-reason to follow along with the [[http://repo.or.cz/w/Worg.git/blob_plain/HEAD:/org-contrib/babel/languages/ob-doc-R-extended.org][raw org mode file]]. 
-
-This tutorial was written in GNU Emacs 23.2 on Ubuntu 10.04, org-mode
-version 7.01trans, pulled directly from the org-mode git repository.
-
-Please send any questions or corrections to eriki at ccbr dot umn dot edu. 
-
-** System Prerequisites for this tutorial 
-
-First, we need to make sure our environment is setup correctly for the
-examples to run.  This requires a bit more work under Windows than
-others, see below.
-
-Here is a list of software we need to run the examples:
-1) org-mode 7.01 or greater, see [[http://orgmode.org]]
-2) a working R installation, see [[http://www.R-project.org]]
-3) The R examples use the ggplot2 and Hmisc packages from CRAN. Simply install from the
-   R command line by issuing the command, 
-   > install.packages(c("ggplot2", "Hmisc"))
-   R must be in your PATH environment variable.  For Windows users, you will probably
-   have to add this yourself. 
-
-For LaTeX support, 
-4) a working LaTeX installation, see [[http://latex-project.org]]. Windows users
-   can use [[http://miktex.org/][MikTeX]].  
-5) dvipng program (comes with MikTeX or texlive-full Ubuntu package)
-
-6) Some extra LaTeX packages (comes with texlive-full Ubuntu package): 
-
-   I found that on my Ubuntu 10.04 installation, I had to install the
-   texlive-latex-extra and texlive-fonts-recommended packages to get
-   the LaTeX documents that org-mode produces to compile. You can get
-   both of these (plus dvipng) through the Ubuntu package
-   texlive-full, so simply installing the `texlive-full` package may
-   be the easiest option if you happen to be on Ubuntu.
-
-   For Windows users who have installed MikTeX, I had to use the
-   MikTeX package manager to install the following packages for LaTeX
-   support to work: soul, marvosysm, wasysym, wasy, zhmetrics. Install
-   these and you should be good to go.
-
-For inline image support,
-7) libpng, GNU/Linux users probably have this.  I found under Windows
-   that I had to download
-   http://downloads.sourceforge.net/gnuwin32/libpng-1.2.37-setup.exe
-   and after running the installation program, *manually* copy the
-   libpng12.dll and zlib1.dll files into my emacs-23.x\bin directory,
-   and then restart emacs for inline image support to work. One easy
-   way to test if png support is working is to simply open a png file
-   within Emacs from dired.
-  
-* Setting up org-mode for source code evaluation 
-
-Setting up org-mode to run source code is very simple. Since you are
-reading the R tutorial, I will assume you want to specifically run R
-source code blocks within org-mode. Since we use LaTeX later on in 
-the tutorial, we'll also take the opportunity to set up org-mode
-to evaluate LaTeX blocks. 
-
-The absolute, bare minimum setup you need to perform is to run the
-following Emacs lisp code. For a preview of what we're going to learn
-with in this tutorial, simply hit C-c C-c anywhere in the following code
-block! You will be asked in the minibuffer to confirm that you want
-to evaluate the source code contained in the block. Confirm this, and
-you'll be set up for the rest of the tutorial. You can also add the
-lines between the #+begin\_src and #+end\_src lines to your Emacs
-initialization file, so that they are always run when starting Emacs.
-
-So go ahead, hit C-c C-c with point in the following code block. 
-
-#+begin_src emacs-lisp :results silent
-  (org-babel-do-load-languages
-   'org-babel-load-languages
-   '((R . t)
-     (latex . t)))
-#+end_src
-
-If you received any type of error message, please make sure that you
-have the proper version of org-mode installed by typing M-x
-org-version <Enter>. You should have at least 7.01. If you still are
-running org-mode version 6.xx or before, please visit the project web
-site for instructions on downloading the latest version.
-
-If you didn't get any errors, org-mode is now setup to run the R
-examples that follow.
-
-Note to Windows users. Make sure the directory containing the R
-executable is added to your PATH variable for you to run these
-examples.
-
-** Prompting for confirmation before evaluating code 
-There is one more variable I set in my Emacs initialization file
-relating to evaluating source code in org-mode. By default, org-mode
-will ask you to confirm each and every time you evaluate a source code
-block. If you ran the above source code block with C-c C-c, you will
-have noticed that behavior. I turn this feature off with the
-following line. If you choose, simply hit C-c C-c to evaluate it for
-this session, or put it in your Emacs initialization file. Then, you
-won't be asked before org-mode evaluates source code blocks. You may
-view this as a security risk. Always look over the code you're going
-to evaluate before submitting it. 
-
-#+begin_src emacs-lisp :results silent :exports code
-  (setq org-confirm-babel-evaluate nil)
-#+end_src
-
-** Other supported languages
-
-Besides R, which we just set up with the above source code block, see
-[[http://orgmode.org/manual/Languages.html#Languages][here]] for a list of languages that org-mode currently supports. You can
-then add more languages to your personal setup if you desire, by
-modifying the variable we defined above to include more languages.
-
-* Org-mode source code blocks 
-** Exporting pretty-printed source code blocks
-
-Before I show you how to evaluate code in org-mode, let's start off
-with looking at a what a typical org-mode code block looks like. We
-just saw a couple examples above of Emacs lisp source code blocks. In
-what follows, we will be working with very simple R functions to show
-off the capabilities of org-mode.
-
-The following is a simple R code block in org-mode. You can edit the
-code in its own buffer by typing C-c ' (that's a single quote), or
-just by editing the code within the org-mode buffer. The nice thing
-about opening the code in its own buffer with C-c ', is that the
-buffer is then in ESS mode. All the ESS key bindings, interaction
-with the inferior R process, and syntax highlighting work as expected.
-
-So here is an example of a source code block. The defining feature is
-the #+begin\_src and #+end\_src lines, with the language definition,
-"R", on the first line. 
-
-Try opening this code block by putting point anywhere inside of it,
-and hitting C-c ' (that's a single quote). This will open a new
-buffer, with the contents of the source code block. You can then edit
-this buffer just like any other R file, as it is in R-mode from
-ESS. When finished editing, hit C-c ' again, and you'll see any
-changes you made reflected in this org-mode buffer. You can control
-how this new buffer is displayed by setting the org-src-window-setup
-variable in Emacs.
-
-#+begin_src R :exports code
-  square <- function(x) 
-  {
-    x * x
-  }
-    
-  square(1:10)
-#+end_src 
-
-So now we have this code block defined. Why would we want to do
-something like that with org-mode? Mostly so that when we export an
-org-mode document to a more human-readable format, org-mode recognizes
-those lines as syntax, and highlights them appropriately in the HTML
-or LaTeX output. The lines will be syntax highlighted just like they
-would be in an R code buffer in Emacs.
-
-Try this for yourself. With point anywhere in this subtree, for
-example, put it here [ ], hit C-c C-e 1 b (that's the number 'one').
-This subtree should be exported to an HTML file and displayed in your
-web browser. Notice how the source code is syntax highlighted. 
-
-Note: for syntax highlighting in exported HTML to work, htmlize.el
-must be in your load-path. The easiest way to make that happen if you
-haven't already is to run the following Emacs lisp code, *after*
-changing the "/path/to" portion to reflect your local setup. I have
-the following in my Emacs init file. 
-
-#+begin_src emacs-lisp :results silent :exports code
- (add-to-list 'load-path "/path/to/org-mode/contrib/lisp")
-#+end_src
-
-** Evaluating the code block using org-mode
-
-As I mentioned, defining the above code block would be useful if
-we wanted to export the org-mode document and have the R code in the
-resulting, say, HTML file, syntax highlighted. The feature that
-org-mode now adds in version 7.01 is letting us actually submit the
-code block to R to compute results for either display or further
-computation.
-
-It is worth pointing out here that org-mode works with many
-languages, and they can all be intertwined in a single org-mode
-document. So you might get results from submitting an R function, and
-then pass those results to a Python or shell script through an
-org-table. Org-mode then becomes a meta-programming tool. We only
-concentrate on R code here, however.
-
-We did see above in the setup section that we have Emacs lisp code in
-this same org-mode file. To be clear, you can mix many languages in
-the same file, which can be very useful when writing documentation,
-for instance.
-
-Next, let's actually submit some R code.
-
-*** Obtaining the return value of an R code block
-
-We will now see how to submit a code block. Just as in the
-Introduction with Emacs lisp code, simply hit C-c C-c anywhere in the
-code block to submit it to R. If you didn't set the confirmation
-variable to nil as I described above, you'll have to confirm that you
-want to evaluate the following R code. So go ahead, evaluate the
-following R code block with C-c C-c and see what happens. 
-
-#+begin_src R
-  square <- function(x) {
-    x * x
-  }
-  
-  square(1:10)
-#+end_src 
-
-If you've submitted the code block using C-c C-c, and everything went
-well, you should have noticed that your buffer was modified. Org-mode
-has inserted a results section underneath the code block, and above
-this text. These results are from running the R code block, and
-recording the last value. This is just like how R returns the last
-value of a function as its return value. Notice how the results have
-been inserted as an org-table. This can be very useful. However,
-what if we wanted to see the standard R output? You will see how to do
-that in the next section.
-
-You can also try changing the source code block, and re-running it.
-For example, try changing the call to the square function to 1:12,
-then hit C-c C-c again. The results have updated to the new value!
-
-*** Obtaining all code block output 
-
-We just saw how the last value after evaluating our code is put into
-an org-mode table by default. That is potentially very useful, but
-what if we just want to see the R output as it would appear printed in
-the R console? Well, just as R function have arguments, org-mode
-source blocks have arguments. One of the arguments controls how the
-output is displayed, the :results argument. It is set to 'value' by
-default, but we can change it to 'output' to see the usual R
-output. Notice the syntax for setting source code block arguments
-below.
-
-#+begin_src R :results output
-  square <- function(x) {
-    x * x
-  }
-
-  square(1:10)
-#+end_src 
-
-
-Now we see the typical R notation for printing a vector. Note in the
-following example that setting `:results output` captures *all*
-function output, not just the return value. We capture things printed
-to the screen with the `cat` function for example, or the printing of
-the variable `x`.
-
-#+begin_src R :results output
-  x <- 1:10
-  x
-  square <- function(x) {
-    cat("This is the square function.\n")
-    x * x
-  }
-  
-  square(1:10)
-#+end_src 
-
-Try changing the :results argument to `value` (which is the same as
-omitting it completely), and re-run the above code block. You should
-see the same org-table output as we saw above.
-*** More information on org-mode source block headers
-
-See [[http://orgmode.org/manual/Header-arguments.html#Header-arguments]]
-for more information on source code block header arguments, including
-the various ways they can be set in an org-mode document: per block,
-per file, or system-wide.
-
-*** Inline code evaluation 
-Much like the Sweave \Sexpr command, we can evaluate small blocks of
-inline code using the
-
-#+begin_example
-SRC_R[optional header arguments]{R source code} 
-#+end_example
-
-syntax.  So, in org-mode I will type
-
-#+begin_example
-SRC_R[:exports results]{round(pi, 2)}
-#+end_example 
-
-and you will see src_R[:exports results]{round(pi, 2)} in the exported
-output.  You'll see examples of how to use the :exports code block
-header in a few sections. 
-* Passing data between code blocks
-
-One of the biggest limitations to using code blocks like above is that
-a new R session is started up `behind the scenes` when we evaluate
-each code block. So, if we define a function in one code block, and
-want to use it another code block later on, we are out of luck. This
-limitation can be overcome by using R session-based evaluation, which
-sends the R code to a running ESS process.
-
-** R session-based evaluation 
-
-Often in R, we will define functions or objects in one code block
-and want to use these objects in subsequent code blocks. However,
-each time we submit a code block using C-c C-c, org-mode is firing up
-an R session, submitting the code, obtaining the return values, and
-closing down R. So, by default, our R objects aren't persistent!
-That's an important point. Fortunately, there is an easy way to tell
-org-mode to submit our code blocks to a running R process in Emacs,
-just like we do with R files in ESS.
-
-You simply use the :session argument to the org-mode source block.   
-
-#+begin_src R :session :results output
-  square <- function(x) {
-    x * x
-  }
-  x <- 1:10 
-#+end_src 
-
-So, the above code block defines our function (square) and object (x).
-Now we want to apply call our square function with the x
-object. Without :session, we could not do this.
-
-#+begin_src R
-  square(x)
-#+end_src
-
-Running the above code block will result in an error, since a new R
-session was started, and our objects were not available. Now try the
-same code block, but with the :session argument, as below.
-
-#+begin_src R :session :results output
-  square(x)
-#+end_src
-
-The results we expect are now inserted, since we submitted this code
-block to the same R session where the square function was defined.
-
-** Code blocks using different languages
-
-Even though this tutorial covers the R language, one of org-mode's
-main strengths is its ability to act as a meta programming language,
-using results from a program written in one language as input to a
-program in another language.
-
-See
-[[http://orgmode.org/worg/org-contrib/babel/intro.php#meta-programming-language]]
-for an example of this. To keep things as focused on R as possible, I
-chose not to include an example like the one found in the link in this
-tutorial.
-
-* Inserting R graphical output 
-
-Here is a really cool feature of evaluating source code in
-org-mode. We can insert images generated by R code blocks inline in
-our Emacs buffer! To enable this functionality, we need to evaluate a
-bit of Emacs lisp code. If this feature is something you want every
-time you use org-mode, consider placing the code in your Emacs
-initialization file. Either way, evaluate it with C-c C-c.
-
-#+begin_src emacs-lisp :results silent :exports code
-  (add-hook 'org-babel-after-execute-hook 'org-display-inline-images)   
-  (add-hook 'org-mode-hook 'org-display-inline-images)   
-#+end_src
-
-The following R code generates some graphical output. There are
-several things to notice.
-
-1) :results output is specified. This is because the figure is
-   generated using the ggplot2 package in R, which is based on
-   something called `grid` graphics. Grid graphics need to be
-   explicitly printed when called within a function for their output
-   to be displayed. See, for example, [[http://cran.r-project.org/doc/FAQ/R-FAQ.html#Why-do-lattice_002ftrellis-graphics-not-work_003f][R FAQ 7.22]]. When :results value
-   (the default) is active, Org-mode is generating an R function
-   wrapper. The upshot is: when generating grid-based graphical output
-   within org-mode, you need to either use :results output, wrap the
-   graphical function in a print call, or use the :session
-   argument. See this mailing list [[http://www.mail-archive.com/emacs-orgmode@gnu.org/msg25944.html][post]] for more explanation if you'd
-   like.
-
-2) We use a new source code block argument, :file. This argument will
-   capture graphical output from the source block and generate a file
-   with the given name. Then, the results section becomes an org-mode
-   link to the newly created file. In the example below, the file
-   generated is called diamonds.png.
-
-   Finally, If you have defined the Emacs lisp code for inline-image
-   support above, an overlay of the file will be inserted inline in
-   the actual org-mode document! Run the following source code block
-   to see how it works.
-
-#+begin_src R :results output :file diamonds.png
-  library(ggplot2)
-  data(diamonds)
-  dsmall <-diamonds[sample(nrow(diamonds), 100), ] 
-  qplot(carat, price, data = dsmall)
-#+end_src
-  
-This opens up many opportunities for doing interesting things with R
-within your org-mode documents!
-
-* Inserting LaTeX output
-
-We have just seen how to include graphical output in our org-mode
-buffer. We can also do something similar with LaTeX output generated
-by R. Of course, this requires at least a working LaTeX
-installation. You will also need to install the dvipng program (dvipng
-package in Ubuntu, for instance). See the System Requirements section
-for other prerequisites.
-
-** A simple example 
-
-Let's work on a very simple example, displaying a LaTeX description
-in our org-mode buffer, using the official LaTeX logo. We will use R
-to generate the code that will display the official logo. There's
-obviously no reason to do this except for demonstration purposes.
-
-First we must define an R source block that generates some LaTeX code
-that displays the logo. That's fairly straightforward. Notice we have
-given the source code block a name, so that we can call it later. We
-use the #+srcname syntax to do this. Note that you *don't* have to
-run the following code block, it will be run automatically by the next
-one.
-
-#+srcname: R-latex
-#+begin_src R :results silent :exports code
-  lf <- function() {
-      "\\LaTeX"
-  }
-  
-  lf()
-#+end_src
-
-Next, we define a new source block using the "latex" language, instead
-of "R", as we have been using. If we use a :file argument with a LaTeX
-source code block, org-mode will generate a file of the resulting dvi
-file that LaTeX produces, and display it. This is just like
-generating graphical output from R using a :file argument, so there is
-nothing new there.
-
-However, note we have a new argument, :noweb. What does that mean? In
-short, it let's us use syntax like <<CodeBlock()>> to insert the
-results of running a code block named CodeBlock into another source
-code block. So, in our example, we're running the R-latex code block
-defined above, and inserting the results, which need to be valid LaTeX
-code, into our latex code block. For this example, we of course didn't
-need to write an R function to generate such simple LaTeX output, but
-it can be much more complicated, as our next example shows. In short,
-our R code block is helping to write the LaTeX code block for us.
-
-Noweb was not invented for org-mode, it's been around for a while, and
-is used in Sweave, for example. See [[http://en.wikipedia.org/wiki/Noweb][its Wikipedia page]]. The :noweb
-argument is set to 'no' be default, because the <<X>> syntax is
-actually valid in some languages that org-mode supports.
-
-Run the following code block. The "R-latex" R code block will be run,
-generating the string \\LaTeX, which is then substituted into this
-LaTeX code block, and then turned into the LaTeX logo by the latex
-program. Don't worry about the complicated header arguments, those
-will be explained in more detail in the next section. 
-
-#+begin_src latex :noweb yes :file (if (and (boundp 'htmlp) htmlp) "latex-logo-html.png" "latex-logo.png") :buffer (if (and (boundp 'htmlp) htmlp) "no" t)
-<<R-latex()>>~is a high-quality typesetting system; it includes
-features designed for the production of technical and scientific
-documentation. <<R-latex()>>~is the de facto standard for the
-communication and publication of scientific
-documents. <<R-latex()>>~is available as free software.
-#+end_src
-
-** A more complicated example, exporting LaTeX in buffer, to HTML, and to PDF
-
-Now let's try something a little more complex, using an R function
-that generates a full LaTeX table. This particular example depends on
-having the R package Hmisc installed. If you don't have it installed,
-start up R and then do: > install.packages("Hmisc")
-
-What follows is an R source block that generates some LaTeX code
-representing a table.  We want to be able to insert a =png= image of
-the table in the buffer when run with C-c C-c, using the colors of our
-current Emacs buffer.
-
-A few sections from now, I'll touch on the exporting features of
-org-mode.  Org can generate HTML and PDF versions of documents like
-this one. 
-
-Back to our example, for HTML export, we also want to generate a
-=png=. However, we want the background to be transparent, not whatever
-color our Emacs buffer happened to be.
-
-For LaTeX output, we don't need a =png= file at all, we would of
-course prefer to simply insert the auto-generated LaTeX code in the
-exported LaTeX document, and then compile to PDF.
-
-The following should accomplish all three goals.  
-
-We tell the R code block to output latex code using the syntax
-/:results output latex/.  Also, only export the code.  If we export
-both, then the LaTeX results would get exported twice when we export
-to PDF, once from each code block.  It would actually be exported
-twice when we export to HTML, but in that case, since the results are
-wrapped in #+BEGIN\_LATEX/#+END\_LATEX lines, and are therefore not
-included in the HTML export.
-
-In the LaTeX code block, a file will be generated for in-buffer
-evaluation and HTML export, but we don't want it produced for LaTeX
-export, otherwise the image /and/ the actual table will be included in
-the PDF.  
-
-The final /buffer/ argument controls the color selection through the
-=org-format-latex-options= variable. Essentially, if buffer is set to
-'yes', your Emacs buffer colors will be used as arguments to the
-=dvipng= program used to produce the image, assuming you don't change
-that values of the elements to something other than 'default' in
-=org-format-latex-options=. If buffer is 'no', then the html* elements
-of that variable will be used.
-
-#+srcname:Hmisc-latex
-#+begin_src R :results output :exports code
-  set.seed(1) 
-  library(Hmisc)
-    
-  df <- data.frame(age = rnorm(100, 10),
-                   gender = sample(c("Male", "Female"), 100, replace = TRUE),
-                   study.drug = sample(c("Active", "Placebo"), 100, replace = TRUE))
-
-  label(df$study.drug) <- "Treatment" 
-  label(df$age) <- "Age at randomization" 
-  label(df$gender) <- "Gender" 
-    
-  latex(summary(study.drug ~ age + gender, data = df,
-                method = "reverse", overall = TRUE, test = TRUE), 
-        long = TRUE,  file = "", round = 2, exclude1 = FALSE, npct = "both",
-        where="!htbp")
-#+end_src
-
-#+begin_src latex :noweb yes :file (if (and (boundp 'latexp) latexp) nil (if (and (boundp 'htmlp) htmlp) "hmisc-html.png" "hmisc.png")) :buffer (if (and (boundp 'htmlp) htmlp) "no" t)
-<<Hmisc-latex()>>
-#+end_src 
-
-* Putting it all together, a notebook interface to R
-
-Combining the techniques shown above: submitting code blocks,
-capturing output for further manipulation, and inserting graphical and
-tabular material, we essentially have a basic notebook-style
-interface for R.
-
-This is potentially useful for countless tasks such as: a laboratory
-notebook, time series analysis of diet/exercise habits, tracking your
-favorite baseball team over the course of a season, or any reporting
-task you can think of. Since org-mode is a general-purpose authoring
-tool, with very strong exporting capabilities, almost anything is
-possible.
-
-For instance, I use org-mode to generate HTML for an R blog that I
-run. Several posters to the org-mode mailing list have mentioned
-writing their entire graduate theses in org-mode, and even books.
-
-I look at this workflow as an alternative to the excellent [[http://www.stat.uni-muenchen.de/~leisch/Sweave/][Sweave]]
-package that cuts out the need for learning LaTeX to produce
-high-quality documents. Org-mode is doing all the exporting for you,
-including LaTeX if you'd like. Getting LaTeX and HTML output
-essentially "for free" should not be underestimated!
-
-On some level, all these activities assume that you are a comfortable
-org-mode user, and that you will be writing code, conducting analyses,
-and possibly exporting results through the familiar Emacs and org-mode
-user interface. Through the exporting functionality, org-mode offers
-many useful and easy-to-use options to share /results/ of your efforts
-with others, but what about the code itself? 
-
-Most people you have to share code with aren't going to want an
-org-mode file full of source code!
-
-* Tangling code 
-
-With many projects, you will have to share /code/ with other
-programmers, who are most likely not going to be programming in
-org-mode. Therefore, sharing an org-mode file full of code is not an
-option.
-
-Or, consider development of an R package. The package building
-process obviously operates on .R files, each full of R functions.
-However, that's not what we have in a document like this one.
-
-It is in situations like these where /tangling/ can be used. 
-
-The process of tangling an org-mode document essentially extracts the
-code contained in org-mode source code blocks, and places it in a file
-of the appropriate type. How do we do this? We use the :tangle
-source code block header argument to direct org-mode what to do. Then,
-we call the tangle function on the file to extract the source code!
-
-Read on to learn how to perform each of these steps. 
-
-** Instructing org-mode how to tangle with header arguments 
-Let's take a look at a few examples. Each example contains an R
-comment, so that you can see in the resulting .R file where it came
-from.
-
-This first example will not extract any code from the source block.
-It is the default behavior. 
-
-#+begin_src R :tangle no :exports code
-# tangle was not specified
-x <- 1:10
-print(x) 
-#+end_src
-
-
-This will place the code in source code block in
-org-mode-R-tutorial.R, since we don't specify a filename for the .R
-file.
-
-#+begin_src R :tangle yes :exports code
-# tangle was specified, but no file given
-x <- 1:10
-print(x)
-#+end_src
-
-This will place the tangled code in Rcode.R, since we specify that name. 
-
-#+begin_src R :tangle Rcode.R :exports code
-# tangle was specified, and a file name given (Rcode.R)
-x <- 1:10
-print(x)
-#+end_src
-
-Note that we will have multiple source code blocks in an org-mode
-file, and they might have different types. For example, we might have
-R and Python code in the same document, but different source blocks. 
-
-This is no problem, as the tangling mechanism will generate
-appropriate files of each type, containing only the code of that type.
-
-Finally, you can specify the :tangle argument as a buffer-wide
-setting, so that you don't have to specify it for every source code
-block.
-
-This opens up exciting possibilities like having a *single* org-mode
-file that includes:
-- all code for an R package
-- all documentation for the package
-- unit tests for the package
-- material to generate slides for presentations, through org-beamer
-- notes taken during package development 
-- links to emails with bug reports, feature requests, etc. 
-- a Makefile to build the package and documentation
-
-** Tangling the document 
-
-Now that we have seen how to instruct org-mode how to produce source
-code files from our org-mode document, how do we actually tangle the
-document?
-
-We simply have to call the org-babel-tangle function, bound by default
-to C-c C-v C-t. 
-
-Org-mode confirms in the minibuffer how many code blocks have been
-tangled, and inspecting the file system should show that your source
-code files have been created. There exists a hook function that will
-run any post-processing programs you have defined, for example, a
-compiler, `R CMD build`, or running `make` with a Makefile, possibly
-itself generated from the org-mode document!
-
-* Exporting documents containing code and results
-
-Org-mode provides a rich set of functions and customizations for
-exporting documents into more human-readable forms, and for users who
-are not Emacs or org-mode users. The most common methods are
-generating PDF documents through LaTeX, and HTML output. Source code
-will be syntax highlighted, in HTML.  There are various options for
-PDF, including using the listings package.
-
-With org-mode source blocks, you can choose to export the source code,
-the results of evaluating the source code, neither, or both.
-The :exports header argument controls this. See the [[http://orgmode.org/manual/Exporting-code-blocks.html#Exporting-code-blocks][documentation]] for
-further examples. 
-
-As an example, type C-c C-e b to see an HTML version of this document.
-
-Some fairly sophisticated processes, including complete report
-generation using R graphics and tables, can be achieved through this
-facility.
-
-Using org-mode in this manner is essentially an alternative to Sweave,
-with the advantages of:
-- do not need to learn LaTeX or other markup language
-- any future org-mode export engines will be available to you
-- writing code in org-mode gives you access to a hyper-commenting
-  system, with features such as TODO items, in-document linking, tags, 
-  and code folding.
-
-If you're an advanced LaTeX user, you probably don't view point 1
-above as an advantage. :) 
-
-Whether or not you use all the features that org-mode provides, you
-can use the system for literate programming and reproducible research,
-on projects large and small.
-
-* Where to go from here? 
-
-We have seen how to submit R code for evaluation in org-mode. There
-are many good reasons to do this, including tying results to source
-code, code folding, exporting of code and results into many common
-formats, improving documentation, and the innumerable features that
-org-mode provides, and will continue to provide in the future. 
-
-As with all new processes, it can be a challenge to start working with
-source code this way. As a current org-mode user, I think the
-benefits are clear.
-
-As for what to do next, try looking at the [[http://orgmode.org/worg/org-contrib/babel/uses.php][results]] of some of those
-who use org-mode with org-babel to accomplish interesting things. You
-can look at current documentation for R support [[http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-R.php][here]].
-
-For an exercise in using org-mode with source code, you can write your
-Emacs initialization file in org-mode! These [[http://orgmode.org/worg/org-contrib/babel/intro.php#sec-8_2_1][instructions]] are slightly
-out of date, but they give you a general idea of how to proceed.
-Essentially, your master Emacs init file will simply tangle an
-org-mode file full Emacs lisp code blocks, and then load the resulting
-file. My Emacs init file is around 1000 lines long, so organizing it
-in a hierarchy with embedded tags and links is very useful to me.
-
-In short, there are many possibilities using these techniques! In many
-ways, I have only scratched the surface of the capabilities of
-org-mode in this tutorial. As always, the [[http://orgmode.org/manual/index.html#Top][official manual]] will be the
-source of the most up-to-date information and features of this great
-tool.