doc/languages-frameworks/r.section.md

   1 # R {#r}
   2
   3 ## Installation {#installation}
   4
   5 Define an environment for R that contains all the libraries that you'd like to
   6 use by adding the following snippet to your $HOME/.config/nixpkgs/config.nix file:
   7
   8 ```nix
   9 {
  10     packageOverrides = super: let self = super.pkgs; in
  11     {
  12
  13         rEnv = super.rWrapper.override {
  14             packages = with self.rPackages; [
  15                 devtools
  16                 ggplot2
  17                 reshape2
  18                 yaml
  19                 optparse
  20                 ];
  21         };
  22     };
  23 }
  24 ```
  25
  26 Then you can use `nix-env -f "<nixpkgs>" -iA rEnv` to install it into your user
  27 profile. The set of available libraries can be discovered by running the
  28 command `nix-env -f "<nixpkgs>" -qaP -A rPackages`. The first column from that
  29 output is the name that has to be passed to rWrapper in the code snipped above.
  30
  31 However, if you'd like to add a file to your project source to make the
  32 environment available for other contributors, you can create a `default.nix`
  33 file like so:
  34
  35 ```nix
  36 with import <nixpkgs> {};
  37 {
  38   myProject = stdenv.mkDerivation {
  39     name = "myProject";
  40     version = "1";
  41     src = if lib.inNixShell then null else nix;
  42
  43     buildInputs = with rPackages; [
  44       R
  45       ggplot2
  46       knitr
  47     ];
  48   };
  49 }
  50 ```
  51 and then run `nix-shell .` to be dropped into a shell with those packages
  52 available.
  53
  54 ## RStudio {#rstudio}
  55
  56 RStudio uses a standard set of packages and ignores any custom R
  57 environments or installed packages you may have.  To create a custom
  58 environment, see `rstudioWrapper`, which functions similarly to
  59 `rWrapper`:
  60
  61 ```nix
  62 {
  63     packageOverrides = super: let self = super.pkgs; in
  64     {
  65
  66         rstudioEnv = super.rstudioWrapper.override {
  67             packages = with self.rPackages; [
  68                 dplyr
  69                 ggplot2
  70                 reshape2
  71                 ];
  72         };
  73     };
  74 }
  75 ```
  76
  77 Then like above, `nix-env -f "<nixpkgs>" -iA rstudioEnv` will install
  78 this into your user profile.
  79
  80 Alternatively, you can create a self-contained `shell.nix` without the need to
  81 modify any configuration files:
  82
  83 ```nix
  84 { pkgs ? import <nixpkgs> {}
  85 }:
  86
  87 pkgs.rstudioWrapper.override {
  88   packages = with pkgs.rPackages; [ dplyr ggplot2 reshape2 ];
  89 }
  90
  91 ```
  92
  93 Executing `nix-shell` will then drop you into an environment equivalent to the
  94 one above. If you need additional packages just add them to the list and
  95 re-enter the shell.
  96
  97 ## Updating the package set {#updating-the-package-set}
  98
  99 There is a script and associated environment for regenerating the package
 100 sets and synchronising the rPackages tree to the current CRAN and matching
 101 BIOC release. These scripts are found in the `pkgs/development/r-modules`
 102 directory and executed as follows:
 103
 104 ```bash
 105 nix-shell generate-shell.nix
 106
 107 Rscript generate-r-packages.R cran  > cran-packages.json.new
 108 mv cran-packages.json.new cran-packages.json
 109
 110 Rscript generate-r-packages.R bioc  > bioc-packages.json.new
 111 mv bioc-packages.json.new bioc-packages.json
 112
 113 Rscript generate-r-packages.R bioc-annotation > bioc-annotation-packages.json.new
 114 mv bioc-annotation-packages.json.new bioc-annotation-packages.json
 115
 116 Rscript generate-r-packages.R bioc-experiment > bioc-experiment-packages.json.new
 117 mv bioc-experiment-packages.json.new bioc-experiment-packages.json
 118 ```
 119
 120 `generate-r-packages.R <repo>` reads  `<repo>-packages.json`, therefore
 121 the renaming.
 122
 123 The contents of a generated `*-packages.json` file will be used to
 124 create a package derivation for each R package listed in the file.
 125
 126 Some packages require overrides to specify external dependencies or other
 127 patches and special requirements. These overrides are specified in the
 128 `pkgs/development/r-modules/default.nix` file. As the `*-packages.json`
 129 contents are automatically generated it should not be edited and broken
 130 builds should be addressed using overrides.