JWatcherTM 1.0An Introductory User’s GuideDaniel T. Blumstein, Janice C. Daniel & Christopher S. Evans ! 2006–Daniel T. Blumstein, Janice C. Daniel & Christopher S. EvansAll rights reserved.Last modified: 9 January 2006

JWatcher 1.0: An introductory user’s guide2Table of Contents1 Thank you!42 A brief overview of JWatcher42.1 Compatibility and Reliability52.2 Installing JWatcher62.3 Compatibility with JWatcher 0.9 Files62.4 Legal MumboJumbo72.5 Acknowledgements73 Using JWatcher84 Global Definition135 Focal Master145.1 Define Codes145.2 Test Details145.3 Questions156 Data Capture166.1 Data File166.2 Questions and Answers166.3 Capture Data166.4 Note on “initializing a focal”177 Edit Data188 Focal Analysis Master198.1 Modifiers208.2 States208.3 Exclusions228.4 Time238.5 State Analysis248.6 Conditional States298.7 Event Analysis318.8 Conditional Events339 Combinations3510 Analysis3710.1 Data37

JWatcher 1.0: An introductory user’s guide10.2 Reliability33811 Summarize Results4012 Sequential Analysis4212.1General4312.2Runs4512.3Sequence Analysis4612.4Markovian Analysis4912.5Lag Sequential5012.6Complex Sequences5213 Strategies for using JWatcher5814 Warnings and errors6015 Frequently asked questions about JWatcher6616 References71

JWatcher 1.0: An introductory user’s guide41 Thank you!Since releasing JWatcher 0.9 in November 2000, we have had thousands ofdownloads from all over the world. Neuroscientists, human factors experts,psychologists, and veterinarians have joined the many behavioral ecologistswho use JWatcher to analyze their observations and experiments. We havetaught thousands of students the fundamentals of quantifying animalbehavior using JWatcher, and these labs at UCLA have been extremelypopular. Educators in other institutions have used these labs to teach theprocess of quantifying behavior to their students. We’re very excited aboutour new release that updates JWatcher to make it more compatible withcurrent versions of Java, as well as adding numerous new and powerfulfeatures. Our philosophy is to provide a free event recorder and analysisprogram to the research community. We are developing a book “Analyzingbehavior the JWatcher way” and are instituting a paid support program tohelp you get the most out of JWatcher. We hope that JWatcher helps yousolve your behavioral analysis problems.2 A Brief Overview of JWatcherTMJWatcher is a powerful tool for the quantitative analysis of behavior. It canbe used to address any theoretical problem that requires a complex sequenceof actions to be scored by a human observer. Thus, it can be used to studyhuman or non-human behavior. JWatcher is written in the JavaTM computerlanguage ( and is therefore not dependent on aparticular operating system. It will run on virtually any microcomputercapable of running a Java Virtual MachineTM, and it has been tested on bothWindowsTM ( and MacintoshTM( operating systems.The simplest use of JWatcher is as an event recorder that logs the time atwhich keys are pressed. It was designed primarily for focal sampling withcontinuous recording (i.e., a single subject is observed continuously for apredetermined time). The real power of JWatcher is, however, in its analysisroutines. These calculate time budgets and statistics about the duration ofbehavioral states, the intervals between them, and a variety of sequentialanalyses.We developed JWatcher because existing event-recording programs typicallyforce the user to make a restrictive series of decisions before beginning toobserve behavior. JWatcher imposes few such constraints. It is based on a“score once, analyze many times” philosophy that we have adopted in ourstudies of animal behavior. For instance, a single data file can be used tocalculate time budgets over both short and long periods, or to track changesin different subsets of behaviors seen. Each behavior can be analyzed bothas an instantaneous event (measuring frequency), and as a state (measuringtotal duration). The logical relationships between behaviors can be edited inpost-processing (i.e., a given behavioral state can be redefined asindependent or as mutually exclusive with others). The number of states

JWatcher 1.0: An introductory user’s guide5that can be tracked independently is limited only by the number ofalphanumeric keys available. Users may choose to exclude or ignore certainbehaviors in analyses, and categories can be combined to generatebehavioral codes that were not originally scored. Batch mode analyses allowefficient processing. Results files can be easily combined for subsequentanalysis in statistical programs. JWatcher can help you check inter- andintra-observer reliability. JWatcher allows you to conduct complex“conditional” analyses (i.e., to calculate the amount of time that individualschew gum given that they are already walking). Sequential analysisalgorithms fit a variety of Markovian and non-Markovian models to look fortrends in the sequence of different activities. We are developing a module toallow data to be scored on a PDA capable of running the Java OperatingSystem and then be imported into JWatcher for post-processing. And, weare developing new capabilities to permit QuickTime videos to be scoreddirectly at different speeds.JWatcher was designed to be used in association with common wordprocessing, spreadsheet, and graphics software. It produces simple outputfiles that can readily be imported by such programs. We have concentratedon developing new scoring/analysis algorithms, rather than duplicatingfunctions in existing software.2.1Compatibility & ReliabilityJWatcher has been comprehensively tested but there are still some quirks inthe way that it behaves on different operating systems and under differentJVMs (i.e., Java operating systems). Version 1.0 is compatible with the Java2 Platform, Standard Edition (J2SE) and requires Java 1.4.2. You should onlyuse this JVM to run JWatcher.To our knowledge, the results are logically and numerically correct. IfJWatcher behaves strangely, it is most likely a memory problem. JWatchershould be run on a machine with a minimum of 128mb free RAM. However,if you should experience memory problems, quitting and restarting theprogram (and quitting other open programs) should allow JWatcher to runmore smoothly. JWatcher runs best on reasonably fast machines (i.e., 500mHz).We welcome bug reports and suggestions for new features via email [email protected] We will attempt to fix bugs in future versions, butcurrently have no funding for future development.Please note: This manual is the only free support available withJWatcher. We are in the process of writing a more elaborate bookthat will comprehensively work through examples using JWatcher,and we provide support and experimental design assistance for a fee(please contact [email protected] for details).

JWatcher 1.0: An introductory user’s guide62.2Installing JWatcherYou must have a current version of Java installed on your computer in orderto run the installation program. To reduce confusion later, we suggest firstdownloading the appropriate JRE/MRJ. For Windows systems, go directly to Sun jsp ) and download the JRE 1.4.2. JWatcher 1.0 is compatible with Macintosh OS-X. For Macintosh OS-Xsystems, Java 1.4.2 is already installed.Download the appropriate version of JWatcher from the JWatcher site( for your operating system. At thisstage, we are providing a Windows XP and a Macintosh OS-X version.Once downloaded, double-click on the installation icon. By default, JWatcheris installed into your Applications directory and will create an alias on yourdesktop. If you are running Windows, you may have to specify the JRE thatJWatcher is to run with; be sure to select JRE Compatibility with JWatcher 0.9 FilesData files scored with Version 0.9 are compatible for use with all applicableVersion 1.0 routines; therefore, no rescoring of existing data files isnecessary (but see exception below).Global definition and focal master files created by Version 0.9 should beopened and resaved in Version 1.0, after verifying that no unintendedalterations have occurred. Note that a number of key codes previouslyallowed in Version 0.9 global definition and focal master files are no longerable to be defined in Version 1.0 (see section 4 – Global Definition for moredetails - the six key codes are \ : , . ). If your previous global definitionand focal master files contain any of these codes, we suggest that you createentirely new files in the new version. Version 0.9 data files containing thesecodes will be able to be analyzed, but these codes will be ignored, and thusinformation may be lost. If your Version 0.9 data files intentionally containedany of these key codes then you will need either to edit them or rescore.Focal analysis master files created by Version 0.9 must be updated within thenew version before use to prevent unexpected results. Open, fix anyinconsistencies, and re-save. All of your original selections should bepreserved except for one case within the Event Analysis window (see below).Files not updated may still be analyzed, but we have not extensively testedthese results.Event Analysis window: In Version 0.9, two analyses (event count andinterval occurrence) were combined into one check box. In the new version,these two analyses are now separated into two independent check boxes. If

JWatcher 1.0: An introductory user’s guide7you had selected the “Event Count and Interval Occurrence” box in Version0.9, you won’t get the “Event Count” box checked in the new version.Therefore, you must update this portion manually.Combinations master files created by Version 0.9 should not be used withVersion 1.0. We suggest creating entirely new combination master files withVersion 1.0, and rerunning the combine key codes routine. See section 9 –Combinations.Version 1.0 files are not compatible for use with Version MumboJumboThe program and manual are copyright by the authors, but JWatcher is“freeware”: this version is given away with no warranty expressed orimplied. Feel free to use it, teach with it, and tell others about it. Werequest that you tell others to download the program directly from theJWatcher web site ( to ensure they obtain themost recent version of the program and the manual. The authors and theirrespective institutions are not responsible for its use or misuse.JWatcher is a registered trademark of the authors. Java, the Java VirtualMachine, and Sun, are registered trademarks of Sun Microsystems, Inc. inthe United States and other countries. Windows XP and Internet Explorer areregistered trademark of the Microsoft Corporation. Macintosh, OS-X, andQuickTime are registered trademarks of Apple Computer, Inc. Any othertrademarks are the property of their respective owners.2.5 Acknowledgements1.0 Development: For programming, we thank Nada and Jose da Viega ofConvolution L.L.C. ( 1.0 development was generouslysupported by the U.S. National Institute of Health grant 5R21MH065226. Wethank the UCLA Life Science Computing staff for help distributing JWatcherand for a number of 0.9 users for suggesting additional features.0.9 Development: For programming, we thank Fiona Walkerden, Xuhong Liand Derek Renouf of Adaptive Arts Pty Ltd (, LindaEvans for creating the JWatcher icon, and members of the MacquarieUniversity Animal Behavior Lab for help with detailed testing. InitialJWatcher development was supported by a Macquarie University ResearchInfrastructure Block Grant. During initial development, Dan Blumstein wassupported by an Australian Research Council Postdoctoral Fellowship, andChris Evans by an Australian Research Council Large Grant.

JWatcher 1.0: An introductory user’s guide83 Using JWatcherTo quantify behavior you must create several types of files. The followingdescription is an outline only to illustrate the overall structure and logicalrelationships (Figures 1-3). Detailed instructions are provided in thesubsequent sections, and also in a series of on-line help pages.Note: The on-line help requires your computer to have a web browser. Ifthe help file does not load properly, try changing your default web browser toMicrosoft Internet ExplorerTM.First, you must create a Global Definition File (.gdf). Global definition filesare a list of all the behaviors that you might possibly be interested in scoring.The .gdf file could be regarded as an ethogram–a catalog of behavior.Additionally, you can specify modifiers that may follow certain behaviors.Modifiers can be anything that has a logical relationship with a behavior(e.g., the identity of the other individual in a dyadic social interaction, thelocation where a behavior was performed, or a variable component of adisplay). The total number of behaviors and modifiers in a .gdf file cannotexceed the number of alphanumeric characters on a keyboard.When asking a focused behavioral question, however, you are typicallyinterested in a sub-set of behaviors and modifiers. You must specify theduration of a focal observation, and any question with which you are to beprompted before beginning a focal observation (e.g., subject identity, date,time, etc.).To do this, you will have to create a Focal Master File (.fmf). The focalmaster file first inherits a pre-existing global definition file (.gdf) to whichyou can add or subtract behaviors or modifiers. Additionally, the .fmfrequires you to specify questions to be prompted with prior to scoringbehavior, to specify a focal duration, to choose whether you want the eventrecorder’s clock to count up or count down, and to choose whether the endof-file sound should be played when scoring behavior.To score behavior, you must specify a focal master file (.fmf). The DataCapture routine allows you to score behavior and then creates a data file(.dat) which contains a log of the key presses scored to the millisecond.For basic analysis (Figure 1), before analyzing a data file (a .dat file), youmust create a Focal Analysis Master File (a .faf file). The focal analysismaster file is the “guts” of JWatcher and specifies which behaviors are to betreated as states and which are to be treated as events. It also allows you to“time window” a single longer focal observation and summarize behavior ineach time window. It allows you to specify which behaviors are mutuallyexclusive, to exclude or modify certain behaviors, and a variety of otherspecific functions. Once a .faf file is created, JWatcher can analyze a singledata file or it can batch process all data files contained in a folder. JWatcherresults files (.res) are comma delimited text files that are opened easily in

JWatcher 1.0: An introductory user’s guide9spreadsheet programs for subsequent post-processing and analysis. (Seesection 10.1 for difference between cd.res and tr.res files.)Sometimes, you may wish to score behavior in some detail and later combinedetailed key codes into a single behavior type. For instance, a subject may“look” in a variety of postures—it can stand and look, crouch and look, orrear-up and look. JWatcher contains a routine to combine these different keycodes into a single key code–look. To do so, a Combinations Master File(.cmf) must be created. Once a .cmf is created, JWatcher can combine thecodes in either a single file, or it can batch process many files. The filesresulting from combination (c.dat files) are analyzed by a modified .fmf and anew .faf. Both of these files are based on the new key codes defined in the.cmf.Once you have analyzed a number of focal data files, you will probably wantto combine your results files into one summary file and calculate somesummary statistics. JWatcher’s Summarize Results algorithms will help youwith this. Importantly, this will also create a file that can be exported intoother spreadsheet or statistical analysis programs for subsequent analyses.Note that only .cd.res files are able to be summarized.One more important tool allows you to calculate inter- or intra-observerreliability (Figure 2). JWatcher’s reliability routine enables you to comparethe sequence of two data files, and is located in the Analysis menu.Reliability result files (rel.res) cannot be summarized with the SummarizeResults routine.For sequential analysis (Figure 3), you must first create a global definition file(.gdf), a focal master file (.fmf), and then score data files (.dat) with thedata capture routine. Sequential analysis functions independently from basicanalysis, and does not require a focal analysis master file (.faf). The Generaltab enables you to specify which behaviors are to be modified or ignored,and several other settings. Unlike basic analysis, sequential analysis assumesthat all key codes represent a simple sequence, and does not take intoaccount the times that these codes were logged. There can be nosimultaneously occurring behaviors for this type of analysis, so data filesmust be scored accordingly. Note that the General tab specifications apply toall Sequential Analysis tabs except for the Runs Test. The Runs Testexamines whether a sequence of dichotomous behaviors is random, andrequires that data files are comprised of no more than two behaviors.Sequential analysis results files (.run.res, .lag.res, .seq.res, .mar.res,.com.res) cannot be summarized with the Summarize Results routine.

JWatcher 1.0: An introductory user’s guide10Figure 1. A taxonomy of JWatcher files and their relationships for basicanalysis.Global Definition File(.gdf)Focal Master File(.fmf)New .fmf(c*.fmf)Focal AnalysisMaster File(.faf)CombinationsMaster File(.cmf) Data CaptureResults File(.tr.res)Data File(.dat)Results File(.cd.res)Summarized Results File(.rsm & .log)CombinedData File(c*.dat & .log)Log File(.log)

JWatcher 1.0: An introductory user’s guide11Figure 2. A taxonomy of JWatcher files and their relationships for reliabilityanalysis.Global Definition File(.gdf)Focal Master File(.fmf)Data CaptureData File(.dat) Results File(rel.res & .log)Data File(.dat)

JWatcher 1.0: An introductory user’s guide12Figure 3. A taxonomy of JWatcher files and their relationships for sequentialanalysis.

JWatcher 1.0: An introductory user’s guide134 Global DefinitionGlobal Definition is a comprehensive ethogram you will create for a givenspecies or project. An ethogram is a catalog of behaviors and modifiersspecified, typically, at the beginning of a study.A global definition file (.gdf) is the first step towards creating a focal masterfile (.fmf).First, click [New] to create a new .gdf or [Open] to modify an existing one.BehaviorsUse the [Add row] button to add rows. Specify a single alphanumeric keycode for each behavior, define it, and describe it.Note: JWatcher is case-sensitive: upper and lower case key codes aretreated separately. Numbers and most punctuation key codes arepermissible, but the space bar, backslash (\), colon (:), period (.), equals( ), given ( ), comma (,), return, tab, delete and other function keys cannotbe defined.Use the [Delete row] button to remove rows.ModifiersUse the [Add row] button to add rows. Specify a single alphanumeric keycode for each modifier, define it, and describe it.Use the [Delete row] button to remove rows.Type in descriptive supplementary information in the bottom text box. Do notuse the return key.Use the [Save] button to save your .gdf file when complete.Note that key codes may be entered either as behaviors or modifiers, but notboth.For a description on how modified behaviors are treated during analysis, seesection 8 (basic analysis), section 10.2 (reliability analysis), and section 12(sequential analysis).

JWatcher 1.0: An introductory user’s guide145 Focal MasterFocal Master creates a set of specifications (the .fmf file) used whenrecording data using Data Capture. It defines a set of questions the user willbe asked prior to capturing the data. The answers to these questions (e.g.,identity of focal subject, date, time of day, habitat, etc.) will be added to theheader of the resulting data file (.dat), and will also be reported in anyresults files generated when analyzing the data file. The focal master filealso contains the duration of a focal observation. It is best used AFTERcreating a global definition file, although this is not required. A .fmf file isalso a pre-requisite for analyzing data as it is required to create a “focalanalysis master file” (.faf) and, if needed, to later create “combinationmaster files” (.cmf).5.1 Focal Master Define CodesUse the [New] button to open a previously created .gdf file and import theexisting behaviors and modifiers. Use [Open] to open an already existing.fmf. Clicking either button will take you into a navigation window.If you have imported a .gdf file, there should be a series of already definedbehaviors and modifiers. Using the [Add row] or [Delete row] buttons, editthis list to include just those behaviors and modifiers you are interested inquantifying for your current project.Use [Save] to save the file with the existing name and [Save As] to save thefile with a new name. The [Save] and [Save As] buttons are only selectable ifyou have made any changes.Note: Making changes in the .fmf will not modify the .gdf from which it wascreated.When all behaviors and modifiers have been defined, click on Test Details tomove to the next window.5.2 Focal Master Test DetailsDefine the observation session in hours, minutes, and seconds. Note, it issufficient to fill in only one box (e.g., “1” in the minutes box will create a 60second focal). If no session duration is specified, data capture will continueuntil stopped.Select “count up” or “count down” to specify whether you want the timer inData Capture to be increasing to the time limit, or decreasing towards 0.Select “sound on” or “sound off” to specify whether you would like JWatcherto play a sound signifying the end of a focal session.Add any notes to the text box.

JWatcher 1.0: An introductory user’s guide5.3 Focal Master QuestionsDefine up to 6 questions the user will be prompted with prior to capturingdata. Do not use the return key. For example, you might want to note theidentity of the focal subject, the time of day, the weather, etc.15

JWatcher 1.0: An introductory user’s guide166 Data CaptureData Capture is JWatcher’s event-recording program. Use this to record theonset of behavioral states (e.g., the onset of a bout of foraging) or theoccurrence of behavioral events (e.g., the occurrence of an alarm call). Datacapture logs any and all definable key presses, whether or not they aredefined in the .fmf file.6.1 Data Capture Data FileIn this window, you will have to both name your data file and select an .fmfused for data capture.In data file field, select the path where the data file will be stored by clickingon the file icon. If you do not select a pathway, the data file will be stored inthe default location—in the Application folder where JWatcher is installed.Selecting the file icon will open a navigation window. Using the pull-downdirectory in the navigation window, specify the location where you want tostore the data file. Name the data file and click the [Open] box. If youselect an existing .dat file you will overwrite it.In the focal master field, select a focal master file (.fmf) that you want to usewhile scoring behavior by clicking on the file icon.WARNING: Data files scored without an associated .fmf file cannot beanalyzed with Sequential Analysis. Therefore, you must specify a .fmf file inthis case. For basic analysis, however, scoring with a .fmf file is not anabsolute requirement.When you have named your data file and selected a .fmf file, click [Next].Note: The first time you open JWatcher after a shut-down it willautomatically revert to the default pathway. Once you select a path,JWatcher will save that path (until changed) to facilitate subsequent scoringsessions. However, this path will be lost when JWatcher is closed.6.2 Data Capture Questions and AnswersIn this window, answer the questions that have been specified in the .fmffile. Do not use the return key.When finished, click [Next].Answers should be saved from one data file to next (but this is not alwaysthe case).6.3 Data Capture Capture DataUsing the mouse, click [Start] to begin scoring behavior (or depress alt-s).The session will either time out at the end, or you can click [Stop] to end anobservation session before the pre-determined time (or depress alt-t or tabspace bar).

JWatcher 1.0: An introductory user’s guide17Alternatively, you can move the cursor around using the tab key. Ensurethat the “focus” is on one of the duration boxes (i.e., there is a blinkingcursor) and tab until the [Start] button is highlighted. Depressing the spacebar will now start the scoring process.To temporarily pause during an observation session, click [Pause] or depressthe space bar (or alt-p). The clock will stop running until data capture isresumed. To resume, either click [Pause] again or depress space bar (or altp). Stopping an observation session while data capture is paused willterminate the session at the time of the last pause.If no session duration is specified, the data can be recorded until stopped.You can select whether you want the clock to count up to the pre-determinedfocal duration or count down. You can also turn the sound signifying the endof the focal on or off.The View [Behaviors] button places a list of behaviors and their key codesinto a separate window. Doing so may facilitate scoring.The View [Modifiers] button places a list of modifiers and their key codes intoa separate window.When finished, the file is automatically saved to the location specified. Click[New] to score the next focal session.6.4Note on “initializing” a focalSome event recorders require the user to initialize behavioral states beforescoring behavior. We elected to allow the user to begin capturing dataimmediately. Therefore, to initialize a behavioral state, the user has twooptions:1) Quickly hit a key after starting JWatcher. The time delay between startingJWatcher and hitting the first key may be unimportant if the focal duration isrelatively long.2) In cases where the time delay may influence later analyses, use the EditData function (see section 7) to edit the data set to begin at time 0.

JWatcher 1.0: An introductory user’s guide187 Edit DataEdit Data allows you to modify the keystrokes and times created in DataCapture. Answers entered during Data Capture to focal master file questionsmay also be modified here.Use the [Open] button to open a data file (data files have the .dat suffix).Use the [Insert Row] button to add rows, the [Delete Row] button to deleterows, and the [Save] or [Save As] buttons to save changes.Notes: Type or edit the time in either the “Elapsed” column or the“hh:mm:ss:ms” column. Changes to one column will automatically update inthe other. If the .fmf is either in the same directory as the data file, or is inthe same location as it was when the data file was scored, then typing arecognized behavior or modifier key code in the key pressed column willresult in the appropriate behavior or modifier being typed in the“Behavior/*Modifier” column. Ensure that new entries are chronological.Non-chronological entries will be treated as errors during analysis and noresults files will be produced. When modifying answers in the Answerswindow, do not use the return key.

JWatcher 1.0: An introductory user’s guide198 Focal Analysis MasterFocal Analysis Master creates a focal analysis master file (.faf) whichspecifies how data files (.dat) will be analyzed and specifies the results to bereported.JWatcher’s “score once, analyze many times” philosophy is embedded in thefocal analysis master file. A single data file can be analyzed differently bychanging definitions in a focal analysis master file. You may wish to modifytime bins, subtract or ignore certain behaviors, re-define mutually-exclusivebehaviors, modify how incomplete time bins are handled, or explore thedifferences between state and event analyses.However, logical errors when selecting non-default options cangenerate meaningless results. Be VERY careful setting up focal analysismaster files. We suggest paying particular attention to the logicalrelationships specified in the States tab. This is particularly important whenanalyzing conditional states or conditional events.Use [New] button to select a focal master file (.fmf file) that contains the keycodes to be analyzed.Use [Open] button to open a pre-existing focal analysis master file (.faf file).Note: Ensure that you use the same .fmf to score behavior and to analyzebehavior. The analysis routine will later check whether the same .fmf wasused to capture data and to create the .faf for analysis. If not, JWatcher willinform you that different .fmf files were used. However, analysis will proceedeven if the .fmf files do not match.Once you have selected analysis options, save changes using [Save], orcreate a new file name using [Save As].NOTE: the first time that you save a .faf file after the program isopened may take a very long time. Simply wait and the file will eventuallybe saved. This problem should not occur for subsequent saves. It is due tothe .faf validation process described below, and is more likely to occur whenusing a computer with limited RAM.Every time that you save a faf, the program will check for logicalinconsistencies among your selections made within the file. For example,out-of-sight may not be subtracted lest meaningless statistics be generated.If such inconsistencies exist, a pop-up window will list the problems andpropose solutions. You may either accept the proposed changes or cancel thesave.Known issue o

The simplest use of JWatcher is as an event recorder that logs the time at which keys are pressed. It was designed primarily for focal sampling with continuous recording (i.e., a single subject is observed continuously for a predetermined time). The real