[bug#61701] [PATCH] doc: Propose new cookbook section for reproducible research.

[Ludovic Courtès]

Hi Kyle,

kyle <kyle@posteo.net> skribis:

> From: Kyle Andrews <kyle@posteo.net>
>
> The intent was to cover the most common cases where R and python using
> researchers could rapidly achieve the benefits of reproducibility.

That’s a great idea!

Overall it looks nice to me.  I would suggest reducing the scope a
little bit by taking inferiors and the Python 3.6 bit out—these things
could be discussed in a separate section.

Inline comments follow:

> +@node Reproducible Research in Practice
> +@section Common scientific software environments

I’d use the same title for both.

> +Many researchers write applied scientific software supported by a

Maybe s/researchers/scientists/ to be more inclusive (that would include
research software engineers, for instance; I’m one of them, hence that
comment. ;-))

> +mixture of more generic tools developed by teams written within the R
> +and Python ecosystems and supporting shell utilities. Even researchers

s/written within … utilities./written in R, Python, and shell./

> +who predominantly stick to using just R or just python often have to use
> +both R and python at the same time when collaborating with others.  This

Make sure to always capitalize “Python” (and similarly for other proper
names).

> +@example
> +(use-modules
> + (gnu packages cran)
> + (gnu packages statistics))
> +
> +(packages->manifest
> + (list r r-tidyverse))
> +

There’s a missing @end here.

For Scheme code, please use @lisp … @end lisp instead.  That enable
syntax highlighting.

> +R packages are defined predominantly inside of gnu/packages/cran.scm and
> +gnu/packages/statistics.scm files under a guix source repository.

Please use @file for file names…

> +This manifest can be run with the basic guix shell command:

… and @command{guix shell} here.

> +@example
> +guix shell --manifest=manifest.scm --container
> +@end example
> +
> +Please remember at the end to pin your channels so that others in the
> +future know how to recover your exact Guix environment.
> +
> +@example
> +guix describe --format=channels > channels.scm
> +@end example
> +
> +This can be done with Guix time machine:
> +
> +@example
> +guix time-machine --channels=channels.scm \
> +  -- guix shell --manifest=manifest.scm --container
> +@end example

Remove ‘guix’ after the double dash.

Here I’d recommend including cross-references to the relevant sections
of the manual: “Writing Manifests” and “Replicating Guix”.

> +If reproducibility becomes an end in itself and not a catlyst towards
> +faster discovery, then Guix will be a non-starter for scientists. Their
> +goal is to develop useful understanding about particular aspects of the
> +world.

I don’t fully understand this paragraph.  I tend to think that 

> +Thankfully, three common scenarios cover the vast majority of
> +needs. These are:
>
> +@itemize
> +@item
> +combining standard package definitions with custom package definitions
> +@item
> +combining package definitions from the current revision with other revisions
> +@item
> +combining package variants which need a modified build-system
> +@end itemize

Like Simon, I’d suggest leaving out the second part (inferiors), and also
avoiding the Python 3.6 example, both of which make things immediately
more complicated.

We can keep the rest of the example though, if possible.

WDYT?

Thanks for your work!

Ludo’.