Package edu.wisc.game.tools

## Class MwByHuman

- java.lang.Object
- - edu.wisc.game.tools.AnalyzeTranscripts
  - - edu.wisc.game.tools.MwByHuman

-     public class MwByHuman
      extends AnalyzeTranscripts

  Ranking rule sets by the ease of learning by human players. As requested by PK, 2022-12-22.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `MwByHuman.PrecMode` | Used to control how series are assigned to comparanda

    - ### Nested classes/interfaces inherited from class edu.wisc.game.tools.AnalyzeTranscripts

      `AnalyzeTranscripts.P0andR, AnalyzeTranscripts.TrialListMap`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `String` | `infomsg` | The JSP page should always print this message.
    `Vector<MwSeries>` | `savedMws` | Info about each episode gets added here

    - ### Fields inherited from class edu.wisc.game.tools.AnalyzeTranscripts

      `quiet`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MwByHuman​(MwByHuman.PrecMode _precMode, int _targetStreak, double _targetR, double _defaultMStar, Fmter _fm)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `String` | `exceptionTrace()` |
    `void` | `exportSavedMws​(File gsum)` | Exports the data generated in Stage1
    `String` | `getErrmsg()` |
    `boolean` | `getError()` |
    `Exception` | `getEx()` |
    `String` | `getReport()` |
    `protected void` | `giveError​(Exception _ex)` |
    `protected void` | `giveError​(String msg)` | Sets the error flag and the error message
    `static void` | `main​(String[] argv)` |
    `void` | `processStage1​(Vector<String> plans, Vector<String> pids, Vector<String> nicknames, Vector<Long> uids)` | The Stage 1 processing involves scanning the transcripts for the players associated with the relevant experiment plan, and computing the required statistics for all (player,ruleSet) pairs involved.
    `void` | `processStage2​(boolean fromFile, boolean useMDagger, File csvOutDir)` | Now, the MW Test, using this.savedMws computed in stage1.
    `protected void` | `saveAnyData​(Vector<TranscriptManager.ReadTranscriptData.Entry[]> section, Vector<EpisodeHandle> includedEpisodes)` | Saves the data (the summary of a series) for a single (player, ruleSet) pair.
    `void` | `setErrmsg​(String _errmsg)` |
    `void` | `setError​(boolean _error)` |
    `void` | `setFm​(Fmter _fm)` |

    - ### Methods inherited from class edu.wisc.game.tools.AnalyzeTranscripts

      `analyzePlayerRecord, computeP0andR, removeDuplicates, splitTranscriptIntoEpisodes`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### savedMws

          public Vector<MwSeries> savedMws

      Info about each episode gets added here

    - #### infomsg

          public String infomsg

      The JSP page should always print this message. Most often it is just an empty string, anyway; but it may be used for debugging and status messages.

  - ### Constructor Detail

    - #### MwByHuman

          public MwByHuman​(MwByHuman.PrecMode _precMode,
                           int _targetStreak,
                           double _targetR,
                           double _defaultMStar,
                           Fmter _fm)

      Parameters:
        `_targetStreak` - this is how many consecutive error-free moves the player must make (e.g. 10) in order to demonstrate successful learning. If 0 or negative, this criterion is turned off
        `_targetR` - the product of R values of a series of consecutive moves should be at least this high) in order to demonstrate successful learning. If 0 or negative, this criterion is turned off

  - ### Method Detail

    - #### main

          public static void main​(String[] argv)
                           throws Exception

      Throws:
        `Exception`

    - #### getReport

          public String getReport()

    - #### getError

          public boolean getError()

    - #### setError

          public void setError​(boolean _error)

    - #### getErrmsg

          public String getErrmsg()

    - #### setErrmsg

          public void setErrmsg​(String _errmsg)

    - #### giveError

          protected void giveError​(String msg)

      Sets the error flag and the error message

    - #### giveError

          protected void giveError​(Exception _ex)

    - #### getEx

          public Exception getEx()

    - #### exceptionTrace

          public String exceptionTrace()

    - #### setFm

          public void setFm​(Fmter _fm)

    - #### processStage1

          public void processStage1​(Vector<String> plans,
                                    Vector<String> pids,
                                    Vector<String> nicknames,
                                    Vector<Long> uids)
                             throws Exception

      The Stage 1 processing involves scanning the transcripts for the players associated with the relevant experiment plan, and computing the required statistics for all (player,ruleSet) pairs involved.
      Throws:
        `Exception`

    - #### exportSavedMws

          public void exportSavedMws​(File gsum)
                              throws IOException

      Exports the data generated in Stage1
      Parameters:
        `gsum` - File to write
      Throws:
        `IOException`

    - #### processStage2

          public void processStage2​(boolean fromFile,
                                    boolean useMDagger,
                                    File csvOutDir)

      Now, the MW Test, using this.savedMws computed in stage1. Generates a report that's attached to this.results.
      Parameters:
        `precMode` - Controls how the series are assigned to "distinct experiences".
        `fromFile` - Indicates that the m* data have come from an extrernal file, and are not internally computed.

    - #### saveAnyData

          protected void saveAnyData​(Vector<TranscriptManager.ReadTranscriptData.Entry[]> section,
                                     Vector<EpisodeHandle> includedEpisodes)
                              throws IOException,
                                     IllegalInputException,
                                     RuleParseException

      Saves the data (the summary of a series) for a single (player, ruleSet) pair. The saved data is put into an MwSeries object, which is then appened to savedMws. In some cases, a series can be skipped (not saved). This is the case if only the data for a specific target is requested (target!=null), or if we only want the data for "Naive" players.

      This method is called from AnalyzeTranscripts.analyzePlayerRecord(), overriding the eponymous method in that class.

      Overrides:
        `saveAnyData` in class `AnalyzeTranscripts`
      Parameters:
        `section` - A vector of arrays, each array representing the recorded moves for one episode. In its entirety, `section` describes all episodes in the series. Before returning, this method clears this array.
        `includedEpisodes` - All non-empty episodes played by this player in this rule set. This array must be aligned with section[]. Before returning, this method clears this array.
      Throws:
        `IOException`
        `IllegalInputException`
        `RuleParseException`