/ 
Grades-0.16
River stage zero No dependents
/ Grades

NAME

Grades - A collocation of homework, classwork and exams

SYNOPSIS

use Grades;

my $script = Grades::Script->new_with_options( league => getcwd );
my $league = League->new( id => $script->league );
my $grades = Grades->new( league => $league );

$league->approach->meta->apply( $grades );
my $classworkgrades = $grades->classwork;
my $homeworkgrades = $grades->homework;
my $examgrades = $grades->examGrade;

DESCRIPTION

An alternative to a spreadsheet for grading students, using YAML files and scripts. The students are the players in a league ( class.) See the README and example emile league in t/emile in the distribution for the layout of the league directory in which homework, classwork and exam scores are recorded.

Grades are a collocation of Classwork, Homework and Exams roles, but the Classwork role 'delegates' its methods to one of a number of approaches, each of which has a 'total' and 'totalPercent' method. Current approaches, or forms of curriculum, include Compcomp, Groupwork and Jigsaw.

Keywords: gold stars, token economies, bean counter

ATTRIBUTES & METHODS

LEAGUE CLASS

leagues

The path to the league directory.

id

Actually, it's a path to the league directory, below the $grades->leagues dir.

yaml

The content of the league configuration file.

name

The name of the league (class).

field

The field of the league (class). What is the subject or description, the area of endeavor?

approach

The style of classwork competition, eg Compcomp, or Groupwork. This is the name of the class (think OOP) to which 'classwork' and other methods are delegated.

members

Hash refs of the players (students) in the league. The module assumes each of the members in the arrayref returned by this attribute is a hash ref containing an id and name of the member.

session

The first week in each session, like { 1 => 1, 2 => 5, 3 => 10, 4 => 14 }, monotonically increasing week numbers.

absentees

Students who have stopped coming to class and so won't be included in classwork scoring.

transfer

$oldleague = $newleague->transfer->{V9731059}

Players who have transferred to this league from some other league at some point and the leagues they transferred from.

is_member

Whether the passed id is that of a member in the league (class).

ided

The id of the member with the given player name.

inspect

Loads a YAML file.

save

Dumps a YAML file

PLAYER CLASS

league

The league the player is in. This is required.

id

The id of the player. This is required.

id

The name of the player.

NONENTITY CLASS

name

The name is 'Bye'. The id is too, as a matter of fact.

GRADES CLASS

Grades' Homework Methods

hwdir

The directory where the homework is.

rounds

An arrayref of the rounds for which there are homework grades for players in the league, in round order, of the form, [1, 3 .. 7, 9 ..].

roundIndex

Given a round name (ie number), returns the ordinal position in which this round was played, with the first round numbered 0. Returns undef if the round was not played.

roundfiles

An hashref of the files with data for the rounds for which there are homework grades for players in the league, keyed on rounds.

hwbyround

A hashref of the homework grades for players in the league for each round.

hwMax

The highest possible score in the homework

totalMax

The total maximum points that a Player could have gotten to this point in the whole season. There may be more (or fewer) rounds played than expected, so the actual top possible score returned by totalMax may be more (or less) than the figure planned.

rawscoresinRound

Given a round, returns a hashref of the raw scores for that round, keyed on the names of the exercises. These are in files in the hwdir with names of the form ^\d+[_.]\w+\.yaml$

hwforid

Given a player's id, returns an array ref of the player's hw scores.

hwforidasHash

Given a player's id, returns an hashref of the player's hw grades, keyed on the rounds.

homework

Running total homework scores of the league.

homeworkPercent

Running total homework scores of the league as percentages of the totalMax to that point, with a maximum of 100.

Grades' Jigsaw Methods

The jigsaw is a cooperative learning activity where all the players in a group get different information that together produces the 'big picture', and where they are each held responsible for the understanding of each of the other individual members of this big picture.

jigsawdirs

The directory where the jigsaws are.

config

The round.yaml file with data about the jigsaw activity in the given round (directory.)

topic

The topic of the quiz in the given jigsaw for the given group.

form

The form of the quiz in the given jigsaw for the given group.

quizfile

The file system location of the file with the quiz questions and answers for the given jigsaw.

quiz

The quiz questions (as an anon array) in the given jigsaw for the given group.

options

$grades->options( '2/1', 'Purple', 0 ) # [ qw/Deborah Don Dovonna Sue/ ]

The options (as an anon array) to the given question in the given jigsaw for the given group.

qn

The number of questions in the given jigsaw for the given group.

responses

The responses of the members of the given group in the given jigsaw (as an anon hash keyed on the ids of the members). In a file in the jigsaw directory called 'response.yaml'.

jigsawGroups

A hash ref of all the groups in the given jigsaw and the names of members of the groups, keyed on groupnames. There may be duplicated names if one player did the activity twice as an 'assistant' for a group with not enough players, and missing names if a player did not do the quiz.

jigsawGroupMembers

An array (was hash ref) of the names of the members of the given group in the given jigsaw, in order of the roles, A..D.

roles

At the moment, just A .. D.

idsbyRole

Ids in array, in A-D role order

assistants

A array ref of all the players in the (sub)jigsaw who did the the activity twice to 'assist' groups with not enough (or absent) players, or individuals with no groups, or people who arrived late.

jigsawGroupRole

An hash ref of the roles of the members of the given group in the given jigsaw, keyed on the name of the player.

id2jigsawGroupRole

An hash ref of the roles of the members of the given group in the given jigsaw, keyed on the id of the player.

name2jigsawGroup

An array ref of the group(s) to which the given name belonged in the given jigsaw. Normally, the array ref has only one element. But if the player was an assistant an array ref of more than one group is returned. If the player did not do the jigsaw, no groups are returned.

rawJigsawScores

The individual scores on the given quiz of each member of the given group, keyed on their roles, no, ids, from the file called 'scores.yaml' in the given jigsaw dir. If the scores in that file have a key which is a role, handle that, but, yes, the keys of the hashref returned here are the players' ids.

chinese

The number of times Chinese was used in the given round by all the groups. If there is no record of Chinese use, returns values of 0.

jigsawDeduction

Points deducted for undesirable performance elements (ie Chinese use) on the quiz of the given group in the given exam.

Grades' Classwork Methods

Classwork is work done in class with everyone and the teacher present. Two classwork approaches are Compcomp and Groupwork. Others are possible. Depending on the league's approach accessor, the methods are delegated to the appropriate Approach object.

approach

Delegatee handling classwork_total, classworkPercent

Classwork Approach

Handles Classwork's classwork_total and classworkPercent methods. Calls the total or totalPercent methods of the class whose name is in the 'type' accessor.

league

The league (object) whose approach this is.

groupworkdirs

The directory under which there are subdirectories containing data for the group/pair-work sessions. Look first in 'groupwork', then 'compcomp' mappings, else use 'classwork' dir.

series

The sessions (weeks) over the series (semester) in each of which there was a different grouping and results of players. This method returns an arrayref of the names (numbers) of the sessions, in numerical order, of the form, [1, 3 .. 7, 9, 10 .. 99 ]. Results are in sub directories of the same name, under groupworkdirs.

classworkPercent

Calls the pluginned approach's classworkPercent.

Grades' Compcomp Methods

The comprehension question competition is a Swiss tournament regulated 2-partner conversation competition where players try to understand more of their opponent's information than their partners understand of theirs.

compcompdirs

The directory under which there are subdirectories containing data for the Compcomp rounds.

all_events

The pair conversations over the series (semester). This method returns an arrayref of the numbers of the conversations, in numerical order, of the form, [1, 3 .. 7, 9, 10 .. 99 ]. Results are in sub directories of the same name, under compcompdirs.

config

The round.yaml file with data about the Compcomp activity for the given conversation (directory.)

activities

The activities which individual tables did in the given round. Keys are topics, keyed are forms. These, in turn, are keys of tables doing those topics and those forms.

tables

The tables with players according to their roles for the given round, as an hash ref. In the 'group' or 'activities' mapping in the config file. Make sure each table has a unique table number. Some code here is same as in Swiss's round_table.pl and dblineup.rc.

activities: drbean: 1: - U9931007 - U9933022 novak: 1: - U9931028 - U9933045

pair2table

A player and opponent mapped to a table number.

compQuizfile

The file system location of the file with the quiz questions and answers for the given Compcomp activity.

topicNames

Returns the names of comp quiz topics as an arrayref.

compQuizAttempted

Returns the comp quiz topics and their associated forms attempted by the given group in the round, as an arrayref of hashrefs keyed on 'topic' and 'form'.

compQuiz

The compQuiz questions (as an anon array) in the given Compcomp activity for the given table.

compTopic

The topic of the quiz in the given Compcomp round for the given table. Each table has one and only one quiz.

compTopics

The topics of the quiz in the given Compcomp round for the given table, as an array ref.

compForm

The form of the quiz in the given Compcomp round for the given table. Each table has one and only one quiz.

compForms

The forms in the given Compcomp round for the given table, in the given quiz (topic), as an array ref.

compqn

The number of questions in the given Compcomp quiz for the given pair.

idsbyCompRole

Ids in array, in White, Black role order

scores

The scores at the tables of the tournament in the given round (as an anon hash keyed on the ids of the members). In a file in the Compcomp round directory called 'result.yaml'.

compResponses

The responses of the members of the given pair in the given round (as an anon hash keyed on the ids of the members). In a file in the Compcomp round directory called 'response.yaml'.

freeTotals

The number of free questions each asked by White and Black.

lowerFreeTotal

The lesser of the 2 numbers of free questions asked by either White and Black.

byer

The id of the player with the Bye, or the empty string.

transfer

An array ref of the ids of the players who were playing in another league in the round, or the empty string.

opponents

The ids of opponents of the players in the given conversation.

correct

The number of questions correct in the given conversation.

assistantPoints

Assistants points are from config->{assistant} of form { Black => { U9933002 => 3, U9933007 => 4}, Yellow => { U9931007 => 4, U9933022 => 4 } }, and are the points for examiners with other responsibilities who are not participating in the round.

dispensation

Dispensation points are from config->{dispensation} of same form as assistantPoints, { Black => { U9933002 => 3, U9933007 => 4}, Yellow => { U9931007 => 4, U9933022 => 4 } }.

payout

If payprotocol field is 'meritPay', 1 question each: 0,1 or 2 pts. 2 question each: 1,2 or 3 pts. 3 question each: 2,3 or 4 pts. 4 question each: 3,4 or 5 pts.

If the 'meritPay' payprotocol field ends in a number the specified number of questions each is required for the maximum points.

points

The points of the players in the given conversation. 5 for a Bye, 1 for Late, 0 for Unpaired, 1 for a non-numerical number correct result, 5 for more correct, 3 for less correct, 4 for the same number correct. Transfers' results are computed from their results in the same round in their old league. Assistants points are from round.yaml, points for non-paired helpers.

total

The total over the conversations over the series.

totalPercent

The total over the conversations over the series expressed as a percentage of the possible score. The average should be 80 percent if every player participates in every comp.

Grades' Exams Methods

examdirs

The directory where the exams are.

examids

An arrayref of the ids of the exams for which there are grades for players in the league, in numerical order, of the form, [1, 3 .. 7, 9, 10 .. 99 ]. Results are in sub directories of the same name, under examdir.

examrounds

The rounds over which the given exam was conducted. Should be an array ref. If there were no rounds, ie the exam was conducted in one round, a null anonymous array is returned. The results for the rounds are in sub directories underneath the 'examid' directory named, in numerical order, 1 .. 99.

examMax

The maximum score possible in each individual exam. That is, what the exam is out of.

exam

$grades->exam($id)

The scores of the players on an individual (round of an) exam (in a 'g.yaml file in the $id subdir of the league dir.

examResults

A hash ref of the ids of the players and arrays of their results over the exam series, ie examids, in files named 'g.yaml', TODO but only if such a file exists in all examdirs. Otherwise, calculate from raw 'response.yaml' files. Croak if any result is larger than examMax.

examResultHash

A hash ref of the ids of the players and hashrefs of their results for each exam. Croak if any result is larger than examMax.

examResultsasPercent

A hashref of the ids of the players and arrays of their results over the exams expressed as percentages of the maximum possible score for the exams.

examGrade

A hash ref of the ids of the players and their total scores on exams.

examPercent

A hash ref of the ids of the players and their total score on exams, expressed as a percentage of the possible exam score. This is the average of their exam scores.

Grades' Core Methods

BUILDARGS

Have Moose find out the classwork approach the league has adopted and create an object of that approach for the classwork accessor. This is preferable to requiring the user to create the object and pass it at construction time.

classwork

An accessor for the object that handles classwork methods. Required at construction time.

config

The possible grades config files. Including Jigsaw, Compcomp.

league

The league (object) whose grades these are.

weights

An hash ref of the weights (expressed as a percentage) accorded to the three components, classwork, homework, and exams in the final grade.

sprintround

sprintf( '%.0f', $number). sprintf warns if $number is undef.

grades

A hashref of student ids and final grades.

AUTHOR

Dr Bean, <drbean, followed by the at mark (@), cpan, then a dot, and finally, org>

BUGS

Please report any bugs or feature requests to bug-grades at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Grades. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Grades

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2009 Dr Bean, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.