[Rd] literate programming

[Kevin R. Coombes]

Hi Terry,

You can do this with Sweave (and something smart like emacs with ESS 
installed as your editor), but you have to work at it a little. The key 
is the fact that a couple of releases ago they added options for 
"keep.source" and "expand". For example, you do the following:

First, describe the various steps in the algorithm. (Unless you are 
defining functions to use later, you probably do not want to evaluate 
these.)

<<extractParameters,eval=FALSE>>=
# code here to get the parameters
@

<<selectTrainingSet,eval=FALSE>>=
# code here to split data into training and test sets
@

<<trainModel,eval=FALSE>>=
# code here to fit a model to training data
@

<<testModel,eval=FALSE>>=
# code here to see how well the model works
@

Then  you can put the pieces together, doing something like

<<runSplits,keep.source=TRUE,expand=FALSE>>=
for (i in 1:numberOfSplits) {
<<extractParameters>>
<<selectTrainingSet>>
<<trainModel>>
<<testModel>>
}
@

The "expand=FALSE" makes sure that the final report does not re-expand 
the lines of code in the displayed output, which allows you to focus on 
the structure of the algorithm.

There are still two weaknesses compared to Knuth's original idea:
[1] You cannot describe the overall algorithm first but wait until later 
to define the pieces. (Actually, I could be wrong about this; it just 
occurred to me that you might be able to manage this with yet another 
clever use of "eval=FALSE", but I haven't tried that.)

[2] The names that you assign to the code chunks do not appear in the 
report automatically, so you have to write text in front of them to make 
them show up. Without these, the references in the final piece do not 
necessarily make sense to the reader trying to follow the action.

Best,
	Kevin



Terry Therneau wrote:
> I'm working on the next iteration of coxme.  (Rather slowly during the summer).
>   
>   This is the most subtle code I've done in S, both mathematically and 
> technically, and seems a perfect vehicle for the "literate programming" paradym 
> of Knuth.  The Sweave project is pointed at S output however, not source code.  
> I would appreciate any pointers to an noweb type client that was R-aware.
>   
>   Other suggestions are welcome as well.  At the end of the day I'd like to have 
> a good user guide, technical reference, and solid enough code documentation that 
> others can begin to participate as well.  (Retirement in 10 years -- I don't 
> expect to maintain this forever!)
>   
>   	Terry Therneau
>   	therneau.terry at mayo.edu
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel