TRAKLA2 User Guide
From SVGWiki
This guide is mainly aimed at the users of the TRAKLA2 system, both students and instructors. The guide describes the use of the TRAKLA2 web environment. At the end of the guide there are also some instructions on how to maintain and administer the TRAKLA2 environment.
All the examples in this guide use the URL http://trakla.cs.hut.fi/ as the URL of the TRAKLA2 system.
Contents |
Introduction
TRAKLA2 is an automatic exercise system for algorithms and data structures. It is the follower of the WWW-TRAKLA system that has been in production use more than 10 years.
TRAKLA2 is a Web-based, computer-aided learning environment for helping to teach algorithms and data structures. Not only does TRAKLA2 provide links to visualizations that portray a variety of algorithms, but it also distributes tracing exercises to the student and then automatically evaluates the student's answers. The student creates his or her answer to these exercises using an interactive graphical editor that is coded in the Java language. Thus, a Java enabled web browser is needed in order to solve the exercises.
The student manipulates conceptual views of data structures simulating actions a real algorithm would perform. The system provides a new input each time the student tries to solve an exercise. This, in turn, allows the student to practice the algorithm until it is learned. Progress on the course can be followed in real time at the exercise page that shows the points received from each exercise.
The Student's View
Most of the users of TRAKLA2 are students, and therefore the student's user interface is the "default" user interface to the TRAKLA2 system. It is the only user interface that is visible at the server root directory http://trakla.cs.hut.fi/. There is a separate user interface for teachers, which is not linked from the student's UI.
The Top Border
The student's user interface can be recognized from the blue border at the top of each page. The border contains links to the different utility pages in the system. The border stays the same on all pages in the system. The links on the border are as follows:
- Exercises. If you're logged in, this link will direct you to the system main page. If you're not logged in, the link will direct you to the login page.
- Ebook. This link directs you to the TRAKLA2 Ebook (in the Finnish version) or to page that links to additional material (English version).
- Settings. This link will direct you to the settings page, if you're logged in, or to the login page otherwise.
- Feedback. This link will direct you to the feedback page.
- Help. This link will direct you to the help page.
- In Finnish/In English. This link will change the language used to Finnish/English. By default, the language is decided by the locale selected in the web browser. If locale does not match either language, English is used.
- Login/Logout When not logged in, this link reads Login, and will direct you to the login page. When logged in, this link reads logout, and will log you out from the system.
The Login Page
The login page contains three different functionality.
First, using the login form a user can log in to the student's user interface. In case of a problem (incorrect password, non-existing username), an information message is shown in red above the login form. After a successful login, the student is directed to the main page.
Second, there is a link to a page where an user can register to the test course. The test course contains all the exercises contained in the system, and is primarily intended for testing and development purposes.
Third, there is a link to a form, where the user can request for a new password. In order to request a new password, the user must input their username and the email address he's given for the system. The username and email are validated in order to prevent the use of the form to send spam.
The Main Page
The main page is the heart of the student's user interface. From there, the student can access exercises and monitor his or her progress. Furthermore, if the student is registered to multiple courses in the system, he or she can also change the course shown.
The current active course is shown immediately below the top border. If the student is registered to just one course in the system, the active course is shown as plain text. However, if the student is registered to multiple courses, the current course is shown in a pull-down menu that can also be used to change the current active course. The course is changed by selecting a new course from the menu and pushing the show -button.
Below the course selection, is the description of the course, if there is one. If there is no course description, none is shown. The course description is free text and can, for example, give an overview of the course.
Below the course description is the round and exercise table. The exercises on TRAKLA2 courses are divided into rounds. Each round has a number of exercises associated to it, a deadline and possibly minimum number of points required for passing the round.
When first visiting the main page, all rounds are minimized. When a round is minimized you can see the name of the round, its deadline (the deadline will be shown in red, if it has already passed), the current point total for the round, and the number of submissions done.
By clicking on the name of a minimized round, it can be expanded. The expanded view shows all the exercises on the round, points gained from each exercise, and the number of submissions to each exercise. An exercise that has been submitted at least once, but from which less than maximum points have been gained, is shown in yellow background. An exercise from which maximum points have been gained is showed in green background. Furthermore, the total number of points gained from the round is also shown, as is the minimum points required for passing the round.
From the expanded view of a round, the student can go to the exercise page by clicking on an exercise.
Below the exercises, there is a short summary of the student's results. The summary contains the student's current point total for all rounds, the minimum number of points required for passing the whole course (which may be different from the number of points required for passing each round separately), and the maximum number of points available on the course.
The Exercise Page
On the exercise page, the student can solve exercises. At the top of the exercise page, just below the top border, are the name of the course, the round and the exercise. By clicking on the course or the round, the student can return to the main page. If the deadline for the exercise has passed, a warning message is shown above the name of the exercise.
Below the name of the exercise is a dark grey navigation bar. At the left end of the navigation bar there are buttons for hiding the exercise instructions and the pseudocode, which are shown below the bar, and for opening them in a new window. Pushing these buttons will change what is shown on the page, but will not cause the system to reload the page (therefore pushing them will not reset the applet).
At the left end of the bar there are buttons for going to the previous and next exercise (if such exist).
Below the navigation bar there are the instructions for doing the exercise, the exercise pseudocode (if such has been written), and the Java applet for solving the exercise. The instructions are typically divided into two tabs: task-tab and instructions-tab. The task tab gives a typically very short description about what the student is expected to do in the exercise. The instructions tab will give more elaborate instructions on how to use the applet for solving the exercise.
Below the instructions there is the pseudocode for the exercise. If no pseudocode has been specified, this part of the page is missing. If required, the pseudocode can have several tabs.
To the right of the pseudocode (or below the instructions, if no pseudocode is present) is the Java applet for solving the exercise.
The Applet
The Java applet allows students to solve exercises by directly manipulating the data structures represented graphically. As a matter of fact, the user manipulates an actual data structure through the GUI. We call this Algorithm Simulation. This has several benefits. First, the exercises can be assessed automatically in order to provide instant feedback. Second, we can provide individually tailored exercises that one can apply to test his or her understanding of a particular data structure or algorithm. Third, if the student fails to solve an exercise, the system is able to provide model solution for each problem instance.
Interaction
The GUI for each exercise has the same look and feel. However, some exercises might require special purpose buttons and functionality that are explained in the assignment. In general, however, the GUI is composed of the following parts.
Control panel and buttons appear on the top of the screen. These are common for all exercises. One can adjust the font size, apply the control panel called Animator or push the control buttons that are used for resetting the exercise, viewing the model answer, and for grading and submitting the answer to the server. Below the control panel appear the data structures the student is asked to interact with. Usually, the upper structure is the input data structure for the algorithm in question. The user manipulates the lower target data structure, for example, by drag and dropping the input keys - or any object - into the target structure.
An object (key, node, reference, or the whole structure) can be selected by using the left mouse button. The very basic manipulation process includes only drag-and-dropping these objects. In order to, for instance, insert a key from an array into a binary search tree, the selected key must be drag-and-dropped from the array to the tree. If an exercise contains tasks that are not possible to complete by just drag-and-drop, special command buttons are provided.
Animator
With the Animator control panel one can traverse through the animation sequence backward and forward and look at the changes performed during the simulation process. The simulation can be continued at any point (of course, the states in the sequence appearing after the new operation are lost).
- Backward - go to the previous state, if that exists.
- Forward - go to the next state, if that exists.
- Begin - go to the first state.
- End - go to the last state.
Control Buttons
- Reset - initialize the exercise. This also resets the input data (new random items). In some exercises the Reset button is not enabled until the exercise has been submitted.
- Model answer - create the model answer. The model answer opens into a new window so that it is viewable side by side with one's own solution. Note, however, that it is not possible to submit an exercise after the model answer is revealed without resetting the exercise first. In some exercises the Model answer button is not enabled until the exercise has been submitted.
- Submit - compare the answer with the model solution and submit answer to the server. The system informs how many steps are correct out of all steps in the animation sequence resulted from the algorithm simulation.
- Compare - Compare the model answer your own answer side-by-side in a separate window. This functionality differs from Model answer in that both visualizations are shown in the same window. It is not possible to submit an exercise after viewing the comparison window. This functionality has not been enabled in all exercises.
- Font size - this selector allows to change the size of the visualized data structures. Note, however, that the applet area must be predefined and thus too large selection might result some of the structures to disappear from the screen.
The Settings Page
In the settings page you can change your own information or your password. For changing the password you need to input your old password and the new password. Other changes that can be done in the settings page are: change your name (real name stored in the system, not user name), your email address, and your preferred language.
The Feedback Page
From the feedback page you can send feedback to the system administrators or teachers.
The Help Page
The help page contains instructions on the use of the system. Some parts of this guide are identical to information on the help page.
The Teacher's Point of View
For the teachers, there is a separate web user interface. This interface is called "monitor" interface, since most of the functionality in it can be used to monitor a course and the student's progress on the course. There are, however, some small administrative actions that can be taken through the interface.
The monitor interface is not linked to the TRAKLA2 root page http://trakla.cs.hut.fi/. It can be found, instead in the URL http://trakla.cs.hut.fi/monitor where the monitor login page resides.
The monitor interface can easily be recognized by the red navigation bar at the top of each monitor interface page.
This top border contains functionality that are available from each page of the monitor interface. The functionality at the top border works only when the instructor has logged into the system. Otherwise clicking on any of the links will just direct the user back to the login page. The following are available at the border:
- Main page link. This link directs to the main page of the monitor interface.
- Master exercise list. This link directs to the master exercise list page.
- Compare Courses. This link directs to the course comparison page.
- Server activity. This link directs to the server activity page.
- Admin. This link is shown if the user has administration priviledges. It directs to the main page.
- Logout. Logs out of the system.
Main Page
The main page contains most of the functionality required for day-to-day operations of a given instructor. In the main page, the instructor can view many details about the course he's giving.
At the top of the page, below the top border, is the course selection menu. If an instructor has more than one course in the system, he can use the menu to change the current active course.
Below the active course is the search form. Using the form an instructor can search for a given student using either the student's user name in the system or the student's name. Searching for a given student directs the user to the student details Page, if a student is found. Otherwise an error message is shown above the search form.
Below the search form are the course information, with the name of the course on the top. There are several different views that can be used to view a course. These views can be selected using the buttons in the grey navigation bar, just below the course name. The different views are Round details view, Point distribution view, Students view, and Course details view. In addition, the instructor can use the navigation bar to view the course as student (opens in a new window) or to get the course results as text.
Round Details View
The round details view is the default view that is shown to the instructor when he logs in to the system. The round details view gives an overview the students' performance on each round on the course. As in the student's user interface, each round is by default minimized, and its details can be shown by clicking on the round.
The round details contains a number of statistics for the round, and a number of statistics for each exercise on the round.
The round details contains the following statistics for the round:
- The round description, if such has been written. It is also possible to add and modify round descriptions through the monitor interface.
- Timestamp when the round opens (that is, when round is shown to the students).
- Deadline for the round
- Total number of submissions for the round
- Average student points for the round
- Maximum points for the round
- The make-up factor. This is a penalty factor (from between 0 and 1) for submissions submitted after the deadline for the round. If this value is 0, late submissions always get 0 points, if it is 1, late submissions are not penalized.
- Minimum points required for passing the round
The round details contains the following statistics for each exercise (in the form name - description) :
- Exercise - Name of the exercise. By clicking on the exercise name, the instructor can go to the exercise view.
- Max points - Maximum points for the exercise
- Max submissions - Number of times the exercise can be submitted
- Languages - Supported languages (languages on which there is an exercise description available)
- # Answers - Number of submissions to the exercise
- % students - Percentage of the students on the course who have made at least one submission to the exercise
- Average (all) - Average points for all submissions
- Average (per student) - Average points for the students (best submission for each student is taken into account)
- %ave - The average percentage of points (out of maximum) when only students who have submitted the exercise are taken into account
- %W - The average percentage of points when all students on the course are taken into account
Point Distribution View
The point distribution view gives a simple distribution of points for each round on the course. For each round, the view shows the number of students (both absolute and relative to number of students on the course) that have gained a given number of points, and the cumulating number of students who have gained at most a given number of points.
Weakness of the view is that only those students who have submitted at least one submission on the round are shown.
Students View
The students view shows a matrix of all students on the course. For each student their username, real name, email address, points for each round, total points, and grade are shown. Also, the minimum and maximum points for each round and for the whole course are shown.
By clicking on a student's username, the teacher can go to the student details page to look at the student's information in more detail.
Course Details View
The course details view shows the course description, basic information about the course, and graphics about the student results and grading on the course.
It is possible to edit the course descriptions, and add new ones for supported locales, from the monitor interface. The instructor can modify an existing description by clicking on the edit link. This will open a text box for editing. The edits can be stored by clicking on the modify-button, and canceled by clicking on the undo changes -link.
It is also possible to add new descriptions for supported locales. In order to do so, the instructor needs to select the language and give the localized name of the course (without a course code). For example, if a course was named "T-106.1220 Data Structures and Algorithms T", where T-106.1220 is the course code, then the instructor should put "Data Structures and Algorithms T" to the course name -textbox. Te new description can be added to the database by clicking the add-button.
Clear Cache
This button is shown to system administrators in the right end of the grey navigation bar. By clicking it, the memory cache used is cleared. The cache is used to reduce the number of database operations required. By clearing the cache modifications that have been done to the database immediately come visible in the web interface. Otherwise they will come visible only when the corresponding object is removed from the cache.
Master Exercise List Page
The master exercise list page lists all exercises in the system by their template ID. For each exercise its name, id, and supported languages are shown. Furthermore, for each exercise the system tells whether there are separate task and instruction tabs in the exercise instructions and whether there is pseudocode for the exercise. The template IDs are required by administrators when creating new courses.
By clicking on an exercise name the instructor can go to the exercise page.
Exercise Page
On the exercise page, the instructor can view and modify the exercise instructions and pseudocode, and try to solve the exercise himself. Also, on the exercise page, it is possible to change the size of the exercise applet. when modifying the exercise instructions follow the on-screen instructions for correct syntax. Furthermore, be advised that changes to the size of the exercise applet affect all courses.
Course Comparison Page
On the course comparison page it is possible to compare courses to one other. The comparison can be done either graphically (the default) or as textual lists, or both. In the graphical comparison the Y-axis contains the number of students that have attained a given number of points or grade, while the X-axis contains either points or grades. When comparing courses with different number of students and different point maximums, the relative values should be used. If number of students or point maximum is the same on both courses, absolute values can be used.
Server Activity Page
The server activity page shows the server activity chart on the selected courses. The chart can show activity for a single day, a single week or the whole course. It is also possible to use the distribution view, which shows total server activity on each hour in the day (added for all days on the course).
Student Details Page
The student details view shows a given student's results on the course. From the page it is possible to view all the student's submissions by clicking on the given exercise, give the student a personal deadline on a given round (useful when a student has missed a deadline because of, for example illness), and move a student to another course (useful when a student has registered to the wrong course by mistake). The page also shows the points the student has gained from each exercise, his totals for each round and for the whole course.
System Administration
Currently, there is no user interface for most administrative tasks in the TRAKLA2 system. The current plan is to create a dedicated administrator's user interface during the fall 2007. Now, however, many administrative tasks need to be done by directly manipulating the PostgreSQL database.
The database can be accessed using the psql program. If the name of the database is trakla2, and the database user owning it is also named trakla2, the database can be accessed with the command
> psql -U trakla2 trakla2
For the rest of this guide, it is assumed that you know how to use psql, know sql syntax, and give all the commands in the psql program.
Creating new courses
In order to create a course, several different tables need to be modified. Course information resides in four tables: course, coursedescription, round, and exercises.
Course table
The course table includes the following columns:
- code - the University's code for the course (e.g. T-106.1220)
- id - unique, system-specific identity number for the course. This number is used by the system to identify the course. Not shown to users.
- minpoints - the factor by which the maximum points on the course are multiplied in order to know how many points are required to pass the course. Legal values are between 0 and 1.
- open - timestamp when the course opens (students can start to register to the course)
- close - timestamp when the course closes (students no longer can submit exercises)
- organization_id, organized_id - used when courses from several institutions are used on the same server. You can ignore these.
Coursedescription table
The coursedescription table includes the following columns:
- cid - course id, refers to the id column in the course table
- name - name of the course in the current locale
- lang - the locale, en for English, fi for Finnish, etc.
- description - the description of the course. Can be html or plain text.
- link - link to additional material, like the homepage of the course.
Round table
The round table includes the following columns:
- cid - course id, refers to the id column in the course table
- id - unique, system-specific id of the round. This number is used by the system to identify the round. Not shown to users.
- deadline - timestamp for the deadline of the round.
- min - the factor by which the maximum points on the round are multiplied in order to know how many points are required to pass. Legal values are between 0 and 1.
- number - the number of the round. First round on a course has number 1, second number 2, etc. Be careful that the numbers are correct, or the system may not work correctly.
- makeupfactor - the factor by which submissions after the deadline are penalized. Legal values are between 0 (late submissions get no points) and 1 (late submissions are not penalized).
- open - timestamp when the round opens (students can start solving exercises).
Exercises table
The exercises table includes the following columns:
- rid - round id, referst to the id column in the round table
- eid - exercise id, refers to the id of the exercise in the exercise table. These id numbers are shown in the master exercise list in the monitor interface.
- number - the number of the exercise on the round. First exercise has number 1, second number 2, etc. Be careful that the numbers are correct, or the system may not work correctly.
- maxpoints - maximum points a student can gain from the exercise.
- maxsubs - the number of times a student can submit the exercise. If left blank, the default value of 32767 (practically unlimited) is used.
Creating new course
First, the new course needs to be added to the course table. For example:
INSERT INTO course (code, id, minpoints, open, close) VALUES ('TEST', 100, 0, '2007-01-01', '2010-08-01');
This will create a course with the code TEST, id 100 and no minimum points. The course opens on new year 2007 and is open until first of August 2010.
Then, the course description can be added. This is an optional step, however.
INSERT INTO coursedescription (cid, name, lang, description) VALUES (100, 'Test Course', 'en', 'This is a test course');
This will give the course the name 'Test Course' and the description 'This is a test course' in English.
Then, rounds can be added:
INSERT INTO round VALUES(100, 101, '2009-01-01 00:00:00', 0, 1, 0, '2005-01-19 00:00:00'); INSERT INTO round VALUES(100, 102, '2009-01-01 00:00:00', 0, 2, 0, '2005-01-19 00:00:00'); INSERT INTO round VALUES(100, 103, '2009-01-01 00:00:00', 0, 3, 0, '2005-01-19 00:00:00');
This will add to the course three rounds (rounds 1,2,3) that close on new year 2009 have 0 minimum points and makeup factor 0.
Then, exercises can be added to a round:
INSERT INTO exercises VALUES(101, 1, 1, 2, 32767); INSERT INTO exercises VALUES(101, 10, 2, 2, 32767); INSERT INTO exercises VALUES(101, 8, 3, 1, 32767);
This will add the exercises Binary search, Interpolation search, and Preorder traversal to the first round of the test course. The maximum points for the first two exercises are 2, and max points for the third exercise are 1.
Automatic grading for a course
The system can also give students an automatic grade on a course. If the student has not gained minimum points for each round and for the whole course, no grade is given. If the student has gained at least minimum points for each round and for the whole course, he or she is given a grade specified in the coursegrading table.
The coursegrading table includes the following columns:
- cid - the id of the course to be graded
- grade - a specific grade. Maximum of 20 characters can be used for the grade. The grade can also be, for example, extra points gained for exam, etc.
- minpoints - minimum points required for the specific grade.
Therefore, in order to grade a course with maximum points of 100 in such way that students need at least 50 points to pass and then each 10 more points gives an extra point to the exam, an instructor could either give the whole course minpoints 0.5, and add the following to the coursegrading:
INSERT INTO coursegrading VALUES(100,'passed',50); INSERT INTO coursegrading VALUES(100,'+1 point',60); INSERT INTO coursegrading VALUES(100,'+2 points',70); INSERT INTO coursegrading VALUES(100,'+3 points',80); INSERT INTO coursegrading VALUES(100,'+4 points',90); INSERT INTO coursegrading VALUES(100,'+5 points',100);
Or, alternatively, the instructor could use minpoints 0, and add the following to coursegrading:
INSERT INTO coursegrading VALUES(100,'failed',0);
User administration
One of the tasks a system administrator sometimes needs to make is to add new users to the TRAKLA2 system. This is not required for students, who are added to the system when they register to a given course. Instructors and other such non-student -users may need to be added to the system manually, however. Users are stored in the users table. The minimum
A new user can be added to the system with the command
INSERT INTO users (id, password, studentNumber, email, name, lang) VALUES ('username', 'passwd', 'studentNro', 'email', 'Real Name', 'en');
Replacing username, passwd, etc. with the desired values. StudentNumber, email, name, and lang are optional. Just id and password are required for the system to work.
Manually added users are not, however, registered to any course, and this too needs to be done manually. Each course is identified by the unique course id (an integer), and all users registered to the course (either as course students, instructors, or administrators) are stored in the registrations table. The table has three columns:
- userid, which must a valid user id stored in the users table
- cid, which must be the course id of a course stored in the course table
- userpriviledge, which is 0 for students, 1 for instructors and 2 for administrators
Therefore, in order to add an instructor to course with cid 100, use the command
INSERT INTO registrations VALUES('username', 100, 1);
The course id 0 has special meaning: if an user is registered to course 0, he or she is registered to all courses in the system with the given priviledge. Therefore, in order to add an administrator to all courses, use the command
INSERT INTO registrations VALUES('username', 0, 2);