An explanation of problem source files, problems, problem sets, and problem libraries

From WeBWorK_wiki
Revision as of 14:23, 15 June 2021 by Berndsing (talk | contribs) (added "needs work" tag)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

So first of all, there's a bunch of data we want to keep track of to represent problem sets and problems:

Global Set Data - Information about the the problem set itself, not including the data about each problem. This consists of the open/due/answer dates and the set/hardcopy header files.

Global Problem Data - Information about each problem in each set. This consists of the weight of the problem ("value"), the number of allowed attempts, and the path to the source file, relative to the course's templates directory.

User-Specific Set Data - Same as "Global Set Data", above, except for a specific user. This allows you to modify the dates and header files for a particular user.

User-Specific Problem Data - Same as "Global Problem Data", above, except for a particular user. This allows you to modify the problem's weight, number of allowed attempts, and (theoretically) the source file for a particular user. ALSO: this adds several pieces of data that are user-specific, like the user's score on the problem ("status"), how many attempts they've consumed, their last submitted answer, and so on.

(FIXME: Make it clear that the user-specific data is PRIMARILY to denote assignment of a set to a student and record student data, and secondarily to allow overrides of the global data.)

If fields in the user-specific data tables are left blank, the global values are used.


In WeBWorK 1, the only data that was kept in the course database was user-specific set and problem data. "Global" values were only stored in the set definition files, and the set definition file for a set was consulted whenever it needed to create new user-specific data. (For example, when "building" an existing set for additional students.)

Since there were no "global" values, it was hard to change things for all users once a problem set was in use. You would have to delete the problem set and rebuild it from the set definition file, or change the value for each user individually. (WeBWorK 1 could change a value for all users, but it would clobber any customizations that had been made to single users, i.e. changing the weight of a problem.)

One of the design goals of WeBWorK 2 was to make WeBWorK less dependant on user-edited files in the filesystem, like set definition files. This meant we had to represent the global set and problem data in the course database as well as the user-specific data. This means that instead of the WeBWorK 1 procedure of chosing or editing a set definition file (which contains the global data) and then "building" the user-specific data for each student in the course, there's a new process: creating a new problem set (global data) and then assigning the set (user-specific data) to each student in the course.

There are a couple of ways to create problem sets. You can create a new, empty, problem set and then add problems to it. (More on this later.)

You can also create a problem set from an existing set definition file. This is now known as "importing" a problem set. WeBWorK looks for set definition files in the course's templates directory. Once a problem set is "imported", the set definition file is is never again consulted. When you assign a problem set to students, the global data (in the database) is used to create user-specific data (also in the database).

Set definition files remain useful, but only as a means of sharing problem set data with others. For example, one professor could export a problem set to a set definition file and send it to another professor. The second professor would import the set definition file to create a copy of the problem in their course.

So that takes care of what data is represented in course databases, and what set definition files are used for in WeBWorK 1 and 2.

Next, we need to talk about problem source files. These contain the actual PG code used to pose a question to the student and evaluate their response.

Problem source files are never stored in the course database. One of the data points about a problem (see above) is the path to the source file. This path is relative to the course's templates directory. In order for WeBWorK to find a problem source file, it must be inside the templates directory or reachabe from that directory by a symlink.

This is the same in WeBWorK 1 and WeBWorK 2.

Several institutions have compiled collections of problem source files that they provide to professors so they don't have to start from scratch. To help professors use these problems, they also maintain collections of set definition files which they distribute along with the source files. These define natural sets of problems.

There are a couple of ways to use these collections. First, you can import set definition files from problem collections into a course.

Second, you can add problems to a set using the (probably misnamed) "Library Browser". It allows you to browse the directories in the collection and add problems therein to problem set. This method does not use set definition files at all.

Of course, to do either of these things, the collection must be accessible through your course's templates directory. Historically, people have copied the contents of the collection into each new course's templates directory at the beginning of the semester. Recently, people have been adding a symlink to a central collection to each new course. This cuts down on disk space requirements for each course and allows individual courses to benefit from updates to the collection. By restricting write access to the collection, one can prevent professors from modifying shared files. However, this does prevent them from being able to customize a problem without making a copy of it first.

Regardless of which method you use (copy or symlink), the WeBWorK 2 Course Administration tool allows you to copy the contents to an existing course's templates directory when creating a new course. You can set up a "model course", add problem source files and set definition files to its templates directory, and then use it when creating new courses.

The "Library Browser" considers problem collections that are symlinked or included in a course's templates directory "Local Problems". However, there is a way to make them appear separately in the library browser, as subcategories of "Local Problems" and also to give them more natural names. To do this, edit $courseFiles{problibs} in global.conf (or course.conf), to map directory or symlink names that will appear in the templates directory, to names for the buttons under "Local Problems" in the library browser. There are comments in global.conf that detail the process.

Main article: Problem Libraries

And now, to complicate things...

The collections described above are sometimes called "Problem Libraries". However, this term is also used by the National Problem Library, a project to provide a problem library with indexed, searchable metadata. It is our hope that eventually all problem libraries will be integrated into the NPL.

Main article: National Problem Library.