report_completion_stats

 Generates a report of completion statistics for given experiment information.
 rp = report_completion_stats(expinfo, report_params)

 Generates a report on the completion statistics for subjects associated with
 an experiment described in the expinfo structure.  

 For each subject (and each session), the session information is consulted in
 the response table to determine the last form submitted in that session.

 The rp structure can contain several fields that guide the behavior of this
 analysis module.

 .ticket_code -- if this cell array of strings is present, only those subjects
                 who accessed the experiment with a ticket from this list are
                 included in the report

 .print_report -- should the report be printed to the screen

 See also: mysql_get_expinfo()

0001 function rp = report_completion_stats(einfo, rp)
0002 % Generates a report of completion statistics for given experiment information.
0003 % rp = report_completion_stats(expinfo, report_params)
0004 %
0005 % Generates a report on the completion statistics for subjects associated with
0006 % an experiment described in the expinfo structure.
0007 %
0008 % For each subject (and each session), the session information is consulted in
0009 % the response table to determine the last form submitted in that session.
0010 %
0011 % The rp structure can contain several fields that guide the behavior of this
0012 % analysis module.
0013 %
0014 % .ticket_code -- if this cell array of strings is present, only those subjects
0015 %                 who accessed the experiment with a ticket from this list are
0016 %                 included in the report
0017 %
0018 % .print_report -- should the report be printed to the screen
0019 %
0020 % See also: mysql_get_expinfo()
0021 
0022 % 10/29/06 Petr Janata - started script
0023 
0024 % Check for an active mysql connection and open one if necessary
0025 try rp.conn_id(1);
0026   conn_id = rp.conn_id;
0027 catch
0028   conn_id = 0;
0029 end
0030 mysql_check_conn(conn_id,'open');
0031 
0032 nexp = length(einfo);
0033 if nexp > 1
0034   error(sprintf('Too many (%d) experiments\n', nexp))
0035 end
0036 
0037 % Check to see if we are restricting the search by ticket
0038 if isfield(rp,'ticket_code') && ~isempty(rp.ticket_code)
0039   ticket_code = rp.ticket_code;
0040   if ~iscell(ticket_code)
0041     ticket_code = {ticket_code};
0042   end
0043   ntickets = length(ticket_code);
0044 
0045   ticket_str = sprintf('"%s"', cell2str(ticket_code,'","'));
0046   mysql_str = sprintf(['SELECT session.session_id FROM session, ticket WHERE' ...
0047     ' session.ticket_id = ticket.ticket_id AND ticket.ticket_code IN (%s);'], ticket_str);
0048   [ticket_sessids] = mysql(conn_id,mysql_str);
0049 else
0050   ticket_sessids = [];
0051 end
0052 
0053 if ~isfield(rp,'report_str')
0054   rp.report_str = {};
0055 end
0056 
0057 fid = 1;
0058 if isfield(rp,'report_fname')
0059   fid = fopen(rp.report_fname,'wt');
0060   if fid == -1
0061     fprintf('Problem opening reporting file: %s\n', rp.report_fname);
0062     fid = 1;
0063   end
0064 end
0065     
0066 
0067 if isfield(rp,'print_report') && rp.print_report
0068   PRINT_REPORT = 1;
0069   % Print the header
0070   fprintf(fid,['Subject Name\tSubject ID\tSession ID\tStart Time\tElapsed time' ...
0071     ' (h)\tLast Form ID\tLast Form Name\n']);
0072 else
0073   PRINT_REPORT = 0;
0074 end
0075 
0076 cexp = einfo(1);  % make a copy of the current experiment info
0077 
0078 % Get the experiment form list
0079 exp_formid_list = cexp.forms.ids;
0080 exp_formname_list = cexp.forms.names;
0081 
0082 % Set up a vector to tally the number of times a form was a terminal form
0083 terminal_form_count = zeros(size(exp_formid_list));
0084 
0085 nsubs = length(cexp.subs.names);
0086 for isub = 1:nsubs
0087   % Determine the number of sessions/subject
0088   nsess = cexp.subs.nsess(isub);
0089   
0090   for isess = 1:nsess
0091     sess_id = cexp.subs.sess{isub}(isess);
0092     
0093     if ~isempty(ticket_sessids) && ~any(ticket_sessids == sess_id)
0094       continue
0095     end
0096     
0097     % Get the session time stamp
0098     mysql_str = sprintf(['SELECT date_time,end_datetime FROM session ' ...
0099       'WHERE session_id=%d;'], sess_id);
0100     [start_datenum, end_datenum] = mysql(conn_id, mysql_str);
0101     
0102     % Get a list of forms that the subject completed
0103     mysql_str = sprintf(['SELECT DISTINCT form_id FROM %s '...
0104       'WHERE session_id=%d;'], cexp.resp_table, sess_id);
0105     completed_ids = mysql(conn_id,mysql_str);
0106     
0107     % See how far the subject got
0108     last_form_idx = max(find(ismember(exp_formid_list,completed_ids)));
0109     
0110     rp.subs.last_form_idx{isub}(isess) = last_form_idx;
0111     rp.subs.last_form_id{isub}(isess) = exp_formid_list(last_form_idx);
0112     rp.subs.last_form_name{isub}{isess} = exp_formname_list{last_form_idx};
0113     rp.subs.starttime{isub}(isess) = start_datenum;
0114     if ~isempty(end_datenum)
0115       elapsed_time = etime(datevec(end_datenum),datevec(start_datenum));
0116       rp.subs.elapsedtime{isub}(isess) = elapsed_time;
0117     else
0118       elapsed_time = -1;
0119     end
0120     
0121     % Increment the tally
0122     terminal_form_count(last_form_idx) = terminal_form_count(last_form_idx)+1;
0123 
0124     curr_str = sprintf('%20s\t%s\t%d\t%s\t%1.2f\t%d\t%s\n', ...
0125     cexp.subs.names{isub}, ...
0126     cexp.subs.ids{isub}, ...
0127     sess_id, ...
0128     datestr(start_datenum), ...
0129     elapsed_time/3600, ...
0130     exp_formid_list(last_form_idx), ...
0131     exp_formname_list{last_form_idx});
0132     rp.report_str{end+1} = curr_str;
0133     
0134     if PRINT_REPORT
0135       fprintf(fid,'%s', curr_str);
0136     end
0137   end % for isess
0138 end % for isub=
0139 
0140 rp.terminal_form_count = terminal_form_count;
0141 
0142 if ~conn_id
0143   mysql(conn_id,'close')
0144 end
0145 
0146 % Print the stuff out if desired