Title: | A Toolbox for Writing 'swirl' Courses |
---|---|
Description: | A set of tools for writing and sharing interactive courses to be used with swirl. |
Authors: | Sean Kross [aut, cre], Nick Carchedi [aut], Chih-Cheng Liang [ctb], Wush Wu [ctb] |
Maintainer: | Sean Kross <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.5.3 |
Built: | 2024-10-13 03:03:05 UTC |
Source: | https://github.com/cran/swirlify |
Licensing your course is important if you want to share your course. For more information see https://github.com/swirldev/swirlify/wiki/Licensing-Your-Course. For more information about Creative Commons licenses see http://creativecommons.org/licenses/. For more information about software licenses see http://www.gnu.org/licenses/license-list.en.html.
add_license(author, year = format(Sys.Date(), "%Y"), open_source_content = TRUE, content_license = "CC BY 4.0", open_source_data = TRUE, data_license = "CC0", open_source_code = TRUE, code_license = "MIT")
add_license(author, year = format(Sys.Date(), "%Y"), open_source_content = TRUE, content_license = "CC BY 4.0", open_source_data = TRUE, data_license = "CC0", open_source_code = TRUE, code_license = "MIT")
author |
The author of the course. This can be an organization. |
year |
The year the course was written. |
open_source_content |
If |
content_license |
Specify which Creative Commons license you would like
to use for the content of your course. This must be equal to one of the
following: |
open_source_data |
If |
data_license |
Currently this value must be equal to |
open_source_code |
If |
code_license |
Specify which open source software license you would like
to use for the content of your course. This must be equal to one of the
following: |
## Not run: # Add a license with simple open source options add_license("Team swirl") # Add a license so that derivative works are shared alike add_license("Team swirl", content_license = "CC BY-SA 4.0", code_license ="GPL3") # Add a license that reserves all of the author's rights add_license("Team Bizzaro swirl", open_source_content = FALSE, open_source_data = FALSE, open_source_code = FALSE) ## End(Not run)
## Not run: # Add a license with simple open source options add_license("Team swirl") # Add a license so that derivative works are shared alike add_license("Team swirl", content_license = "CC BY-SA 4.0", code_license ="GPL3") # Add a license that reserves all of the author's rights add_license("Team Bizzaro swirl", open_source_content = FALSE, open_source_data = FALSE, open_source_code = FALSE) ## End(Not run)
The MANIFEST file located in the course directory allows you to specify the order in which you'd like the lessons to be listed in swirl. If the MANIFEST file does not exist, lessons are listed alphabetically. Invisibly returns the path to the MANIFEST file.
add_to_manifest()
add_to_manifest()
MANIFEST file path, invisibly
## Not run: # Check what lesson you're working on, then add it to the MANIFEST get_current_lesson() add_to_manifest() ## End(Not run)
## Not run: # Check what lesson you're working on, then add it to the MANIFEST get_current_lesson() add_to_manifest() ## End(Not run)
Returns and prints the number of questions in the current lesson.
count_questions()
count_questions()
Number of questions as an integer, invisibly
## Not run: count_questions() ## End(Not run)
## Not run: count_questions() ## End(Not run)
Jump right in to the current swirl lesson without needing to navigate swirl's menus. It's also possible to jump into the middle of a lesson.
demo_lesson(from = NULL, to = NULL)
demo_lesson(from = NULL, to = NULL)
from |
Question number to begin with. Defaults to beginning of lesson. |
to |
Question number to end with. Defaults to end of lesson. |
## Not run: # Demo current lesson from beginning through the end demo_lesson() # Demo current lesson from question 5 through the end demo_lesson(5) # Demo current lesson from question 8 through question 14 demo_lesson(8, 14) ## End(Not run)
## Not run: # Demo current lesson from beginning through the end demo_lesson() # Demo current lesson from question 5 through the end demo_lesson(5) # Demo current lesson from question 8 through question 14 demo_lesson(8, 14) ## End(Not run)
Get question numbers for any questions matching a regular expression
find_questions(regex)
find_questions(regex)
regex |
The regular expression to look for in the lesson.
This gets passed along to |
A vector of integers representing question numbers.
## Not run: set_lesson() find_questions("plot") find_questions("which") ## End(Not run)
## Not run: set_lesson() find_questions("plot") find_questions("which") ## End(Not run)
Prints the current lesson and course that you are working on to the console
get_current_lesson()
get_current_lesson()
## Not run: get_current_lesson() ## End(Not run)
## Not run: get_current_lesson() ## End(Not run)
Decode Student's Submissions from Google Forms
google_form_decode(path = file.choose())
google_form_decode(path = file.choose())
path |
The path to a |
A data frame containing each student's results.
## Not run: # Choose the csv file yourself google_form_decode() # Explicity specify the path google_form_decode("~/Desktop/My_Course.csv") ## End(Not run)
## Not run: # Choose the csv file yourself google_form_decode() # Explicity specify the path google_form_decode("~/Desktop/My_Course.csv") ## End(Not run)
Create an easily shareable HTML version of your swirl lesson. This function
detects the lesson you are working on
automatically via getOption('swirlify_lesson_file_path')
,
converts it to R Markdown (Rmd), then generates a stylized HTML
document and opens it in your default browser. To prevent clutter,
the Rmd files are not kept by default, but they can be kept
by setting keep_rmd = TRUE
.
lesson_to_html(dest_dir = NULL, open_html = FALSE, keep_rmd = FALSE, quiet = FALSE, install_course = TRUE)
lesson_to_html(dest_dir = NULL, open_html = FALSE, keep_rmd = FALSE, quiet = FALSE, install_course = TRUE)
dest_dir |
Destination directory (i.e. where to put the output files). If not set, default is the directory which contains the course directory. |
open_html |
Should the HTML file produced be opened in your browser?
Default is |
keep_rmd |
Should the Rmd file be kept after the HTML is
is produced? Default is |
quiet |
Should the Rmd rendering output be silenced? Default
is |
install_course |
Should the course
be installed? Default is |
The output is formatted to be a readable, standalone tutorial. This means that information contained in the swirl lesson such as answer tests and hints are excluded from the Rmd/HTML output.
Useful for creating paths to a particular swirl course, as you might want
to do in files like initLesson.R
.
make_pathname(name)
make_pathname(name)
name |
A vector of strings. |
A string vector where spaces are replaced with underscores.
make_pathname("Developing Data Products") # "Developing_Data_Products" make_pathname(c("R Programming", "Exploratory Data Analysis")) # "R_Programming" "Exploratory_Data_Analysis"
make_pathname("Developing Data Products") # "Developing_Data_Products" make_pathname(c("R Programming", "Exploratory Data Analysis")) # "R_Programming" "Exploratory_Data_Analysis"
Creates a new lesson and possibly a new course in your working directory. If
the name you provide for course_name
is not a directory in your
working directory, then a new course directory will be created. However if
you've already started a course with the name you provide for course_name
and that course is in your working directory, then a new lesson will be created
inside of that course with the name you provide for lesson_name
.
new_lesson(lesson_name, course_name, open_lesson = TRUE)
new_lesson(lesson_name, course_name, open_lesson = TRUE)
lesson_name |
The name of the lesson. |
course_name |
The name of the course. |
open_lesson |
If |
## Not run: # Make sure you have your working directory set to where you want to # create the course. setwd(file.path("~", "Developer", "swirl_courses")) # Make a new course with a new lesson new_lesson("How to use pnorm", "Normal Distribution Functions in R") # Make a new lesson in an existing course new_lesson("How to use qnorm", "Normal Distribution Functions in R") ## End(Not run)
## Not run: # Make sure you have your working directory set to where you want to # create the course. setwd(file.path("~", "Developer", "swirl_courses")) # Make a new course with a new lesson new_lesson("How to use pnorm", "Normal Distribution Functions in R") # Make a new lesson in an existing course new_lesson("How to use qnorm", "Normal Distribution Functions in R") ## End(Not run)
.swc
file of the course you are working on"Pack" the course you are working on into a single compressed file that is
easy to share. Invisibly returns the path to the .swc
file.
pack_course(export_path = NULL)
pack_course(export_path = NULL)
export_path |
Optional, full path to the directory you want the swirl course file to be exported to. If not specified, then the file will appear in the same directory as the course directory. |
A string, the path to the new .swc
file, invisibly.
## Not run: # Set any lesson in the course you want to pack set_lesson() # Pack the course pack_course() # Export the .swc file to a directory that you specify pack_course(file.path("~", "Desktop")) ## End(Not run)
## Not run: # Set any lesson in the course you want to pack set_lesson() # Pack the course pack_course() # Export the .swc file to a directory that you specify pack_course(file.path("~", "Desktop")) ## End(Not run)
Choose a lesson to work on with swirlify by specifying the path to the
lesson.yaml
file or interactively choose a lesson file.
set_lesson(path_to_yaml = NULL, open_lesson = TRUE, silent = FALSE)
set_lesson(path_to_yaml = NULL, open_lesson = TRUE, silent = FALSE)
path_to_yaml |
Optional, full path to YAML lesson file. If not specified, then you will be prompted to select file interactively. |
open_lesson |
Should the lesson be opened automatically?
Default is |
silent |
Should the lesson be set silently? Default is
|
## Not run: # Set the lesson interactively set_lesson() # You can also specify the path to the \code{yaml} file you wish to work on. set_lesson(file.path("~", "R_Programming", "Functions", "lesson.yaml")) ## End(Not run)
## Not run: # Set the lesson interactively set_lesson() # You can also specify the path to the \code{yaml} file you wish to work on. set_lesson(file.path("~", "R_Programming", "Functions", "lesson.yaml")) ## End(Not run)
Find the directory where swirl courses are stored
swirl_courses_dir()
swirl_courses_dir()
A string with the path to where swirl is searching for courses.
This function launches a user interface for writing swirl lessons.
swirlify(lesson_name = NULL, course_name = NULL)
swirlify(lesson_name = NULL, course_name = NULL)
lesson_name |
The name of the new lesson you want to
create. The default value is |
course_name |
The name of the new course you want to
create. The default value is |
## Not run: # Set lesson beforehand set_lesson() swirlify() # Start a new lesson in your current directory swirlify("Lesson 1", "My Course") ## End(Not run)
## Not run: # Set lesson beforehand set_lesson() swirlify() # Start a new lesson in your current directory swirlify("Lesson 1", "My Course") ## End(Not run)
Run basic tests on all questions in the lessons listed in the MANIFEST
.
See add_to_manifest
for information about the MANIFEST
file.
test_course()
test_course()
## Not run: # To test a course, set any lesson in that course as the current lesson set_lesson() # Run tests on every lesson in that course listed in the MANIFEST test_course() ## End(Not run)
## Not run: # To test a course, set any lesson in that course as the current lesson set_lesson() # Run tests on every lesson in that course listed in the MANIFEST test_course() ## End(Not run)
Run basic tests on all questions in the current lesson.
test_lesson()
test_lesson()
## Not run: # Set a lesson interactively set_lesson() # Run tests on that lesson test_lesson() ## End(Not run)
## Not run: # Set a lesson interactively set_lesson() # Run tests on that lesson test_lesson() ## End(Not run)
This function is deprecated. Please use demo_lesson
instead.
testit(from = NULL, to = NULL)
testit(from = NULL, to = NULL)
from |
Question number to begin with. Defaults to beginning of lesson. |
to |
Question number to end with. Defaults to end of lesson. |
.swc
file into a swirl courseInvisibly returns the path to the unpacked course directory.
unpack_course(file_path = file.choose(), export_path = dirname(file_path))
unpack_course(file_path = file.choose(), export_path = dirname(file_path))
file_path |
Optional, full path to the |
export_path |
Optional, full path to the directory where the swirl course
should be exported. If not specified, the course will appear in the same
directory as the |
A string, the path to the unpacked course directory, invisibly.
## Not run: # Unpack a course and interactively choose a .swc file unpack_course() # Unpack a course where the .swc file is explicitly specified unpack_course(file.path("~", "Desktop", "R_Programming.swc")) # Unpack a course and specify where the .swc file is located and where the # course should be exported. unpack_course(file.path("~", "Desktop", "R_Programming.swc"), file.path("~", "Developer", "swirl")) ## End(Not run)
## Not run: # Unpack a course and interactively choose a .swc file unpack_course() # Unpack a course where the .swc file is explicitly specified unpack_course(file.path("~", "Desktop", "R_Programming.swc")) # Unpack a course and specify where the .swc file is located and where the # course should be exported. unpack_course(file.path("~", "Desktop", "R_Programming.swc"), file.path("~", "Developer", "swirl")) ## End(Not run)
Template for R command question
wq_command(output = "explain what the user must do here", correct_answer = "EXPR or VAL", answer_tests = "omnitest(correctExpr='EXPR', correctVal=VAL)", hint = "hint")
wq_command(output = "explain what the user must do here", correct_answer = "EXPR or VAL", answer_tests = "omnitest(correctExpr='EXPR', correctVal=VAL)", hint = "hint")
output |
Text that is displayed to the user. |
correct_answer |
A string that designates the correct answer, in this case an R expression or a value. |
answer_tests |
An internal function from |
hint |
A string that is printed to the console if the user answers this question incorrectly. |
## Not run: # While writing a new lesson by hand just use: wq_command() # If converting from another format to a swirl course you may want to sue the # API: wq_command("Assign the value 5 to the variable x.", "x <- 5", "omnitest(correctExpr='x <- 5')", "Just type: x <- 5") ## End(Not run)
## Not run: # While writing a new lesson by hand just use: wq_command() # If converting from another format to a swirl course you may want to sue the # API: wq_command("Assign the value 5 to the variable x.", "x <- 5", "omnitest(correctExpr='x <- 5')", "Just type: x <- 5") ## End(Not run)
Template for figure questions
wq_figure(output = "explain the figure here", figure = "sourcefile.R", figure_type = "new")
wq_figure(output = "explain the figure here", figure = "sourcefile.R", figure_type = "new")
output |
Text that is displayed to the user. |
figure |
An R script that produces a figure that is displayed in the R plotting window. |
figure_type |
Either |
## Not run: # While writing a new lesson by hand just use: wq_figure() # If converting from another format to a swirl course you may want to sue the # API: wq_figure("Here we can see the curve of the normal distribution.", "normalplot.R", "new") ## End(Not run)
## Not run: # While writing a new lesson by hand just use: wq_figure() # If converting from another format to a swirl course you may want to sue the # API: wq_figure("Here we can see the curve of the normal distribution.", "normalplot.R", "new") ## End(Not run)
Template for output without a question
wq_message(output = "put your text output here")
wq_message(output = "put your text output here")
output |
Text that is displayed to the user. |
## Not run: # While writing a new lesson by hand just use: wq_message() # If converting from another format to a swirl course you may want to sue the # API: wq_message("Welcome to a course on the central limit theorem.") ## End(Not run)
## Not run: # While writing a new lesson by hand just use: wq_message() # If converting from another format to a swirl course you may want to sue the # API: wq_message("Welcome to a course on the central limit theorem.") ## End(Not run)
Template for multiple choice question
wq_multiple(output = "ask the multiple choice question here", answer_choices = c("ANS", "2", "3"), correct_answer = "ANS", answer_tests = "omnitest(correctVal= 'ANS')", hint = "hint")
wq_multiple(output = "ask the multiple choice question here", answer_choices = c("ANS", "2", "3"), correct_answer = "ANS", answer_tests = "omnitest(correctVal= 'ANS')", hint = "hint")
output |
Text that is displayed to the user. |
answer_choices |
A vector of strings containing a user's choices. |
correct_answer |
A string that designates the correct answer. |
answer_tests |
An internal function from |
hint |
A string that is printed to the console if the user answers this question incorrectly. |
## Not run: # While writing a new lesson by hand just use: wq_multiple() # If converting from another format to a swirl course you may want to sue the # API: wq_multiple("Which of the following is not a planet in our solar system?", c("Venus", "Saturn", "Pluto"), "Pluto", "omnitest(correctVal= 'Pluto')", "It's the smallest celestial body you can choose.") ## End(Not run)
## Not run: # While writing a new lesson by hand just use: wq_multiple() # If converting from another format to a swirl course you may want to sue the # API: wq_multiple("Which of the following is not a planet in our solar system?", c("Venus", "Saturn", "Pluto"), "Pluto", "omnitest(correctVal= 'Pluto')", "It's the smallest celestial body you can choose.") ## End(Not run)
Template for exact numerical question
wq_numerical(output = "explain the question here", correct_answer = "42", answer_tests = "omnitest(correctVal=42)", hint = "hint")
wq_numerical(output = "explain the question here", correct_answer = "42", answer_tests = "omnitest(correctVal=42)", hint = "hint")
output |
Text that is displayed to the user. |
correct_answer |
The numerical answer to the question. |
answer_tests |
An internal function from |
hint |
A string that is printed to the console if the user answers this question incorrectly. |
## Not run: # While writing a new lesson by hand just use: wq_numerical() # If converting from another format to a swirl course you may want to sue the # API: wq_numerical("The golden ratio is closest to what integer?", "2", "omnitest(correctVal=2)", "It's greater than 1 and less than 3.") ## End(Not run)
## Not run: # While writing a new lesson by hand just use: wq_numerical() # If converting from another format to a swirl course you may want to sue the # API: wq_numerical("The golden ratio is closest to what integer?", "2", "omnitest(correctVal=2)", "It's greater than 1 and less than 3.") ## End(Not run)
Template for R script question
wq_script(output = "explain what the user must do here", answer_tests = "custom_test_name()", hint = "hint", script = "script-name.R")
wq_script(output = "explain what the user must do here", answer_tests = "custom_test_name()", hint = "hint", script = "script-name.R")
output |
Text that is displayed to the user. |
answer_tests |
An internal function from |
hint |
A string that is printed to the console if the user answers this question incorrectly. |
script |
The name of the script template to be opened. This template
should be in a directory called |
## Not run: # While writing a new lesson by hand just use: wq_script() # If converting from another format to a swirl course you may want to sue the # API: wq_script("Write a function that adds three numbers.", "add_three_test()", "Something like: add3 <- function(x, y, z){x+y+z}", "add-three.R") ## End(Not run)
## Not run: # While writing a new lesson by hand just use: wq_script() # If converting from another format to a swirl course you may want to sue the # API: wq_script("Write a function that adds three numbers.", "add_three_test()", "Something like: add3 <- function(x, y, z){x+y+z}", "add-three.R") ## End(Not run)
Template for text question
wq_text(output = "explain the question here", correct_answer = "answer", answer_tests = "omnitest(correctVal='answer')", hint = "hint")
wq_text(output = "explain the question here", correct_answer = "answer", answer_tests = "omnitest(correctVal='answer')", hint = "hint")
output |
Text that is displayed to the user. |
correct_answer |
The answer to the question in the form of a string. |
answer_tests |
An internal function from |
hint |
A string that is printed to the console if the user answers this question incorrectly. |
## Not run: # While writing a new lesson by hand just use: wq_text() # If converting from another format to a swirl course you may want to sue the # API: wq_text("Where is the Johns Hopkins Bloomberg School of Public Health located?", "Baltimore", "omnitest(correctVal='Baltimore')", "North of Washington, south of Philadelphia.") ## End(Not run)
## Not run: # While writing a new lesson by hand just use: wq_text() # If converting from another format to a swirl course you may want to sue the # API: wq_text("Where is the Johns Hopkins Bloomberg School of Public Health located?", "Baltimore", "omnitest(correctVal='Baltimore')", "North of Washington, south of Philadelphia.") ## End(Not run)
The url
provided for video_link
can be a link to any website.
wq_video(output = "Would you like to watch a short video about ___?", video_link = "http://address.of.video")
wq_video(output = "Would you like to watch a short video about ___?", video_link = "http://address.of.video")
output |
Text that is displayed to the user. |
video_link |
A link to a url. Please make sure to use |
## Not run: # While writing a new lesson by hand just use: wq_video() # If converting from another format to a swirl course you may want to sue the # API: wq_video("Now Roger will show you the basics on YouTube.", "https://youtu.be/dQw4w9WgXcQ") ## End(Not run)
## Not run: # While writing a new lesson by hand just use: wq_video() # If converting from another format to a swirl course you may want to sue the # API: wq_video("Now Roger will show you the basics on YouTube.", "https://youtu.be/dQw4w9WgXcQ") ## End(Not run)