Functions and scripts

RaukR 2024 • Advanced R for Bioinformatics

Sebastian DiLorenzo

21-Jun-2024

R Functions

• Organised, human readable code
• Any code that will be repeated
• Add less objects to workspace
• Perform a set task, preferably that task is not “this whole analysis”

R Functions

Without a function

a <- 5
a + a

[1] 10

b <- 3
b + b

[1] 6

• User is performing the operation each time

An R function is something you have probably used many times already.. Functions perform a set task within R. Lets looks at a quick example.

With a function

doubleUp <- function(x){
  x + x
}

a <- 5
doubleUp(a)
b <- 3
doubleUp(b)
z <- doubleUp(3)

[1] 10
[1] 6

• Function is performing the operation each time

R Functions

The pieces that make a function

function_name <- function(param1, param2 = 20, ...){
  param1*2 # Operational space
  param1+param2 # What is returned. Alt, use return(param1+param2)
}

• function_name : Name of the function
• function() : Parameters. User input
  • param1 : No default value. Required.
  • param2 = 20 : Default value
  • ... : ellipses pass other arguments into function
• function(){} : The function body
• return : the last line or invoked with return() function.

A parameter is a variable in the declaration of the function. An argument is the actual value of the variable that gets passed to the function.

Tip

How to add a function to your workspace

• copy paste
• source() / library()

R scripts as standalone tools

In many ways this quote about the UNIX philosophy relates to the philosophy you should have for an R script.

McIlroy is best known for having originally proposed Unix pipelines and developed several Unix tools, such as spell, diff, sort, join, graph, speak, and tr.

• Data analysis with R is usually performed interactively using e.g. RStudio
• Tasks can be executed from the terminal using R scripts
• R scripts can form powerful standalone tools

Usually when you are analyzing data you will use the interactive view and try different things going forward. But say that you have figured out something that you want to do for multiple numbers of datasets?

And like the quote it should do one thing and do it well. Because of the power in that an R script can contain multiple functions, or “programs”, this one thing can be quite simple, or quite advanced. And like the textstream mentioned here Rscripts often take input, something we will look more at now.

In this case it might be efficient to use an Rscript.

So USUALLY an rscript is something that is executable, can take some inputs and arguments, and returns something.

Now lets look at those pieces starting with how an rscript can be executed.

Executing an R script

• Interactively: source("myscript.R") in R console

One way to execute an Rscript is to use “source myscript.R” from an interactive session which runs whatever code is in the R script. So if it has functions or wether it reads a separate file and creates some new object, these will be in your R environment after sourcing the script.

• Command line: Rscript myscript.R

You can also run the Rscript from the command line, or terminal. Then we use the command Rscript. It used to be not long ago that people used R CMD batch, but nowadays people usually use Rscript. Like the source, this will execute whichever code is in myscript.R but there is no environment for the objects or functions to pop into so the code in this Rscript is probably different than one that is intended for source.

• As executable file: path/myscript.R if:
  • Script is executable: chmod +x myscript.R
  • First line in script is a hashbang e.g. #!/usr/bin/env Rscript
  • Script’s path is included in call or $PATH

You can also execute the Rscript itself, from terminal. To execute an R script it must meet three requirements. It must be executable. It must start with this special line, specifying how it is executed if run on its own. If you want to run it without giving path, its folder must be in you $PATH variable.

Providing arguments to an R script

• Passing arguments to the script allows for flexibility in settings and input data

Often when we use an R script, like I mentioned in the beginning, we want to pass multiple files/samples through it for efficiency reasons. It doesnt just have to be files, like functions it can also be argument settings.

./myscript.R inputfile.vcf outputfile.vcf

Here for example we are using the Rscript as an executable file, giving it an inputfile and specifying what we want the outputfile to be named. Notice that the only way the R script knows what is what is positionally.

• Packages are available that support long and short flags

./myscript.R -i inputfile.vcf -o outputfile.vcf

Short flags are when you give a single dash and usually a shortened version of the keyword, here i for input and o for output for example.

./myscript.R --input inputfile.vcf --output outputfile.vcf

And here long flags with two dashes

./myscript.R --output inputfile.vcf --input outputfile.vcf

A part of the flexibility of this is that you can give the flags in any order.

./myscript.R --output inputfile.vcf -i inputfile.vcf

And you can also mix the long/short flag order and styles. It is the coding in the script that determines how it handles this input.

Parsing arguments - Positional

Example: ./myscript.R inputfile.vcf outputfile.vcf

• commandArgs()

Use commandArgs() to capture whatever was passed into R as it was executed. To be clear; this is a command that is within the Rscript file.

• trailingOnly = TRUE

Add trailingOnly = TRUE to suppress the first few items and get the arguments you passed to the script.

A standard arg, but not default, that you can use when invoking commandArgs() is trailingOnly = TRUE, which basically tells it to start counting the input from after the Rscript arguments. As you can see here when we invoke it without this parameter it returns the script itself, in this case R studio. But with it the invocation is clear, there were no trailing command line arguments.

commandArgs()

[1] "/usr/local/lib/R/bin/exec/R"        "--no-save"                         
[3] "--no-restore"                       "--no-echo"                         
[5] "--no-restore"                       "--file=/opt/quarto/share/rmd/rmd.R"

commandArgs(trailingOnly = TRUE)

character(0)

Parsing arguments - Flags

Example: ./myscript.R --input inputfile.vcf --output outputfile.vcf

So how do we do it with flags?

• Several packages are available: getopt, optparse, argparser, …

Define set of possible arguments at start of script:

library(optparse)
my_options = list(
  make_option(c("-i", "--inputfile"), default='variants.vcf'),
  make_option(c("-o", "--outputfile"), default='variants_filtered.vcf'))

If we use optparse as an example you create your options using the make_option command, and can set default values. We see also that you can give both long and short form here.

Parse arguments using your definition:

parse_args(OptionParser(option_list=my_options))

$inputfile
[1] "variants.vcf"

$outputfile
[1] "variants_filtered.vcf"

$help
[1] FALSE

And then you use the my_options object we defined together with parse_args and OptionParser to check our input for those flags We also see an option, help, that we did not make, this is a standard flag that optparse always looks for and can generate what arguments it is looking for.

Text streams

• Text streams allow for piping of data through a set of applications without writing intermediate files.

What I am sure most of you will think of when you read this is the bash pipe sign.

samtools mpileup -uf ref.fa aln.bam | bcftools call -mv | myPythonscript.py | myRscript.R > variants.vcf

So how does R handle taking input piped to it. And the answer is that we have to write some special code if this is the use case.

Reading

• To define and open a connection, read one line, and close it:

input_con  <- file("stdin")
open(input_con)
oneline=readLines(input_con, n = 1)
close(input_con)

• Tidyverse can read a tibble from text stream: read_csv(file("stdin"))

What we do is open a connection from standard input and then read this text stream for n number of lines at a time. It is also good to close this connection afterwards.

Alternatively you can read a text stream into a tibble from tidyverse by using read_csv, note that it isnt read.csv the generic R command, which can take our input connection and create the tibble in R.

Text streams

Writing

• Any stdout produced by the code (print(), cat(), etc) can be piped to a new process: ./myRscript.R | myNewScript

• or written to a file: ./myRscript.R > output.csv

• To write a tibble as a text stream: cat(format_csv(my_tibble))

What about piping from your R script to something else? Continuing the stream? So just writing these commands. print, cat etc, can be piped to a new process.

If you already have a tibble, you can stream it out of R using this command.

Summary

• Functions are great for organizing code and repeating tasks
• R scripts are great for performing tasks from command line
• R scripts can be built in different ways to take arguments or text streams

So to summarize, R scripts are powerful tools to solve a specific problem that you define, and often fit well together with other tools. And now you have learned to execute them in different ways, with inputs and outputs and with other programs. All that is left is to actually write the content.

Thank you! Questions?

         _                  
platform x86_64-pc-linux-gnu
os       linux-gnu          
major    4                  
minor    3.2                

2024 • SciLifeLab • NBIS • RaukR