ENMTools

ENMTools 1.3 is out!

2011-03-21T08:05:00.000-07:00

We have a shiny new version of ENMTools ready to go! This version includes some minor bug fixes and adds a few new features. The new features are described in detail in the user manual, but here's a quick rundown:

*Handy tool for eliminating duplicate occurrence points from a .csv file using either exact location or an ASCII grid.
*New feature to make maps of the spatial distribution of residuals from a regression between two environmental variables (Warren and Moskwik, in prep).
*Tool to standardize raster files so that they sum to 1 over the geographic space.
*Tool for calculating range overlap from rasters, applying a user-selected presence/absence threshold.
*New rank-based overlap metric for rasters (RR) that estimates the probability that a pair of rasters agree in the relative ranking of any two patches of habitat (Warren and Seifert 2011).
*Addition of RR metric to hypothesis tests.

The manual has been expanded considerably, including some basic troubleshooting FAQs.

New Functions in ENMTools to Identify Environmental Barriers to Dispersal

2010-11-10T07:45:00.000-08:00

We're pleased to announce publication of a paper that uses new functions in ENMTools to identify environmental barriers to dispersal. These new features of ENMTools permit identification of two types of environmental barriers that might be acting to maintain geographic boundaries between populations in nature: (1) steep environmental gradients and (2) ribbons of unsuitable habitat. ENMTools is now able to assess the significance of such boundaries in nature using geographically informed randomization procedures. Although you may have noticed that these 'new' features have been available in the last few releases of ENMTools, they haven't been published on previously, or really been explained in enough detail to make them useful. We hope that this will change with publication of this paper! For more details on how to use these new 'range breaking' methods please see section II.c.iii of the ENMTools manual [pdf document].

Glor, R. E. and D. Warren (Accepted Article) Testing ecological explanations for biogeographic boundaries. Evolution. [doi link]

New version of ENMTools up

2010-10-14T09:54:00.001-07:00

We've got a new version of ENMTools. This update fixes a couple of issues and adds one handy little tool. The manual is not completely updated yet, but the program is here:

http://www.danwarren.net/enmtools/builds/Release/ENMTools_1.2.zip

Here's what has changed:

-The problems with the I metric that were mentioned in a previous post/email have been fixed. It should now scale from 0 to 1.

-The breadth metrics have both been changed to standardized niche breadth, scaling from 0, where only one grid cell has a nonzero suitability score, to 1, where all grid cells are equally suitable.

-There's a new tool called "standardize rasters". It basically just takes a bunch of rasters and scales suitability scores so that they sum to 1.

-The model selection functions are now in the main build, but as yet are not documented in the manual. See my previous blog post/mailing for how to use that function. For more details read the Warren and Seifert paper currently in the "accepted" section of Ecological Applications' web page.

Error in I metric (but don't panic!)

2010-09-07T07:00:00.001-07:00

Thanks to a manuscript by Dennis Rödder and Jan Engler that is currently in revision for Global Ecology and Biogeography (entitled “Quantitative metrics of overlaps in Grinnellian niches: advances and possible drawbacks”), we have discovered a typographical error in our description of the niche overlap metric I, Eq. (3) of Warren, Glor and Turelli (2008, Evolution 62:2868-2883). Unfortunately, this error also found its way into ENMTools. Fortunately, the error is only a scaling issue. It does not affect the statistical tests presented in our paper or any known test based on ENMTools. Those tests use only relative rankings of overlaps (rather than specific values), and our error does not change relative rankings.

The formula we provided for Hellinger distance, H, is one of several alternatives. In the form we provided, H ranges from 0 to Sqrt(2). The incorrect formula we published is I = 1 – (H/2), which ranges from 1 – (1/Sqrt(2)) to 1 (not 0 to 1 as we stated). The correct formula is 1 – (H^2/2), which ranges from 0 to 1. Denoting our incorrect formula, Iold, and the intended formula, Icorrect,

Icorrect = 1 – 2(1 – Iold)^2.

Because both formulas decrease monotonically from 1 with increasing H, our typo does not alter relative rankings of I values. Hence, it does not affect P values obtained from resampling-based tests of niche identity or similarity, such as those in Warren et al. (2008). If you have manuscripts that use the I metric, there is no need to re-run any analyses based on ranks; and resulting conclusions about niche identity or similarity remain valid.

We will release an updated version of ENMTools shortly that corrects this error. We thank Dennis Rödder and Jan Engler for bringing it to our attention. We apologize for any inconvenience it has caused.

Model selection paper now online

2010-08-11T05:20:00.000-07:00

The paper I've been working on with Stephanie Seifert on model selection in Maxent is now available as a preprint from Ecological Applications. The paper demonstrates that AIC and BIC can be useful in setting regularization, and also acts as the first demonstration of the utility of ENMTools' data simulation functions.

New test version of ENMTools with model selection

2010-06-08T07:57:00.000-07:00

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 version of ENMTools up

2010-04-07T07:40:00.000-07:00

I've tracked down the sorting bug that Rich and I found last night, and there's now a new version of ENMTools that fixes the issue. It does appear that it only affected the ribbon analysis, and only the sorted output. There are some new functions added as well. One is just a simple tool for measuring correlations between raster files using the Pearson correlation coefficient. The second gives you the ability to sample occurrences from a raster file either randomly or with a probability determined by some function of the suitability of habitat in that grid cell. You can download the new version and manual here. There's more information on the new functions in the manual.

Now that the application note is out we're going to start using actual version numbers instead of build dates. This is version 1.1.

Sorting bug with ribbon range-breaking analysis

2010-04-06T16:11:00.000-07:00

It has just now come to my attention that ENMTools has a bug involving the sorting of I and D values for the ribbon range-breaking analysis. This bug can cause incorrect values to be inserted into the sorted output. The unsorted output files are still fine, and as far as we can tell at the moment this bug doesn't apply to any other analysis. If you are using the ribbon analysis, please use the .csv files for the unsorted output and sort them in Excel yourself. I am working on this bug right now and will post a corrected version of the software ASAP. My apologies for any inconvenience this might have caused.

Problems with ENMTools and Maxent 3.3.2

2010-04-05T16:06:00.001-07:00

Rich and I just hit a problem, but luckily it's one with an easy solution.

As discussed on the Maxent discussion group, Maxent version 3.3.2 does not necessarily like underscores too much. Since ENMTools generates replicate names using underscores, this leads to replicates crashing, often with "number format exception" messages from Maxent and "Can't open ..." messages from ENMTools. Steven is aware of the issue and is working on it, but for now we'd suggest sticking with version 3.3.1 for your ENMTools runs.

ENMTools application note now available

2010-02-12T06:44:00.000-08:00

The application note for ENMTools is now available in the Early View section of Ecography's website. Due to the limits of space, the note really only discusses the measurement of overlap and the identity and background tests (i.e., the tests that were presented in Warren et al. 2008). Papers that present the rangebreaking tests and niche breadth measurements are on the way, and should be out fairly soon.

I'm going to be putting out an update of ENMTools shortly which will add a couple of interesting features and fix a few minor issues.

How to run ENMTools tests on a cluster, or using a modeling method other than Maxent

2009-10-05T06:36:00.000-07:00

ENMTools tests can take a long time to run, due to the number of Maxent runs necessary to construct a distribution of expected overlaps. For that reason, people occasionally ask whether there's a way to break up analyses and run them on a cluster, or just manually spread them across several computers. People also occasionally ask whether it's possible to use ENMTools with non-Maxent methods of ENM construction. There's no built-in way to do either of these at present, and given the number of different ways that people might want to do this I'm not sure there will be. However, it CAN be done! It requires a bit of extra work, but it's not too bad, particularly with a few simple new tools that I'm presenting here.

Let's say you want to do an identity test, and split it up so that replicates are submitted to a cluster. For starters, we'll just set up the test in ENMTools as usual but de-check the box marked "Run Maxent". This will cause ENMTools to generate the data sets necessary for the test, but the data will not be sent to Maxent to analyze.

Okay, now we have a file that has a whole bunch of replicates in it. What we would like to do is analyze each of those separately. I've got a really simple no-frills script here that simplifies this process. All you need to do is drop this file into the directory where your file of replicates is, then go to a command prompt in that directory. Type "splitcsv.pl INFILE", where INFILE is the name of your .csv file of replicates. In short order, you will have a new .csv file in that directory for each replicate in the input file. Note: you can also use this little tool to split a large file up by species. It will spit out a file for each unique species name in the input file. Another note: this script will overwrite files without asking, so it's best to run it in its own directory!

At this point it's up to you to figure out how to submit jobs to your cluster using the Maxent command line options. One thing to keep in mind: Maxent by default writes to a file called maxentResults.csv. If you've got a shared file system, or just a directory on a single multi-core computer that's being shared by two different simultaneous Maxent jobs, both of those jobs will by default try to write to the same results file. Java will happily allow multiple instances of Maxent to fight over the same filehandle, but what comes out in that results file will be incomplete and quite possibly not useful. I've just set my stuff up so that it writes to different directories, but it's possible that using the "perspeciesresults" option will fix this issue as well. On a side note: if you're doing jackknife or bootstrap on a cluster, you pretty much can't have multiple instances of Maxent writing to the same directory. The perspeciesresults option doesn't work for resampling, and having multiple instances writing to the same output file simultaneously will cause Maxent to fail when calculating summary grids. Just FYI.

All right, now you've gotten all of your runs finished and want to bring your data together to construct a distribution of overlaps. This is where a handy new half-developed tool in ENMTools becomes useful: scripting mode. You'll need the newest test version of ENMTools for this. I'll admit that it's a little weird to have a scripting interface for a program that is itself just an elaborate scripting interface for Maxent, but that doesn't mean it's not useful. At present the scripting interface is only hooked up for a few functions, and I'm not even close to writing a comprehensive manual entry for it. However, it works for our purposes.

What you need to do is build a .csv file that has a line for each comparison to be made. The script command is "measureOverlap". Capitalization is not important. A typical line looks like this:

measureOverlap,c:/sample data/species1_rep1.asc,c:/sample data/species2_rep1.asc,testing_measureOverlap1

The first entry is the command, the next two are the two files to compare, and the last entry is the name for the analysis. If you're doing a comparison between two species using 100 replicates, you need 100 lines in your script file, each with its own name for generating output files. In cases like this, the "concatenate" function in Excel is your best friend. Once you've got your script file, just go to Options->Run Script File in ENMTools and let it do its thing.

Now you've got two output files per replicate (I and D), and you'd really like to have all of those in one file. In Windows, the easy way to do this is to go to a command prompt and use the "copy" command with some clever wildcards. In the above example, let's say I've got 100 files named "testing_measureOverlap1_I_output.csv" to "testing_measureOverlap100_I_output.csv", and likewise for D. The appropriate command would be something like:

copy testing_measureOverlap*_I_output.csv collected_I_scores.csv

This would concatenate all of those output files for I into one csv file that can then be edited in Excel. There's going to be a bit of cleanup to do, since each of those files had its own header line and two copies of each score. That's all fairly easy, though, and should only take a couple of minutes with some clever sorting.

Everything I've said here goes for other modeling methods as well - you can generate data sets and analyze them in whatever software you like, and then use the scripting interface to build your distributions. When I get a chance I plan to make an interface that will make the comparison of multiple files easier (i.e., send everything to one formatted outfile). Seeing as I'm currently in a blind rush to finish my dissertation before my postdoc starts, though, I don't think that's going to happen too soon.

New manual!

2009-09-11T14:13:00.000-07:00

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.

New version of ENMTools up

2009-08-05T07:09:00.000-07:00

There's a new version of the software up now that improves compatibility with Maxent. There's a new setting in the "ENMTools options for setting the Maxent version (3.2 and below versus 3.3 and higher), which is necessary due to some changes in the command line arguments for Maxent.

A few things are worth mentioning right off the bat:

-We're going to go Tkx-only from now on due to massive improvements in appearance, compatibility, and ease of updating the software.

-Due to all of the recent changes to the software, the manual has gone from "incomplete" to "almost useless". We'll work up a new version shortly. One thing to mention immediately is that we've turned off the Kullback-Leibler (KL) statistics for niche overlap. They weren't really useful for much, and were causing errors. Because of this, the niche overlap function now only spits out two files, not five as the manual suggests.

-The new zip file is much larger than the previous ones for two reasons: it contains a Mac executable and a sample data set. The Mac executable is still a little sketchy, and Rich has been having some problems that I (Dan) can't seem to duplicate. If anyone has any feedback on this it would be much appreciated. The sample data comes from the Knouft et al (2006) study of Cuban anoles, and consists of occurrences for Anolis allogus (east) and Anolis ahli as well as some environmental data.

-At the moment the newest version is the release version, so the testing and release links above point to the same place.

ENMTools Used in Bigfoot Study

2009-07-03T09:53:00.001-07:00

Who would have guessed that the first published study using the test for niche identity implemented in ENMTools would be about bigfoot? The study in question is a guest editorial in the Journal of Biogeography that uses niche modeling of bigfoot localities (both observations and footprints) as part of a tongue-in-cheek critique of contemporary niche modeling practices. The main point of the study is that dubious observational data can be used to generate niche models that produce "visually convincing distributions." Using the test for niche identity, the authors show that the niche model projection for bigfoot is indistinguishable from the niche model projection for the black bear, bolstering their case that putative bigfoot observations may be cases of mistaken identity. The authors' general suggestion that point locality data extracted from public databases (including databases that are considered more reputable than the Bigfoot Field Researchers Organization) requires greater scrutiny is well-taken; nobody should be niche modeling from publicly available databases without expert validation of the localities being considered.

New Version of Maxent Available

2009-04-24T10:15:00.001-07:00

Steven Phillips just posted a new version of Maxent (v. 3.3.0). I've already used this new version successfully with ENMTools, so hopefully there won't be any unforeseen compatability issues. One of the coolest features of the new version is the capability to do replicated runs, allowing "cross-validation, bootstrapping and repeated subsampling."

New executables of ENMTools for Windows and OSX! Hooray!

2009-04-21T17:03:00.000-07:00

Thanks to Activestate's PerlApp (which is awesome), we now have executable versions of the testing build of ENMTools. You can download the new Mac OS X executable here, or the Windows executable here. For some reason the OS X executable is way bigger than the Windows version, and it only launches from the console on my Mac (double-clicking doesn't work). If anyone has insight into either of those issues, please let me know. I should also mention that neither of these builds have been tested extensively yet, as they're hot off the compiler. Please check your results and let me know if anything comes out weird.

OSX users of the Tkx version - possible bug

2009-04-19T07:59:00.001-07:00

Rich gave the Tkx version a spin yesterday, and had a bit of an odd bug come up that I've never seen before. It seems that the program wouldn't let him set the path to maxent.jar, no matter what he did. It works fine on my Mac, though. If anyone else runs into this problem, please let me know. If you do see this happen, you can fix it by opening the Perl script in a text editor and changing line 3329 from this:

$maxent_path = Tkx::tk___getOpenFile(-initialfile=>"maxent.jar");

to this:

$maxent_path = Tkx::tk___getOpenFile();

Tkx version ready for testing!

2009-04-17T16:09:00.000-07:00

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.

We're starting to work on the new Tkx version!

2009-04-09T15:20:00.000-07:00

Hooray! In case you don't know why you should be excited about this, I'll give you a couple of reasons. First, it's going to make it so that it works with the default install of ActivePerl on Windows, which means no more downloading Tk to get it to run as a script. Second, it will take us much, much closer to having a Mac-friendly version, which I'm told a few people want. Finally, it looks a lot less like something you'd expect to see scratched on a wall at Lascaux. Just take a look:

Okay, so it's not Rembrandt, but it at least looks like something that was written in the last twenty years.

I'm hoping to have an alpha version of it up on the web site in a few days. The tabs are gone, replaced by a more normal-looking menu system. I'm also slowly but surely going to start adding more flexibility in how Maxent runs are conducted, with the ultimate goal being that the user can set any Maxent option from within ENMTools and apply that to all runs automatically. That's a bit of a ways away, though.

ENMTools is about to get a "testing" version

2009-04-03T17:07:00.000-07:00

As it stands, ENMTools basically is a testing version. We're about to crank out a version that only has the bits in that we've worked with extensively, and that already have some associated published paper that we can point to and say "here, this is what this tool does". At the moment that's just the overlap, identity, and background tabs.

Like an infant, or possibly a drunken hobo...

2009-03-31T10:48:00.001-07:00

...the ENMTools website is slowly lurching its way onto its feet. The site is intended primarily as a distribution point for new builds of the ENMTools software. This software was designed to make the tests used in Warren et al (2008) accessible to those who want to use them. At its current state, "accessible" might be a bit overly generous, but the software at very least makes these tests possible. In addition, there are other analyses and tools that are being added all the time. Most of these are being developed for papers in progress by Dan Warren, Rich Glor, Michael Turelli, or some combination of those three.

At present, the software only works on Windows systems. A Mac version will be available as soon as possible, but it may take a while. The whole thing basically needs to be ported from Tk to Tkx, which is a bit of an undertaking. When that happens, though, it will have the added bonus of making ENMTools look like it was at least programmed some time after 1995. Until then, we've decided to keep the web site's appearance consistent with that of the software.

Along with ENMTools updates, we'll probably post some other handy little tools or observations from time to time.