Figure 1: Illustration of sending R code from several vim viewports (in middle) to an R session (on top right). The vim session can run on a local computer, while the
R session can run on the same or a remote system. The snapshot also illustrates the omni completion utility of the vim-r-plugin (purple box), viewing of an R
function help document in a separate tmux pane (bottom right) and the NERDTree file browser (left). A major benefit of tmux is that it allows the user to switch
between independently accessible windows within the same terminal instance that can be tracked with tabs on the bottom of the terminal (here eight window tabs).
Format of this Manual
In this manual all commands are given in code boxes, where the commands are printed in black and the comment text in blue starting with the standard comment sign '#'. Commands starting with a '$' sign need to be executed from the Unix/Linux command prompt and those starting with '>' from the R console. Commands starting with a colon ':' or 'Ctrl-a :' refer to the vim command or tmux command modes, respectively.
vim (version 7.3 or higher). Most Unix/Linux operating systems come with vim pre-installed.
(2) Install a recent version of the R software.
(3) Install a recent version of tmux (version 1.6 or higher)
(4) Download the screen.vim plugin and then install it from within vim as follows:
$ vim screen.vba # type from command-line
:so % # type in vim command mode; if this gives an error download below .vimrc and then repeat this step
Table of Contents
(5) Download the latest version of the vim-r-plugin, unzip it and move its content folders to ~/.vim. The latter can be achieved with the following command:
$ unzip vim-r-plugin-*.zip -d ~/.vim # change name of *.zip to proper version
:helptags ~/.vim/doc # execute in vim's command mode to activate plugin help in vim
(6) Optional: user who want to automatically load specific vim/tmux versions from a module system upon log in, can include the following lines into their .bashrc file:
if [ -n "$MODULESHOME" ]; then
module load vim/7.3 # adjust to corresponding version in module system
module load tmux/1.6 # adjust to corresponding version in module system
Download the following sample .tmux.conf file to the highest level of your home directory. Before this is done, it is recommended to make a backup copy of any existing .tmux.conf file.
$ mv .tmux.conf .tmux.conf.bak # creates backup copy of any existing .tmux.conf file
$ wget http://faculty.ucr.edu/~tgirke/Documents/R_BioCond/My_R_Scripts/vim-r-plugin/.tmux.conf # downloads sample .tmux.conf file
Copy the section "sample settings for vim-r-plugin" from this sample .vimrc file to any existing .vimrc file. If there is none then one can download the entire sample.vimrc file to the highest level of a user's home directory.
$ mv .vimrc .vimrc.bak # creates backup copy of any existing .vimrc file
$ wget http://faculty.ucr.edu/~tgirke/Documents/R_BioCond/My_R_Scripts/vim-r-plugin/.vimrc # downloads sample .vimrc file
Table of Contents
To open R automatically in a terminal rather than the R Gui, OS X users want to uncomment/include the following two lines in their .vimrc file. This step should be skipped on Linux/Unix systems.
let vimrplugin_applescript = 0
let vimrplugin_screenplugin = 0
This archive contains all of the above components and configuration files needed to make things work on UCR's biocluster system. A newer version with support for *.Rmd files and color highlighting in R console is here.
$ tmux # or 'tmux attach' to attach to an existing session
This will open a tmux session with a single window. After this a tmux custom session can be loaded with with "Ctrl-a r". The one provided with the above ".tmux.conf" sample file contains 6 windows with tabs at the bottom. They are defined in the section "sample session initialization" of the .tmux.conf file. Users want to edit this configuration according to their personal preferences.
(2) Open any *.R script file in vim or create a new one
$ vim myscript.R
(3) Open vim-connected R session by pressing the F2 key on the keyboard
This will open an R session in a separate tmux pane. Closing vim will also close the R pane. Note, in the provided .tmux.conf file the command key binding has been reassigned from tmux's default 'Ctrl-b' to 'Ctrl-a', and the shortcut for starting R has be reassigned from '\rf' to 'F2' in the .vimrc file. The command key binding 'Ctrl-a' is the most important key sequence in order to move around in tmux. For instance, the key sequence 'Ctrl-a o' will switch between the vim and R panes, and 'Ctrl-a Ctrl-o' will swap the two panes.
(4) Send R code line-by-line from vim to the R pane by moving the cursor to a chosen line and then pressing the space bar
To send several lines at once, one can select them in vim's visual mode and then hit the space bar. Please note, the default command for sending code lines in the vim-r-plugin is '\l'. This key binding has been remapped in the provided .vimrc file to the space bar. Most other key bindings (shortcuts) still start with the '\' as LocalLeader, e.g. '\rh' opens the help for a function/object where the curser is located in vim. More details on this are given below.
Important commands/shortcuts (key bindings) for the vim-r-plugin
<F2> # opens vim-connected R session; remapped in .vimrc from default \rf
<space bar> # sends code from vim to R; here remapped in .vimrc from default \l
:h vim-r-plugin # opens vim-r-plugin help page from vim; works after running ':helptags ~/.vim/doc'
:h screen.txt # opens screen.txt help page from vim
:split or :vsplit # splits viewport (similar to pane in tmux)
Ctrl-w-w # jumps cursor to next viewport
Ctrl-w-r # swaps viewports
Ctrl-w Ctrl-++ # resizes viewports to equal split
Ctrl-w 10+ # increase size of current viewport by value
Ctrl-x Ctrl-o # omni completion command for R objects/functions from within vim
:RUpdateObjList # run to update object list for omni completion with information from new libraries
:set filetype=r # If a script without an *.R extension has been opened one can reset the file type to 'R' with this
# command. This way one can also send commands from a bash script (or other languages) to the unix/linux
# command prompt after quitting the R session in the connected pane.
Ctrl-s and Ctrl-x # freezes/unfreezes vim on some systems
Ctrl-a % # splits pane vertically
Ctrl-a " # splits pane horizontally
Ctrl-a-o # jumps cursor to next pane
Ctrl-a Ctrl-o # swaps panes
Ctrl-a <space bar> # rotates pane arrangement
Ctrl-a-: resize-pane -L 10 # resizes pane by 10 to left (L R U D)
Ctrl-a-+ and Ctrl-a-- # zoom in and out of pane; requires settings under "Maximizing and Restoring Panes" in .tmux.conf
Ctrl-a n # switches to next tmux window
Ctrl-a Ctrl-a # switches to previous tmux window
Ctrl-a c # creates a new tmux window
Ctrl-a 1 (2, 3, ...) # switches to specific tmux window selected by number
Ctrl-a : rename-window <...> # renames window including label on corresponding tab
$ tmux source-file ~/.tmux.conf # reloads config settings specified in a user's ~/.tmux.conf file
Ctrl-a r # key binding for previous line defined in .tmux.conf
$ tmux new -s <name> # starts new session with a specific name
Ctrl-a : new-session -s <name> # key binding for previous line defined in .tmux.conf
$ tmux ls # lists available tmux session(s)
$ tmux attach -t <id> # attaches to specific tmux session
$ tmux kill-session -t <id> # kills a specific tmux session
Ctrl-a d # detaches from current session
$ tmux attach # reattaches to session
Ctrl-a s # allows to switch between available tmux sesssions
Ctrl-a : kill-session # kills tmux session; tmux server can be killed with "Ctrl-a : K"
NERDTree is a vim plugin that adds file browsing functionality in visual tree mode to vim. It also provides very useful features to quickly switch between files (e.g. within tmux panes), which is particularly helpful when working with many files.
Checking/reassigning session variables for vim and R panes:
:echo ScreenShellTmuxPane # returns session variable vim pane
:let ScreenShellTmuxPane = "%1" # reassign vim pane session variable (here "%1"), should be the same as output of "Sys.getenv("TMUX_PANE")"
> Sys.getenv("TMUX_PANE") # returns R session variable
> Sys.setenv(TMUX_PANE="%1") # reassign R session variable (here "%1"), should be the same as output of "let ScreenShellTmuxPane = "%1"
If there is a problem with sourcing your.bashrc upon pane splits or creation of new windows, add these lines to the end of your ~/.bash_profile file: