## MacArthur's Broken-stick distribution

### Description

Density, distribution function, quantile function and random generation for the Broken-stick distribution with parameters `N` and `S`.

### Usage

```dbs( x, N, S, log = FALSE )
pbs( q, N, S, lower.tail = TRUE, log.p = FALSE )
qbs( p, N, S, lower.tail = TRUE, log.p = FALSE )
rbs( n, N, S )
drbs( x, N, S, log = FALSE )
prbs( q, N, S, lower.tail = TRUE, log.p = FALSE )
qrbs( p, N, S, lower.tail = TRUE, log.p = FALSE )
rrbs( n, N, S)
```

### Arguments

 `x` vector of (non-negative integer) quantiles. In the context of species abundance distributions, this is a vector of abundances (for `dbs`) or abundance ranks (for `drbs`) of species in a sample. `q` vector of (non-negative integer) quantiles. In the context of species abundance distributions, a vector of abundances (for `dbs`) or abundance ranks (for `drbs`) of species in a sample. `n` number of random values to return. `p` vector of probabilities. `N` positive integer 0 < N < Inf, sample size. In the context of species abundance distributions, the sum of abundances of individuals in a sample. `S` positive integer 0 < S < Inf, number of elements in a collection. In the context of species abundance distributions, the number of species in a sample. `log, log.p` logical; if TRUE, probabilities p are given as log(p). `lower.tail` logical; if TRUE (default), probabilities are P[X <= x], otherwise, P[X > x].

### Details

The Broken-stick distribution was proposed as a model for the expected abundance of elements in a collection:

n(i) = N/S (sum(from k=i to S) 1/k)

where n(i) is the abundance in the i-th most abundant element (MacArthur 1960, May 1975). Hence the probability (or expected proportion of occurrences) in the i-th element is

p(i) = n(i)/N = (sum(from k=i to S) 1/k) / S

`[dpq]rbs` stands for "rank-abundance Broken-stick" and return probabilities and quantiles based on the expression above, for p(i). Therefore, `[dpq]rbs` can be used as a rank-abundance model for species' ranks in a sample or in a biological community see `fitrad`.

The probability density for a given abundance value in the Broken-stick model is given by

p(x) = (1 - x/N)^(S-2) (S - 1)/N

Where x is the abundance of a given element in the collection (May 1975). `[dpq]bs` return probabilities and quantiles according to the expression above for p(x). Therefore, `[dpq]bs` can be used as a species abundance model see `fitsad`.

### Value

`dbs` gives the (log) density and `pbs` gives the (log) distribution function of abundances, and `qbs` gives the corresponding quantile function. `drbs` gives the (log) density and `prbs` gives the (log) distribution function of ranks, and `qrbs` gives the corresponding quantile function.

### References

MacArthur, R.H. 1960. On the relative abundance of species. Am Nat 94:25–36.

May, R.M. 1975. Patterns of Species Abundance and Diversity. In Cody, M.L. and Diamond, J.M. (Eds) Ecology and Evolution of Communities. Harvard University Press. pp 81–120.

`fitbs` and `fitrbs` to fit the Broken-stick distribution as a abundance (SAD) and rank-abundance (RAD) model.

### Examples

```x <- 1:25
PDF <- drbs(x=x, N=100, S=25)
CDF <- prbs(q=x, N=100, S=25)
par(mfrow=c(1,2))
plot(x,CDF, ylab="Cumulative Probability", type="b",
main="Broken-stick rank distribution, CDF")
plot(x,PDF, ylab="Probability", type="h",
main="Broken-stick rank distribution, PDF")
par(mfrow=c(1,1))

## quantile is the inverse of CDF
all.equal( qrbs( CDF, N=100, S=25), x) # should be TRUE
```