Monday, April 22, 2013

Unit Tests vs Parametrized Unit Tests

Unit Tests

Using the conventions of NUnit unit tests as test methods contained in test classes. A parameterless method decorated with a custom attribute like [TestMethod] is a test method. Usually, each unit test explores a particular aspect of the behavior of the class-under-test.

Here is a unit test written in C# that adds an element to a .NET ArrayList instance. The test first creates a new array list, where the parameter to the constructor is the initial capacity, then adds a new object to the array list, and finally checks that the addition was correctly performed by verifying that a subsequent index lookup operation returns the new object.

[TestMethod] 
void TestAdd() 
{ 
 ArrayList a = new ArrayList(0); 
 object o = new object(); 
 a.Add(o); 
 Assert.IsTrue(a[0] == o); 
}

It is important to note that unit tests include a test oracle that compares observed behavior with expected results. By convention, the test oracle of a unit test is encoded using assertions. The test fails if any assertion fails or an exception is thrown. Unit test frame- works can also deal with expected exceptions. For a quick introduction about NUnit refer previous posts.

A test suite produced by unit testing with high code coverage gives confidence in the correctness of the tested code. However, writing unit tests to achieve high coverage can be time-consuming and tedious given that test execution frameworks only automate the test executions. You still have to write your test cases !

To address this problem, several automatic unit test generation tools such as Parasoft JTest or jCUTE can automatically generate conventional unit tests. These tools, nevertheless, cannot guarantee high code coverage, unless testers manually write some tests.

 


Parametrized Unit Tests


The unit test above specifies the behavior of the array list by example. Strictly speaking, this unit test only says that by adding a new object to an empty array list, this object becomes the first element of the list. What about other array lists and other objects?

[TestAxiom]
void TestAdd(ArrayList a, object o) 
{
 Assume.IsTrue(a!=null);
 int i = a.Count;
 a.Add(o);
 Assert.IsTrue(a[i] == o);
}

By adding parameters we can turn a closed unit test into a universally quantified conditional axiom that must hold for all inputs under specified assumptions.

Adding parameters to a unit test improves its expressiveness as a specification of intended behavior, but we lose concrete test cases. We can no longer execute this test axiom by itself. We need actual parameters. But which values must be provided to ensure sufficient and comprehensive testing? Which values can be chosen at all?

In the ArrayList example, if we study the internal structure of the .NET Framework implementation, we observe that there are two cases of interest. One occurs when adding an element to an array list that already has enough room for the new element (i.e. the array list’s capacity is greater than the current number of elements in the array list). The other occurs when the internal capacity of the array list must be increased before adding the element.

If we assume that library methods invoked by the ArrayList implementation are themselves correctly implemented, we can deduce that running exactly two test cases is sufficient to guarantee that the parametrized TestAdd(...) succeeds for all array lists and all objects.

[TestMethod]
void TestAddNoOverflow() 
{
 TestAdd(new ArrayList(1), new object());
}

[TestMethod]
void TestAddWithOverflow() 
{
 TestAdd(new ArrayList(0), new object());
}

Splitting axioms and test cases in this way is a separation of concerns:


  • First, we describe expected behavior as parametrized unit tests.
  • Then we study the case distinctions made by the code paths of the program under test to determine which inputs make sense for testing.

So, parametrized unit tests are more general specifications than conventional unit tests because it specifies the behavior for the whole input classes other than for a single concrete value of the input. But it needs concrete parameter values to be executed.


The good news is, Given a parametrized unit test, a test-generation tool, such as Microsoft Pex, can automatically generate tests with concrete inputs for the parameters to achieve high coverage. Pex explores the behaviors of a parametrized unit test using a technique called dynamic symbolic execution. Dynamic Symbolic Execution (DSE) is a variation of symbolic execution, which systematically explores feasible paths of the program under test by running the program with different test inputs to achieve high structural coverage. It collects the symbolic constraints on inputs obtained from predicates (condition statements like if else, switch,…) in branch statements along the execution and relies on a constraint solver [like Zap or Simplify] to solve the constraints and generate new test input for exploring new path. For each set of concrete test input that leads to a new path that achieves new coverage, Pex generates a corresponding conventional unit test. So, all what you have to do is write your parametrized unit test.


In this post we gave a brief overview about parametrized unit tests and its related research areas. It’s a very important concept to understand before start learning Microsoft Pex, which we will start . In later posts, we will explore Microsoft Pex in detail.

Saturday, March 30, 2013

Getting Started with Java PathFinder

Java™ Pathfinder, or "JPF" as we call it from here, is a highly customizable execution environment for verification of Java™ bytecode programs. JPF was developed at the NASA Ames Research Center, open sourced in 2005, and is freely available here under the NOSA 1.3 license. JPF started as a software model checker but it integrates model checking, program analysis and testing.

In this post  we will go in a step by step process to setup the  environment where Java Path Finder can be used within Eclipse IDE environment. We will show a simple example of using JPF.

  • Step 1. Install Eclipse
    • Step 1.1 : Download and install the latest JDK fro your platform from here.
    • Step 1.2 : Download the latest Eclipse from here. Once you have unzipped the previously downloaded file, you will see a folder named eclipse.  In that folder you will find the eclipse application.  We recommend you create a shortcut on the desktop to simplify the launching of eclipse.  Notice that unlike Java, Eclipse does not have an installation process. Once you have unzipped the file you are done.
  • Step 2. Download JPF
    • Step 2.1 : Download Mercurial plug-in for Eclipse
      • Launch Eclipse. Go to Help >> Install New Software
      • 2013-03-28 13_54_12-Java - jpf_junit_demo_src_TestGenerator.java - Eclipse SDK
      • Click Add
      • 2013-03-28 14_01_12-Install
      • Insert “Mercurial” in the Name box. Insert “http://mercurialeclipse.eclipselabs.org.codespot.com/hg.wiki/update_site/stable/” in the Address box. Click Ok.
      • In the install dialog select the newly added site from Work with drop down box. The list below it will show the available software at this site, select the item named MercurialEclipse and click Next, then finish..
      • 2013-03-28 14_05_37-Install
    • Step 2.2 : Download the JPF source code
      • In Eclipse menu : File >> Import >> Mercurial >> Clone Existing Mercurial Repository >> Next.
      • 2013-03-28 14_42_31-Mercurial clone repository wizard
      • In the repository location URL, insert “http://babelfish.arc.nasa.gov/hg/jpf/jpf-core”. Click Next, then Finish. The JPF project files will be downloaded to your local computer.
    • Step 2.3 : Build the JPF
      • In the package explorer, select the build.xml, right click on it, select “run as” >> “Run as Ant build “.
      • Eclipse will build JPF and a new folder named “build” will appear in the package explorer (it may not appear even the build was successful, double check the windows explorer for it.)
        • If the build failed due to error missing JDK:
          • On Eclipse menu : Project >> Properties. Select Builders from the lift hand side list
          • 2013-03-30 19_52_18-Java - jpf_junit_demo_test_CalculatorTest.java - Eclipse SDK
          • Select Ant Builder and click New.
          • Select Ant Builder and click New.
          • In the Edit Configuration dialog, select the “JRE” tab, then select “Separate JRE” from the “Runtime JRE section”. In the drop down list, select JDK:
          • 2013-03-30 20_01_41-Edit Configuration
          • If you couldn’t find the JDK in the drop down list, click “Installed JRE …”
          • 2013-03-30 20_05_18-Preferences (Filtered)
          • In the “Preferences” dialog, click “Add”
          • 2013-03-30 20_07_40-Preferences (Filtered)
          • Select “Standard VM” and click “Next”
          • 2013-03-30 20_10_06-Edit Configuration
          • Click “Directory” and navigate to your JDK installation directory. Then click “Finish” to return to the previous dialog.
          • 2013-03-30 20_11_56-Preferences (Filtered)  
          • Select the JDK and click Ok.
          • Select JDK in the drop down box and click OK
          • 2013-03-30 20_13_43-Edit Configuration
  • Step 3 : Install and configure JPF
    • Step 3.1 : Install JPF files : Copy the whole jpf-core project folder into <user.home>/projects/jpf
    • Step 3.2 : Create site.properties
      • Create site.properties under <user.home>/.jpf folder.
      • To create the folder on windows, use the following command on the command window after navigating to the user home: mkdir .jpf .
      • Paste the following content into the site.properties file.
        # JPF site configuration
        
        jpf.home = ${user.home}/projects/jpf
        
        # can only expand system properties
        jpf-core = ${user.home}/projects/jpf/jpf-core
        
        # annotation properties extension
        jpf-aprop = ${jpf.home}/jpf-aprop
        extensions+=,${jpf-aprop}
        # numeric extension
        jpf-numeric = ${jpf.home}/jpf-numeric
        extensions+=,${jpf-numeric}
        # concurrent extension
        #jpf-concurrent = ${jpf.home}/jpf-concurrent
        #extensions+=,${jpf-concurrent}
        jpf-shell = ${jpf.home}/jpf-shell
        extensions+=,${jpf-shell}
        jpf-awt = ${jpf.home}/jpf-awt
        extensions+=,${jpf-awt}
        
        jpf-awt-shell = ${jpf.home}/jpf-awt-shell
        extensions+=,${jpf-awt-shell}
        
    • Step 3.3 : Install Eclipse plug-in
  • Step 4 : Start the demo project
    • Step 4.1 : Create and configure project
      • In Eclipse menu : File >> New >> Java project : project name = jpf_junit_demo
      • In the package explorer, right click on the project name. Choose “Build Path” >> “Add libraries”
      • 2013-03-28 15_41_55-Add Library 
      • Select User Library and click Next.
      • Click User libraries. Then New. You will see a window for creating a library. Put “jpf” as the library name and click Ok to return to the previous dialog.
      • Select the newly added jpf library and click “Add External JARs …”.
      • Select all the jar files under <user.home>/jpf/jpf-core/build and click “Open” to add them under library jpf
      • Click New to create a new user library. Name it “jpf-support”.
      • Select the newly added jpf-support library and click “Add External JARs …”.
      • Select all the jar files under <user.home>/jpf/jpf-core/lib and click “Open” to add them under library jpf-support
      • Now the User Libraries should look like the following:
      • 2013-03-28 15_54_32-Preferences (Filtered) 
      • Right click on the project name and select : New >> Folder, name the folder as test. Right click on the newly created test folder and select : Build Path >> Use as Source Folder. This folder will be used in the future to hold the JUnit test classes.
      • Now the project folder should look like the following:
      • 2013-03-28 16_00_38-Java - jpf_junit_demo_src_TestGenerator.java - Eclipse SDK
    • Step 4.2 : Create a class (program under test)
      • Right click on the “src” folder and choose: New >> Class. Name it Calculator and click Finish.
      • This is the content of the very simple Calculator.java which prints the sum of two integers. The Verify statements are the only JPF statements, the rest is pure java. We will explain the JPF statements through its results in the next step.

        import gov.nasa.jpf.jvm.Verify;
        
        public class Calculator {
            int add (int a, int b)
            {
                return a+b;
            }
            public static void main(String[] args)
            {
                int a = Verify.getInt(1,3);
                int b = Verify.getInt(5,8);
                Calculator cal = new Calculator();
                System.out.println(a + "+" + b + "=" + cal.add(a, b));
            }
        }
        
      • Step 4.3 : Run JPF from Eclipse
        • Right click on the project name and select: New >> File. Name the file “jpf_junit_demo.jpf”.
        • This is the content of the newly added file

          +classpath=${config_path}/bin
          target=TestGenerator

        • In the package explorer, right click on the “jpf_junit_demo.jpf” and select “Verify …”.
        • If you couldn’t see the “Verify…” option, this means that you didn’t installed the JPF plug-in properly.  See step 3.3.
        • JPF will get started and you will see its output in the console pane. It will be like the following:
      Executing command: java -jar C:\Users\Ebeid\projects\jpf\jpf-core\build\RunJPF.jar +shell.port=4242 C:\Users\Ebeid\projects\jpf_junit_demo\jpf_junit.demo.jpf
      JavaPathfinder v6.0 (rev 960+) - (C) RIACS/NASA Ames Research Center
      
      ====================================================== system under test
      application: Calculator.java
      
      ====================================================== search started: 3/28/13 4:41 PM
      1+5=6
      1+6=7
      1+7=8
      1+8=9
      2+5=7
      2+6=8
      2+7=9
      2+8=10
      3+5=8
      3+6=9
      3+7=10
      3+8=11
      
      ====================================================== results
      no errors detected
      
      ====================================================== statistics
      elapsed time:       00:00:02
      states:             new=5, visited=11, backtracked=16, end=12
      search:             maxDepth=3, constraints hit=0
      choice generators:  thread=1 (signal=0, lock=1, shared ref=0), data=4
      heap:               new=545, released=197, max live=353, gc-cycles=13
      instructions:       5098
      max memory:         55MB
      loaded code:        classes=82, methods=1362
      
      ====================================================== search finished: 3/28/13 4:41 PM
      

      According to our program code and the JPF results, you may already guessed what the verify statements are doing in the following lines of code:

      int a = Verify.getInt(1,3);
      int b = Verify.getInt(5,8);

      • Simply, Verify.getInt(x, y) get a new integer within the range [x,y].
      • That is it ?
      • Partially yes.
      • But how JPF get 12 print outputs ?
      • Ok Actually JPF starts a new clone of the program for each value resulted from a Verify.getInt() statement.
      • This means that JPF will create 3 versions of the program, each one of these versions runs with a different value of a (1, 2, 3).
      • Each version of these three versions will be used as a base to create another 4 versions of the program for variable b, each one of these versions runs with a different value of b (5, 6, 7, 8).

      So, the total versions of the program running by JPF is 3 * 4 = 12. Its like a tree where the leafs are the print statements :

      • a = 1
        • a = 1, b = 5    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    1+5=6
        • a = 1, b = 6    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    1+6=7
        • a = 1, b = 7    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    1+7=8
        • a = 1, b = 8    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    1+8=9
      • a = 2
        • a = 1, b = 5    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    2+5=7
        • a = 1, b = 6    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    2+6=8
        • a = 1, b = 7    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    2+7=9
        • a = 1, b = 8    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    2+8=10
      • a = 3
        • a = 1, b = 5    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    3+5=8
        • a = 1, b = 6    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    3+6=9
        • a = 1, b = 7    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    3+7=10
        • a = 1, b = 8    |    System.out.println(a + "+" + b + "=" + cal.add(a, b));    |    3+8=11

      you can use JPF for your JUnit tests to generate explore your code states as we did; just keep in mind that a small increase in the number of states of variables could result in huge number of total program states.

      I hope you enjoyed it, and see you later in more posts about JPF.

Monday, January 21, 2013

Introduction to R – Charts and Graphics

R includes several packages for visualizing data:

  • graphics contains plotting functions for the “base” graphing systems, including plot, hist, boxplot and many others.
  • lattice contains code for producing Trellis graphics, which are independent of the “base” graphics system; including functions like xyplot, bwplot, levelplot. It built on grid which implements a different graphing system independent of the “base” system.
  • grDevices contains all code implementing the various graphics devices, including X11, PDF, PostScript, PNG, etc.

before making you chart, you need to think in the following:

  • To what device will the chart be sent ? The default on windows is windows, on Mac OS X it is quartz, on Unix it is x11. You can find a list of devices available on your system in ?Devices
  • Is The chart for viewing temporarily on the screen, or will it eventually end up in a paper ? Are you using it in a presentation ? charts included in a paper/presentation need to use a file device rather than a screen device.
  • Is there a large amount of data going into the chart ? Or is it just a few points ?
  • Do you need to be able to resize the chart ?
  • What graphics system will you use: base or grid/lattice ?
  • Base graphics are usually constructed with each aspect of the chart handled separately through a series of function calls; this is often conceptually simpler and allows plotting to mirror the thought process.
  • Lattice/grid graphics are usually created in a single function call, so all of the graphics parameters have to be specified at once; specifying everything at once allows R to automatically calculate the necessary spacings and font sizes.

You can close the graphics device for your system with dev.off() or set it by dev.set() or turn all the graphics devices with graphics.off().

The base graphics system has many parameters that can set and tweaked for the whole session using par() function. Any of these parameters can be overridden as arguments to specific plotting functions. Some important parameters are:

  • pch the plotting symbol (default is open circle). For more options run example(points)
  • lty the line type (default is solid line). More information here
  • lwd the line width, specified as an integer.
  • col the plotting color, specified as a number, string, or hex code; the colors function gives you a vector of colors by name.
  • las the orientation of the axis labels on the plot. More information here
  • bg the background color
  • mar the margin size
  • oma the output margin size

you can get the default value of a parameter by par(“param_name”)

Plotting function

  • plot make a scatterplot, or other type of plot depending on the class of the object being plotted.
  • lines add lines to a plot, given a vector x values and a corresponding vector of y values (or a 2-column matrix); this function just connects the dots
  • points add point to a plot
  • text add text lebels to a plot using specified x, y coordinates
  • title add annotations to x, y axis labels, title, subtitle, out margin
  • mtext add arbitrary text to the margins (inner or outer) of the plot
  • axis adding axis ticks/labels

RGui (64-bit)_2013-01-17_14-02-00

now try to add some red points to it (this can be used make different types of points on the same scatterplot)

RGui (64-bit)_2013-01-17_14-04-56

Now lets create a plot in a PDF file.

RGui (64-bit)_2013-01-17_14-24-59

nothing will appear on the screen but a file names “testPlot.pdf” will be created in your working directory and contains the histogram. Notice that you have to call dev.off() to close the PDF device.

Copying plots

You can copy your plot to another device. This is useful because some plots require a lot of code and it can be a pain to type all that in again for a different device.

  • dev.copy copy a plot from one device to another
  • dev.copy2pdf copy a plot to a PDF file
  • dev.list show a list of open graphics devices
  • dev.next switch control to the next graphics device on the device list
  • dev.set set control to a specific graphics device
  • dev.off close the current graphics device

 

Plotting with lattice graphics

Major lattice functions

  • xyplot the main function for creating scatterplots
  • bwplot for box-and-whiskers plots
  • histogram for histograms
  • stripplot like box-and-whiskers but with actual points
  • dotplot for dots on violin strings
  • splom scatterplot matrix
  • levelplot contoutplot for plotting image data

Lattice functions generally take a formula for their first argument, usually of the form y ~ x | f * g where x, y are the x, y variables, after | are the conditioning variables (optional). The second argument is the data frame or list from which the variables in the formula should be obtained. If no data frame or list is passed, then the parent frame is used. If no other arguments are passed, there are defaults that can be used. To see some example in action before getting all the details, run the following:

> library(lattice)
> library(nlme)
> xyplot(distance ~ age | Subject, data = Orthodont)
> xyplot(distance ~ age | Subject, data = Orthodont, type = "b")

Lattice functions behave differently from base graphics functions. Base graphics functions plot data directly on graphics device. Lattice graphics functions return an object of class trellis which can be stored. On the command line, trellis objects are auto printed; otherwise you have to print the trellis object.

Lattice functions have a panel function that controls what happens inside each panel of the entire plot. Lets create two sets of random values that are linearly related; and create a factor level that will be used as condition between them :

> x <- rnorm(100)
> y <- x + rnorm(100, sd = 0.5)
> f <- gl(2, 50, labels = c("Group 1", "Group 2"))
> xyplot(y ~ x | f)
RGui (64-bit)_2013-01-17_15-51-04

In the previous example we used the default panel function to draw each panel but we can write our own function to draw panels. In below example we just added a line representing the median of y.

> xyplot(y ~ x | f,
+ panel = function(x, y, ...) {
+ panel.xyplot(x, y, ...)
+ panel.abline(h = median(y), lty = 2) }
+ )

RGui (64-bit)_2013-01-17_15-56-46

mathematical annotation

R can produce LaTeX-like symbols on a plot for mathematical annotation. Math symbols in R are expressions that need to be wrapped in expression() function and passed to plotting functions (that accepts text like text, mtext, axis, legend). The output will be formatted according to LaTeX-like rules. ?plotmath gives you a list of allowed symbols. The following shows LaTex-like chart, x-axis, and y-axis titles:

> plot(x, y, main=expression(theta==0), ylab=expression(hat(gamma)==0), xlab=expression(sum(x[i]*y[i],i==1,n)))

RGui (64-bit)_2013-01-21_09-17-21

You can concatenate strings with LaTex symbols using *. like :

RGui (64-bit)_2013-01-21_09-24-29

If you want to use a computed value in the annotation, use substitute()  to substitute the right hand side variable with your computed value (provided in list()).

RGui (64-bit)_2013-01-21_09-31-46

Important help pages for plotting

  • ?par set or get graphical parameters
  • ?plot generic xy charts (base)
  • ?xyplot generic xy charts (lattice)
  • ?plotmath for mathematical annotation
  • ?axis for modifying axes

In this post we explored the basic charting capabilities in R using both base package and lattice package. Stay tuned for more R notes.

Thursday, January 17, 2013

Introduction to R – Random Variables Generation & Probability Distribution Functions

Simulation is important topic for statistical applications and scientific purposes in general.

Generating Random Numbers

The first step in simulation is to generate random values based on your variables distribution. R has a large number of functions that generate the standard random variables.

for Normal random variable generation

rnorm() simulate a simple random normal variable with a given mean and standard deviation and generate as many random values as requested.

RGui (64-bit)_2013-01-17_10-01-50

When generating any random variable setting the random number seed with set.seed ensures reproducibility. In the following example, notice that the first and the third sets are identical (both called set.seed with 1 before generating the numbers), and the second is different (because we didn’t set the seed)

RGui (64-bit)_2013-01-17_10-32-05

for Poisson random variable generation

rpois() simulate a Poisson random variable with a given rate (lambda) and generate as many random values as requested.

RGui (64-bit)_2013-01-17_10-39-53

Radom sampling

The sample function draws randomly from a specified set of (scalar) objects allowing you to sample from arbitrary distributions (sample space).

RGui (64-bit)_2013-01-17_11-31-03

if you didn’t specified the number of values you want, sample will give you random permutation of the sequence.

RGui (64-bit)_2013-01-17_11-32-51

as you noticed, by default sample will not repeat values, set parameter replace= TRUE to make it repeat .

RGui (64-bit)_2013-01-17_11-36-09

Probability distribution functions

Probability distributions usually have four functions associated with them. The functions are prefixed with:

  • r for random number generation
  • d for density
  • p for cumulative distribution
  • q for quantile function

some useful distributions are:

Nickname Distribution For more information
norm normal distribution ?Normal
pois poisson distribution ?Possion
binom binomial distribution ?Binomial
geom geometric distribution ?Geometric
t students t distribution ?TDist
f F distribution ?FDist
chisq Chi-Squared distribution ?Chisquare

function names are : prefix + distribution nickname. rnorm, rpois, rbinom,….. –> for random number generation, and so on.

In this note we introduced the basic functions for random number generation based on variable distribution type, arbitrary random sampling, and the associated probability distributions functions. Later will present each of them in detail.

Stay tuned for more R notes.

Wednesday, January 16, 2013

Introduction to R – Basic Debugging

In this post we will talk about native debugging support in R. Mostly, you start debugging when something goes wrong, which have many indications:

  • message A generic notification/diagnostic message produced by the message function; execution of the function continues.
  • warning An indication that something is wrong but not necessarily fatal; execution of the function continues; generated by the warning function; you got it after the function completion.
  • error An indication that a fatal problem has occurred; execution stops; produced by the stop function.
  • condition A generic concept for indicating that something unexpected can occur; programmers can create their own conditions.

The primary tools for debugging functions in R are:

traceback() prints out the function call stack after an error occurs; does nothing if there’s no error.

debug(f) flags a function for “debug” mode by setting a breakpoint at the beginning of the function f which allows you to step through execution of a function one line at a time. Use undebug() to turn off debug mode for that function. The debug mode turned off automatically when reloading your code using source().

When you execute your code and hit a breakpoint, you enter the debugger which called the browser in R. The command prompt will be something like Browse[2] instead of just >.

RGui (64-bit)_2013-01-16_16-51-58

Then you can invoke various debugging operations operations:

  • n or Enter to step through single line of code. If it is a line-level breakpoint, you have to hit n the first time, then Enter after that.
  • c to skip to the end of the current context (a loop or a function).
  • where to get a stack report
  • Q to exit the debugger and return to the > command line.
  • All normal R operations and functions are still available to you. So for instance to query the value of
    a variable, just type its name, as you would in ordinary interactive usage of R. If the variable’s name
    is one of the debug() commands, though, say c, you’ll need to do something like print(c) to print it
    out.

browser() suspends the execution of a function wherever it is called and puts the function in debug mode.

recover allows you to modify the error behavior so that you can browse the function call stack. It’s a global option that applies for the current global environment. You set it by calling options(error = recover) after that, any functions causes an error to occur you will get function call stack (like the one you got from traceback) with the option to jump into debugging any function that call stack.

RGui (64-bit)_2013-01-16_17-25-57

trace() allows you to insert debugging code into a function at specific places. For example trace(f, t) would instruct R to call the function t() every time we enter the function f(). This helps if you want to put a breakpoint in the beginning of a specific function in your code file without opening the file, modifying the function, reloading the file using source(). You can just call trace(Your_Function, browser) . When you done with debugging this function you can call, untrace(Your_Function) to remove that debugging feature from your function.

These are interactive tools specifically designed to allow you to pick through a function. There’s also the more blunt technique of inserting print/cat statements in the function.

Stay tuned for more R notes.

Tuesday, January 15, 2013

Introduction to R – Control Structures

Like every other programing language, R have control structures that allow you control the flow of your code execution.

If, else for testing a condition. else section is optional.

RGui (64-bit)_2013-01-15_15-43-49

if it’s all about assigning a value to a variable, you can do like this

RGui (64-bit)_2013-01-15_15-46-22

for for executing a loop for a fixed number of times. It takes a variable and assign it successive values from a sequence or vector.

RGui (64-bit)_2013-01-15_15-59-06

while for executing a loop while a condition is true. It begins by testing that condition, if it is true, the loop body will execute, if not, R will skip the loop.

RGui (64-bit)_2013-01-15_16-08-36

repeat for executing an infinite loop; the only way to exit the loop is to call break

RGui (64-bit)_2013-01-15_16-12-57

break for breaking the execution of a loop and continue from the next line of code after the loop (just like in the previous example)

next is used to skip an iteration of a loop

RGui (64-bit)_2013-01-15_16-35-49

Writing multiple lines of code on the command-line interactive environment is hard. I have used the script editor to write the code in this post and then copied it to R console.

Loop functions

Loop functions is so similar to loops. It just more compact and easy to use on command line.

lapply loop over a list and evaluate a function on each element. If the first argument wasn’t a list, it will be coerced to a list (using as.list). lapply always returns a list. Any arguments passed to lapply beyonf the FUN parameter, will be assigned to the ellipsis and then passed as parameters to FUN. FUN can be an anonymous function.

RGui (64-bit)_2013-01-16_12-46-03

sapply will try to simplify the result of lapply if possible. If the result is a list where every element is length 1, then it returns a vector. If the result is a list where every element is a vector of the same length (>1), it returns a matrix. If it can’t figure things out, it returns a list.

RGui (64-bit)_2013-01-16_12-59-27

apply apply a function over the margins of an array. Often used to apply a function to rows and columns of a matrix. It takes as parameters the array; margin which indicates which dimension will be used as parameter to the function applied; and the function to be applied. In the example below, when passing 2 for the margin it means apply the function to columns, so we got a result of vector with length 10 containing the sum of each column. When we passed 1 for the margin, it means apply the function to rows, so we got a result of vector with length 20 containing the sum of each row.

RGui (64-bit)_2013-01-16_13-15-23

for sums and means of matrix dimensions, we have some shortcuts:

  • rowSums = apply(x, 1, sum)
  • rowMeans = apply(x, 1, mean)
  • colSums = apply(x, 2, sum)
  • colMeans = apply(x, 2, mean)

tapply apply a function over subsets of a vector. It is equal to using split and lapply together. split take a vector or other objects and splits it into groups determined by a factor or list of factors.

mapply is a multivariate version of lapply. Each element will in 1:4 repeated by the corresponding number in 4:1.

RGui (64-bit)_2013-01-16_14-14-26

In this post we introduced the basic control structured in R. Its almost the same in any c-like programming language.

Stay tuned for more R notes.

Sunday, January 13, 2013

Introduction to R – Functions

Functions

Functions are just like what you remember from math class. Most functions are in the following form: f(argument1, argument2, ...) Where f is the name of the function, and argument1, argument2, . . . are the arguments
to the function. Here are a few examples of built-in functions:

RGui (64-bit)_2013-01-08_16-25-25_thumb[1]
Note in the last example that if you give the argument in the default order, you can omit the names. Some built-in functions have operator form like the following examples:
RGui (64-bit)_2013-01-08_16-29-23_thumb[3]
A function in R is just another object that is assigned to a symbol. You can define your own functions in R, assign them a name, and then call them just like the built-in functions. Writing your function code on the R Console is hard, so R provided a simple text editor for that. To write your code go to File >> New Script. This will open the R Editor, enter the following code
RGui (64-bit)_2013-01-10_09-05-56

You could select the code, copy and paste it in R console. Now you can call the function to get its result (note that entering the function name and hitting enter retrieves the function code. This is a useful trick to view function code before using it).
RGui (64-bit)_2013-01-10_10-29-47
Now lets go back to the editor and save the code in our working directory in MyCode.R (.R is the extension for R code files). To load the code in any R code file inside the console for use, use source() and pass the file name for it. Then you can use the code inside that file in the console. Each time you edit that code file, you have to call source() again to load the latest code.
RGui (64-bit)_2013-01-10_10-40-49

Arguments

A function definition in R includes the arguments’ names (in the previous example we didn’t use any arguments).
RGui (64-bit)_2013-01-10_11-08-31
Optionally, you can include default values for arguments. If you specify a default value for an argument, it will be considered optional (can be omitted from the function call). If you provided a value for an argument with default value, your value will override the default one. Non-optional parameters have to be provided in the function call.
RGui (64-bit)_2013-01-10_11-26-13

If you want to specify a variable-length argument list, specify (…) in the arguments to the function. Everything other than the named arguments, will be stored in the ellipsis … .To can then convert the ellipsis to a list to work with it.
RGui (64-bit)_2013-01-10_12-31-13
You can also refer directly to items within the ellipsis using the variables ..1 for the first item, ..2 for second and so on to ..9. Any argument that appear after the ellipsis in the function call, have to be named explicitly.
You can get the set of arguments accepted by a function, use the args function. NULL represents the function body.
RGui (64-bit)_2013-01-10_14-30-46
You can pass named arguments any ware in the function call by their name. Unnamed arguments have to match the order that they are listed in the function definition. The following lm() function calls are equivalent :
lm(data = mydata, y ~ x, model = FALSE, 1:100)
lm(y ~ x, mydata, 1:100, model = FALSE)
Named argument are helpful if you have a long argument list which you remember it by arguments’ names, not the order.

Lazy Evaluation

Arguments to functions are evaluated lazily, so they are evaluated only as needed. The function below never uses the argument b, so calling f(2) will not produce an error because the 2 gets positionally matched to a (the only variable needed).
RGui (64-bit)_2013-01-15_17-07-50
even if you will use a missing argument, R will not give an error until the first use of this missing argument. Everything before that will execute normally.
RGui (64-bit)_2013-01-16_07-49-45

Return Values

You can use the return function to specify the value to be returned by the function. Also R will return the last evaluated expression as the result of the function if no return() is found.
RGui (64-bit)_2013-01-10_12-52-41

Functions as Arguments

Many functions in R can take other functions as arguments. An example of these functions, the sapply function iterates through each element in a vector, applying another function to each element in the vector and returning the results.
RGui (64-bit)_2013-01-10_13-07-51

Anonymous Functions

You create functions that do not have names. These are called anonymous functions. Anonymous functions are usually passed as arguments to other functions.
RGui (64-bit)_2013-01-10_13-32-56
the R interpreter assigns the anonymous function functions(x) {x * 7} to the argument f of function apply.to.three then assigns 3 to the argument x of the anonymous function. So, it will ends up by evaluating 3 * 7 and returns the result.
anonymous functions can also be used with sapply()
RGui (64-bit)_2013-01-10_13-43-09
it is possible also to define an anonymous function and apply it directly to an argument.
RGui (64-bit)_2013-01-10_13-45-53

Scoping rules

How does R know which value to assign to which symbol ? How does R know what value to assign to the symbol lm ? Why doesn’t it give it the value of lm that is in the stats package ?
RGui (64-bit)_2013-01-16_09-13-32
When R tries to bind a value to a symbol, it searches through a series of environments (sets of symbols, objects,…) to find the appropriate value. When you are working on the command line and need to retrieve the value of an R object, the search begins with the global environment you working in it and look for a symbol name matching the one requested. If not found, R starts searching the namespaces of each of the packages on the search list. You can get the search list using search() function. .GlobalEnv represents your current working environment on the R command line, and its always the first element of the search list. The base package is always the last one. The order on the list matters
RGui (64-bit)_2013-01-16_09-25-18
If you loaded a package with library the namespace of that package will be in the 2nd position of the search list, and everything else will be shifted down the list.
RGui (64-bit)_2013-01-16_09-34-34
You can also load package on the command line window by going to Packages >> Load package >> then select the desired package and click Ok.
You can configure which packages to be loaded automatically on startup to be available for you. To do that open C:\Program Files\R\<Your-R-Version>\etc\Rprofile.site using Notepad and append the following to the bottom of the file. You can append whatever package you want to the vestor c and it will be loaded for your on startup.
local({
old <- getOption("defaultPackages")
options(defaultPackages = c(old, "car", "RODBC", "foreign", "DAAG", "MASS",

"lattice ", "latticedl", "sciplot", "tree", "lme4"))
})

Lexical Scoping Rules (or Static Scoping Rules)  determines how a value is associated with a free variable in a function. The values of free variables are searched for in the environments in which the function was defined.
So what is a a free variable ? a free variable is not a formal argument (arguments declared in function signature) nor a local variable that is declared and assigned in the function body. In the following example, x and y are formal arguments. z is a free variable. f <- function(x, y) { x^2 + y / z }
So what is an environment ? an environment is a collection of (symbol, value) pairs. Every environment has a parent environment, and it is possible for an environment to have multiple children. A function + an environment = a closure or function closure.
So, searching for the value for a free variable starts in the environment in which the function was defined, if not found, the search continued to the parent environment. The search continues until we hit the top-level environment ( workspace or the namespace of the package). After that the search continues down the search list until we hit the empty environment. If not found, an error is thrown.
You can get the environment of a function using environment() (for functions coded on the command line, that will be the global environment). You can get the parent of an environment using parent.env() (for functions coded on command line, it will be send item in the search list).
RGui (64-bit)_2013-01-16_10-37-17
Why does knowing lexical scoping rules matters ? Typically, a function is defined in the global environment, so that the values of free variables will be found in the user’s workspace (which is the right approach). However, in R you can define functions inside other functions, in this case the environment in which a function is defined is the body of another function.
In this post we talked about functions and using it weather from the console or from external files, functions as parameters, anonymous functions, and many other low level stuff.
Stay tuned for more R notes.