Help to the R function nb.ls (v. 1.1)    
May 2003

Rodrigo A. S. Pereira
Seção de Botânica, Dep. Biologia, FFCLRP, Universidade de São Paulo, 14040-901 Ribeirão Preto, SP, Brazil  -- raspereira@yahoo.com.br

Adriano S. Melo
Dep. Biologia Geral, ICB, Universidade Federal de Goiás, 74001-970 Goiânia, GO, Brazil  --  grumicha@yahoo.com.br

In this document you will find information on how to run the function nb.ls in R, a FREE language and environment software, which contains the tools needed by the function.
The function nb.ls calculate two species richness estimators, called Negative Binomial (nb) and Logarithmic Series (ls). The estimators are presented by Efron and Thisted (1976) and are based on the Log Series model developed by Fisher et al. (1943) to fit relative abundance of species in a sample. To our knowledge, there are only two papers to date that have evaluated these estimators, Keating et al. (1998) and Melo et al. (2003). The function nb.ls is a simplification of the function used in Melo et al. (2003), adapted from the S-plus language (you have to pay for it!) to the R-language (free!). Below we explain (1) how to get the R-software, (2) how to install the nb.ls function in R, (3) how to format and import your data into R and (4) how to run the function. We believe that you will not have troubles to get your estimates. In case you get, contact us by e-mail.

1.	Getting the R software
1.1 Download the software from http://cran.r-project.org

1.2 Install it in your computer

2. Installing the nb.ls function
2.1 Open the function file “nb_ls_v_1_0.txt” using the Notepad or other text editor. Maintain the window open.

2.2 Open the R-software.

2.3 In the line command, creat a new function called nb.ls:
	nb.ls<-function (){}

2.4 Edit the created function:
	nb.ls<-edit(nb.ls)

2.5 R will open a Notepad window. Delete the text “ function(){} ” that will appear in the window. Maintain the window open.

2.6 Activate the text editor containing the function file. Copy all the text.

2.7 Activate the Notepad window opened by R. Paste the function copied from the function text file. Save the file using the name supplied by R. Close the text editor.

2.8 The function should be installed now. In order to see it in the R command line, type its name:
	nb.ls

3. Formating and importing your data into R
1. The Log Series model was developed by Fisher in order to fit species abundance. Sample size is thus usually expressed as number of individuals. Calculations are done using information on number of species occurring with 1 individual, number of species with 2 individuals etc. Efron and Thisted (1976) illustrated their paper with the problem of estimating the size of the vocabulary of Shakespeare. In this case, calculations were done using information on number of words that appeared once, number of words that appeared twice etc, in Shakespeare’s known works. In our paper (Melo et al. 2003), instead of using number of species occurring with 1, 2 etc individuals, we used the information on number of species occurring at 1, 2 etc sampling units (quadrats, traps etc). 

2. The function nb.ls was designed to work on data presented as a matrix of sampling units (rows) by species (columns). This is the usual form used in most diversity and multivariate statistical softwares. An artificial example would be:

	0	1	0	0	1	1
	0	0	0	1	1	1
	0	1	1	0	0	1
	1	1	1	0	1	1

3. In the example above there are 4 sampling units (rows) and 6 species. Two species occurred in 1 sampling unit, 1 species occurred in 2 sampling units etc. There is a file called “japi.txt” supplied with this help. You may want to open it to see the format.

4. You can prepare your data using Notepad, although a worksheet software (e.g. MS Excel) should be necessary in case you want to transpose your matrix (because species are in the rows and sampling units in columns of the file you have) or transform an abundance matrix into an incidence matrix (presence [1] and absence [0]).

5. Be sure that:
All cells contain a “ 0 ” OR a “ 1 ”;
All species occur at least once in our data;
Species are located in columns and sampling units in rows;
There are NO headers, names of species or of sampling units.

6. Save your file as text ( .txt) tab delimited.

7. Import your data into a R object. As an example, in order to import the file “japi.txt” supplied with this help and saved by you, for example, in “c:\my files\japi.txt” into a new R object named “stream”, you should type:
	stream<-read.table(“C:\\my files\\japi.txt”)

8. Check if your data was imported correctly, typing:
	stream

4. Running the nb.ls function
4.1. The function nb.ls needs four arguments in the following order: 
a) Name of the object containing your data;
b) Magnitude of extrapolation, expressed as a proportion of the sample size of your data. For example, 0 = no extrapolation, 0.3 = extrapolation to a sample size that is 30% larger than the current one, 1 = extrapolation to a sample size that is twice the current one.
c) An initial value of the alpha parameter. Try initially values in the range –1 – 1. In case you get an error message related to the nonstabilization of the nonlinear fitting, try lower or higher values.
d) An initial value of the gamma parameter. Try initially values in the range –1 – 1. In case you get an error message related to the nonstabilization of the nonlinear fitting, try lower or higher values.

Using the object “stream”, extrapolated to a sample size 40% larger (i.e. 75 + 30 = 105), and with initial values of the parameters alpha and gamma of 0.6 and 1 respectively, the line command should be:
	nb.ls(stream, 0.4, 0.6, 1)

The result, in a “list format”, will be:
$obs.ditribution
   occurrences frequency
1            1        15
2            2         5
3            3         5
4            4         2
5            5         1
6            6         3
7            7         2
8            9         2
9           10         1
10          11         3
11          12         2
12          13         2
13          16         4
14          18         1
15          20         1
16          21         1
17          23         3
18          26         2
19          30         1
20          31         2
21          32         1
22          35         1
23          46         1
24          51         2
25          65         1
26          69         1
27          70         1

$param
         Spp.obs     Spp.with.one.occur.        alpha             gamma 
         66.0000000          15.0000000         -0.1076249        1.0381457 

$nb
[1] 71.11323

$ls
[1] 71.01826

Where,
$obs.ditribution is the matrix of frequencies of each class of occurrence (or incidence).

$param is the matrix of parameters, presenting the “total number of observed species”, the “number of species with one occurrence” and the alpha and gamma parameters.

$nb is a vector with the richness estimated by the Negative Binomial estimator.

$ls is a vector with the richness estimated by the Logarithmic Series estimator.

Literature Cited
Efron, B. and R. Thisted. 1976. Estimating the number of unseen species: How many words did Shakespeare know? Biometrika 63:435-447.
Fisher, R. A., A. S. Corbet, and C. B. Williams. 1943. The relation between the number of species and the number of individuals in a random sample of an animal population. Journal of Animal Ecology 12:42-58.
Keating, K. A., J. F. Quinn, M. A. Ivie, and L. Ivie. 1998. Estimating the effectiveness of further sampling in species inventories. Ecological Applications 8:1239-1249.
Melo, A. S., R. A. S. Pereira, A. J. Santos, G. J. Shepherd, G. Machado, H. F. Medeiros, and R. J. Sawaya. 2003. Comparing species richness among assemblages using sample units: why not use extrapolation methods to standardize different sample sizes? Oikos 101:398-410.