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.

absentees

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

transfer

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

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.

roundMax

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.

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.

all_weeks

All the weeks, or sessions or lessons for which grade data is being assembled from for the grade component.

points

Week-by-weeks, or session scores for the individual players in the league.

classwork_total

Calls the pluginned approach's classwork_total.

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.

league

The league (object) which is doing CompComp.

compcompdirs

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

all_weeks

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.)

tables

The tables with players according to their roles for the given round. In the 'pairs' mapping in the config file.

compQuizfile

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

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.

compForm

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

compqn

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

idsbyCompRole

Ids in array, in White, Black role order

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'.

opponents

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

correct

The number of questions correct in the given conversation.

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.

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' Groupwork Methods

The idea of Cooperative Learning, giving individual members of a group all the same score, is that individuals are responsible for the behavior of the other members of the group. Absences and tardies of individual members can lower the scores of the members who are present.

Also, grading to the curve is employed so that the average classwork grade over a session for each student is 80 percent.

league

The league (object) which is doing groupwork.

groupworkdirs

The directory under which there are subdirectories containing data for the groupwork sessions.

series

The sessions over the series (semester) in which there was a different grouping (beancans) of players. Everyone in the same beancan for one session gets the same number of beans (classwork score.) This method returns an arrayref of the names 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.

beancanseries

The different beancans for each of the sessions in the series. In the directory for each session of the series, there is a file called beancans.yaml, containing mappings of a beancan name to a sequence of PlayerNames, the members of the beancan.

allfiles

The files containing classwork points (beans) awarded to beancans.

all_weeks

The weeks (an array ref of integers) in which beans were awarded.

lastweek

The last week in which beans were awarded.

data

The beans awarded to the beancans in the individual cards over the weeks of the series (semester.)

card

Classwork beans for each beancan for the given week

beancans

A hashref of all the beancans in a given session with the names of the members of each beancan. The number, composition and names of the beancans may change from one session of the series to the next.

Players in one beancan all get the same Groupwork grade for that session. The beancan members may be the same as the members of the class group, who work together in class, or may be individuals. Usually in a big class, the beancans will be the same as the groups, and in a small class they will be individuals.

Players in the 'Absent' beancan all get a grade of 0 for the session.

Rather than refactor the class to work with individuals rather than groups, and expand some methods (?) to fall back to league members if it finds them in the weekly files instead of groups, I decided to introduce another file, beancans.yaml, and change all variable and method names mentioning group to beancan.

active

Given a session, returns the active beancans, ie all but the 'Absent' beancan.

files

Given a session, returns the files containing beans for the session of form, $session/\d+\.yaml$

weeks

Given a session, returns the weeks (an array ref of integers) in which beans were awarded in the session.

week2session

        $Groupwork->week2session(15) # fourth

Given the name of a week, return the name of the session it is in.

names2beancans

A hashref of names of members of beancans (players) and the beancans they were members of in a given session.

name2beancan

        $Groupwork->name2beancan( $week, $playername )

Given the name of a player, the name of the beancan they were a member of in the given week.

beancansNotInCard

        $Groupwork->beancansNotInCard( $beancans, $card, 3)

Test all beancans, except Absent, exist in the beancans listed on the card for the week.

beancanDataOnCard

        $Groupwork->beancansNotInCard( $beancans, $card, 3)

Test all of the beancans, except Absent, have all the points due them for the week. Duplicates the check done by the Card type.

merits

The points the beancans gained for the given week.

absences

The numbers of players absent from the beancans in the given week. These are demerits.

tardies

The numbers of players not on time in the beancans in the given week. These are demerits.

payout

How much should be given out for each beancan (except the 'Absent' beancan) for each week in this session, so that the total score of each player over the session averages 80?

demerits

The demerits that week. calculated as twice the number of absences, plus the number of tardies. In a four-member beancan, this ranges from 0 to 8.

favor

A score of 1 given to beancans with no more than 6 demerits, to prevent beancans who were all there but didn't do anything (ie had no merits and no demerits) from getting a log score of 0, and so getting a grade of 0 for that week.

maxDemerit

The max demerit that week. achieved by the beancan with the most absences and tardies.

meritDemerit

Let beancans with no merits, and no demerits get a score greater than 1, so the log score is greater than 0. Let beancans with 3 or more absences and 1 tardies not be eligible for this favor, but get at least 0. Let other beancans get the number of merits - number of demerits, but also be eligible for the favor, and get a score of above 1.

logwork

The points given by the teacher are log-scaled to prevent active students from taking all the payout, and the other students getting very low grades. There may be better ways of grading to the curve than using log scaling. The log of one point is 0, which results in a grade of 0 for that week for that beancan.

work2grades

The work (ie merits - demerits) of the individual beancans for the week, as a percentage of the total work of all the beancans, determines the payout of grades, which should average 80 over the sessions of play. I was logscaling grades. I am now not doing that.

grades4session

Totals for the beancans over the given session. TODO Why '+=' in sessiontotal?

totalPercent

Running totals for individual ids out of 100, over the whole series.

Grades' GroupworkNoFault Approach

Unlike the Groupwork approach, GroupworkNoFault does not penalize members of a group who are present for the absence of other members who are not present or tardy. Instead the individual members not present get a grade of 0 for that class.

Also, no scaling of the grades (a group's merits) takes place.

league

The league (object) which is doing groupwork.

classMax

The maximum score possible in individual lessons for classwork.

groupworkdirs

The directory under which there are subdirectories containing data for the groupwork sessions.

series

beancanseries

allfiles

The files containing classwork points (beans) awarded to beancans.

all_weeks

The weeks (an array ref of integers) in which beans were awarded.

lastweek

The last week in which beans were awarded.

data

The beans awarded to the beancans in the individual cards over the weeks of the series (semester.)

card

Classwork beans for each beancan for the given week

beancans

Players in the 'Absent' beancan all get a grade of 0 for the session.

active

Given a session, returns the active beancans, ie all but the 'Absent' beancan.

files

Given a session, returns the files containing beans for the session of form, $session/\d+\.yaml$

weeks

Given a session, returns the weeks (an array ref of integers) in which beans were awarded in the session.

week2session

        $Groupwork->week2session(15) # fourth

Given the name of a week, return the name of the session it is in.

names2beancans

A hashref of names of members of beancans (players) and the beancans they were members of in a given session.

name2beancan

        $Groupwork->name2beancan( $week, $playername )

Given the name of a player, the name of the beancan they were a member of in the given week.

beancansNotInCard

        $Groupwork->beancansNotInCard( $beancans, $card, 3)

Test all beancans, except Absent, exist in the beancans listed on the card for the week.

beancanDataOnCard

        $Groupwork->beancansNotInCard( $beancans, $card, 3)

Test all of the beancans, except Absent, have all the points due them for the week. Duplicates the check done by the TortCard type.

merits

The points the beancans gained for the given week.

absent

The players absent from each beancan in the given week.

points

The merits the beancans gained for the given week, except for those members who were absent, and who get zero. Keyed on player id.

grades4session

Totals for the beancans over the given session.

total

Totals for individual ids, over the whole series.

totalPercent

Running totals for individual ids out of 100, over the whole series.

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

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:

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Grades
CPAN Ratings

http://cpanratings.perl.org/d/Grades
RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Grades
Search CPAN

http://search.cpan.org/dist/Grades

COPYRIGHT & LICENSE

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

To install Grades, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Grades

CPAN shell

perl -MCPAN -e shell
install Grades

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)