ETHO DOCUMENTATION

Etho is a program designed to allow the user to capture the precise time of observed events by striking keys on the computer. Its primary use is intended to be making records of behavioral events, however it is flexibly designed and could be used to record any event.

OVERVIEW
For the most part, Etho is simple and its use should be relatively intuitive and need little explanation. When started up, the initial screen has buttons or menu items for all the major features of the program. You can enter some specific assay parameters in the boxes, which will be saved in your output file appropriately labeled. You can modify many Etho settings (see below for specifics) using the Settings Frame. After you have accumulated some Etho timer output files, you can use the Analysis Frame button to process groups of these files in various ways.

Finally, you can open the Timer Frame, from which you initiate, perform, and save your assay. In the Timer Frame, use the Start Timer button to initiate the assay. The precise time of the activation is recorded, and the keyboard is activated for input. Pressing any of 13 keys will result in a record of the key and the exact time it was pressed. The 13 keys are set by default to 'j', 'k', 'l', ';', spacebar, 'u', 'i', 'o', 'p', 'n', m', ',', and '.', which were chosen because they are easy to use with one hand on most laptop computers without looking. If you want to change the keys used (for example if you will type with your left hand), you can do so in the Settings Frame. During the assay, you may use 3 special keys: the 'q' key will end the timer, the 's' key will result in an interim save file being written (crash protection), and the backspace key will cancel the last key stroke record in case you make a mistake. When the assay is finished, press "q" or click the Stop and Save button, which result in the same action. The end time of the assay is recorded, a variety of calculations are made, and a simple graphical output of the assay is generated, in which each unit of time is represented either by a dot (no event) or a letter (key press event). You are also prompted to save the data to a file if you want.

Four sample assay results are included in the "EthoSupportFiles" folder. These are real assays collected by Jeanna Wheeler, a graduate student in the Thomas lab. They are records of defecation motor events in N2 wild type on reduced food concentrations. You can open them with a text editor or load them in the Etho analysis frame to see how computations are done. (Note - these assays used only 9 keys. Etho analysis should handle older files gracefully because the key-stroke parameters are determined from the assay file itself.)

SETTINGS
A variety of preferences can be set for Etho. By default, they are stored in a file called "ethoprefs.serial", which is in the same folder with the Etho program. If you reset preferences while Etho is running, they will take immediate effect and will also be stored for the future. The settable preferences are: 1) the nine keys used, plus their screen and file save output and their ethogram letter; 2) whether to do mean and standard deviation calculations for the intervals between specific keystrokes; 3) whether to do calculations relating the frequency of one keystroke to another one; 4) the time unit for the ethogram and whether to include an ethogram; 5) whether to use special keystrokes 'q', 's', and 'c' during the assay; and 6) the time interval for a "whoosh" sound and whether to use the sound.

To change Settings, click the Settings Frame button in the startup window. Use the tabs to switch between Preference categories and either type into the boxes or check and uncheck boxes to change the settings. If you make text changes be sure to press "Enter" to record them before saving - the table box should change color in response. You can also view the Settings to remind yourself of the current settings without making changes.

You can also save your own Settings files and load them using the appropriate buttons in Settings Frame. This permits you to create different Settings profiles for different types of assays and also to have your own settings in case the Etho program is used by others and settings are changed by them. The program will always start up using the default preferences file, so remember to check them and load your own if needed before starting an assay.

Records settings: The left column determines the word or phrase that will be shown on the screen during the assay (and later saved to the assay file) when you press the corresponding key. You may set them to any word or phrase, but I suggest a short entry as it keeps the output uncluttered. The center column determines the character that will be used in the ethogram output. Only a single letter is used, in order to maintain the appropriate graphical spacing for events. The right column determines the nine keys that are active for recording during the assay. Pressing any key other than these (and special keys if used) will cause a bonk sound as a warning but will result in no other output. .

Key duration settings: You can set key 1 and key 2 to be used in a different mode. Specifically, if you select this feature, the program will record the time the key is pressed AND the time it is released. Calculations can be performed on the duration of the key press. This mode simplifies collection of data records in which the duration of an event is of interest (though of course you could press two normal keys to record the beginning and ends of events). As with the other key mode, you can use the table to modify the way the keys are recorded. If you make text changes be sure to press "Enter" to record them before saving - the table box should change color in response.

Mean and SD settings: The types of calculations you can make are preset, but you can choose to leave them out if you prefer. Check or uncheck the boxes to choose to calculate mean and standard deviation for the intervals between each key. You can make similar calculations at a later time by using the Analysis functions (partially implemented at this time).

Key relate settings: Similar to Mean and SD settings, but allows the calculation of the frequency of one key stroke compared to another.

Other option settings: Choose whether or not to use various optional key strokes and a time sound warning (and its interval). One experimental setting on this panel is only transient (it won't get saved as a preference and the default is off when you start the program). If checked, the program will attempt to warn you just before the next key 1 event should occur. This is based on the mean for all previous key 1 intervals, and will only activate when there are at least two such intervals and the standard deviation is less than 15% of the mean. Under these conditions, a two-tone ping sound will play quietly one standard deviation before the next key 1 event should occur. If the standard deviation is too large, a plop sound will play after one second to warn you of this fact. You can turn this feature off during a run by pressing the 'e' key.

Ethogram settings: Choose whether or not to generate an ethogram and set the time increment represented by each character in the output ethogram. The best setting will depend on the frequency of events you record and the duration of your typical assay.

TIMER FRAME
When you click the Start Timer button or press Alt 's' with the Timer Frame active, the timer initializes and immediately starts. When you press any of the defined keys, the key output and its time is displayed. At the end of the assay, the same output will be written to your save file. The keys are case sensitive. The record can be run indefinitely. When you press the 'q' key (if set) or click the Stop and Save button, the timer stops and final calculations are made and recorded. A new window will appear that contains the text that will be recorded to the saved file. YOu can make any desired changes before saving, including adding comments (there is a place for them near the top) and correcting any keystroke errors you made. Take care changing the file because if you violate the expected format, the analysis functions will fail with the file.

A small box at the lower left shows the approximate time elapsed during the assay (in seconds). Every X minutes (see Settings) a "whoosh" sound plays as an aid to keeping approximate time if you can't watch the display. On laptops, automatic power-saving features can cause problems, including mistiming the "whoosh" sound. Keep the power cord plugged in and set power-saving conditions off if you have a problem. If you do have a power-save problem, times will still be recorded approximately correctly, but computer response time to keystrokes may be delayed and there will be no indication that the record is inaccurate. One possible work around is to hit an "illegal" key every once in a while to give the computer a goose to keep the processor active. If anybody knows a better solution, let me know.

When the timer starts and at certain other times (successful file save etc.) you should hear a "ping" sound to indicate success. During an assay, when you press a legal key you should hear a "click" sound and if you hit an illegal key you should hear a "bonk" sound. These provide audible feedback that your keystroke has been recorded. If you use the backspace key to erase a keystroke, you should hear another distinctive sound. These sounds are useful when you have to keep you eyes on your assay but want feedback. They can't be turned off in Settings, but you can mute your computer sound out if they irk you.

When you are finished with your assay and comments, you will be prompted to save the data to a file. You can cancel out of the file save dialogue box if you don't want to save the particular assay, but don't do this lightly - the data will be permanently lost. If you do this, or you try to quit the program without remembering to save, you will be prompted to confirm that you really don't want to save as a safeguard. Individual assays can accumulate quickly, so using good folder (directory) organization for different types of assay is a very good plan. You can initiate further assays if you wish, or you can use other Etho functions or you can quit the Etho program.

FILE SAVE FORMATS
For each assay, two text files are saved with the same primary name but different extensions. The first file (.eth) contains essentially the same information as you see on screen while running the timer. The second file (.tab) is generated for convenient imports into statistical analysis programs or spreadsheets. Saving the .tab file can be turned off in preferences. The .tab file contains a tab-delimited series of columns, headed by the record entry (as set by the user) and followed by each of the key stroke times.

DATA ANALYSIS WINDOW
This window enables you to make a variety of simple calculations on single data files or sets of data files. To use these, first load the files you want to analyze, select the appropriate radio button, then enter the key or keys you want to analyze. Allowable buttons and entry fields become activated or inactivated appropriately. There is little error and format checking in this part of the program. You shouldn't get subtly incorrect data analysis, but you will get odd values such as -1 and perhaps other nonsense if your files don't match standard format. This won't happen unless you edit the primary data files. An "NA" entry indicates that the particular calculation is not applicable (e.g. you can't calculate a standard deviation for one interval).

In all cases the keys are analyzed based on the recorded entry for each key stroke (in Settings), so be sure they match the files you are analyzing.

Analyze one key: this function calculates the time interval between each appearance of the indicated keystroke. For each file, the number of intervals, their mean duration, their standard deviation (SD), and their standard error of the mean (SEM) are calculated. The statistical calculations are made using standard definitions.

Relate two keys: this function is very similar to single event periodicity, except that it uses the interval of time between two different events. The two events need not be reliably associated - the calculation is made using the closest pairs of events. Be careful to enter the two keys in the order you want to test them.

Analyze key down: this function calculates features of key down times. It will work only if the files loaded contain key duration (key down time) data. It calculates the number of times the key was down, the total time it was down, and the mean and standard deviation of times it was down.

Show values: this button will generate a listing of all the times each key type was pressed, for the file that is highlighted in the Analysis Frame table. Be warned that the rows in the list box do not reflect data pairing. They are simply a set of independent lists for each key, displayed together for convenience.

ETHOGRAM GENERATION WINDOW
Since this is only relevant once a file is loaded for analysis, this function is accessed via the Analysis Window when files are loaded. A menu allows to you to activate the Ethogram generation window using the data from the assay highlighted in the table. The ethogram window starts with default settings for the time interval between sequential characters and the line length. Use the text fields or the sliders to adjust each of these parameters until you get a graphical output that is most useful. If the relevant events happen to line up near line ends, you can add a positive or negative "Pad" to shift the events to a more visible region of the ethogram. You can save the current ethogram that is displayed at any time with the menu, and the settings will be saved in the file as well for future reference.

UTILITIES
You can convert old Mac RealBasic file formats to make them compatible with the analysis functions in Etho Java. You need to identify the record lines that directly precede and follow the keystroke data lines and enter them in the text boxes. Other than that, this is self-explanatory. It’s a good idea to check one of the converted files to be sure that the conversion has occurred without problems.

EDITOR WINDOW
Primarily for your convenience, a very simple text editor is included as part of Etho. If you double click an Etho data file or open one from the File Menu in the usual manner, its text contents will be shown in a text editor window. You can make changes and save the file, but be careful as I have not built in some of the usual safeguards against inadvertently losing content or files. It might be better practice to use a professional text editor - for nearly all of them, as long as you use file "Save" instead of "Save As", the file contents will remain simple text and the file ownership will remain Etho.

MISCELLANEOUS
If you want to add comments in between recorded event lines, you can do so by beginning the line with ##, which will be ignored by all data analysis methods. (Actually, anything that doesn't meet a more specific format will be ignored, but it is a good idea to stay clean (lines that begin with ## are guaranteed not to be misinterpreted.)


Please email me to report bugs, especially if they cause you to lose assay data: jht@u.washington.edu

Programmer: James H. Thomas, Department of Genetics, University of Washington

Documenter and Chief Bottle Washer: James H. Thomas, Department of Genetics, University of Washington