Nvim-R-Tmux: Neovim-based IDE for R

Author: Thomas Girke
Last update: 16-Mar-2022
Note: this repos replaces old Nvim-R-Tmux Tutorial on Gist.

Table of Content

Overview
Installation
Usage and configuration
Config files
Advanced topics
Useful links

1. Overview

This page gives an overview of the installation and usage of the new Nvim-R plugin from Jakson Alves de Aquino, the developer of the original vim-R plugin. The new plugin now also supports the new extension of Vim called Neovim. The main advantages of Neovim compared to Vim are its better performance and its built-in terminal emulator facilitating the communication among Neovim and interactive programming environments such as R. Since the Vim and Neovim environments are managed independently, one can run them in parallel on the same system without interfering with each other. The Nvim-R project page can be found here and its main manual is here. The usage section below introduces how to use the plugin with or without Tmux.

Animated Screenshot of Nvim-R (from here):

2. Installation

2.1 Quick install of Nvim-R-Tmux

The following provides a quick convenience install for configuring the Nvim-R-Tmux environment in a user's home directory. This assumes that recent versions of Neovim and optionally Tmux are already pre-installed on a user's system. If this is not the case, then steps 2.2 (or 5.2) and 2.3 (or 5.3) need to be completed first.

Note, executing the Install_Nvim-R_Tmux.sh script as shown below will activate custom config files/directories in a user's home directory, including: .bashrc, .tmux.conf, .Rprofile, .config/ and .local/. Prior to executing Install_Nvim-R_Tmux.sh, users want to make sure that they want these changes performed in their home account. Instructions how to undo these changes, in case something goes wrong, are printed to the screen. An alternative is to install the individual components stepwise by executing the lines in Install_Nvim-R_Tmux.sh individually, or to proceed with the manual configuration outlined in the subsequent sections.

Clone repos to your home directory

git clone git@github.com:tgirke/Nvim-R_Tmux.git

Install Nvim-R_Tmux environment

This installs the entire Nvim-R_Tmux environment into a users home account.

cd Nvim-R_Tmux
bash Install_Nvim-R_Tmux.sh

2.2. Install Neovim for your OS

Neovim Version >= 0.1.7 is required for Nvim-R. For the installation, follow the instructions here. A sample config file for controlling Neovim, called init.vim, is given below. This or a similar init.vim file should be downloaded and saved to a user's home under ~/.config/nvim/init.vim.

Advanced: for more advanced users it may often become important to install the latest Neovim version. For this it can be very useful to download Neovim from its GitHub repos, and then install it from source following these instructions. Using a package management software available on a user's system may be more convenient, but this will often only allow the installation of older Neovim versions. More detailed instructions for installing Neovim from source are given below.

2.3. Install Tmux

The usage of Tmux with Nvim-R is highly recommended on Linux or OS X systems but not absolutely necessary. Supported Tmux versions are >=2.0. To upgrade Tmux to a more recent version, one can follow the instructions here. To install it from source, consult see intructions below here. If you get on Ubuntu 16.04 a locale-gen en_US.UTF-8 error, then the last step here fixes it. A sample config file for controlling Tmux, called .tmux.conf, is given below. This or a similar .tmux.conf file should be downloaded and saved to a user's home under ~/.tmux.conf.

2.4. Install R package `colorout`

The R package colorout is available on GitHub here. If it is not yet installed in an R environment, one can install it from within R via the devtools package as follows:

devtools::install_github("jalvesaq/colorout")

2.5. Install Nvim-R plugin for Neovim

2.5.1 Manual install

Download the latest *.vmb from here. Then open the downloaded file with nvim (neovim), and then run from nvim's command mode the following commands:

:packadd vimball
:so %
# press space bar a few times until install is complete!

2.5.2 Install with plugin manager

When new features become available in Nvim-R then one can get them immediately by installing the Nvim-R plugin from its GitHub repos directly. After downloading the repos, one can move its content (files and directories) manually to ~/.config/nvim or install it with a Neovim plugin manager that includes GitHub support. The following uses vim-plug as plugin manager. After installing vim-plug for neovim as outlined here one can install plugins by listing them at the end of the ~/.config/nvim/init.vim file as follows:

" Plugins will be downloaded under the specified directory.
call plug#begin(has('nvim') ? stdpath('data') . '/plugged' : '~/.vim/plugged')                               
" Declare the list of plugins.                               
Plug 'jalvesaq/Nvim-R'                    
Plug 'preservim/nerdtree'
Plug 'jalvesaq/vimcmdline'
Plug 'nvim-treesitter/nvim-treesitter'
Plug 'lukas-reineke/indent-blankline.nvim'
" List ends here. Plugins become visible to Vim after this call.                          
call plug#end()

After this, the vim commands :PlugInstall, :PlugUpdate and :PlugClean will install, update and remove plugins accordingly. Note, when using vim-plug, the init.vim config file remains under .config/nvim and the plugins will be installed under ~/.local/share/nvim/plugged/.

The version information for the Nvim-R plugin can be returned from vim's command mode as follows.

:help nvim-r

2.6. Install NERDTree (optional)

Download the NERDTree vim plugin from here. Then extract to ~/.config/nvim with the following command. Note, if vim-plug is used as outlined here then Nerdtree will be installed automatically.

unzip NERD_tree.zip -d ~/.config/nvim

2.7. Color Scheme (optional)

Jakson Alves de Aquino has developed the southernlights color scheme that works well with Nvim-R. To enable it, users want to save the file southernlights.vim from this repos to ~/.config/nvim/colors/ and add the recommended bash configurations to your .bashrc as described here. Note, this color scheme should be installed under ~/.config/nvim/colors/ even if a plugin manager is used that installs other plugins under ~/.local/share/nvim/plugged/.

2.8. Indentation guides

Vertical indentation lines (guides) are useful for tracking context in code. To enable indentation lines in nvim, one can use the indent-blankline.nvim plugin. When using it the nvim-treesitter plugin should also be installed. Both are included in the vim-plug install example above (see 2.5.2). When nvim is configured with an init.vim file instead of init.lua, it is important to enclose lua parameter code (e.g. for indentation guides here) in init.vim with the start/end tags given below. For details on init.vim and init.lua, see here. Note, when the plugin is installed, then the indentation guides show by default. To toggle them on/off, use :IndentBlanklineToggle or additional commands of this plugin starting with Indent....

lua <<EOF
---lua lines
EOF

2.9. Setup in user accounts of UCR's HPCC

Neovim and Tmux are already installed systemwide on the HPCC, but need to be loaded from the module system (step 1). What remains to be installed in each user's account are the plugins and configuration files as outlined below under steps 2-5. Alternatively, all required resources will be installed automatically by executing the command Install_Nvim-R_Tmux (old version was install_nvimRtmux) in a user's HPCC account.

Add to your .bashrc the following lines

if [ -n "$MODULESHOME" ]; then
    module load neovim/0.6.0
    module load tmux/3.3
fi

Install Nvim-R plugin for Neovim as instructed here
Save this init.vim sample file to ~/.config/nvim/init.vim
Install NERDTree plugin as instructed here
Install southernlights color scheme as instructed here
Now log out of the system and in again. After this start tmux and then open a .R or .Rmd file with nvim command. Next open a connected R session with the key combination \rf and then follow the usage instructions given here.

3. Usage and configuration

The usage of Neovim is almost identical to Vim. Two important differences are:

The command for opening Neovim is nvim instead of vim.
Plugins are usually stored under ~/.config/nvim/ and the counter part of the .vimrc config file is init.vim located at ~/.config/nvim/init.vim.

3.1. Run R in built-in terminal emulator (preferred solution)

Open a *.R or *.Rmd file with nvim and intialize a connected R session with \rf. This command can be remapped to other key combinations, e.g. uncommenting lines 10-12 in init.vim will remap it to the F2 key. Note, the resulting split window among Nvim and R behaves like a split viewport in nvim or vim meaning the usage of Ctrl-w w followed by i and Esc is important for navigation.

Important keybindings for nvim (vim):

\rf: opens vim-connected R session (R version toggle is outlined below)
spacebar: sends code from vim to R; here remapped in init.vim from default \l
:split or :vsplit: splits viewport (similar to pane split in tmux)
gz: maximizes size of viewport in normal mode (similar to Tmux's Ctrl-a z zoom utility)
Ctrl-w w: jumps cursor to R viewport and back; toggle between insert (i) and command (Esc) mode is required for navigation and controlling the environment.
Ctrl-w r: swaps viewports
Ctrl-w =: resizes splits to equal size
Ctrl-w 5< or 5>: resizes splits to left or right by 5 steps; change number as needed
Ctrl-w H or Ctrl-w K: toggles between horizontal/vertical splits
Ctrl-spacebar: omni completion for R objects/functions when nvim is in insert mode. Note, this has been remapped in init.vim from difficult to type default Ctrl-x Ctrl-o.
:h nvim-R: opens nvim-R's user manual; navigation works the same as for any Vim/Nvim help document
:Rhelp fct_name: opens help for a function from nvim's command mode with text completion support
Ctrl-s and Ctrl-x: freezes/unfreezes vim (some systems)

3.2. Run R in Tmux pane (historical solution)

To run R in a separate Tmux pane, include the following two lines in your init.vim. Note: with Neovim's built-in terminal emulator this option is not so important anymore, since Neovim's vim-r split is more robust and feature-rich. To incorporate the features of a terminal multiplexer like Tmux, one simply runs the environment within a Tmux session, where the vim-r splits are handled by Neovim rather than Tmux. Yet, running R in a sparate Tmux pane is still possible as outlined below.

- `let R_in_buffer=0`
- `let R_tmux_split=1`

Open a *.R or *.Rmd file with nvim and start R with \rf. Similarly as above, the \rf command can be remapped to other key combinations, e.g. uncommenting three lines containing F2 in init.vim will remap it to the F2 key. To navigate among the Nvim and R panes, the key combination Ctrl-w-o is important.

Important keybindings for Tmux panes:

Ctrl-a o: jumps cursor to next pane e.g. from Nvim to R console pane
Ctrl-a Ctrl-o: swaps panes
Ctrl-a z: maximizes (zooms into) active pane
Ctrl-a d: detaches from current session
tmux a: attaches to tmux session
tmux attach -t <id>: attaches to specific tmux session

Note, closing R in this setup will also close the corresponding Tmux pane. This is different from the behavior of the older vim-R plugin where the R pane stayed open and returned a shell after quitting R. This behavior can be useful to open a different R version or ssh into remote systems while maintaining the connected Nvim pane from where code can still be sent to the original pane. To achieve a similar behavior with the new Nvim-R plugin, one can use the following workaround:

Switch cursor scope to R esssion (with Ctrl-a o) and then execute from R pane system("tmux set remain-on-exit on")
Quit R with q(). This gives a dead pane that can be reactivated by starting a shell in it with the commands Ctrl-a and :respawn-pane bash

3.3. Basic NERDTree usage

Important key bindings for NERDTree usage:

zz or :NERDTreeToggle: opens NERDTree ('zz' requires corresponding setting in .config/nvim/init.vim)
:NERDTreeFind: finds current file in tree
?: opens NERDTree help
I (shift i): toggle between showing and hiding hidden files/directories
q: closes NERDTree
Ctrl-w-w: jump cursor to next viewport including the one for NERDTree
o or <enter>: opens selected file
t: opens file in new tab
gt and gT: switches between tabs
i: opens file with horizontal split
s: opens file in vertical split
m: opens menu mode for creating/deleting files, Ctrl-c exits out of this mode
B: shows bookmarks
:Bookmark <name>: creates bookmark for selected tree branch
D: deletes selected bookmark

4. Config files

The following config files (or similar custom versions) should be saved to the following locations in a user's home directory:

File init.vim for Neovim: ~/.config/nvim/init.vim
File tmux.conf for Tmux: ~/.tmux.conf

5. Advanced topics

This section is only relevant for advanced users who require a high level of customization, e.g. for R package development.

5.1. R version toggle

Different R versions installed on a system can be loaded via specific keybinding in Nvim-R. The example below loads one of two R versions (e.g. R-release or R-development) with the keybindings \r1 or \r2, respectively. With a Tmux pane split both R versions can be loaded in a single terminal window simultaneously.

Screenshot of two different R versions loaded in one terminal window:

Note, the R version keybinding toggle was added by Jakson Alves de Aquino in April-2020. To obtain this feature, one needs to first download an Nvim-R version from Github (here) from April-2020 or later, and then move it to ~/.config/nvim, or use a Neovim plugin manager with GitHub support. Subsequently, the following lines need to be added to the ~/.config/nvim/init.vim file where \r1 and \r2 can be customized as needed, and the associated paths need to point to the corresponding R load bash scripts installed on a system. Currently, the latter need to be named explicitly 'R' to work with Nvim-R. To allow calling specific R versions from the command-line (outside of Nvim), one can use an alias in ~/.bashrc. For instance, include the following alias setting to open R's development version by typing R-dev on the command-line: alias R-dev='/usr/local/lib/R-devel/bin/R'. Optionally, one can also provide a custom path for packages installed in a user's home directory like this: alias R-dev='R_LIBS_USER=R_LIBS_USER=~/R/%p-library/%v_<my_subdir> /usr/local/lib/R-devel/bin/R'. The latter can be important for managing several Bioconductor versions that use the same R version (see here for additional details).

Lines to include in init.vim:

function StartRFromPath(path)
    let g:R_path = a:path
    let $R_LIBS_USER='~/R/%p-library/%v' " default path for packages installed in a user's home directory
    call StartR("R")
endfunction

nmap \r1 :call StartRFromPath('/usr/bin')<CR>
nmap \r2 :call StartRFromPath('/usr/local/lib/R-devel/bin/')<CR>

To manage several Bioconductor versions for the same R version, one can define two or more R start up functions, e.g. one for release (StartRFromPath) and one for development (StartRdevFromPath), where R_LIBS_USER is assigned the corresponding path for packages installed in a user's home directory, e.g. ~/R/%p-library/%v_Bioc3.14 for development version.

Note, one can also load specific R versions manually by enabling one of the following two lines. The first one is enabled here in combination with the above R version toggle to allow loading of the default R version with Nvim-R's default keybinding \rf if that version's load script is located in /usr/bin/.

let R_path = '/usr/bin/' "to load default R (here release)
"let R_path = '/usr/local/lib/R-devel/bin/' "to load R-development

5.2. Install Neovim from source

General instructions for installing Neovim from source are available here. The corresponding prerequisites for the install are outlined here.

The following provides additional details that were required for installing the latest Neovim on Debian/Stretch, Debian/Buster and Ubuntu/18.04 systems (here nvim v0.5.0). Installs on other Linux systems will be similar, but the required dependency packages added in the first step may differ. The best way to find out is to install according to the official instruction guidelines here, and then address the depencies according to possible warning and/or error messages occuring during the install.

1. Install dependencies

sudo apt install cmake clang libtool libtool-bin libboost-all-dev gettext

2. Download latest Neovim from GitHub

git clone https://github.com/neovim/neovim.git

3. Build Neovim from source (paths below install into ~/bin)

cd neovim
rm -r build/ # clear the CMake cache if 'build' is present from previous install                                  
make CMAKE_EXTRA_FLAGS="-DCMAKE_INSTALL_PREFIX=$HOME/bin/neovim"                                                
make install

4. Include these lines in your .bashrc to load custom built Neovim with vim or nvim

export PATH="$HOME/bin/neovim/bin:$PATH"
alias vim=nvim

5. Now open Neovim and check from command mode its version

:version # type from command mode
NVIM v0.5.0-427-g1f56f9a4b # first returned line from 9-Apr-2020 install

5.3. Install tmux from source

Use the following steps to build and install tmux from source on Debian and/or Ubuntu. These instructions are derived from here.

cd ~/bin # optional step to manage custom installs under ~/bin
VERSION=3.3-rc # select tmux version to install from here: https://github.com/tmux/tmux/releases
sudo apt-get -y remove tmux
sudo apt-get -y install wget tar libevent-dev libncurses-dev
wget https://github.com/tmux/tmux/releases/download/${VERSION}/tmux-${VERSION}.tar.gz
tar xf tmux-${VERSION}.tar.gz
rm -f tmux-${VERSION}.tar.gz
cd tmux-${VERSION}
./configure
make
sudo make install
cd -
sudo rm -rf /usr/local/src/tmux-*
sudo mv tmux-${VERSION} /usr/local/src

5.4. Install pre-built R versions

Current and historical versions of R can be downloaded for all common operating systems from CRAN here. Install instructions via binaries and OS specific package managers are given in the corresponding OS specific subdirectories of the same page. This is usually the preferred install solution for most users.

A basic workflow for installing and upgrading to a specific version of R (here for R-4.0.x under Debian Buster) would look like this. First, add the following line to your /etc/apt/sources.list file: deb http://cloud.r-project.org/bin/linux/debian buster-cran40/. If not available yet, add the proper key to your keyserver. For example: sudo apt-key adv --keyserver keys.gnupg.net --recv-key 'E19F5F87128899B192B1A2C2AD5F960A256A04AF' Next, run these commands, where the first two lines will install some typical dependencies. For additional details, open the CRAN instructions for installing R for your specific operating system here.

sudo apt install libcurl4-openssl-dev
sudo apt-get install libcurl4-openssl-dev
sudo apt update
sudo apt upgrade
# sudo apt install -t buster-cran40 r-base r-base-dev # run this line if previous one doesn't trigger R install

Now continue under section 5.4.5 with the installation of important dependencies and R packages.

5.5. Install R from source

Instructions for installing R from source are provided in the corresponding install manuals from CRAN and RStudio. Source installs are mainly relevant for R package development routines to test code on specific R versions (e.g. development version). Typical R users not involved in package development may not need this and can follow the instructions linked under installing pre-built R versions.

The following outlines how to install any R version from source on Debian/Ubuntu systems. The given example installs the latest R development version after downloading it via svn or ftp/http. For comparison, a similar but not identical R source install setup by a user is described here.

1. Install dependencies (these may be installed already)

sudo apt install r-base r-base-dev \
    subversion \ 
    ccache \
    xorg-dev \
    default-jdk \
    libx11-dev \
    libcurl4-openssl-dev

2. Download R source via svn or ftp/http from the corresponding source download page, and save it to a target directory. The below svn command downloads the development version of R from trunk, and saves it to a directory called R-devel. The latter directory name can be customized as needed. An advantage of the svn download appoach is that it makes it easier to keep up with future incremental version updates during a develpment/release cycle. The R version options downloadable via svn can be looked up here: https://svn.r-project.org/R/.

mkdir ~/svn                                   
cd ~/svn 
svn co https://svn.r-project.org/R/trunk R-devel # downloads developer version of R from trunk

## Alternatively, look up latest R version and download it
# wget ftp://ftp.stat.math.ethz.ch/Software/R/R-devel_yyyy-mm-dd.tar.gz                                            
# gunzip R-devel_yyyy-mm-dd.tar.gz; tar -xvf R-devel_yyyy-mm-dd.tar

3. Build and install R

The following will build and install the R source stored under ~/svn/R-devel in /usr/local/lib/R-devel. The latter path is defined under '--prefix' below. This path can be changed to the desired install location on a system. For instance, installing R under /opt/ or in a user account under ~/bin/ would be common alternative locations. When installing it in your own user account, then drop sudo in the corresponding command(s) below. For tracking purposes it may be most convenient to generate for the below install commands a *.sh script named after a specific R version install (e.g. R_devel_4_1.sh). This way it will be easier to customize and track the install commands used for each instance of an R source install.

mkdir ~/svn/R-devel-build # in case of svn build in dedicated directory 
cd ~/svn/R-devel-build
../R-devel/configure \
    --prefix=/usr/local/lib/R-devel \
    --enable-R-shlib \
    --enable-BLAS-shlib \
    --enable-shared \
    --enable-static \
    --with-blas \
    --with-lapack \
    --with-libpng \
    --with-jpeglib \
    --with-cairo \
    --with-x \
    --without-recommended-packages

make
sudo make install

Troubleshooting: if you get under make an error like libR.so: undefined reference to drot_ (e.g. on Ubuntu 18.04) then drop in configure the line:--with-blas. Most likely OpenBlas was already installed via sudo apt install lipopenblas-base. In this case the default OpenBlas will be used on a system.

To update the R development version via svn, run the following update steps, and then re-run under the ~/svn/R-devel-build directory the install of the previous code box.

cd ~/svn/R-devel
svn update
./tools/rsync-recommended

To check which optional features have been enabled for building R, one can do this from within R with:

capabilities()

4. Starting specific R versions

Add the following alias definition lines to your ~/.bashrc file. The first two lines may be optional if it is the default setting in a user's $PATH.

alias R='/usr/bin/R' 
alias Rscript='/usr/bin/Rscript' 
alias R-dev='/usr/local/lib/R-devel/bin/R'
alias Rscript-dev='/usr/local/lib/R-devel/bin/Rscript'

Now, one can load the release or development versions of R by typing on the command-line R or R-dev, respectively. In addition, the same R versions are called with Rscript and Rscript-dev, respectively.

5. Install common system dependencies

This installs a variety of system dependencies that are required by many R packages. Note, the texlive-full package is very large (5.2GB). If disk space is limited then one may want to skip its install or just install texlive instead (270MB).

sudo apt install build-essential \
    libcurl4-gnutls-dev \
    openjdk-7-* \
    libxml2-dev \
    libssl-dev \
    texlive-full \
    librsvg2-dev \
    libcairo2-dev \
    libxt-dev \ 
    libgsl-dev

For R Markdown one will need to have the command-line tool pandoc installed. On Debian/Ubuntu systems it can be installed via apt get install pandoc pandoc-citeproc. Alternatively, installing RStudio will include a pandoc version recommended by R Markdown. If command-line R cannot locate RStudio's pandoc version, then one can set the proper path in any R/Rmd script or in a user's .Rprofile file with Sys.setenv(RSTUDIO_PANDOC="<insert_path>"). The path (here <insert_path>) can be identified by running from RStudio: Sys.getenv("RSTUDIO_PANDOC").

6. Install common R packages

The R package collection devtools is required for many development tasks including the install of other R packages from GitHub directly. In addition, tidyverse is a collection of packages that are often required for many routine tasks, including ggplot2, dplyr and more.

Run the following package installs from R.

install.packages(c("devtools", "tidyverse"))

Now install Bioconductor's package manager from R.

if (!requireNamespace("BiocManager", quietly = TRUE)) 
    install.packages("BiocManager")  
BiocManager::install()

After this one can install Bioconductor packages from R as follows.

BiocManager::install(c("GenomicFeatures", "AnnotationDbi"))

The Bioconductor version can be returned with this command.

BiocManager::version()

For additional details see Bioconductor's package install page.

7. Simple uninstall

To remove the above R source installation, one can simply remove the following directories.

/usr/local/lib/<R-devel>
~/R/x86_64-pc-linux-gnu-library/<X.X> # Present when R packages were installed in user's home

8. Troubleshooting

a. Graphics: X11 font problem

If certain R graphics libraries, such as ggplot2 or lattice, return X11 font problems (like 'X11 font -adobe-helvetica ... not found'), then it may be necessary to include the following or a similar X11 default setting in your ~/.Rprofile file. For additional details on this issue, these user postings may be helpful: post1 and post2. Note, the last line, options(bitmapType = 'cairo'), is necessary to address this rmarkdown::render() issue. Alternatively, for building R Markdown vignettes, this line can be included at the beginning of a vignette's YAML header under parameter: vignette:.

# default X11() setting
setHook(packageEvent("grDevices", "onLoad"),
	function(...) grDevices::X11.options(width = 8, height = 8, xpos = 0, pointsize = 10, type = "cairo"))
options(bitmapType = 'cairo')

On shared user systems, one can define these settings system-wide by including them in an Rprofile.site file under file.path(R.home(), "etc/Rprofile.site"). The content in the Rprofile.site file could look like this:

local({                                   
   setHook(packageEvent("grDevices", "onLoad"),
   function(...) grDevices::X11.options(type='cairo'))                             
   options(device='x11')                                                  
})

Additinal details on this is available in R's main documentation here.

b. ...

...

5.6. Useful links

rig: The R Installation Manager

tgirke/Nvim-R_Tmux