[R] summary: Sweave - documenting a long function

[John.Gavin@ubsw.com]

Hi,

Here is a summary of the replies to my question yesterday
about documenting a long function with Sweave.
My thanks to those who replied.

Friedrich Leisch suggested a work around
which was copied to the mailing list 
so I wont repeat it here. This worked well.
(I made a minor addition by adding braces
around each chunk of code to make the
output in the pdf file look a bit prettier.
This seems to work without any side effects.)

Frank Harrell suggested implementations of 
'pretty printing' for Sweave.
Again, this was copied to the list, so I wont repeat it.

Peter Wolf pointed me to noweb without Sweave
http://www.eecs.harvard.edu/~nr/noweb/intro.html
(see below for more).

Regards,

John.

John Gavin <john.gavin at ubsw.com>,
Quantitative Risk Models and Statistics,
UBS Warburg, 100 Liverpool Street (6th floor),
London EC2M 2RH, UK.
Phone +44 (0) 207 567 4289
Fax   +44 (0) 207 568 5352


> -----Original Message-----
> From: Peter Wolf [mailto:pwolf at wiwi.uni-bielefeld.de]
> ... 
> For documentation your functions the best way may be to use noweb
> without Sweave.
> 
> See: http://www.eecs.harvard.edu/~nr/noweb/intro.html
> 
> noweb allows you to process a file like:
> 
> ------------ begin of file ----------------------------
> First, define the funciton header
> <<define function x>>=
> x <- function(a =1){
> <<step1: assignment of a>>
> <<step2: some operations>>
>  }
> 
> @
> Explain the code in the first part of the function
> <<step1: assignment of a>>=
> a <- a+1
> 
> @
> Explain the code in the second part of the function
> <<step2: some operations>>=
>  a <- a^2
> aa<- a + a
> 
> @
> Return the result.
> <<return result>>=
> return(aa)
> 
> @
> Finally, we show an example of the function
> <<example using x>>=
> x(3)
> 
> @
> That's it.
> ------------ end of file -----------------------
> 
> This file has to be processed by TANGLE and WEAVE.
> The output of the tangle process can be sourced into R.
> The output of the weave process can be processed e.g. by latex.

My original email reads

-----Original Message-----
From: Gavin, John 
Sent: 04 November 2002 20:26

Hi,

I would like to use Sweave to document a long function.
Is it possible to split the function's code into chunks
such that Sweave will accept each chunk without complaining.

I have tried various approaches without sucess
but I feel sure that someone has done this already.
Here is one attempt

==============
% First, define the funciton header
<<defFunHdr, eval=FALSE>>=
x <- function(a =1)
@

% Explain the code in the first part of the function
<<defFunBodyPt1, eval=FALSE>>=
{ a <- a+1
@

% Explain the code in the second part of the function
<<defFunBodyPt2, eval=FALSE>>=
 a <- a^2
 a
 } # end of function
@

% now bring the chunks together so that Sweave evaluates the function.
<<evalFun, echo=FALSE>>=
<<defFunHdr>>
<<defFunBodyPt1>>
<<defFunBodyPt2>>
@

% Finally, show an example of the function
<<exampleFun>>=
x(3)
@
===========

eval=FALSE doesnt seem to prevent the code being evaluated,
as I get an error with the first chunk.

(label=defFunHdr)
Error in parse(file, n, text, prompt) : parse error
Execution halted

The output from Stangle seems ok
i.e. I can execute it without error.

I am on R 1.6.0, on Windows NT4.

Visit our website at http://www.ubswarburg.com

This message contains confidential information and is intended only 
for the individual named.  If you are not the named addressee you 
should not disseminate, distribute or copy this e-mail.  Please 
notify the sender immediately by e-mail if you have received this 
e-mail by mistake and delete this e-mail from your system.

E-mail transmission cannot be guaranteed to be secure or error-free 
as information could be intercepted, corrupted, lost, destroyed, 
arrive late or incomplete, or contain viruses.  The sender therefore 
does not accept liability for any errors or omissions in the contents 
of this message which arise as a result of e-mail transmission.  If 
verification is required please request a hard-copy version.  This 
message is provided for informational purposes and should not be 
construed as a solicitation or offer to buy or sell any securities or 
related financial instruments.


-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._