Src/DasherCore/UserLog.h

   1
   2 // Handles logging of user activities such as what they write, how
   3 // long they were writing, mouse positions, parameters, etc
   4 //
   5 // Two different kinds of logging can be produced:
   6 //      1) Running stats file that records basic stats about
   7 //         how much and how fast a user is writing.
   8 //      2) Detailed per session log file for use during
   9 //         user trials.
  10 //
  11 // If detailed mode isn't enabled, calls should stop here in this object
  12 // and not go on to create UserLogTrial objects or anything that isn't
  13 // strictly needed to do the simple logging.
  14 //
  15 // For normal dasher, a new trial involves this sequence:
  16 //      1) Program start or new doc
  17 //      2) Nav start
  18 //      3) Nav stop
  19 //      4) Optionally goto 2
  20 // A new trial must be indicated by the user resetting using new doc event.
  21 // Time from 2-4 is elapsed trial time.
  22 //
  23 // Copyright 2005 by Keith Vertanen
  24
  25 #ifndef __USER_LOG_H__
  26 #define __USER_LOG_H__
  27
  28 #include "FileLogger.h"
  29 #include <string>
  30 #include <vector>
  31 #include "SimpleTimer.h"
  32 #include "TimeSpan.h"
  33 #include "UserLogTrial.h"
  34 #include <algorithm>
  35 #include "UserLogParam.h"
  36 #include "UserLogBase.h"
  37 #include "Event.h"
  38 #include "XMLUtil.h"
  39 #include "SettingsStore.h"
  40
  41 using namespace std;
  42
  43 extern CFileLogger* g_pLogger;
  44
  45 const int USER_LOG_DEFAULT_SIZE_TRIAL_XML   = 65536;    // How big we think the XML string representing a single trial will be
  46 const int LOG_MOUSE_EVERY_MS                = 200;      // How often to log the mouse position (-1 for never), the frequency is also depends on how often the WM_TIMER event fires in dasher
  47
  48 static const string    USER_LOG_SIMPLE_FILENAME         = "dasher_usage.log";      // Filename of the short text log file
  49 static const string    USER_LOG_DETAILED_PREFIX         = "dasher_";               // Prefix of the detailed XML log files
  50 static const bool      USER_LOG_DUMP_AFTER_TRIAL        = true;                    // Do we want to dump the XML after each trial is complete?
  51 static const string    USER_LOG_CURRENT_TRIAL_FILENAME  = "CurrentTrial.xml";      // Filename we look for information on what the subject is doing
  52
  53 enum eUserLogLevel
  54 {
  55   userLogSimple           = 1,    // Simple running log file
  56   userLogDetailed         = 2     // Detailed per session user trial style
  57 };
  58
  59 #ifndef VECTOR_STRING
  60 typedef vector<string>                      VECTOR_STRING;
  61 #endif
  62 #ifndef VECTOR_STRING_ITER
  63 typedef vector<string>::iterator            VECTOR_STRING_ITER;
  64 #endif
  65 #ifndef VECTOR_VECTOR_STRING
  66 typedef vector<VECTOR_STRING>               VECTOR_VECTOR_STRING;
  67 #endif
  68 #ifndef VECTOR_VECTOR_STRING_ITER
  69 typedef vector<VECTOR_STRING>::iterator     VECTOR_VECTOR_STRING_ITER;
  70 #endif
  71
  72 /// \ingroup Logging
  73 /// @{
  74
  75 // We need to be notified when parameters we are logging get changed, but UserLogBase
  76 // is already watching BP_DASHER_PAUSED
  77 class CUserLog : public CUserLogBase, protected Dasher::CSettingsUserObserver {
  78 public:
  79   CUserLog(Dasher::CSettingsUser *pCreateFrom, Observable<const Dasher::CEditEvent *> *pHandler, int iLogTypeMask);
  80
  81   ~CUserLog();
  82
  83   // Methods called whenever our user interface gets a relevant event, this
  84   // object will decide how to put it into its representation.
  85   void                        AddParam(const string& strName, const string& strValue, int iOptionMask = 0);
  86   void                        AddParam(const string& strName, double dValue, int iOptionMask = 0);
  87   void                        AddParam(const string& strName, int iValue, int iOptionMask = 0);
  88   void                        StartWriting();
  89   void                        StopWriting(float dNats);
  90   void                        StopWriting();
  91   void                        AddSymbols(Dasher::VECTOR_SYMBOL_PROB* pVectorNewSymbolProbs, eUserLogEventType iEvent = userLogEventMouse);
  92   void                        DeleteSymbols(int iNumToDelete, eUserLogEventType iEvent = userLogEventMouse);
  93   void                        NewTrial();
  94
  95   void                        AddWindowSize(int iTop, int iLeft, int iBottom, int iRight);
  96   void                        AddCanvasSize(int iTop, int iLeft, int iBottom, int iRight);
  97   void                        AddMouseLocation(int iX, int iY, float dNats);
  98   void                        AddMouseLocationNormalized(int iX, int iY, bool bStoreIntegerRep, float dNats);
  99   void                        OutputFile();
 100   void                        InitIsDone();
 101   void                        SetOuputFilename(const string& strFilename = "");
 102   int                         GetLogLevelMask();
 103   void KeyDown(int iId, int iType, int iEffect);
 104   void                        HandleEvent(int iParameter);
 105
 106   // Methods used by utility that can post-process the log files:
 107   CUserLog(string strXMLFilename);
 108   VECTOR_VECTOR_STRING        GetTabMouseXY(bool bReturnNormalized);
 109   VECTOR_VECTOR_DENSITY_GRIDS GetMouseDensity(int iGridSize);
 110
 111 protected:
 112   CTimeSpan*                  m_pApplicationSpan;         // How long the application has been up
 113   string                      m_strFilename;              // Name we output our XML file to
 114   VECTOR_USER_LOG_TRIAL_PTR   m_vpTrials;                 // Holds object for each trial in this session
 115   VECTOR_USER_LOG_PARAM_PTR   m_vParams;                  // Stores general parameters we want in the XML
 116   double                      m_dLastMouseUpdate;         // When the last mouse update was pushed
 117   bool                        m_bSimple;                  // Are we outputting the simple running log file?
 118   bool                        m_bDetailed;                // Are we outputting per session detailed logs?
 119   CFileLogger*                m_pSimpleLogger;            // Used to log the simple running log file
 120   bool                        m_bIsWriting;               // Has StartWriting() been called but not StopWriting()?
 121   bool                        m_bInitIsDone;              // Set to true once the initialization of default values is done
 122   WindowSize                  m_sCanvasCoordinates;       // The size of our canvas from the last call to AddCanvasSize()
 123   WindowSize                  m_sWindowCoordinates;       // Records the window coordinates at the start of navigation
 124   bool                        m_bNeedToWriteCanvas;       // Do we need to write new canvas coordinates on the next navigation?
 125   int                         m_iLevelMask;               // What log level mask we were created with.
 126   string                      m_strCurrentTrialFilename;  // Where info about the current subject's trial is stored
 127
 128   // Used whenever we need a temporary char* buffer
 129   static const int            TEMP_BUFFER_SIZE = 4096;
 130   char                        m_szTempBuffer[TEMP_BUFFER_SIZE];
 131
 132   CUserLogTrial*              AddTrial();
 133   CUserLogTrial*              GetCurrentTrial();
 134   string                      GetXML();
 135   bool                        WriteXML();
 136   bool                        UpdateMouseLocation();
 137   string                      GetParamsXML();
 138   void                        PrepareNewTrial();
 139   string                      GetCycleParamStats();
 140   string                      GetVersionInfo();
 141   void                        InitMemberVars();
 142   void                        AddInitialParam();
 143   void                        UpdateParam(int iParameter, int iOptionMask);
 144
 145   // Things that support simple stats of a single Start/Stop cycle:
 146   Dasher::VECTOR_SYMBOL_PROB  m_vCycleHistory;          // Tracks just the most recent Start/Stop cycle, used for simple logging
 147   unsigned int                m_iCycleNumDeletes;       // Track number of deletes in last Start/Stop cycle
 148   CSimpleTimer*               m_pCycleTimer;            // Length of the last Start/Stop cycle
 149   double                      m_dCycleMouseNormXSum;    // Sum of all normalized mouse X coordinates
 150   double                      m_dCycleMouseNormYSum;    // Sum of all normalized mouse Y coordinates
 151   unsigned long               m_iCycleMouseCount;       // How many mouse updates have been stores
 152   double                      m_dCycleNats;             // The last nats value we got from a mouse event
 153
 154   string                      GetStartStopCycleStats();
 155   double                      GetCycleBits();
 156   void                        ComputeSimpleMousePos(int iX, int iY);
 157   void                        ResetCycle();
 158   void                        InitUsingMask(int iLogLevelMask);
 159
 160 };
 161 /// @}
 162
 163 #endif