macroeco.models.sampling_ear¶

macroeco.models.sampling_ear = <macroeco.models._curves.sampling_sar_gen object at 0x10885c0d0>¶

A general sampling SAR/EAR

As described in Wilber et al. 2015 [1], a sampling SAR is defined by a species abundance distribution (SAD, \(\phi\)) and a species-level spatial abundance distribution (SSAD, \(\Pi\))

\[S(A) = S_0 \sum_{n_0=1}^{N_0} \phi(n_0 | \Theta_{\phi}) [1 - \Pi(0 | A / A_0, n_0, \Theta_{\Pi})]\]

where \(\Theta_{\phi}\) and \(\Theta_{\Pi}\) defines the parameters of the SAD and SSAD respectively, \(S_0\) is the total number of species at the base area \(A_0\), \(N_0\) is the total number of individual at the base area, and A is the area at which to calculate species richness.

A flexible choice for the SAD is a zero-truncated negative binomial with parameters \(\mu\) and \(k_{SAD}\). Fisher Logseries (\(k_{SAD} = 0\)), Canonical Lognormal (\(0 < k_{SSAD} < 1\)), and Broken Stick (\(k_{SAD} = 1\)) SADs can all be exactly or approximately represented by this distribution. A flexible choice for the SSAD is the condition (finite) negative binomial distribution (FNBD) with parameters \(\mu\) and \(k_{SSAD}\). When \(k_{SSAD}\) is large a binomial distribution is obtained and when \(k_{SSAD} = 1\) and truncated geometric distribution is obtained. See Wilber et al. 2015 for more information. We implement these two distributions in the general sampling SAR.

The general sampling SAR and EAR may be used either for downscaling, when values of \(A\) are less than \(A_0\), or upscaling, when values of \(A\) are greater than \(A0\). Downscaling creates the traditional SAR known to ecologists, while upscaling is useful for estimating large- scale species richness from small- scale plot data.

The parameters required for the sampling SAR are species richness at the base scale A_0 (\(S_0\)), total community abundance at the base scale (\(N_0\)), the aggregation parameter of the SAD (\(k_{SAD}\)), and the aggregation parameter of the SSAD (\(k_{SSAD}\)). See examples below.

If the standard SAR is chosen (sampling_sar), the SAR is calculated by solving the above equation for any given value \(A\) greater than or less than \(A_0\).

If the iterative SAR is chosen (sampling_sar_iterative), the SAR is calculated by successively halving (if downscaling) or successively doubling (if upscaling) the base area, calculating the values S and N at this new scale, and then setting these calculated values of S and N as the base \(S_0\) and \(N_0\) for subsequent calculations. This iterative form was used in Harte et al [2], although note that the implementation here uses a different internal equation. Note that the the iterative form of the SAR can only calculate species richness at values of A that are doublings or halvings of the A_0. Any value of A can be passed to sampling_sar_iterative, but it will return the species richness at the closest iterative halving that is less than or equal to the given \(A\) or the closest doubling that is greater than or equal to the given \(A\). See examples below.

If the endemics area relationship (sampling_ear) is choosen (as given in Harte (2011) pg. 46), the number of endemics are calculated at any given \(A \leq A_0\) where \(a < 1\). This method requires the same parameters as the SAR.

Parameters:

x : iterable Areas at which to calculate SAR or EAR. The first element must be A0, the base area. S0 : float Species richness at A0 N0 : float Community abundance at A0 sad_k : float Aggregation parameter of the SAD. Between [0, infinity) ssad_k : float Aggregation parameter of the SSAD. Between (0, infinity). approx : bool (opt) Approximate the truncated logseries. Default True. The approximation is much faster and not very different than the exact answer for most cases.

References

[1]	Wilber, M., Kitzes, J., and Harte, J. (2015). Scale collapse and the emergence of the power law species-area relationship. Global Ecology and Biogeography. 24(8), 883-895

[2]	Harte, J., Smith, A. B., & Storch, D. (2009). Biodiversity scales from plots to biomes with a universal species-area curve. Ecology Letters, 12(8), 789-797.

Examples

>>> # Use a standard SAR with a Broken Stick SAD and an truncated geometric
>>> # binomial SSAD. sad_k = 1, ssad_k = 1
>>> import macroeco.models as md

>>> # Specify the areas at which to calculate species richness
>>> areas = [1, 0.5, 0.25, 0.125] # 1 is the base area A0

>>> # Set community abundance and species richness at A0
>>> N0, S0 = (10000, 50)

>>> # Get the standard SAR
>>> md.sampling_sar.vals(areas, S0, N0, sad_k=1, ssad_k=1, approx=True)
array([ 50.        ,  48.91333114,  47.3371818 ,  45.00844875])

>>> # Get the iterative SAR
>>> md.sampling_sar_iterative.vals(areas, S0, N0, sad_k=1, ssad_k=1, approx=True)
array([ 50.        ,  48.91333114,  47.13849657,  44.37798735])

>>> # Get the EAR
>>> md.sampling_ear.vals(areas, S0, N0, sad_k=1, ssad_k=1, approx=True)
array([  5.00000000e+01,   1.08666886e+00,   1.23816570e-01, 4.15836438e-02])

>>> # Upscaling species richness
>>> areas = [5, 10, 11, 13]
>>> md.sampling_sar.vals(areas, S0, N0, sad_k=0, ssad_k=1, approx=True)
array([ 50.        ,  57.19380999,  58.10403751,  59.66376591])

>>> # Iterative SAR with doubled areas
>>> areas_up = [1, 2, 4, 8]
>>> md.sampling_sar_iterative.vals(areas_up, S0, N0, sad_k=0, ssad_k=1, approx=True)
array([ 50.        ,  57.19380999,  64.72987319,  72.58968402])

>>> # Iterative SAR with not quite doubled areas
>>> areas_up = [1, 2.1, 4.1, 8.1]
>>> md.sampling_sar_iterative.vals(areas_up, S0, N0, sad_k=0, ssad_k=1, approx=True)
array([ 50.        ,  64.72987319,  72.58968402,  80.75754743])

>>> # Notice that the iterative method rounds up if the areas are not
>>> # exact doublings.  This is equivalent to the following
>>> md.sampling_sar_iterative.vals([1, 4, 8, 16], S0, N0, sad_k=0, ssad_k=1, approx=True)
array([ 50.        ,  64.72987319,  72.58968402,  80.75754743])

Methods

vals(x, S0, N0, sad_k, ssad_k, approx=True)

Calculate SAR given starting values and two aggregation parameters. See notes.