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.
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.
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 this page. 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.
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")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!Download the Nerdtree vim plugin from here. Then extract to ~/.config/nvim with:
unzip NERD_tree.zip -d ~/.config/nvimJakson 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.
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 (steps 2-5).
- Add to your
.bashrcthe following lines
if [ -n "$MODULESHOME" ]; then
module load neovim
module load tmux/2.2
fi- Install Nvim-R plugin for Neovim as instructed here
- Save this
init.vimsample file to~/.config/nvim/init.vim - Install Nerdtree plugin as instructed here
- Install
southernlightscolor scheme as instructed here - Now log out of the system and in again. After this start tmux and then open a
.Ror.Rmdfile withnvimcommand. Next open a connected R session with the key combination\rfand then follow the usage instructions given here.
The usage of Neovim is almost identical to Vim. Two important differences are:
- The command for opening Neovim is
nviminstead ofvim. - Plugins are usually stored under
~/.config/nvim/and the counter part of the.vimrcconfig file isinit.vimlocated at~/.config/nvim/init.vim.
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 sessionspacebar: sends code from vim to R; here remapped ininit.vimfrom default\l:splitor:vsplit: splits viewport (similar to pane split in tmux)gz: maximizes size of viewport in normal mode (similar to Tmux'sCtrl-a zzoom 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 viewportsCtrl-w =: resizes splits to equal sizeCtrl-w 5< or 5>: resizes splits to left or right by 5 steps; change number as neededCtrl-w HorCtrl-w K: toggles between horizontal/vertical splitsCtrl-spacebar: omni completion for R objects/functions when nvim is in insert mode. Note, this has been remapped ininit.vimfrom difficult to type defaultCtrl-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 supportCtrl-s and Ctrl-x: freezes/unfreezes vim (some systems)
To run R in a separate Tmux pane, include the following two lines in your init.vim:
- `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 paneCtrl-a Ctrl-o: swaps panesCtrl-z z: maximizes (zooms into) active pane
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 panesystem("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 commandsCtrl-aand:respawn-pane bash