## Class SoftKeyboardExperiment

- java.lang.Object
- - SoftKeyboardExperiment

-     public class SoftKeyboardExperiment
      extends java.lang.Object

  # SoftKeyboardExperiment

  ## Summary

  - Experiment software for text entry using a soft keyboard

  - Several soft keyboard layouts are supported:

    - Qwerty
    - Opti
    - Phone
    - L4K
    - Metropolis
    - LKL (Lewis-Kennedy-LaLomia)
    - Fitaly *

  - Custom keyboards supported through external key-def text files

  - New (October 2018). Support for
    - Word completion
    - Ambiguous keyboards
  - New (March 2019). Support for
    - Keyboard scale

  ## Related References

  - "The Design and Evaluation of a High Performance Soft Keyboard", by MacKenzie and Zhang (CHI '99). This is the paper where the Opti design was introduced. Opti was the first soft keyboard to be designed using a Fitts-digram model.

  - "Predicting Text Entry Speed on Mobile Phones", by Silverberg, MacKenzie, and Korhonen. This paper examines the predictive T9 entry method for mobile phones.

  - "Text Entry Using a Small Number of Buttons". This book chapter presents a detail analysis of ambiguous keyboards.

  - "KSPC (Keystrokes per Character) as a Characteristic of Text Entry Techniques". This is the paper that introduced KSPC as an analytic metric for text entry on soft keyboards. Both non-ambiguous and ambiguous keyboards are included in the analysis.

  - "Physics-based Graphical Keyboard Design", by Hunter, Zhai, and Smith (CHI 2000). This paper introduced the Metropolis soft keyboard, offered as an alternative Opti. Metropolis was also designed using a Fitts-digram model; however, the design process was automated using an algorithm.

  - "Evaluation of Typing Key Layouts for Stylus Input", by Lewis, LaLomia, & Kennedy (HFES '99). This is the paper introducing the LKL (Lewis-Kennedy-LaLomia) keyboard.

  - Textware Solutions web site. Textware Solutions is the company that introduced the Fitaly soft keyboard.

  - "Text Entry for Mobile Computing: Models and Methods, Theory and Practice", by MacKenzie and Soukoreff (Human-Computer Interaction, 2002). This paper includes an extensive section on soft keyboards, including a comparison of entry speed predictions using a Fitts-digram model. The comparison includes Qwerty, Opti, Metropolis, LKL, Fitaly, and several other layouts (Figure 21).

  - "Theoretical Upper and Lower Bounds on Typing Speed Using a Stylus and Soft Keyboard", by Soukoreff and MacKenzie (Behaviour & Information Technology, 1995). This is the paper that introduced the Fitts-digram model for designing soft keyboards.

  ## Background

  This software is for testing soft or virtual keyboards rendered on a computer display. Input is typically with a finger or stylus. Other forms of input are possible, such eye, head, or face tracking in combination with a selection method such as dwell-time selection. Mouse input can be used but this is generally not the intended mode of interaction for a soft keyboard.

  In designing a soft keyboard, the goal is often to improve input over the standard Qwerty keyboard. Sometimes improvements are achieved by rearranging keys, with keys bearing common letters clustered in the middle of the keyboard. An example is Opti which minimizes stylus or finger movement for English text entry on a soft keyboard (1st reference above). Consider the movements required to enter "airplane":

  Clearly, there is less finger or stylus movement for the Opti design. The trick is to minimize movement as an overall average for text entry in a particular language, such as English.

  Sometimes improved performance is achieved by adding word completion: As a word is entered, a list of suggested words is presented to the user. The entries in the list are based on the current word stem and a built-in dictionary of words and word-frequencies in the target language. Before entering the full word, the user selects a word from the word completion list, thus saving keystrokes.

  Another consideration is size. Many computing devices, such as mobile phones or smart watches, are small. In such cases, a design with fewer keys might work well. One approach is an ambiguous keyboard. With an ambiguous keyboard, there are fewer letter-keys than letters. The classic example is the phone keypad which positions 26 letters on 8 keys (2nd reference above). But, other possibilities exist where there are even fewer keys. An example is the L4K keyboard which positions 26 letters on just 4 keys (3rd reference above). Both the phone and L4K keyboards are implemented herein.

  ## Running the Experiment Software

  Click here for instructions on launching/running the application.

  ## Setup Parameters

  Upon launching, the program presents a setup dialog:

  The default parameter settings are read from a configuration file called `SoftKeyboardExperiment.cfg`. This file is created automatically when the application is launched for the first time. The default parameter settings may be changed through the setup dialog. The setup parameters are as follows:

  > Parameter | Description
  > --- | ---
  > Participant code | Identifies the current participant. This is used in forming the names for the output data files. Also, the sd2 output data file includes a column with the participant code.
  > Condition code | An arbitrary code used to associate a test condition with this invocation. This parameter might be useful if the software is used in an experiment, since conditions might be tested that are not inherently part of the application (e.g., Gender → male, female; Input method → mouse, stylus). The condition code is used in forming the name for the output data file. Also, the sd2 output data file contains a column with the condition code.
  > Session code | Identifies the session. Useful if testing proceeds over multiple sessions to gauge the progression of learning. The session code is used in forming the name for the output data file. Also, the sd2 output data file contains a column with the condition code. Note: The setup dialog does not include an entry for "Block code". The block code is generated automatically by the software.
  > Number of phrases | Specifies the number of phrases presented to the participant in the current block.
  > Phrases file | Specifies a file containing phrases of text to be presented to participants for entry. Phrases are drawn from the file at random. Typically, phrases2.txt is used. This is the phrase set published by MacKenzie and Soukoreff in 2003 (see Related references, above). Other file names may be specified. For example, the file quickbrownfox.txt contains the phrase
  >          the quick brown fox jumps over the lazy dog
  > This phrase might be useful for demonstration or specialized testing.
  > Dictionary file | Specifies a word-freq file containing words and their frequencies to be used for word completion and for disambiguation (for ambiguous keyboards). The default is `d1phrases2-wordfreq.txt` which contains about 10,000 words, including all words in `phrases2.txt`. An alternative is `phrases2-wordfreq.txt` which contains only the 1163 unique words in `phrases2.txt`. Obviously, there is less ambiguity with a small dictionary. Using such a dictionary is perhaps unrealistic, since text entry involves considerably more words. However, using a small dictionary might be realistic if contextual word completion or correction is also used.
  > Show presented text during input | A checkbox item that determines whether or not the presented text is visible during entry of a phrase. Either way, the text phrase appears at the beginning of a trial. If this option is unchecked, the phrase will disappear when the first keystroke is entered.
  > Keyboard | Identifies the soft keyboard to use in the experiment. The options currently supported are as follows: (click to enlarge) Qwerty Opti Phone L4K Metropolis Lewis-Kennedy-LaLommia Fitaly Custom (see below)
  > Keyboard scale | A scaling factor to increase or decrease the default size of the soft keyboard. The scalling factor is used in forming the name for the output data file. Also, the sd2 output data file contains a column with the condition code.
  > Custom keyboard | Used in conjunction with the Custom option above to select a custom keyboard layout. The layout is read from a keyboard definition file which is selected from a file chooser. The file chooser opens when the "Browse..." button is clicked.
  > Word completion list size | Specifies 0, 1, 3, or 5 words for a word-completion list. Choosing zero effectively disables this options. If 1, 3, or 5 is chosen, suggested words appear above the keyboard as entry proceeds. Selecting words from the word completion list has the potential to reduce the number of keystrokes and speed-up entry. Words are suggested based on a built-in dictionary. The default dictionary contains about 10,000 words.

  ## Program Operation

  The experiment launches with the selected soft keyboard displayed and with a text phrase presented for input. Examples are shown below for the Qwerty layout without word completion (left) and with word completion (right).

  At the end of each phrase, a popup dialog gives results for the phrase. Here's an example:

  ## Custom Mode

  The last item in the Keyboard drop-down list is "Custom (select below)". If this option is selected, a custom keyboard is then selected using the setup item below, "Custom keyboard". This option allows the software to use a custom layout which is read from a text file. The "Browse..." button pops up a file chooser to select the keyboard definition file for the custom layout. Three examples are provided. Study the definition files to learn how to define additional customized soft keyboards.

  Dvorak. A custom example is provided for the well-known Dvorak layout: `dvorak.txt`. If this file is selected, the program launches with the following soft keyboard:

  L2K. Another example is L2K, an ambiguous keyboard that contains just two letter-keys: `letters_on_two_keys.txt`. If this file is selected, the program launches with the following soft keyboard:

  As an ambiguous keyboard, the L2K keyboard works with word completion and a disambiguation algorithm. See the 3rd reference above for details on the design, operation, and rationale for the L2K and other ambiguous keyboards.

  L6K. Another example is L6K, an ambiguous keyboard with six letter-keys. To provide ideas for designs to compare in a user study, four variations are provided:

  - (a) `letters_on_six_keys_a.txt` – 2x3 small,
  - (b) `letters_on_six_keys_b.txt` – 2x3 big,
  - (c) `letters_on_six_keys_c.txt` – 3x2 small, and
  - (d) `letters_on_six_keys_d.txt` – 3x2 big.

  Here they are: (click to enlarge)

  (a) (b) (c) (d)

  Perhaps you can think of other designs suitable for empirical testing.

  ## Output Data Files

  At the end of a block of phrases, results are written to files. There are two output data files, an "sd1" file and an "sd2" file. ("sd" is for "summary data".) The sd1 file contains data on a keystroke by keystroke basis, including timestamps. The sd2 file contains summary data for each phrase, one line per phrase. Examples follow:

  - sd1 example
  - sd2 example

  Actual output files use "SoftKeyboardExperiment" as the base filename. This is followed by the participant code, the condition code, the keyboard, the session code, and the block code. An example might be `SoftKeyboardExperiment-P01-C01-OP-Scale_1.00-S01-B01.sd1`.

  In most cases, the sd2 data files are the primary files used for data analyses in an experimental evaluation. The data in the sd2 files are full-precision, comma-delimited, to facilitate importing into a spreadsheet or statistics application. Below is an example for the sd2 file above, after importing into Microsoft Excel: (click to enlarge)

  Columns A-H are the conditions present for entry of a phrase. Columns I-P are the user performance measures computed during entry of the phrase. Most of the performance measures are well known in text-entry research.

  Efficiency (column J) is computed as Keystrokesmin / Keystrokesactual, where Keystrokes min is the minimum number of keystrokes required to enter a phrase, and Keystrokesactual is the actual number of keystrokes entered by the user. Efficiency is only valid if the error rate is 0%. If the phrase is entered error-free and the user enters it in as few keystrokes as possible, efficiency = 1, or 100%. If the transcribed phrase is error-free, it is still possible that the user's input is sub-optimal, resulting in efficiency < 1. Sub-optimal input occurs, for example, if there are additional keystrokes for correcting mistakes or if the user does not select words in the word completion list when they first appear.

  ## Miscellaneous

  When using this program in an experiment, it is a good idea to terminate all other applications and disable the system's network connection. This will maintain the integrity of the data collected and ensure that the program runs without hesitations.

  For demonstration, a mouse can be used for input, but finger or stylus input is more appropriate and should be used if possible.

  Author:
    Scott MacKenzie, 2011-2018, Steven Castellucci, 2014

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SoftKeyboardExperiment()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `main(java.lang.String[] args)`

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

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

- - ### Constructor Detail

    - #### SoftKeyboardExperiment

          public SoftKeyboardExperiment()

  - ### Method Detail

    - #### main

          public static void main(java.lang.String[] args)
                           throws java.io.IOException

      Throws:
        `java.io.IOException`