Hey what's the deal with the ENMTools R package?

It has come to my attention that at least one person is actually using the ENMTools R package I sorta half-made a couple of years ago, for which I would like to express my deepest condolences.

Seriously, though, I did want to at least acknowledge its existence and the absolutely massive caveats that should come with any attempt to use it in its current state.  

The package exists because I needed a project in order to learn R; I've found that reading a book and doing examples is one thing, but to really assimilate a new language I need to have a project that makes me sit down and work on it every day.  When I started my postdoc at ANU a few years ago, I said to myself "I am going to do everything in R from this day forward, and in order to learn R I will rewrite as much of ENMTools as I need to to feel like I've mastered it".  

So that's what I did.  I wrote bits to generate reps for most of the major tests in ENMTools, including the background, identity, and rangebreak tests.  I also wrote code to measure breadth and overlap using the metrics in ENMTools, and a couple of other little utility functions.  That helped me get comfortable with the basics in R, and at that point I got busy enough with my actual postdoc work that I had to drop it.  

And that's pretty much where it stands today, a couple of years later.  It mostly works, but it ain't exactly pretty or well documented - it was my first R project, after all.  While some of its functionality has already been duplicated elsewhere (e.g., the identity and background tests in phylocom), some of it hasn't (e.g., the rangebreak tests).  Now that I've been writing R pretty much daily for the past three years, I see a million things I did sub-optimally, and a bunch of areas where I could have taken advantage of existing functionality to do things more quickly, more cleanly, and with a lot more cool bells and whistles.

So why do I bring this up?  First, as I mentioned, because apparently some people are actually using it.  I'm not sure whether that's due to masochism or desperation, but they are.  Second, and more importantly, because I'm going to try to bash it into a somewhat more useful form over the next however-long.  It's probably not going to duplicate all of the functionality of the original ENMTools, but the eventual goal is to include a lot of very cool stuff that the old version didn't have.  If you want to contribute or are brave enough to muck around with it in its current state, it's here:

https://github.com/danlwarren/ENMTools

New test version of ENMTools with model selection

There's a new test version of ENMTools up here. In addition to fixing a few minor annoyances from previous versions, there's a new function that allows criterion-based model selection using AICc and BIC. The user interface for the function is almost non-existent - all it really does is ask for a script file. Here's a quick-and-dirty rundown of how to use it. In order to correctly calculate likelihoods, the data must be formatted appropriately. For that reason we suggest that users pay very close attention to the requirements below.

1. Build a set of models to compare. It is absolutely crucial that suitability scores be output in RAW format! You will need both the .asc file and the .lambdas file associated with each model.

2. Make sure that each set of occurrence points to be compared is in its own independent file. You do not want to load an occurrence file that has points for multiple species. You also need to eliminate duplicate occurrence points from the file, particularly if you have Maxent set to ignore duplicate occurrences.

3. Build a script. A script is simply a .csv file with the paths to the files you want to analyze. Each line of the script should consist of a .csv file, a .asc file, and a .lambdas file. Relative paths will not work, you need fully qualified path names. A typical line will look like this:

c:\mydata\points.csv,c:\mydata\species.asc,c:\mydata\species.lambdas

You need one line per analysis. Also note that ENMTools will output results into a file with a name based on your script file. If your script file is named myscript.csv, the output will be named myscript_model_selection.csv. At present it will overwrite that output file (if it already exists) without asking, so BE CAREFUL.

4. In ENMTools, choose the "Model Selection" tool under "ENM Measurements". A file dialog will pop up. At this point you should choose the script file that you just made. ENMTools will chug along for a while, and will tell you when it's finished. The process is fairly simple: ENMTools uses your raw suitability scores (after standardization) and occurrence points to calculate the likelihood of observing your data under that model. It then counts the number of parameters from your lambdas file, counting any parameter with nonzero weight. Finally, it uses these values to calculate AICc and BIC.

Preliminary studies (Warren and Seifert, in review) indicate that AICc outperforms BIC in selecting models on simulated data. I'll be talking about this study at Evolution this year, for those who are interested (shameless plug).

Keep in mind that this is a test build and may be buggy. Feedback is appreciated.

New manual!

We've finally bashed together a first take on the full manual for ENMTools. You can find it here, or in the zip file with the new version of ENMTools.

The new manual outlines for the first time the niche breadth, range breaking, spatial cross-validation, and jackknife/bootstrap functionality of ENMTools. Papers are in progress discussing all of these tools in more detail, but there should be enough information in the manual to get the general idea now.

Now I'm almost immediately going to start adding new features so that the manual is obsolete again. We'll try to keep it more up to date, though. Scout's honor.

Tkx version ready for testing!

I'm excited to announce that there's already a test version of the new Tkx ENMTools. And here's the big news - IT WORKS ON OSX! Porting from Tk to Tkx was a bit of a hassle, but once that was done it turned out to be trivial to make it work on a Mac. It also has the side effect of making ENMTools look considerably more modern on a PC than it did before. Contrary to my earlier statements, though, I think we're going to keep the retro look of the web page. If you're as deeply in love with Sparklee logos as I am, you can actually save the above logo into the same folder as the new Tkx ENMTools and it will show up when you start up the software.

Anyway, HERE is the perl script for the new version. In order to keep your browser from trying to interpret that link as a web script, Windows users will need to right click and "save as" to download it. Mac users will have to do the Mac equivalent, whatever that is. I'll have a Windows executable version ready as soon as my new license for Perl Dev Kit gets here. For now, you'll need the very, very newest version of ActivePerl from activestate.com. Mac users will need to go to a console and type the path to the Activestate installation of ActivePerl, because ENMTools won't run using the default OSX perl installation. That'll look something like this:

/usr/local/ActivePerl-5.10/bin/perl ./ENMTools TkxTest 4-17-09.pl

...assuming you're in the directory where you've dropped the perl script.

Now in addition to looking considerably sexier and running on OSX, there are a couple of new features that will be of interest to many users. Here are a few:

-Change the amount of memory that is allotted to Maxent (make sure you put in -mx####m, where #### is the number of Mb to assign)
-Ability to turn on/off response curves, pictures, and ROC plots for pseudoreplicates
-New flavors of occurrence point jackknife (I'll write up an explanation of what these are soon)
-Generate data sets for random spatial cross-validation (ditto)
-A new rangebreak test that we haven't told anyone about, which is even cooler than the other ones that we haven't explained
-Measuring niche breadth on ENMs using Levins' measures of niche breadth

Now this stuff is all very, very new. We've done some testing, and things seem to be working correctly. Please email Dan (danwarren@ucdavis.edu) if you hit any snags. Oh, and there's a slight bit of weirdness on OSX in that it seems to want to draw the window slightly smaller than it needs to be, no matter how large I tell the program to make it. Just drag the bottom right corner out a bit and everything's fine. If anyone happens to know what to do about that little glitch, I'd appreciate the info.