macroeco.empirical.o_ring

macroeco.empirical.o_ring(patch, cols, splits, spp, bin_edges, density=True, full=False)

Calculates univariate O-ring for a species

Parameters:

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.

bin_edges : iterable

List of edges of distance classes to bin histogram of distances

spp : str

String corresponding to focal species code

density : bool

If True, return densities (counts divided by area of torus defined by bin edges) instead of counts. Default True.

full : bool

If True, return a separate column giving density at distance x for every individual, rather than mean density. Default False.
Returns:

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 two columns, x and y, that give the distance to the center

of a torus and the number or density of individuals found in that torus. :

Notes

If density is False, counts are raw counts, non-edge corrected, within rings.

Pairwise distances are directional, giving n(n-1) total distances for a species with n individuals, as edge correction is inherently directional.

Bins include the lower edge and exclude the upper edge, except for the final bin which includes both the lower and upper edge. Floating point arithmetic may cause points located “exactly” on edges to be allocated contrary to this rule, however.

If there are no records for a species, result table will be a dataframe with no records. If there are records but a species has only one individual, dataframe will have zero count at all torus areas.

When using density, the maximum distance used for edge correction, given by the mean of the last two bin_edge values, should ideally be set to no greater than one half the diagonal distance across the plot. This ensures that it is not possible for an entire edge correction buffer to be outside of the plot.

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 0-ring analysis, cols must also contain x_col and y_col, giving the x and y dimensions along which to analyze spatial pattern.

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.