Recommended Workflow and Examples

Vilmantas Gegzna

2017-12-14

This vignette introduces to package spAddins: describes a recommended workflow, explains how the functions of the package should be used and gives several examples.

About The Package

spAddins is an R package that provides a set of RStudio addins which are designed to be used in combination with user-defined RStudio keyboard shortcuts. These addins do the following:

  1. format text in R Markdown documents:
    • enclose either selected text or selected rows with special symbols and text gets inerpreted in a special way when rendered with R Markdown (e.g., converts “bold” into “**bold**” that is interpreted as “bold”).
  2. insert text (e.g., operators %>%, <<-, %$%) at the cursor position;
  3. replace symbols in selected pieces of text (e.g., convert backslashes to forward slashes which results in strings like "c:\data\" converted into "c:/data/").

The Workflow

The recommended workflow consists of four main steps. Step 1 and Step 2 should usually be done only once. Step 3 and Step 4 can be repeated as many times as needed.

Step 1: Install the package

Released version of package spAddins can be installed from CRAN:

install.packages("spAddins")

Development version can be installed from GitHub:

if (!require(devtools)) install.packages("devtools")
library(devtools)
install_github("GegznaV/spAddins")

Step 2: Define keyboard shortcuts

The most of the functions in the package are also RStudio addins. This fact allows setting user-defined RStudio keyboard shortcuts that call the functions in a more convenient way. Thus the second step is to define keyboard shortcuts for package’s spAddins functions of interest.

To learn how to add user defined RStudio keyboard shortcuts, visit these links:

Step 3: Place a cursor / Select some text

Package spAddins contains 3 types of addins:

For addins which insert text, in either R editor or in R console place your cursor at the position at which the text should be inserted.

For addins which either replace or enclose text, in R editor or in R console select a piece of text in which certain symbols should be replaced or enclosed.

Step 4: Use the keyboard shortcuts

To call a desired addin function, apply an appropriate keyboard shortcut which in Step 2 was associated with that function.

A Few Examples

Insert %$% operator

This example demonstrates how to use addins which insert text.

Let package spAddins be already installed. First, let’s set keyboard shortcut Ctrl + Alt + Shift + S to call function rs_insert_exposition_pipe() which inserts exposition pipe-operator %$% at the cursor position. This operator is defined in package magrittr thus the package must be loaded too:

library(magrittr)

To learn more about the %$% operator type:

?magrittr::`%$%`

It can replace this commands, where $ is used, e.g.:

table(CO2$Type, CO2$Treatment)

Next, place your cursor at the position, where the operator should be inserted. For example, between the name of data set CO2 and the name of a function table():

CO2  table(Type, Treatment)

Apply the shortcut combination Ctrl + Alt + Shift + S. As a result the operator is inserted:

CO2  %$%  table(Type, Treatment)
##              Treatment
## Type          nonchilled chilled
##   Quebec              21      21
##   Mississippi         21      21

Replace \ with /

This example describes how to use addins which replace text.

Conciser having a string "c:\data\" in which backslashes (\) must be replaced with forward slashes (/). Addin function rs_replace_slash_b2fw() (b – backslash, fw – forward slash) is designed exactly for this task. Let’s define a new shortcut combination, say Ctrl + Alt + Shift + /, which calls the addin function. Now to know the place where the replacement should be applied an appropriate piece of text in either R editor or R console must be selected. Thus let’s select whole string "c:\data\" and push Ctrl + Alt + Shift + /. The result: as expected, the string is converted into "c:/data/".

Enclose with ****

This example describes how to use addins which enclose text.

Conciser having an R Markdown file and a string "This word should be in bold." in it. In this string word word must be in bold. Addin function rmd_bold() encloses selected text in double asterisk ** signs, and this is interpreted as bold in R markdown. Let’s define shortcut combination, say Ctrl + Shift + B, which calls the addin function. Now select the word word which is either in R editor or R console and push Ctrl + Shift + B to call the addin function. The result: "This **word** should be in bold."

Available add-in functions

“Insert” family

These functions insert various R operators.

A few examples of addins that insert operators
Function Inserts Package associated with operator
rs_insert_arrow_rl2() <<- R base
rs_insert_arrow_lr() -> R base
rs_insert_arrow_lr2() ->> R base
rs_insert_infix_in() %in% R base
rs_insert_matrix_multiplication() %*% R base
rs_insert_pipe %>% magrittr
rs_insert_tee_pipe() %T>% magrittr
rs_insert_update_pipe() %<>% magrittr
rs_insert_exposition_pipe() %$% magrittr

The following functions may be useful for either editing R Markdown files or, if commented (#), for structuring R code files.

Addins that insert lines
Function Description Example (first 10 symbols)
rs_insert_line_ss() Insert single straight (SS) line ----------
rs_insert_line_ds() Insert double straight (DS) line ==========
rs_insert_line_sw() Insert single wavy (SW) line ~~~~~~~~~~

The length of line is from the beggining of selection to the 79-th column of the row (i.e., the position of 79-th symbol in the row).

“Replace” family

Addins that convert between types of slashes
Action Function Text to edit Result
Replace \ with \\ rs_replace_slash_bs2d() “c:\data\” “c:\\data\\”
Replace \ with / rs_replace_slash_b2fw() “c:\data\” “c:/data/”
Replace / with \ rs_replace_slash_fw2b() new line/n new line\n
Replace \\ with \ rs_replace_slash_bd2s() new line\\n new line\n

“Enclose” family

These functions are useful for editing R Markdown files.

Several examples of addins that format text in R Markdown
Action Function Text to edit Result Interpreted as
Enclose with double asterisk (**) rmd_bold() bold **bold** bold
Enclose with single underscore (**_ and _**) rmd_italics() italics _italics_ italics
Enclose with single underscore (_) rmd_bold_italics() bold italics **_bold italics_** bold italics
Enclose with double underscore (__) rmd_bold2() bold __bold__ bold
Enclose with single asterisk (*) rmd_italics2() italics *italics* italics
Enclose with caret (^) rmd_superscript() a superscript a ^superscript^ a superscript
Enclose with single tilde (~) rmd_subscript() a subscript a ~subscript~ a subscript
Enclose with double tilde (~~) rmd_strikethrough() strikethrough ~~strikethrough~~ strikethrough
Enclose with single backick (`) rmd_code_inline() code `code` code
Enclose as inline R code to evaluate rmd_r_code_inline() 2 + 3 ` r 2 + 3` 5
Enclose with single dollar sign ($) enclose_with_dollar() equation^{inline} $equation^{inline}$ \(equation^{inline}\)
Enclose with double dollar sign ($$) enclose_with_dollar2() equation_{block} $$equation_{block}$$ \(equation_{block}\)

Feedback

Your feedback is wellcome at https://github.com/GegznaV/spAddins/issues