--- loncom/interface/statistics/lonproblemstatistics.pm	2003/03/26 21:55:18	1.46
+++ loncom/interface/statistics/lonproblemstatistics.pm	2003/03/27 19:26:33	1.47
@@ -1,6 +1,6 @@
 # The LearningOnline Network with CAPA
 #
-# $Id: lonproblemstatistics.pm,v 1.46 2003/03/26 21:55:18 matthew Exp $
+# $Id: lonproblemstatistics.pm,v 1.47 2003/03/27 19:26:33 matthew Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -26,7 +26,26 @@
 #
 # (Navigate problems for statistical reports
 #
-###
+###############################################
+###############################################
+
+=pod
+
+=head1 NAME
+
+lonproblemstatistics
+
+=head1 SYNOPSIS
+
+Routines to present problem statistics to instructors via tables,
+Excel files, and plots.
+
+=over 4
+
+=cut
+
+###############################################
+###############################################
 
 package Apache::lonproblemstatistics;
 
@@ -37,9 +56,20 @@ use Apache::loncoursedata;
 use Apache::lonstatistics;
 use Spreadsheet::WriteExcel;
 
-#######################################################
-#######################################################
+###############################################
+###############################################
+
+=pod 
+
+=item &CreateInterface()
 
+Create the main intereface for the statistics page.  Allows the user to
+select sections, maps, and output.
+
+=cut
+
+###############################################
+###############################################
 sub CreateInterface {
     my $Str = '';
     $Str .= '<table cellspacing="5">'."\n";
@@ -77,6 +107,13 @@ sub CreateInterface {
 
 =item &CreateAndParseOutputSelector()
 
+Construct a selection list of options for output and parse output selections.
+The current output selected is indicated by the values of the two package
+variables $output_mode and $show.  @OutputOptions holds the descriptions of
+the output options and the values for $output_mode and $show.
+
+ Based on code from lonstudentassessment.pm.
+
 =cut
 
 #######################################################
@@ -135,10 +172,10 @@ sub OutputDescriptions {
 
 sub CreateAndParseOutputSelector {
     my $Str = '';
-    my $elementname = 'outputmode';
+    my $elementname = 'statsoutputmode';
     #
     # Format for output options is 'mode, restrictions';
-    my $selected = 'html, with links';
+    my $selected = 'HTML problem statistics grouped';
     if (exists($ENV{'form.'.$elementname})) {
         if (ref($ENV{'form.'.$elementname} eq 'ARRAY')) {
             $selected = $ENV{'form.'.$elementname}->[0];
@@ -170,6 +207,14 @@ sub CreateAndParseOutputSelector {
 ###############################################
 ###############################################
 
+=pod 
+
+=item &Gather_Student_Data()
+
+Ensures all student data is up to date.
+
+=cut
+
 ###############################################
 ###############################################
 sub Gather_Student_Data {
@@ -200,6 +245,14 @@ sub Gather_Student_Data {
 ###############################################
 ###############################################
 
+=pod 
+
+=item &BuildProblemStatisticsPage()
+
+Main interface to problem statistics.
+
+=cut
+
 ###############################################
 ###############################################
 sub BuildProblemStatisticsPage {
@@ -213,6 +266,14 @@ sub BuildProblemStatisticsPage {
     $r->print('<input type="hidden" name="sortby" value="'.$ENV{'form.sortby'}.
               '" />');
     if (! exists($ENV{'form.statsfirstcall'})) {
+        $r->print(<<ENDMSG);
+<p>
+<font size="+1">
+Please make your selections in the boxes above and hit 
+the button marked &quot;Update&nbsp;Display&quot;.
+</font>
+</p>
+ENDMSG
         return;
     }
     #
@@ -248,6 +309,15 @@ sub BuildProblemStatisticsPage {
 ###############################################
 ###############################################
 
+=pod 
+
+=item &output_html_grouped_by_sequence()
+
+Presents the statistics data as an html table organized by the order
+the assessments appear in the course.
+
+=cut
+
 ###############################################
 ###############################################
 sub output_html_grouped_by_sequence {
@@ -259,7 +329,6 @@ sub output_html_grouped_by_sequence {
                   "S.D.","Skew.");#,"D.F.1st","D.F.2nd");
     # #FFFFE6 #EEFFCC #DDFFFF FFDDDD #DDFFDD #FFDDFF
     foreach my $sequence (&Apache::lonstatistics::Sequences_with_Assess()) {
-        my $show_part = 0;
         next if ($sequence->{'num_assess'}<1);
         $r->print("<h3>".$sequence->{'title'}."</h3>");
         $r->print('<table border="0"><tr><td bgcolor="#777777">'."\n");
@@ -275,7 +344,6 @@ sub output_html_grouped_by_sequence {
                         (undef,$resource->{'symb'},$part,
                          $ENV{'request.course.id'});
                 #
-                $show_part = 1 if ($part ne '0');
                 $part = '&nbsp;' if ($part == 0);
                 #
                 my $wrongpercent = 0;
@@ -283,7 +351,6 @@ sub output_html_grouped_by_sequence {
                     $wrongpercent=int(10*100*($num-$Solved+$solved)/$num)/10;
                 }
                 my $option = '';
-                $option .= 'no part' if (! $show_part);
                 $r->print('<tr>'.&statistics_html_table_data
                           ($resource,$part,$num,$tries,$mod,$mean,$Solved,
                            $solved,$wrongpercent,$DegOfDiff,$STD,$SKEW,
@@ -302,6 +369,15 @@ sub output_html_grouped_by_sequence {
 ###############################################
 ###############################################
 
+=pod 
+
+=item &output_html_ungrouped()
+
+Presents the statistics data in a single html table which can be sorted by
+different columns.
+
+=cut
+
 ###############################################
 ###############################################
 sub output_html_ungrouped {
@@ -452,7 +528,6 @@ sub output_html_ungrouped {
                    $row->{'#YES'},$row->{'#yes'},$row->{"\%Wrng"},
                    $row->{'DoDiff'},$row->{'S.D.'},$row->{'Skew'},
                    $option));
-
         $r->print("</tr>\n");
     }
     $r->print("</table>\n");
@@ -462,10 +537,17 @@ sub output_html_ungrouped {
     return;
 }
 
-
 ###############################################
 ###############################################
 
+=pod 
+
+=item &output_excel()
+
+Presents the statistical data in an Excel 95 compatable spreadsheet file.
+
+=cut
+
 ###############################################
 ###############################################
 sub output_excel {
@@ -587,6 +669,14 @@ sub output_excel {
 ###############################################
 ###############################################
 
+=pod 
+
+=item &statistics_html_table_data()
+
+Help function used to format the rows for HTML table output.
+
+=cut
+
 ###############################################
 ###############################################
 sub statistics_html_table_data {
@@ -601,7 +691,10 @@ sub statistics_html_table_data {
     foreach ($num,$tries) {
         $row .= '<td bgcolor="#EEFFCC" align="right">'.$_.'</td>';
     }
-    foreach ($mod,$mean) {
+    foreach ($mod) {
+        $row .= '<td bgcolor="#DDFFFF" align="right">'.$_.'</td>';
+    }
+    foreach ($mean) {
         $row .= '<td bgcolor="#DDFFFF" align="right">'.
                   sprintf("%5.2f",$_).'</td>';
     }
@@ -621,6 +714,15 @@ sub statistics_html_table_data {
 
 ###############################################
 ###############################################
+
+=pod 
+
+=item &plot_statistics()
+
+=cut
+
+###############################################
+###############################################
 sub plot_statistics {
     my ($r,$datafield) = @_;
     my @Data;
@@ -714,6 +816,12 @@ sub plot_statistics {
 ###############################################
 ###############################################
 
+=pod 
+
+=item &DrawGraph()
+
+=cut
+
 ###############################################
 ###############################################
 sub DrawGraph {
@@ -742,6 +850,12 @@ sub DrawGraph {
 ###############################################
 ###############################################
 
+=pod 
+
+=item &ProblemStatisticsLegend()
+
+=cut
+
 ###############################################
 ###############################################
 sub ProblemStatisticsLegend {