Patreon: Become a Runestone Patron
As you have seen from the data in previous post Runestone is growing and helping to introduce many students at many institutions to computer science, data science, web programming, you name it. I think we are helping to make the world a better place.
When I left my full time teaching job at Luther College a year ago, it was with the goal of making Runestone my full time work. That is still my goal. Originally I had given myself a year to figure out a business model. Then Google presented one to me. Come and consult with us, they said. Help us with our project. That has been, and continues to be, a great opportunity for me, but it won’t last forever. And, its not really a business model, And I need to strike a better balance between writing books and developing the Runestone platform!
Make Textbooks Free
I could follow a model of charging every student a modest sum of money to access books on Runestone Academy But did you know that about half of the schools that use Runestone are public high schools? That model does not work for public school students, and I don’t want to leave them behind. Runestone has saved students millions of dollars in textbook costs, and I’d like to keep it that way.
I could create a freemium business model, where the basic books are free, but more advanced features and teaching materials would cost the school money. That may still be a path to follow, but that makes the code more complex to check whether I should expose a feature to someone based on some flag that tells me if you’ve paid or not.
So instead, I’m doubling down on the supporter model by starting a Patreon campaign. Patreon is for people like us, for content creators that need support to keep on creating! You can use a trusted website to make a regular monthly payment that will come to Runestone.
We have so much work that we could do to make Runestone better than it is today. In my ideal world I would like to be able to hire students that have been through one or more Runestone courses. How cool is that? You got your introduction to CS through Runestone and now you can help develop the very platform that helped you get a start. At the same time they would get valuable resume building experience!
So, today I’m asking you to please support Runestone. Become a patron. It doesn’t have to be a lifetime commitment, but if Runestone has helped you this year why not help us in return?? Go to our page on Patreon and become a patron today.
Then, make sure you tell in the comments what you would like to see most in the next generation of Runestone tools and books.
Thanks!
New Feature Friday
Yes I’m posting this on Monday, but Friday sounded like a better title. Many instructors have asked for the ability to download student data to import into a spreadsheet. This was a feature we removed a couple years back because downloading the raw stream of click information really wasn’t that useful, and we take data security of student information very seriously.
So, this weekend I pushed a new release of the Runestone server that gives you four new reports that you can either view online or download as a CSV file to import into your favorite spreadsheet program.
Click on the Overview Reports link to access
The four new reports are:
Count of Subchapter Activities
First Interaction with all Activities
Last Interaction with all Activities
Number of interactions with each Activity
The count of subchapter activities is a good cross check on reading assignments. If a student wants to know why they are not getting full credit, this report will show you how many distinct activities in each subchapter a student has attempted.
Count of unique components a student has interacted with.
As you can see, this report is organized by Chapter and then Subchapter. And then one column for each student. So you can see that btest has been looking at the Classes and ClassesBasics chapters, but hasn’t done any of the work in the AdvancedFunctions chapter. Meanwhile, bmiller has been busy with Conditionals and Dictionaries. Yes, sorting by chapter number would be nice, and will be coming soon, it requires a couple of other pieces to be in place first.
The Number of interactions with each activity takes you one level deeper and shows the list of known activities in each Subchapter and the number of interactions each student has taken with each activity. Compare this next figure with the last. In the previous figure you see that bmiller had 6 interactions in the graphing_with_altair subchapter. Now you see exactly which six components they were, and how many times bmiller interacted with each of them.
Count of interactions with each component.
The First Interaction and Last Interaction reports are just variations on this one, that show you the first time a student interacted with some component. “How come I didn’t get credit for doing this?” Because this report shows that you didn’t do it until 2 hours after the deadline.
All four of these are downloadable by clicking the “Download CSV” button.
These reports came about because I was writing about making pivot tables with Pandas, and I realized how easy it would be to apply my lesson to real life to make some useful reports for you. I know there may be more reports like this that you would find useful, so please feel free to make requests in the comments section, or make an issue on our Github page
Wandering Students
One problem with grading on Runestone is that I have noticed that students don’t always end up doing their work in the right class. Sometimes students don’t remember where they should be and end up Googling their way into Runestone. But often times this googling lands them in the “open to anyone” version of the textbook the instructor has chosen for the course. This means their activities are recorded under that course and not your own.
To combat this behavior I have added two features that require you to rebuild your course to activate.
The Navbar for your course should now contain your course name, and not the name of the textbook. Teach them to pay attention to that. We are going to develop more visual cues to clearly differentiate between the open version of a course and a bespoke course this summer.
When students are logged we now check to make sure that if they are in a course for which they have not registered we will alert them, and then take them to the course selector to make sure they are in the proper course.
We love to hear from yo, so let us know what you think of these updates!
A Lab in Three Easy Steps
This weeks post is an update of a post that has been continually one of the most popular on my Personal Blog So I thought it would be good to update it a bit and publish it here. These instructions can be used to create a lab or any kind of in-class activity that you want to use with your students. Its a good “Getting Started with Runestone” tutorial.
Getting Started
The major steps in getting started are
Installing Python
Installing the Runestone Components
Building your first lab
Install Python
If you are on a Mac you are already done with this step.
If you are on Windows you will need to go to Python.org
If you are an advanced Python user you may want to may want to create a virtualenvironment for this project but it is not a requirement.
If you are on Windows you may want to edit your PATH environment variable following the instructions here. Again, Mac users can ignore this.
Installing the Runestone Components
You are going to need to use the command line for the rest of this tutorial, so start up a terminal (/Applications/Utilities/Terminal) on macOS or run Powershell or cmd.exe on Windows) I will repeat myself here. These commands need to be run from the command line, not from the Python shell.
Run the pip command
$ pip install runestone
Or on Windows if you have not modified your PATH try:
C:\Python34Scriptspip.exe install runestone
From now on I’m only going to give the Mac way of running the commands. If you are on windows you will need to add C:\Python34Scripts to the beginning of the command and add .exe to the end.
You can watch as a lot of text goes scrolling by. But as long as you don’t get any errors you should be good to go. You only need to do these first two steps once. Once you have installed Python and Runestone you will not have to do it again.
Starting your first Runestone Project
Here is a session of me on my computer creating a simple project.
$ mkdir mynewproject
$ cd mynewproject
$ runestone init
This will create a new Runestone project in your current directory.
Do you want to proceed? [Y/n]: y
Next we need to gather a few pieces of information to create your configuration files
Project name: (one word, no spaces): MyLab
Path to build dir [./build]:
Path to deploy built site [../../static]:
Use Runestone Web Services (true, false) [false]:
Your Name [bradleymiller]:
Title for this project [Runestone Default]: My First Lab
Use Simple Python3 Semantics [false]: true
Default ActiveCode language [python]:
Enable inline Activecode downloads by default (single activecode downloads may be enabled with the :enabledownload: flag) [false]:
Done. Type runestone build to build your project
You should answer no to using the Runestone services as at this point you are just making a static page with no ability to capture and store data about your students. You can write Runestone labs for lots of languages, including C++ and Java but Python, Javascript, and HTML are the only languages supported directly in the browser.
At this point you will have the following files and folders:
mynewproject/
_static/
_sources
_templates
build
conf.py
pavement.py
The
_staticfolder is for things like images or Javascript files.The
_sourcesfolder is where you will put your own writing. To start with there are a couple of example files for you.The
_templatesfolder is for styling. There is a default set of templates that match the Runestone interactive look and feel. That is a good thing to start with. Once you become more familiar with the system you may want to customize the templates or even make your own.The
conf.pyfile is used by Sphinx, and contains information from some of the questions you answered when you initialized your project.The
pavement.pyfile is used for building and setting build parameters.
All of these files are important, and you should not delete any of them.
Next run runestone build This command will create a build/mynewproject folder with an index.html file in it. If you want you can now run runestone serve and then go to your browser and open up the following URL http://localhost:8000/index.html Yay! You have a webpage. Feel free to explore a bit to get an idea about some of the components you can use in your lab.
Writing your Own Lab
OK, lets edit _sources/index.rst Initially it looks like this:
=====================
This Is A New Project
=====================
SECTION 1: Introduction
:::::::::::::::::::::::
Congratulations! If you can see this file you have probably successfully run the ``runestone init`` command. If you are looking at this as a source file you should now run ``runestone build`` to generate html files. Once you have run the build command you can run ``runestone serve`` and then view this in your browser at ``http://localhost:8000``
This is just a sample of what you can do. The index.rst file is the table of contents for your entire project. You can put all of your writing in the index, or as you will see in the following section you can include additional rst files. those files may even be in subdirectories that you can reference using a relative path.
The overview section, which follows is an ideal section to look at both online and at the source. It is pretty easy to see how to write using any of the interactive features just by looking at the examples in ``overview.rst``
SECTION 2: An Overview of the extensions
::::::::::::::::::::::::::::::::::::::::
.. toctree::
:maxdepth: 2
overview.rst
SECTION 2: Add more stuff here
::::::::::::::::::::::::::::::
You can add more stuff here.
If you are not familiar with markup languages, this file should still be quite readable to you, and you can probably easily guess what most things do. Runestone uses a markup language called restructuredText. There is a very nice, short tutorial here. But maybe the most important reminder is that restructuredText is like Python, indentation matters.
To give you an idea of what you see in the example above, the section that starts with .. toctree:: is called a directive and it creates a table of contents for you. the maxdepth part sets the table of contents to show sections and subsections. And the line with overview.rst indicates that it is a file that should be included in the overall web page. More on all of this later. Our first task is simply going to be to wipe everything out, and start over. Using a plain text editor change index.rst to look like this:
=============
My Sample Lab
=============
Part 1: Turtle Graphics
=======================
In this section we will do the following:
* Create a turtle
* Make the turtle draw a box
.. activecode:: turtle1
import turtle
timmy = turtle.Turtle()
for i in range(4):
timmy.forward(100)
timmy.right(90)
Now it is your turn. Can you modify the program to make timmy draw an octagon instead of a square?
Now save the file and rerun the runestone build command. Everything should build without a problem and you can now run runestone serve and open up http://localhost:8000 from your browser. Notice that you can change the program and rerun it right from your browser.
It is probably obvious that you can create headings and subheadings. Unordered lists are created using * and the runnable code examples are created by the .. activecode:: directive. The name turtle1 must be unique on the webpage, other than that it is not used for too much at this point. The rest of the activecode directive contains plain old python code, but it must be indented to line up with the a in activecode. All indented lines are included as the body of the activecode directive, regular text processing starts at the first unindented line.
There you have it. You have created a very nice little lesson without a lot of hassle. The Runestone and Sphinx tools take care of all of the formatting for you!
Documentation
There are lots of resources to help you with writing resources with Runestone.
Using the
runestone doccommand. Runestone has some basic documentation built right into the command.runestone doc --listgives you a list of all of the various components. You can guess what they do from the name pretty well.
$ runestone doc --list
Runestone Directives List
activecode
clickablearea
codelens
datafile
disqus
dragndrop
fillintheblank
mchoice
parsonsprob
poll
qnum
reveal
shortanswer
showeval
tab
tabbed
timed
usageassignment
video
vimeo
youtube
To get the detailed Syntax and options for any of the components you can run runestone doc <componentname>
runestone doc fillintheblank
.. fillintheblank:: some_unique_id_here
Complete the sentence: |blank| had a |blank| lamb. One plus one is: (note that if there aren't enough blanks for the feedback given, they're added to the end of the problem. So, we don't **need** to specify a blank here.)
- :Mary: Is the correct answer.
:Sue: Is wrong.
:x: Try again. (Note: the last item of feedback matches anything, regardless of the string it's given.)
- :little: That's right.
:.*: Nope.
- :2: Right on! Numbers can be given in decimal, hex (0x10 == 16), octal (0o10 == 8), binary (0b10 == 2), or using scientific notation (1e1 == 10), both here and by the user when answering the question.
:2 1: Close.... (The second number is a tolerance, so this matches 1 or 3.)
:x: Nope. (As earlier, this matches anything.)
config values (conf.py):
- fitb_div_class - custom CSS class of the component's outermost div
Giving Students Browser Access to the Lab
At this point the build folder has a static webpage that you can upload to any web server. If you have your own webpage hosted on a school server that you normally use for class you can make your Lab available to the students by simply taking the folder mynewproject inside the build folder and putting that on your website. The folder is self contained and can be hosted on any web server.
If you know the IP Address of your own computer and you simply want to give let students bring up the webpage from your computer you can do that too. For example, lets suppose you know that your IP address is 10.0.0.23 Your students can get everything they need from http://10.0.0.23:8000/index.html
In another post, I’ll cover how to host your lab using Github pages.
If you have questions or comments on getting going, please leave them below, or join our community on Slack or our Google Group. You’ll find links to these resources on our Support Page
Runestone Dashboard
I’ve recently started working on a Runestone Dashboard to monitor our progress in terms of the number of students, and traffic, bandwidth, new courses that are created etc. I thought that it would be interesting to share a few of the graphs with you.
We launched Runestone.academy in September of 2017 so we are closing in on the end of our second academic year. After 5 years on our old hosting service it was time for a fresh start. This first graph shows you the number of students that have registered each week since we started.
You can clearly see the beginning of semester registration peaks, and of course its exciting to see the year over year growth. Its interesting to note that fall registrations tend to be larger than spring registrations, but that may be because many students register for a course that continues in the spring so there is no need to re-register.
With the number of new courses in our library growing, I was really interested to see what courses people are using the most. This is not necessarily a fair comparison as thinkcspy has been around the longest and is a very popular book in its own right. But its really fun to see how quickly the Foundations of Python Programming book has taken off, since that was just launched in the fall of 2018. The APCS A Review book continues to be a very valuable resource for many schools. This graph is showing only the courses built in the last 14 weeks so it should be a pretty good indicator of what is happening Spring semester of 2019.
Not surprisingly, the number of students registering by base course has the same shape as the previous graph. But this does count students that are studying the material as part of a formal course, as well as independent learners that just sign up for one of the open textbooks that anyone can learn from.
Finally, many people ask about the daily traffic. There are many ways of thinking about this, from the number of unique students each day to the number of pages served each day to the number of student activities per day. this graph shows just the count of student activities each day for the last 14 months.
Its pretty interesting to note our “summer lull” which definitely shows that we are getting most of our use during the school year. No surprise there. Its also amazing to see how much our traffic has grown from Spring semester 2018 to Spring semester 2019. Finally, you can see the orange colored days are the weekends. Is this definitive proof that our students don’t study as much as we would like on the weekends!?
Book Spotlight: How to Think like a Data Scientist
It is said that the most important characteristic of a data scientist is curiosity. So how do you structure a class that encourages students to be curious and ask questions of the data? When I first taught DS-320 at Luther in 2017 I had to make it up as I went. Luckily I had some great, and very patient students that were willing to go with it. My main goal was to “let the data drive the learning!” My vision for the course was to pick some data sets, do exploratory data analysis on them, generate a bunch of questions as a class, and then figure out what we needed to know in order to answer our questions. As a course, I thought this was an amazing and really fun way to structure the learning. It doesn’t lend itself to a structured day by day syllabus since you can’t necessarily predict everything you are going to learn when you start! But we learned a LOT in that class, and we had a lot of fun doing it.
Finding textbooks for undergraduate data science courses is really hard. There is little agreement on curriculum at the undergrad level and definitely not much with a more liberal arts emphasis. So, I was thrilled when the Applied Computing Series team at Google asked me to take the lead on creating a book for their AC201 course.
This book is an attempt to build some structure around the approach described above, without totally killing the spontaneity of encouraging students to ask good questions of the data. You are never going to find a data set to make everyone happy, but if you pick several data sets hopefully enough of them will interest enough students to keep everyone engaged. In this text (so far) we look at World Happiness data, Movie Reviews, the CIA world factbook, United Nations speeches, Bike Rental data from Washington DC and shopping cart data from Instacart.
The learning objectives of the course are as follows:
Articulate the data science processing pipeline
Extract data using SQL
Gather data from the Internet using web API’s and screen scraping
combine data from different sources
Clean the data
Handle missing data/finding outliers/fixing data
Normalizing and rescaling data
Visualize the data
Translate questions to analysis and analysis to interesting stories
Analyze data
Single variable regression, logistic regression
Market basket analysis
Cohort analysis
Sentiment analysis, exposure to Bayes Theorem
Time series
Geographic analysis
Simulations, Monte Carlo
Understand statistical significance and how to test for it using practical simulation techniques.
You can see how the individual skills learned map onto different data sets and chapters by taking a look at the preface
One of the big challenges of this was how to make the book interactive even while wanting students to install and run their own copy of a Jupyter notebook server. The approach is to have the book lead the students through some analysis while asking them to do work in the notebook and bring answers back into the textbook. For example use the notebook to find the busiest bike rental pickup point, and then paste the id of that station into a multiple choice question in the text.
Maybe at some point we’ll have a way to embed Jupyter notebook cells into a Runestone text, but that will require a LOT more computing power.
In the meantime please take a look. The book, as is, has been classroom tested in four schools this spring, but I think there is a lot more content that could be added, and the existing content still needs work to clean up. So feel free to let us know about any issues on github.
Runestone History and a Roadmap
Runestone Interactive was created in 2011 during Brad’s sabbatical. I should have been working on a new edition for two paper textbooks, but I had the worst kind of writers block. I just couldn’t stand the idea of a paper textbook for computer science in 2011. Textbooks should let you run the examples! Even better textbooks should encourage you to edit the examples and play around with them. When a google search for python in the browser turned up the skulpt project I knew I was onto something.
After spending a couple of months building a turtle graphics module, I realized that nobody would write a book if they had to do a ton of javascript programming for every example. So I started to look around and found Sphinx and docutils. Although markdown is probably more popular, Sphinx/docutils is so much more extensible. So I set out about writing some extensions to Sphinx, and the rest is history. Now adding an example to the textbook is just as easy as copy/pasting the code into the plain text document!
We first used Runestone in the classroom in 2012 for 60 students at Luther College. From 2012 to now Runestone has grown to serving 25,000 students a day around the world at something like 800 institutions. The real surprise came when I discovered that many of them were high schools. This made me very happy !
Our library now lists 18 books! But there are probably at least another 18 that I don’t know about. The number of translations of Runestone books that I have randomly discovered is amazing. That makes me very happy also.
The tagline “democratizing textbooks for the 21st century”, is really inspired by a class visit with Guy Kawasaki in a class I taught during January Term when I would take 12 students to Silicon Valley to visit with entrepreneurs, at all kinds of companies. It is, in Guy’s terms, a mantra. It means that textbooks should be free! You should not be excluded from learning about CS because you cannot afford $200 for a textbook! If Runestone can play a role in disrupting textbook publishing that would be awesome. I’m hoping that Runestone can serve 2 million students a day in my lifetime! It also means that textbooks should be interactive, intelligent, living documents.
In 2018, I decided to leave my dream job at Luther College to focus all of my energy on a new dream job, Runestone Interactive. I was growing increasingly frustrated that there were not enough hours in the day to teach classes, attend committee meetings, grade homework, prep lectures, and work on Runestone. This turned out to be a great leap of faith, as not long after I made the decision I was contacted by a some team members in Google’s EngEDU organization that wanted to use Runestone as part of their Applied Computing Series of courses. The goals of Runestone and the goals of the AC team could not be more aligned. Runestone is also used as a platform for teaching courses by LaunchCode. I get to work with a bunch of really smart Googlers, and have time to continue to develop Runestone.
A Roadmap for the Future
The sign of a good project is that the todo list never gets shorter. Every time I cross something off the list three new things replace it. There is no doubt that with focus, time and energy that Runestone can be way more awesome than it is today. The details and current development priorities are outlined here .
What I am most interested in is creating a sustainable community around Runestone so that it will continue after I am not caring for it every day. This means a concerted effort on funding, on growing the number of students, and building the number of authors and developers.
All of the above has been happening organically, but we need to accelerate on all fronts. This new home page, is one part of that. YOu will begin to see articles detailing development, as well as posts about how people are using Runestone in the classroom in real life. Please share this site with your friends, and colleagues, introduce influencers to Runestone and help us spread the word.