This is a short manual for configuring vim and tmux (or screen) in order to use them as a flexible working environment (IDE) for R. The intent of this outline is not to provide a usage manual of the Vim-R-Tmux trio. Instead it describes the setup and basic usage of a relatively functional sample configuration. Movies and sample screenshots for exploring many of their additional capabilities are available here. The developers of this powerful integration infrastructure include Jakson Aquino and Jose Claudio Faria (vim-r-plugin), Eric Van Dewoestine (screen.vim), as well as the many developers of vim, tmux and R. Users who prefer emacs over vim as code editor may be more interested in the ESS add-on package, whereas beginners without any prior knowledge of vim or emacs might be more interested in one of the GUI-based IDEs for R that are listed here. Some of the specific benefits of the Vim-R-Tmux integration environment include:
  • Works consistently across different Linux, Unix and OS X platforms
  • Using vim and tmux as standard working environment increases productivity with many computer languages, not just R
  • Efficient reattachment system to tmux sessions frees up processing resources on local computers when working with long running analysis tasks
  • Flexible code sending options from local vim instances to R sessions on remote machines or among remote machines  
  • Similar setups are available for other computer languages, such as bash, Python or Ruby (see also vimux and vimux-pyutils)



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.

Requirements

Table of Contents

Installation

(1) Install a current version of 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
fi

Configuration

Tmux Settings

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

Vim Settings

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.

Basic Usage

Start Vim-R-Tmux Session

(1) Start tmux session

$ 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.


Basic Vim-R-Plugin Usage 

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

Vim-r-plugin manuals

Vim manuals


Basic Tmux Usage

Tmux sessions consist of three main viewing components and it is important for the user to learn how to manage and navigate them:
  1. panes: grid components within a window
  2. windows: entire terminal views each with one or many panes
  3. sessions: independent tmux terminal emulation instances
Note: many tmux commands can be executed from both the Unix/Linux command prompt or the tmux command mode indicated below with '$' or ':', respectively.  The latter can be accessed with the key sequence 'Ctrl-a :' and then typing the same commands as on the command prompt without the 'tmux' prefix. Also, the following uses 'Ctrl-a' as tmux's command key binding. Users who are not using the above .tmux.conf file may need to use here tmux's default key binding 'Ctrl-b' instead.

Pane-level comands/shortcuts

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        

Window-level comands/shortcuts

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   

Session-level comands/shortcuts

$ 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"

Tmux manuals:

Miscellaneous Utilities

NERDTree

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. 

###########################
## NERDTree Installation ##
###########################
## Download the plugin from here: http://www.vim.org/scripts/script.php?script_id=1658
## Then extract to ~/.vim/ with:
$ unzip nerdtree.zip -d ~/.vim
:helptags ~/.vim/doc           # execute in vim's command mode once to activate plugin help in vim

##########################
## Basic NERDTree Usage ##
##########################
zz or :NERDTreeToggle          # opens NERDTree ('zz' requires setting below)
:NERDTreeFind                  # finds current file in tree
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

#############################################
## Helpful Vim Commands for File Switching ##
#############################################
Ctrl-o or Ctrl-i               # jumps to previous or next file in current buffer
:ls                            # lists files in current buffer
:b <number> or <name>          # opens specific file in buffer by number or name
:browse old                    # opens menu of previously used files that can be selected by numbers
:e <file>                      # opens new file
:cd %:p:h                      # changes directory to currently open file; useful when using system commands, e.g. Latex work          

########################
## Settings in .vimrc ##
########################
"" Open NERDTree with custom shortcut, here 'zz'
let mapleader = "z"           
nmap <leader>z :NERDTreeToggle<cr>

"" Optional, to show special NERDTree browser characters properly (e.g. on remote linux system)
let g:NERDTreeDirArrows=0

"" Show bookmarks by default
let NERDTreeShowBookmarks=1

"" Open *.pdf, .jpg, *.doc and other files with GUI applications (choose solution for your OS)
"" Linux: open PDFs with xpdf
au BufRead *.pdf silent !xpdf %<.pdf 2>/dev/null &
"" OS X: open PDFs with associated PDF viewer
au BufRead *.pdf silent !open %<.pdf 2>/dev/null &

Session Variables

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"

Scope Issues

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:

. ~/.bashrc                
export PATH=/opt/local/bin:/opt/local/sbin:$PATH   

DISPLAY Error

If there are problems with the DISPLAY settings, follow these instructions that fixes the problem by running "tmux update-environment". 

Table of Contents