Before beginning a session, be sure these packages are loaded using the library() or require() commands.

Transcription

1 Instructions for running state-space movement models in WinBUGS via R. This readme file is included with a package of R and WinBUGS scripts included as an online supplement (Ecological Archives EXXX-XXX-03) to the following publication: Breed, G. A., I. D. Jonsen, R. A. Myers, W. D. Bowen, and M. L. Leonard Sex-specific, seasonal foraging tactics in adult grey seals (Halichoerus grypus) are revealed by behaviour discriminating state-space models. Ecology XXX(XX):xxx-xxx. Preface All of the scripts needed for implementing state-space analysis of Argos tracking data are included here as a single.zip file. In addition, we have included an R file with all the required scripts and functions already sourced into an R workspace. You may need to install a few R packages and/or upgrade your version of R in order for this R environment to work. This package is setup so that a user should be able to unzip the folder, leave all the contents in place, and run an analysis. In its current form, it should work as is under windows operating systems. Mac OS and Linux environments will also work fine with minor modifications (see the WinBUGS webpage Users will need to have a working copy of WinBUGS, but experienced users of BUGS should be able to implement the model in OpenBUGS. Aside from installing the needed R packages, the only changes needed will be to ensure the directories are pointed in the right direction on your computer, particularly within the function wbs.r. 1. Required Software First, install and register a copy of WinBUGS if you haven t already done so. It is free and installs easily. You will also need to install the WinBUGS patch as per instructions on the WinBUGS webpage. Next, if you haven t already done so, install R. Technically, you don't need R to run these models, but doing so without R is considerably more difficult. The following packages will need to be installed (MASS is included as part of the base in newer versions of R, and installing it will probably not be necessary): R2WinBUGS matlab MASS chron Before beginning a session, be sure these packages are loaded using the library() or require() commands. Only R2WinBUGS is needed to actually run the state-space models, the other packages are needed to load and prepare the data.

2 Once these packages are installed and WinBUGS is registered and patched, you should be ready to start. 2. Preparing the data. Before fitting a model, you will need to read the data into R and then run a script which will generate a set of indices needed for temporal regularization. Included in this package are 3 adult grey seal tracks that were part of the data set used in the analysis. They are formatted to be read by the scripts and function included here. The file is called testdata.csv. You will notice the last 2 columns are zeros. These were reserved for dive characteristics, but since I don t have any data for them, they re zeros. These columns simply hold places for my data loading routine, and allow for tracks with no dive data to be stored in the same file as tracks that do. For this demonstration, the last two columns can be ignored. Here are the metadata for the header row: track id = sdate = time = lc = lat = lon = steptime = btype = dtime = id number, references the track Location date Location time, in minutes past midnight. Location class Latitude Longitude Time between the current location and the previous, in minutes Bottom time (dive character) Dive time (dive character) Users will need to edit data loading and preparation scripts if they wish to change the format of their input data. New users will probably find it is simpler to reformat their data so that it matches this format rather than edit these R scripts to match their data format. However, changing the data loading and preparation functions should not be difficult once users become familiar with them. There are a number of scripts and functions that work together to load and prepare the data. They will all need to be sourced into the R environment in order to work. Make sure they are all in your working directory and source them in. Here is the list: datprep.r: The function you will call to prepare and load your data into the R workspace. THE VERSION PROVIDED HERE WILL NOT WORK PROPERLY IF TRACKS CROSS THE INTERNATIONAL DATE LINE. This is true even if just a few

3 outliers cross the Date Line. Extreme outliers may need to be removed if they cause the raw track to cross both the International date line and the Prime Meridian. Otherwise, users will simply need to uncomment a single line of code, which allows for tracks to cross the International Date line, and is actually in the dat2bugslite.r script, at around line 41. However, if this line is implemented, tracks that cross the Prime Meridian will not fit properly. Don't forget to source the modified file in if you make this change. It will not take much to simply add an if statement here which will automatically do this, but I haven't needed to do this yet. dat2bugslite.r: seald.r: step.time.r: Produces most of the regularization indices. Short script that reads the data from the master data file, it currently set to read testdata.csv. Users will need to change the name of the input file accordingly when they have their own data properly formated. Alternatively, users may copy and paste properly formated data into the testdata.csv file using their favorite spreadsheet or text editor. Small module needed to for regularization find.missing.dates.r: Small module needed to handle days with no locations add.missing.dates.r: Same as previous calcj.r: Module needed to map the irregular observations onto regularized locations / times. After all of the modules are sourced into an R workspace, the needed packages have been loaded, and WinBUGS is properly installed, enter the following command on the R command line: test <- prepdat(64, ) The object on the left side of the expression will become a properly formated data array that will be read into WinBUGS during the next step, it can be named whatever you like. When WinBUGS has completed, the model results will be stored as an object with.wb appended to the name, so that in this case the result file would be test.wb. The first input argument is the track id number; each individual track in your database will need to have a unique numeric id number so that it can be specifically identified by prepdat.r and pulled out of the larger dataset. The first argument can also be a vector of up to 19 tracks allowing them to be run as nested or hierarchal analysis. Running tracks

4 as a group often works better, especially if individual tracks are short. To run a group, enter the first argument as a list as shown below. test <- prepdat(c(5099,64,99574), ) Alternatively, users can create a list object of track ids and run the file like so: sealstorun <- c(5099,64,99574) test <- prepdat(sealstorun, ) The second argument is the regular time step (in minutes) you wish to apply to the data. I typically use 3 points per day. In early versions, adding a tiny fraction of a minute to the timestep sometimes prevents crashes, and I still often prepare my data this way, which is why the timestep in this example is and not 480. Also note that the track id numbers used in this example are the same 3 which are included in the testdata.csv file, and as such the code above should work if entered into R verbatim. The decision of what size time step to use is tricky. If one has high resolution data and expects to observe relatively frequent changes in behaviour, one might consider using smaller time steps. In fact, this might even been necessary to properly track very fine scale behaviours. However, computation time will go up rapidly as time step decreases. If your animals are not changing their behaviour very often, there is little reason to use time steps smaller than the 480 minutes. It should be noted, however, that time steps should not be too large, as at some point the lower resolution will decease the quality of location estimates. For the most part, the spatial and especially temporal resolution of your data will dictate the choice of time step. 3. Running the WinBUGS State-Space CRW model: One all the above steps have been taken and no errors have been returned, a user should have an object in their R workspace named test ready to run in WinBUGS. There are a few more scripts and functions needed to fit the model. The first is a script, do not source in this file until all others have been prepared and sourced in and you are ready to run a model: runssm.r: This is the script that I use to run my models, it should be sourced in only at the time you want to run the model. It allow users to change numerous settings without and can be modified to run batches. I edit this script to prepare model runs in an external text editor. See section 3.1. Finally, there is the wbs.r function, which calls WinBUGs, and the model itself, 1diff2stateM.bug. wbs.r: This needs to be sourced into R before running WinBUGS. wbs.r may be sourced in at the same time as the data loading and

5 preparation scripts. It contains all the calls to WinBUGS; runssm calls this function. This file takes the object (in this case test ) and tells WinBUGS how to reassemble it into WinBUGS format. It also contains all the initialization information. There are also a number of other options hidden in this file. Most should be left alone, the most import ones are controlled through runssm.r However, you will need to ensure the WinBUGS directory is correct on line 49 of wbs.r. 1diff2stateM.bug: This is the actual model file. This will not need to be sourced ahead of time. It is called by the bugs command within the wbs.r script when R initiates a link between WinBUGS and begins a model run. The options and initials for this model are contained within the wbs.r file. Leave these alone until you feel a bit more comfortable with the models and have run them a bit. Eventually, you might want to change some of these or write a new model Preparing the runssm.r script. In a text editor, open the runseal.r script. In this script you will need to set a number of parameters. The script is short, and looks like this. wbs(test, model = '1diff2stateM.bug', samples=1000, burn = 500, thin = 2, chains = 2, debug = FALSE) saveresults(test.wb) The first line calls wbs.r. Its arguments are as follows 1). The data object you created with predat.r 2). The BUGS model you want to fit 3). The number of MCMC samples 4). The length of the MCMC burn in 5). The MCMC thinning. For example, if thin = 2, every other MCMC sample after the burn in is retained for parameter estimation 6). The number of MCMC chains to run. Currently you must run two, you will have to make changes to the wbs.r inits in to run 1 or more than 2 chains. 7). If set to TRUE WinBUGS will remain open after a model run is complete so you can examine the log file. This is handy when WinBUGS encounters and error. About 90% of the time errors have to do with misspecified initial values. The second line saves the results in the working directory. Refer to section 4 for more information.

6 Once you ve set your options and are ready to go, save the runssm.r file in your working directory and initiate a run by entering the command: source( runssm.r ) If things work, you should see a WinBUGS window pop up with a log file window with various WinBUGs commands. The log file should read model is updating. It will be some time before you have results. At this point your computer may become very sluggish as WinBUGS takes over most of your memory and CPU resources. However, the WinBUGS process is set to a lower priority, so any other processes will have priority and you may not notice anything at all. You will not be able to use the R workspace used to initiate WinBUGS until the model has finished running. The data provided take about an hour to run 1000 samples on an average laptop, but on faster machines could take as little as 15 minutes. Having lots of memory makes things run much more smoothly. WinBUGS will only use one processor, so multiple processor machines won't help much, except that it is possible to open another R window and run another WinBUGS model concurrently (some modifications need to be made to the provided scripts). New users should start with a very small number of updates until they are confident things are working. Increase the samples and burn in to something around 10,000 and 5,000, respectively, when you are confident things are working and actually want to estimate locations and movement parameters. However, when things are working smoothly, remarkably small numbers of updates will often yield excellent estimates. 4. Reviewing your results Finally, the runssm.r script also includes a call to the function saveresults.r. This will also need to be sourced before runssm.r is sourced to initiate a model fit. However, it will not cause the model to fail if it is not done in advance, nor will you lose your data; it will only produce an error message. This function saves the.wb object, which contains virtually all possible information produced by the WinBUGS call as an R workspace in the working directory. It will be named after the WinBUGS data object, so for the example here test.rdata. It also produces a small ASCII file of key estimates named after the original object, again following the example here, it would be test.dat. Particularly relevant are mean location estimates and mean behavioural states (the first 3 columns are long (mean), lat (mean), behavioural state (mode)). It also includes behavioural state mean (column 4), the month (column 5, useful for quick seasonal comparisons), and the track id (column 6). This file is produced mainly so the results can be quickly imported into the mapping program of your choice. It does not include any information on variance, credible limits, or certainty, nor does it contain the needed information to judge the quality of the MCMC run. All of these things can be found in the.wb object created at each run. Mapping your results will immediately give you a sense of how successful your model run was. If the modelled track seems reasonable, then things are probably (but not necessarily) good. Open the log file (log.odc) in the working directory and look at the

7 traces, they should mix. If you are happy with the fit track and MCMC chains appear to mix, further MCMC diagnostics should be taken if desired, but exactly what one does from here is beyond the scope of this readme. This is not a comprehensive guide, only enough to get started. Consult the WinBUGS web page for errors and be prepared for some frustration. These models work very well, but WinBUGS can be a difficult package to use, and understanding exactly what a statespace model is and how it is being fit will take users a fair bit of time. Good luck!