tnt.metrics
Class TnWPM

java.lang.Object
  extended by tnt.metrics.TnWPM
All Implemented Interfaces:
TnMetric

public class TnWPM
extends java.lang.Object
implements TnMetric

This program accounts for mental processing time and predict the asymptotic text entry rate using one- or two-thumb input on an ambiguous keyboard. It was previously called FittsTwoThumb.java and used on miniature QWERTY keyboards.

From FittsTwoThumb.java:
Text entry using two thumbs on a miniature Qwerty keyboard is distinctly different from touch typing on a standard keyboard or stylus input on a soft keyboard. The full details of the two-thumb text entry model are provided in MacKenzie and Soukoreff's A model of two-thumb text entry. Update: This model now accounts for keys that are assigned to both left and right thumbs (e.g. keys in the center of the keyboard that can easily be pressed by either thumb). A key pressed twice in succession is pressed with the same thumb, but if two successive keys are assigned to both thumbs, then thumb assignment is alternated/balanced.

Regarding the Model Definition File or Object:
This program works in concert with a model definition file (e.g. model.txt) or an object from the ModelDefinition.java class. The contents specify various components and prameters for the model.

Important:
Words must contain only lowercase letters and the keystroke case should match the case used to assign left and right thumb letters in the model definition. All keystroke strings should be space-terminated (i.e. end with the character identifying the SPACE key). All keys used for text entry (except the SPACE key) should be assigned to the right thumb, left thumb or to both. The SPACE key is exempt, as it is assigned by the "space key policy".

If the defined keyboard is an ambiguous one, the keystroke field must have the appropriate number of presses of Next (typically indicated by 'N') appended to it (see TnKSPC.java). Furthermore, the NEXT key must also be assigned to the right thumb, left thumb or to both by including the corresponding character identifier in at least one of those fields.

Example invocations (using various models):

        PROMPT>java TnWPM ?
        usage: java TnWPM model.txt [-p] [-b] [-d] [-m] [-t] [-l]

        where model.txt = a model definition file
              -p = prediction
              -b = breakdown of prediction
              -d = debug information
              -m = model components and parameters
              -t = thumb usage statistics

           Default output is WPM prediction only.

        PROMPT>java TnWPM -p
        wpm = 59.18646136479296

        PROMPT>java TnWPM -b
        Number of unique words = 9022
        Total of frequencies = 67962112
        Quickest to enter = a (0.267 seconds)
        Slowest to enter = telecommunications (4.319 seconds)
        tCorpus = 7.478035148478729E7
        nCorpus = 368832032
        tChar = 0.20274907002867712
        -----

        PROMPT>java TnWPM -m
        MODEL PARAMETERS
        Corpus: d1-wordfreqks.txt
        Keyboard: SharpEL-6810
        Left thumb letter assignments: qwertasdfgzxcvb
        Right thumb letter assignments: yuiophjklnm
        Left thumb ratio of keystroks endings (w/o SPACE): 0.7048896155552081
        Right thumb ratio of keystroke endings (w/o SPACE): 0.2951103844447918
        Fitts' law coefficients...
        Left thumb intercept: 176.0
        Left thumb slope: 64.0
        Right thumb intercept: 176.0
        Right thumb slope: 64.0
        tMIN: 0.088
        Space key policy: Alternate
        Values for perceptual, cognitive and motor processes...
        Eye movement time: 0
        Perceptual processor cycle time: 0
        Motor processor cycle time: 0
        Cognitive processor cycle time: 0
        Time to determine if same word: 0
        -----

        PROMPT>java TnWPM -t
        THUMB USAGE
        All... (n = 368832032)
        L = 195459980 (52.99%), R = 173372052 (47.01%),
        LL = 78917833 (21.40%), LR = 116542147 (31.60%),
        RR = 56829905 (15.41%), RL = 116542147 (31.60%)
        Keystroke beginnings... (n = 67962112)
        L = 44686347 (65.75%), R = 23275765 (34.25%)
        Kkeystroks endings (w/o SPACE)... (n = 67962112)
        L = 47905787 (70.49%), R = 20056325 (29.51%)
        -----

        PROMPT>type hello.txt
        hello 1 helloS

        PROMPT>java TnWPM -d      (Note: word-freq file = hello.txt)
 hello ***
        1 : h : .R     : 0.306 -> 1.0*tFitts + 0.0*tMin
        2 : e : RL <0> : 0.088 -> max(0.306+0.088, 0.000+0.377)
        3 : l : LR <1> : 0.271 -> max(0.394+0.088, 0.306+0.359)
        4 : l : RR     : 0.176 -> tFitts
        5 : o : RR     : 0.270 -> tFitts
        6 : S : RL <2> : 0.088 -> max(1.112+0.088, 0.394+0.377)
        t[] = 0.306, 0.394, 0.666, 0.842, 1.112, 1.200
        -----
        

Version:
1.0 - 2001 (MacKenzie and Soukoreff's A model of two-thumb text entry),
1.1 - 03/2005 (Accounts for overlapping thumb-letter assignments, e.g. SureType keyboard),
1.2 - 08/2005 (Accounts for perceptual, cognitive and motor processs),
1.2.1 - 10/2005 (Streamlined and renamed TnWPM.java),
1.2.2 - 02/2006 (Progress reporting and halting functionality added.)
Author:
Scott MacKenzie,
Steven John Castellucci
See Also:
ModelDefinition.java, TnKSPC.java

Constructor Summary
TnWPM(ModelDefinition m)
          Loads WPM parameters from the passed ModelDefinition object.
TnWPM(java.lang.String modelDefFile)
          Loads WPM parameters from the model definition file.
 
Method Summary
 java.lang.String breakdownText()
          Returns breakdown data, formatted to be printed to the console.
 void cancel()
          Signals calculation of this metric to stop.
 boolean cancelled()
          Returns whether or not cancel() was called on this metric.
 float getProgress()
          Returns a float in the range [0..1], representing the progress of the process() method.
 java.lang.String getUnassignedKeys()
          Returns a keys that appear in the keystroke field of the corpus, but are not assigned to either thumb.
static void main(java.lang.String[] args)
          Allows this class to be run from the command-line.
 void printDebugData()
          Outputs debug information to the console.
 void printModelData()
          Outputs model data to the console.
 void process()
          Performs the required calculations and actions to determine the value and result of this metric.
 java.lang.String thumbUsageText()
          Returns thumb usage statistics, formatted to be printed to the console.
 java.lang.String wpmText()
          Returns WPM value, formatted to be printed to the console.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TnWPM

public TnWPM(java.lang.String modelDefFile)
      throws FormatException,
             java.io.FileNotFoundException,
             java.io.IOException
Loads WPM parameters from the model definition file.

Parameters:
modelDefFile - the name of the model definition file.
Throws:
FormatException - if the file has a formating error.
java.io.FileNotFoundException - if the file cannot be read.
java.io.IOException - if an IO error occurs.

TnWPM

public TnWPM(ModelDefinition m)
Loads WPM parameters from the passed ModelDefinition object.

Parameters:
m - ModelDefinition objcet to use.
Method Detail

process

public void process()
Description copied from interface: TnMetric
Performs the required calculations and actions to determine the value and result of this metric.

Specified by:
process in interface TnMetric

getProgress

public float getProgress()
Description copied from interface: TnMetric
Returns a float in the range [0..1], representing the progress of the process() method.

Specified by:
getProgress in interface TnMetric
Returns:
a float in the range [0..1], representing the progress of the process() method.

cancel

public void cancel()
Description copied from interface: TnMetric
Signals calculation of this metric to stop.

Specified by:
cancel in interface TnMetric

cancelled

public boolean cancelled()
Description copied from interface: TnMetric
Returns whether or not cancel() was called on this metric.

Specified by:
cancelled in interface TnMetric
Returns:
true iff cancel() was called on this metric object.
See Also:
TnMetric.cancel()

wpmText

public java.lang.String wpmText()
Returns WPM value, formatted to be printed to the console. For example:
                wpm = 59.18646136479296
                

Returns:
a String representing the WPM value, formatted to be printed to the console.

breakdownText

public java.lang.String breakdownText()
Returns breakdown data, formatted to be printed to the console. For example:
                Number of unique words = 9022
                Total of frequencies = 67962112
                Quickest to enter = a (0.267 seconds)
                Slowest to enter = telecommunications (4.319 seconds)
                tCorpus = 7.478035148478729E7
                nCorpus = 368832032
                tChar = 0.20274907002867712
                

Returns:
a String representing breakdown data, formatted to be printed to the console.

printDebugData

public void printDebugData()
Outputs debug information to the console. For example:
                PROMPT>type hello.txt
                hello 1

                PROMPT>java TnWPM -d      (Note: word-freq file = hello.txt)
 hello ***
                1 : h : .R     : 0.306 -> 1.0*tFitts + 0.0*tMin
                2 : e : RL <0> : 0.088 -> max(0.306+0.088, 0.000+0.377)
                3 : l : LR <1> : 0.271 -> max(0.394+0.088, 0.306+0.359)
                4 : l : RR     : 0.176 -> tFitts
                5 : o : RR     : 0.270 -> tFitts
                6 : _ : RL <2> : 0.088 -> max(1.112+0.088, 0.394+0.377)
                t[] = 0.306, 0.394, 0.666, 0.842, 1.112, 1.200
                


printModelData

public void printModelData()
Outputs model data to the console. For example:
                MODEL PARAMETERS
                Corpus: d1-wordfreqks.txt
                Keyboard: SharpEL-6810
                Left thumb letter assignments: qwertasdfgzxcvb
                Right thumb letter assignments: yuiophjklnm
                Left thumb ratio of word endings: 0.7048896155552081
                Right thumb ratio of word endings: 0.2951103844447918
                Fitts' law coefficients...
                Left thumb intercept: 176.0
                Left thumb slope: 64.0
                Right thumb intercept: 176.0
                Right thumb slope: 64.0
                tMIN: 0.088
                Space key policy: Alternate
                Values for perceptual, cognitive and motor processes...
                Eye movement time: 0
                Perceptual processor cycle time: 0
                Motor processor cycle time: 0
                Cognitive processor cycle time: 0
                Time to determine if same word: 0
                


thumbUsageText

public java.lang.String thumbUsageText()
Returns thumb usage statistics, formatted to be printed to the console. For example:
                All... (n = 368832032)
                L = 195459980 (52.99%), R = 173372052 (47.01%),
                LL = 78917833 (21.40%), LR = 116542147 (31.60%),
                RR = 56829905 (15.41%), RL = 116542147 (31.60%)

                Keystroke beginnings... (n = 67962112)
                L = 44686347 (65.75%), R = 23275765 (34.25%)

                Keystroke endings... (n = 67962112)
                L = 47905787 (70.49%), R = 20056325 (29.51%)
                
Note that thumb usage applies to keystrokes, while word beginnings/endings applies to the words.

Returns:
a String representing the thumb usage statistics, formatted to be printed to the console.

getUnassignedKeys

public java.lang.String getUnassignedKeys()
Returns a keys that appear in the keystroke field of the corpus, but are not assigned to either thumb.

Returns:
a String whose characters represent keys not assigned

main

public static void main(java.lang.String[] args)
                 throws FormatException,
                        java.io.FileNotFoundException,
                        java.io.IOException
Allows this class to be run from the command-line.

Throws:
FormatException
java.io.FileNotFoundException
java.io.IOException