Vim-R-Tmux: An Integrated Working Environment for R
This manual is outdated. A more up-to-date version can be found here.
IntroductionGeneral Overview
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
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 ConfigurationTmux SettingsDownload 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 SettingsCopy 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 UsageStart 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 UsageImportant 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 UsageTmux sessions consist of three main viewing components and it is important for the user to learn how to manage and navigate them:
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 UtilitiesNERDTreeNERDTree 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.
au BufRead *.pdf silent !open %<.pdf 2>/dev/null &
Session VariablesChecking/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 IssuesIf 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 ErrorIf there are problems with the DISPLAY settings, follow these instructions that fixes the problem by running "tmux update-environment". |