macroeco.empirical.sar(patch, cols, splits, divs, ear=False)

Calculates an empirical species area or endemics area relationship


patch : Patch obj

Patch object containing data for analysis

cols : str

Indicates which column names in patch data table are associated with species identifiers, counts, energy, and mass. See Notes.

splits : str

If multiple analyses for subsets of patch data table are desired, specifies how columns should be split. See Notes.

divs : str

Description of how to divide x_col and y_col. See notes.

ear : bool

If True, calculates an endemics area relationship


list :

List of tuples containing results, where the first element of each tuple is a string indicating the split values used for that result and second element is a dataframe giving the result. Result has 5 columns; div, x, and y; that give the ID for the

division given as an argument, fractional area, and the mean species :

richness at that division. :


The parameter cols is a string describing which column in the data table should be used for which “special columns” in analysis. The five possible special columns are

  • spp_col - Unique species identifiers
  • count_col - Number of individuals at a location
  • x_col - x coordinate of location
  • y_col - y coordinate of location
  • energy_col - Energetic requirements of individual(s) at a location

For example, setting cols to spp_col: spp: count_col: number will use the column named “spp” in the data table to represent the unique species identifiers, and the column “number” in the data table to represent the count of individuals at a point.

Different special columns are required for different analyses. count_col is used when multiple individuals of a species may be found at a single recorded location, as is the case in gridded censuses where all individuals in a quadrat are “assigned” to a single point. If count_col is not specified, each record in the data table will be presumed to represent a single individual (i.e., a count of 1).

Note that the value of spp_col may be set to a columm in the data table giving the genus, family, functional group, etc., which allows for analysis of this metric by those groups.

For the SAR and EAR, cols must also contain x_col and y_col, giving the x and y dimensions along which to grid the patch.

The parameter splits is a semicolon-separated string in the form of “column: value”, where column is a name of a column in the patch data table and value is either (a) an integer giving the number of equally-spaced divisions of a column, or (b) the special keyword ‘split’, which evaluates all unique levels of a column.

For example, presume a data table has columns for x and y spatial coordinates and a column for year, of which there are three. The string “x:2; y:2; year:split” will perform the analysis separately for each of four subplots of the patch (created by dividing the x and y coordinates each into two equally sized divisions) within each of the three years, for a total of 12 separate analyses. Note that if you pass in the x split you MUST also pass in a y split (even if it is just “y:1”) or vice versa. Otherwise, the computed areas will be incorrect.

The parameter divisions describes how to successively divide the patch along the x_col and y_col dimensions. For example, the string ‘1,2; 2,2; 2,4’ will produce an output table with three rows, giving the result across two subplots when the patch is split along y_col, across four subplots when the patch is split into a 2x2 grid, and across eight subplots when the patch is split into 2 parts along x_col and 4 parts along y_col.


>>> # Using the ANBO data provided in found at
>>> #
>>> import macroeco as meco
>>> # Pass in path to metadata in order to make patch object
>>> pat = meco.empirical.Patch('~/Desktop/ANBO.txt')
>>> # Get the SAR at the full area (1,1), 1 x 2 division,
>>> # 2 x 1 division, 2 x 2 division, 2 x 4 division, 4 x 2 division, and
>>> # 4 x 4 division
>>> sar = meco.empirical.sar(pat,
            cols='spp_col:spp; count_col:count; x_col:row; y_col:column',
            divs="1,1; 1,2; 2,1; 2,2; 2,4; 4,2; 4,4")
>>> sar[0][1]
   div  n_individs    n_spp   x        y
0  1,1   2445.0000  24.0000  16  24.0000
1  1,2   1222.5000  18.5000   8  18.5000
2  2,1   1222.5000  17.0000   8  17.0000
3  2,2    611.2500  13.5000   4  13.5000
4  2,4    305.6250  10.1250   2  10.1250
5  4,2    305.6250  10.5000   2  10.5000
6  4,4    152.8125   7.5625   1   7.5625

The column div gives the divisions specified in the function call. The column n_individs specifies the average number of individuals across the cells made from the given division. n_spp gives the average species across the cells made from the given division. x gives the absolute area of a cell for the given division. y gives the same information as n_spp and is included for easy plotting.

See for additional examples and explanation