Eduard Szöcs

Data in Environmental Science and Eco(toxico-)logy

rspear released on CRAN!

My first self-authored r-package is now on the way to CRAN! The windows binary is already available, the MacOS X binary will hopefully be available in the next few days.

rspear was developed for the Department System Ecotoxicology of the Helmholtz Centre for Environmental Research a R package to calculate SPEAR (Liess & Von Der Ohe, 2005; Liess et. al. 2008).

The package is an interface to their web-application. It retrieves trait-data from their server and calculates from this SPEAR. Now you can perform all calculations/plots directly in R - no need to go to the webpage, upload data and download results and load them into R.



rspear is now available on CRAN, so installation is as simple as:


I added some example data to the package which I will use for demonstration:

##            Taxon Abundance Year           Site
## 1         Baetis         1 2007 Sample Point A
## 2 Baetis rhodani         1 2007 Sample Point A
## 3  Baetis rodani         1 2007 Sample Point A
## 4      xxxxxxxxx         1 2007 Sample Point A
## 5     Baetis sp.         1 2007 Sample Point A
## 6    Athericidae         2 2007 Sample Point A

So the data has for columns ‘Taxon’ (holding the species names), ‘Abundance’ (holding the abundances), ‘Year’ and ‘Site’ (which are two grouping variables). As you can see the data is in the log format and rspear requires long data (as the web-application). If you have your data in the wide format you can use melt() from the reshape2-package.

We want to calculate SPEAR-values per year and site. The main function of rspear is spear():

sp <- spear(spear_example, taxa = "Taxon", abundance = "Abundance", group = c("Year", 

## Warning: There were unmatched species: xxxxxxxxx Set SPEAR to 0.
## Warning: Non-direct taxon matches! Check trait table if match is
## appropiate!!

The first argument is our data (‘spear_example’), and afterwards we must specify the columns holding the taxon names, the abundances and grouping variables. These must match the column names of the data, otherwise the function stops with an error.

The warnings tell us that not all taxa could be matches directly with the trait-database. rspear tries to guess which taxon matches, however you should always check! For taxon ‘xxxxxxxxx’ rspear was not able to make a good guess and the SPEAR-value for this species was set to 0.

Let’s look at our results: rspear returns a list with two entries: ‘spear’ and ‘traits’.

First we check the matched species, since we got a warning. We look a the trait-table for this:

##         taxa_data   taxa_matched match_val   region exposed generationTime
## 18      xxxxxxxxx           <NA>        NA     <NA>      NA             NA
## 17  Baetis rodani Baetis rhodani       0.1  Eurasia       0         0.5000
## 1          Baetis         Baetis      -1.0  Eurasia       1         0.6456
## 2  Baetis rhodani Baetis rhodani      -1.0  Eurasia       0         0.5000
## 3      Baetis sp.     Baetis sp.      -1.0  Eurasia       1         0.5000
## 4     Athericidae    Athericidae      -1.0  Eurasia       1         0.6875
##    sensitivity migration SPEAR
## 18          NA        NA     0
## 17     0.02159         0     0
## 1      0.02159         0     1
## 2      0.02159         0     0
## 3      0.02159         0     1
## 4     -0.35000         0     1

Looking at the

match_val column

we see that there has been no match (match_val == NA) for taxon ‘xxxxxxxxx’ and ‘Baetis rodani’ has been matched approximately (match_val = 0.1) with ‘Baetis rhodani’. The value in match_val indicates how good the guess for the species is.

All other taxa have been matched directly (match_val = -1). The SPEAR-value for ‘xxxxxxxx’ has been set to ‘0’. We could check and clean our input data, but the matches are appropriate in this case.

Now let’s look at the spear values:

##   Year           Site SPEAR
## 1 2007 Sample Point A 35.01
## 2 2007 Sample Point B 63.24
## 3 2007 Sample Point C 34.99
## 4 2007 Sample Point D 58.64
## 5 2008 Sample Point A 42.31
## 6 2008 Sample Point B 19.38
## 7 2008 Sample Point C 28.16
## 8 2008 Sample Point D 30.65

These results can be directly used for further analysis (plotting, hypothesis testing, etc):

spear_df <- sp$spear
plot(SPEAR ~ factor(Year), data = spear_df, xlab = "Year")

plot of chunk spear_plot

You can also change the thresholds (not recommended) or change the SPEAR-values of individual species. Please read the vignette for further information.

rspear is currently under development, so if you have suggestions/problems or find bugs contact me: either on github or here.


Liess M and Von Der Ohe P (2005). “Analyzing Effects of Pesticides on Invertebrate Communities in Streams.” Environmental Toxicology And Chemistry, 24. ISSN 0730-7268,

Liess M, Schäfer RB and Schriever CA (2008). “The Footprint of Pesticide Stress in Communities—Species Traits Reveal Community Effects of Toxicants.” Science of The Total Environment, 406. ISSN 00489697,


Written on December 26, 2012