From carey.vj at gmail.com  Thu Jun 17 23:01:30 2010
From: carey.vj at gmail.com (Vincenzo Carey)
Date: Thu, 17 Jun 2010 17:01:30 -0400
Subject: [Rd] Package development process?
In-Reply-To: <AANLkTimzwzW_k58juurZ11GszYxsnV_fW32prr9K4oHa@mail.gmail.com>
References: <4C182C9E.2080604@structuremonitoring.com>
	<AANLkTinvljHoZC-XA5UgJkMoSmft9z9SjsUPwt_9W2F6@mail.gmail.com>
	<4C18E297.7020805@structuremonitoring.com>
	<AANLkTimtGcfzKshfvQsRBNGAqfxfiZkrabf0loOVtc1V@mail.gmail.com>
	<4C19E971.7000807@pburns.seanet.com>
	<AANLkTimzwzW_k58juurZ11GszYxsnV_fW32prr9K4oHa@mail.gmail.com>
Message-ID: <AANLkTilEVr2gPM4gKBp5pkYDISnAI9OwvAnjar1-HYdN@mail.gmail.com>

On Thu, Jun 17, 2010 at 7:45 AM, Dominick Samperi <djsamperi at gmail.com> wrote:
>
> On Thu, Jun 17, 2010 at 5:22 AM, Patrick Burns <pburns at pburns.seanet.com>wrote:
>
> > I agree with Hadley, and add that trying
> > to have an example be both an example and
> > a test may not be good for the example
> > aspect either.
> >
> > Examples should make people who are ignorant
> > of the function twig as to how the function
> > works. ?Creating good examples is hard.
> >
> > Problems that really test the software are
> > unlikely to serve as a good example. ?Good
> > examples are unlikely to seriously test the
> > code. ?(But you do want the examples to run,
> > it is seriously bad advertising when they
> > don't.)
> >
> > Pat
>
>
> Creating good examples is hard, but so is creating a research
> compendium following the ideas of Reproducible Research of
> Donoho and others at Stanford, called Literate Statistical
> Practice in the statistical community. The tools are there in
> R for this purpose (vignettes, etc.) but they seem to be rarely
> used for this purpose.
>

"Rare" is vague.? Almost every software package in the Bioconductor
repository has a vignette; the informal advice to contributors is that
the vignette should take the reader through all the steps of a
substantively interesting analysis with motivating/explanatory prose
and executable code.? Many analysis processes rely on effective
interoperability with independently maintained packages; thus the
nightly building of all vignettes in Bioconductor serves to not only
to provide some evidence of package soundness but also some degree of
notification of decays of interoperability.? The main Bioconductor
monograph, and the case studies book are both executable documents,
written with Sweave.? I would imagine that a number of other UseR
titles were composed in this way.

A recent NSF workshop addressed frameworks for creating replayable
experiments in various fields:
https://www.protogeni.net/trac/archive10/

>
> One reason examples are hard is that they are often isolated
> from the research itself, and hard to understand out of context.
> The notion of a Research Compendium that includes this
> context might help.
>
> But this requires a fair amount of work, and I don't think it is
> currently rewarded in the publication process (Journals do not
> require it).
>
> The creation of a research compendium can be viewed as
> a form of unit testing, and the fact that R has powerful tools
> that support this process (Sweave) could be viewed as one of
> its outstanding features (relating these comments back to
> the topic of this thread).
>
> A list of references on Reproducible Research and LSP
> can be found in the package cxxPack. A template for creating
> a compendium can also be found there.
>
> Dominick
>
> ? ? ? ?[[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel



[Rd] Package development process?
Vincenzo Carey