swirldev/swirl

:cyclone: Learn R, in R.

swirl's Issues

Beginning of Intro to R course

nxt() to resume, or anything else?

It appears that it's not just nxt() that will resume instruction after watching a video in Data Analysis - module1.

| Would you like to watch a brief video on mean, median, and mode?

Yes or No? yes

| Type nxt() to continue
> 4
[1] 4

| Mean, median, and mode are all measures of ____________.

Suggest use of parentheses when user incorrectly calls menu option

For example, during a lesson a user wishes to skip a question and incorrectly types skip, omitting the () at the end. We can use something like the following (adapted from Hadley's frndly.R) to alert them of their mistake.

attr(skip, "source") <- "| Hey you! To evaluate a function in R, 
    you need to put () on the end."

Module objects using attributes to store instructor info, package dependencies, etc…

Test 2.0 on various machines/operating systems

Have a handful of people install and run 2.0 on their machines (windows, osx, linux) — maybe we can do this on virtual machines to make sure dependencies are loaded properly

Termination after video issue

Name of the course: Data Analysis module1
Problem: Video not available terminated swirl, resuming module also encountered error and terminated.

Some screenshots:

OS: Windows 8 x64

Session Info:
R version 3.0.1 (2013-05-16)
Platform: x86_64-w64-mingw32/x64 (64-bit)

locale:
[1] LC_COLLATE=English_United States.1252
[2] LC_CTYPE=English_United States.1252
[3] LC_MONETARY=English_United States.1252
[4] LC_NUMERIC=C
[5] LC_TIME=English_United States.1252

attached base packages:
[1] stats graphics grDevices utils datasets methods base

other attached packages:
[1] swirl_2.0.1

loaded via a namespace (and not attached):
[1] evaluate_0.4.7 openintro_1.4 plotrix_3.5-3 pwr_1.1.1 stringr_0.6.2
[6] testthat_0.7.1 tools_3.0.1

play() feature

During a cmd_question, when the user is on the prompt, if they type play(), they should break temporarily from the back and forth interaction with swirl so they can experiment. Callback remains active and waits for a resume() command from the user to resume instruction. resume() conflicts with our current function naming, but I'm sure we can think of some alternative.

Figure/plot content class that sources appropriate plot files

(Minor) Module description before choosing a module

Ok, so I'm a swirl 1st timer, and following the default menu, I end up at the point where I choose the recommended "Intro to R" course. I'm then asked to choose a module like shown in the picture:

It'd be nice at that point to at least see the title of each module or some kind of information describing them.

I browsed a bit through the code, and it seems to me that https://github.com/swirldev/swirl/blob/master/R/menu.R#L70 which reads

modules <- dir(file.path(courseDir(e), courseU), pattern="module")

(Side note, if you change the file, does the line link reflect this?)
constructs the names of the modules from the available "module*" directories. In this case, module1, 2 and 3 from https://github.com/swirldev/swirl/tree/master/inst/Courses/Intro_to_R

I guess that a simple option is to rename those directories to something like:

• module1-SomeTitle
• module2-AnotherTitle
• module3-FinalTitle

Or maybe it's best to create some metadata describing the modules, which is then loaded and that can contain better titles/short descriptions.

Anyhow, it's not a big thing because once you choose a module (like module 1), you get a nice short intro description:

In the end, congratulations for the release of swirl 2.0!! and the continuous development (I see that a 2.1 is already here!).

Nick, you should give a talk about it at JHSPH!

Cheers,
Leo

Two small bugs

1. Esc flag in resume.default should be made FALSE before every legit exit. Now fixed.
2. Had failed to mark progress file as done under certain circumstances. This caused a bad resume state if user exited via Esc rather than Enter when last row of mod was text. Appears to be fixed.

Add estimated time to complete full swirl course to FAQ

The title of this issue pretty much sums it up.

Basic unit tests (using testthat)

Smooth transition between modules after completion

Full welcome menu similar to 1.0

1. New or existing user?
2. If New, get user name and email (to be used as unique identifier) then present course options
3. If Existing, start over or resume progress?

Transition after module completion

Right now, when a user completes a module, swirl presents the full menu of courses to them. Maybe we should try this instead:

Would you like to proceed to the next module in this course?

If yes (and next module exists), begin next module.

If no, present user with full course menu.

I'm happy to work on a solution in a separate branch.

Warning message after resuming Test Modules, Module 1

| Would you like to continue with one of these modules?

1: Test Modules module1
2: No. Let me start something new.

Selection: 1

| Now compute the mean of these numbers by calling the mean() function on your new
| vector.

warning messages from top-level task callback 'mini'
Warning message:
In is.na(object) : is.na() applied to non-(list or vector) of type 'NULL'

User progress with random number generation will be restored differently.

Currently, user progress tracking saves the expressions which a user enters, but not their values. If such an expression involves generation of random variables, e.g., rnorm(100), then when user progress is restored, the same expression will evaluate differently, which may confuse a user.

Failure to check for empty Course and Module directories.

Course and Module menus fail to check for empty directories. This could be significant if a user happens to run swirl("dev"). In dev mode swirl looks for courses in the working directory (where they would be for a package developer, but not for a user.)

dir(path) will return character(0) if path is an empty directory (or if path is a file, apparently.)

Treatment of new vs additional plots

See swirl 1.0. This only matters when user is resuming progress. May just ignore for this release, but if we do we'll have to cut OpenIntro. May do that anyways.

newVar should have a right hand side, i.e., newVar=somename (duplicates swirl 2.0 #10)

The test keyphrase, newVar, should have a right hand side. Currently, the newVar test (runTest.newVar in AnswerTests.R) tests whether the user has created a new variable and, if so, stores its value in e$newVar for use in a subsequent test.

If the keyphrase had a right hand side, e.g., newVar=for_later_use, the value could be referenced by a name of the course author's choosing, in this case e$for_later_use. A subsequent test could then reference the new variable by that name, e.g., useFunc=mean(for_later_use).

Must modules have the naming scheme /module[0-9]+/ ?

In relation to line 70 of menu.R:

modules <- dir(file.path(courseDir(e), courseU), pattern="module")

Is there a design reason other than an inherent ordering that the names of the directories must be module1, module2, etc?

Clean up package directory, retaining only necessary files/code

Include NEWS.md file in package

Remove data/cars.csv

There are legacy dependencies in the code which must be removed first.

Using swirl to explain a package's functions

Hello,

I'm wondering how hard would it be to use swirl for further documenting a package and if you foresee any difficulties.

As you most likely know, vignettes are supposed to explain how different functions from the same package can be used and how they are connected. However, it seems to me that having a swirl module would help teach the users how to use the package. After all, it's a completely different thing to read it than to type the commands and even swirl::play() with the output. Also, by the way swirl works, modules help teach users the names of the arguments of the functions instead of relying on the argument order. For example, the seq(0, 10, by=0.5) in module 2 from the intro to R course only works like that and not when typed as seq(0, 10, 0.5); which is good for learning/teaching.

I can see that the special .Rmd format is fairly straightforward. What I haven't seen (maybe it's there) is equivalents to the shiny::runApp(), shiny::runUrl(), shiny::runGist(), shiny::runGitHub() functions.

For the package documentation use case, all you really need is an equivalent of the shiny::runApp() function where you feed it the correct location of the swirl module (it's the appDir argument).

The rest would be also very useful for other situations, like developing modules and sharing them on the web (runUrl), gists (runGist) or as part of git repos (runGitHub). After all, I don't think that the plan is for developers to submit pull requests with the new modules and have them all be a part of the swirl package (this would greatly discourage people from making modules and I bet that it would be a big burden on you).

Returning to the package use case, would there be any complications when running R CMD check? I know that ultimately any issues could be avoided by using the dontrun clause, but that takes away automatic checks to make sure that the package tutorial is working. After all, I can foresee a case where you update a function but then forget to update the tutorial, and without the error popping up in R CMD check you wouldn't notice it until a user reports it.

Thanks,
Leo

unit test: correct answer should pass associated answer tests

Gina's idea, though I'm posting it.

If skip() is invoked, swirl acts for the user using a module's CorrectAnswer column. The correct answer is then subjected to tests, just as the user's answer would have been. If the correct answer fails to pass its own tests, e.g., because of a typo, the question will be impossible to skip.

Unit tests could insure that a module's correct answers pass their associated tests.

Updated DESCRIPTION file based on final codebase

Fails to run initModule.R code when restoring an unfinished module.

True of both original prototype and new "dev" methods.

User progress with random number generation will be restored differently. (duplicates swirl 2.0 issue #8)

Currently, user progress tracking saves the expressions which a user enters, but not their values. If such an expression involves generation of random variables, e.g., rnorm(100), then when user progress is restored, the same expression will evaluate differently, which may confuse a user.

Add skip() feature

Don't forget to export the function so the user has access to it. Should it simply increment the content row number?

Revise 1.0 content

Remove or revise bad/duplicate content and shed obsolete columns

Swirl 2 exits silently, fails to print message.

Unlike swirl 1, swirl 2 exits silently, failing to print an exit message when quitting. This could confuse users.

Change all instances of "swirlfancy" to "swirl"

DESCRIPTION file, hard-coded items, etc...

`runTest.expr_identical()` has trouble with lonesome variable

The entry in AnswerTests column is expr_identical=x

Better names for modules

Currently, module names have the form, mod*_new.csv. The _new is vestigial and should be dropped, although users never see the actual file names. Attendant code changes would be needed.

Users see the names of directories in which the csv files reside. Currently, they are named module1, module2, etc. It would be useful if these directories could have names more indicative of content. Quite possibly they could, even with no attendant code changes. Directory names such as "1 Variables and Assignments" may work just fine, although I haven't tested the possibility.

Use roxygen2 for documentation (duplicates swirl2.0 issue #5)

Needed for CRAN.

Remove deprecated code prior to Jan 14

Creating directory permission denied

Can I set the default location of where modules are downloaded to? I tried using setwd() before running swirl, but it did not help.

My error message is below. This occurs after selecting a module

Thanks for any help.
D

Selection: 1
Error in gzfile(file, mode) : cannot open the connection
In addition: Warning messages:
1: In dir.create(udat, recursive = TRUE) :
cannot create dir '\phsabc.ehcnet.ca\homedir', reason 'Permission denied'
2: In gzfile(file, mode) :
cannot open compressed file '\phsabc.ehcnet.ca/homedir/HomeDir05/dfrizzell/R/win-library/3.0/swirl/user_data/Darren/Intro_to_R_module1_.rda', probable reason 'No such file or directory'

| Leaving swirl now. Type swirl() to resume.

Diagnostic messages not being returned in "dev" mode

This only applies in "dev" mode (i.e. when running swirl("dev")).

results$message is NULL in expectThat(), so diagnostic messages are not being returned when user gets the wrong answer.

Empty last lines in csv files cause module termination errors

If there is an extra newline at the end of a csv module, the module may not be properly terminated, at least in "dev" mode. We probably should check for empty rows when loading modules.

Typo in module 1 of Intro to R course: 5 + 7 = 13

> x <- 5+7

| Great job!

| You'll notice that R did not print the result of 13 this time. When you use the assignment operator, R assumes that you
| don't want to see the result immediately, but rather that you intend to use the result for something else later on.

mechanism to smoothly install/load packages required for modules

Tests for functions edited by users (duplicates swirl 2.0 #12)

At a recent meetup, Peter demonstrated how edit(f), where f, is a function, could be used in swirl. The result would be a function modified or largely created by the user. Tests for such functions are likely to be fairly specialized, just as unit tests for any function would be. How might they be specified in a key phrase?

Perhaps a key phrase syntax borrowed from Hadley's testthat package would work. For instance, there could be an expect_that key phrase whose right hand side specifies parameters analogous to those of the epynomous testthat function, e.g.,
expect_equals=f(x),y
expect_throws=f(u),v
(I'm not sure how x, y, u, and v would be specified.)

Blank AnswerTests entry causes error.

If its AnswerTest column is blank, any answer to a question should be considered correct. Currently, it causes an error.

skip_after parameter in swirl_out calls is unused but displayed.

swirl_out's skip_after parameter appears in 7 calls, e.g., in present.default:

swirl_out(current.row[, "Output"], skip_after=TRUE)

It is not used and does not appear in swirl_out's signature. Possibly its appearance in the calls is vestigial. Possibly it was left out of swirl_out by mistake.

Detail:

swirl_out <- function(...) { wrapped <- strwrap(str_c(..., sep = " "), width = getOption("width") - 2) message(str_c("| ", wrapped, collapse = "\n")) }

This causes skip_after's value to be appended to the message, e.g.,

| Leaving swirl now. Type swirl() to resume. TRUE

Waiting for more info before fixing.

Same expressions, evaluated in different contexts, can give different answers.

This issue includes #7, #24, and #35, and hopefully explains them better.

The main problem involves evaluating the same expression in two different contexts and expecting them to have the same result. They won't, necessarily.

Examples:

• x <- 2*x. The user types the expression in response to a question and, in checking the answer, swirl evaluates it again, inadvertently picking up the value of x on the right from the global environment where it has already been doubled.
• newVar. The user is asked to create a new variable with any chosen name. The course author uses runTest.newVar to check if the user has done so. The test re-evaluates the user's expression in its run-time environment while the user has evaluated it in the global environment. A variable appearing on the expression's right hand side will not, in general, be in runTest.newVar's immediate environment so R will look for a matching name in enclosing environments of which there are four. (See details below.) R will use the first match it finds which will not necessarily have the same value as that in the global environment. Either an error or a wrong value could result.
• Random numbers. Random numbers are generated as data in one swirl session and restored by re-generation in a second. Random seeds in the two cases will generally be different, and so will the data.
• Corruption during play(). The user creates a new variable, x <- c(1, 2, 3), in response to a question. Swirl detects and saves its value while testing. The next question asks the user to take its mean. Instead, the user decides to play, during which the value of x changes. Say x <- c(4, 5, 6). When the user types nxt(), the question repeats. The user uses c(4, 5, 6) for x, while swirl uses c(1, 2, 3), and counts the user's answer as incorrect.

Details. Using the debugger on Test Modules, module 1:

NOTE: Earlier draft of this post was in error. As a rule, R uses lexical scoping. "Lexical scoping looks up symbol values based on how functions were nested when they were created, not how they are nested when they are called."--Adv R Programming. I should have used parent.env() rather than parent.frame() earlier.

| First, create a vector of numbers using the c() function and store that vector in
| a variable of your choice.

x <- c(3, 5, 7, 11, 13)

Called from: eval(expr, envir, enclos)

Browse[1]> n

debug at /home/william/dev/r/swirlfancy/R/answerTests.R#78: eval(e$expr)

Browse[2]> ls()

[1] "e" "keyphrase"

Browse[2]> exists("x", environment(), inherits=FALSE)
[1] FALSE

Browse[2]> exists("x", environment(), inherits=TRUE)
[1] TRUE

Browse[2]> e0 <- environment()

Browse[2]> (e1 <- parent.env(e0))
<environment: namespace:swirlfancy>

Browse[2]> exists("x", e1, inherits=FALSE)
[1] FALSE

Browse[2]> (e2 <- parent.env(e1))
<environment: 0xac3d990>
attr(,"name")
[1] "imports:swirlfancy"

Browse[2]> exists("x", e2, inherits=FALSE)
[1] FALSE

Browse[2]> (e3 <- parent.env(e2))
<environment: namespace:base>

Browse[2]> exists("x", e3, inherits=FALSE)
[1] FALSE

Browse[2]> (e4 <- parent.env(e3))
<environment: R_GlobalEnv>

Browse[2]> exists("x", e4, inherits=FALSE)
[1] TRUE

Browse[2]> x
[1] 3 5 7 11 13

Recommended tests for question in mod3 of intro to R?

To add (or "concatenate") your name to the end of my_char, use the c() function like this: c(my_char, "your_name_here"). Place your name in double quotes where I've put "your_name_here". Try it now, storing the result in a new variable called my_name.

my_name <- c(my_char, "Nick")

*** .ans_tests
is_a=character, my_name; uses_func=c; creates_var=my_name; [[more tests here...?]]

menu selection - no error detection

If the user enters an invalid numeric choice for a given menu the software accepts it as if it were correct instead of being caught as an error.

Failure to account for dependencies when checking for creation of a new variable

In several places we test if an expression creates a new variable by evaluating the expression in a clean environment. This would fail if the "right side" of an assignment depended upon previously defined variables which are inaccessible from the clean environment.

By luck, this does not seem to affect current content.

Full tests for responses implemented in 1.0 content (which will occur after Nick audits the 1.0 content)