Analyses#
Note
This text about available analyses uses several terms and mathematical symbols one might be unfamiliar with. The Glossary should be able to explain those terms.
The seal analyse subcommand reads a taskfile
and performs the analyses as specified in it. The subcommand requires a single argument,
--taskfile, specifying path to the taskfile. Users are strongly encouraged to familiarize themselves
with the provided example taskfile before configuring their own analyses.
Example:
seal analyse --taskfile ./tasks/example-task.toml
Alternatively, seal can be used directly as a Python library instead of through the command-line interface. The seal.analyse()
method in combination with seal.Config.from_taskfile() does the same analysis workflow as the seal analyse CLI command.
This is useful when seal analyses need to be incorporated into a larger Python script, notebook, or automated workflow.
Provided dataset, specified by the key encounters in the taskfile, must be a comma-delimited CSV file.
Some software export CSV files with semicolons as a delimiter by default. Such files must be converted before
they can be processed by seal.
Both numerical and graphical outputs are saved in the output directory specified in the taskfile. Numerical results are stored as CSV files and can be used in any external post-processing or visualization workflow.
Warning
Remember that the graphical outputs are optional and mostly for initial inspection of the results. As datasets can differ in structure and size, it is impossible for us to optimize the built-in plots for every use case, nor is that our intention. Users are encouraged to create their own visualizations from the output files using their preferred plotting software or to modify the plotting code directly.
Figures shown in this documentation are illustrative rather than prescriptive. They serve to demonstrate different plotting options available and might not represent the optimal visualization for a particular dataset.
Note
Results of analyses based on quadrat pairs may become less robust at larger extents as these are typically represented by fewer pairs of quadrats. For example, in any grid, the most extreme distance (or distance bin) will be represented solely by two pairs of quadrats using the Nested transects strategy and one pair for transect-based strategies. Such cases should be interpreted with caution. When appropriate, results based on an insufficient number of observations may be omitted from further processing.
Overview#
This analysis summarizes the spatial distribution of the sampled community at each transformation level. For each sampling unit it calculates species richness and, if abundance data is provided, total number of encountered individuals.
The auxiliary output provides a general summary of the dataset and the descriptive statistics for individual variables at each level.
coord_x,coord_y,n_species,n_individuals,level
0,0,3,6,1
0,1,1,3,1
1,0,1,2,1
1,1,0,0,1
====LEVEL 1 OVERVIEW START====
==Unique per quadrat==
┌─────────┬─────────┬───────────┬───────────────┐
│ coord_x ┆ coord_y ┆ n_species ┆ n_individuals │
╞═════════╪═════════╪═══════════╪═══════════════╡
│ 0 ┆ 0 ┆ 3 ┆ 6 │
│ 0 ┆ 1 ┆ 1 ┆ 3 │
│ 1 ┆ 0 ┆ 1 ┆ 2 │
│ 1 ┆ 1 ┆ 0 ┆ 0 │
Default graphical output consists of heatmaps showing these values across the transformed study grid. One figure is created for each level.
Heatmap showing the number of species per quadrat at transformation level 1. Empty cells represent quadrats that have not been sampled.#
Heatmap showing the number of individuals per quadrat at transformation level 1. Empty cells represent quadrats that have not been sampled.#
This analysis provides a simple overview of the dataset and can be used as an initial check of how the selected transformation strategy represents the data across levels.
Species richness generally increases with sampled area, as larger samples are more likely to encompass additional species and environmental heterogeneity2. The total number of recorded individuals also typically increases with sampled area simply because a larger area is being sampled and therefore has the potential to include more individuals.
Species–area relationship#
Note
This analysis shows how grain and extent influence the species–area relationship and thus observed species richness. It is the core analysis of seal.
For each transformation level, a species–area curve is calculated by progressively accumulating quadrats and tallying the number of species. As the resulting curves are dependent on the order in which quadrats are accumulated, the analysis repeats the accumulation using random permutations of quadrat order. Number of permutations can be specified in the taskfile (default = 200).
Auxiliary output provide descriptive statistics summarizing the calculated species–area results.
area,acc_0,acc_1,acc_2,acc_3,acc_4,acc_5,acc_6,acc_7,acc_8,acc_9,min_acc,max_acc,level
100.0,0,1,1,1,3,1,1,1,1,0,0,3,1
200.0,1,4,4,2,3,2,2,2,2,3,1,3,1
300.0,4,5,5,2,4,5,5,2,2,4,4,4,1
400.0,5,5,5,5,5,5,5,5,5,5,5,5,1
n_species_mean,n_species_count,n_species_min,n_species_max,n_species_std,n_species_med,n_species_sem,n_species_p025,n_species_p975,area,level
1.0,10,0,3,0.8165,1.0,0.2582,0.0,3.0,100.0,1
2.5,10,1,4,0.9718,2.0,0.3073,1.0,4.0,200.0,1
3.8,10,2,5,1.3166,4.0,0.4163,2.0,5.0,300.0,1
5.0,10,5,5,0.0,5.0,0.0,5.0,5.0,400.0,1
Default graphical output shows the arithmetic mean number of accumulated species at each sampled area across all permutations and transformation levels. A second plot shows the extremes observed across permutations, highlighting minima and maxima at each sampled area. All figures in this section were generated using data of Palmer et al. (2007) :cite:p:` Palmer2007DukeData`.
Species–area relationship curves showing the arithmetic mean of cumulative species richness at each sampled area across the specified number of permutations for all transformation levels. Error bars indicate standard deviations.#
Fastest- and slowest-growing species–area relationship curves observed across all permutations for each transformation level.#
The greater the scale influence, the further apart the curves representing each transformation level tend to be. The lower end of each curve represents the mean number recorded in a single observation unit at that level, and reflects the species richness at corresponding grain. The upper end of the curve of the highest level corresponds to the total number of species recorded in the study grid, as only at this level the entire grid is included in the analysis. This does not apply to the Contiguous Transects strategy, in which the entire grid is analysed at every level.
The extremes plot can be particularly informative when scale dependence is weak. In such cases, the mean curve may obscure differences that occur only for some accumulation sequences, while the fastest- and slowest-growing curves reveal the full range of observed responses.
Note
If scale dependence is pronounced, the same cumulative sampled area may contain more species when it is composed of a larger number of smaller, more widely spaced quadrats than when it is composed of fewer, larger, more spatially aggregated quadrats6. This indicates that both grain and extent influence the observed species–area relationship.
Species turnover analysis#
Note
Turnover and dissimilarity are treated as separate analyses because they describe different aspects of compositional change. Turnover focuses on gains, losses, and replacement of species between quadrats, whereas dissimilarity quantifies their overall compositional difference. Overall dissimilarity may therefore reflect not only replacement, but also differences in species richness or abundance.
This analysis quantifies differences in species composition between pairs of quadrats as a function of their spatial distance. It can be used to examine how community turnover changes across transformation levels.
For every pair of quadrats, seal calculates their spatial distance using the distance metric specified
in the taskfile. Distances can be grouped into bins using
the interval parameter. Binning is particularly useful for Euclidean distance metrics, whereas it is usually unnecessary for Chebyshev
distance[1].
Two measures of species turnover are available: asymmetric species difference6
and Simpson pairwise dissimilarity3. The requested measures are specified using
the formulas parameter in the taskfile. If this parameter is omitted or left empty, difference is used by default.
analyses = [{ type = "turnover", interval = 10, formulas = ["difference", "simpson"] }]
The formulas are calculated for all pairs of quadrats (\(q_1\) and \(q_2\)). For asymmetric difference, the calculations are performed in both directions (\(q_1\) -> \(q_2\) and \(q_1\) <- \(q_2\)).
For each pair of quadrats, define:
- Asymmetric species difference:
The number of species occurring in one of the two quadrats and not the other.
\[\mathrm{diff} = |Q_1 \setminus Q_2|\]The reverse comparison is calculated analogously as \(|Q_2 \setminus Q_1|\).
A value of 0 indicates that all species occurring in the first quadrat also occur in the second, while larger values indicate greater compositional difference. Because this measure is expressed as a number of species rather than as a standardized proportion, its magnitude also depends on species richness.
- Simpson pairwise dissimilarity:
Measures compositional turnover while reducing the influence of differences in species richness between the two quadrats.
Define:
\[ \begin{align}\begin{aligned}a = |Q_1 \cap Q_2|\\b = |Q_1 \setminus Q_2|\\c = |Q_2 \setminus Q_1|\end{aligned}\end{align} \]Then:
\[\beta_{sim} = \frac{\min(b, c)}{a + \min(b, c)}\]Values range from 0 to 1. A value of 0 indicates no compositional turnover, while values approaching 1 indicate increasingly different species composition attributable to species replacement.
Note
If a calculation results in division by zero, the result is recorded as
null. Number of calculations resulting innullis returned in auxiliary output.
distance,abs_diff,simps_diss,distance_bin,level
50.0,3,1.0,"[50, 60)",1
50.0,3,1.0,"[50, 60)",1
50.0,3,,"[50, 60)",1
50.0,1,1.0,"[50, 60)",1
Default graphical outputs summarize turnover among quadrat pairs at each transformation level. For unbinned distances, curves show arithmetic mean turnover at each observed distance. If distance is binned, turnover values are shown as standard boxplots for individual distance intervals.
Asymmetric species difference between quadrat pairs as a function of spatial distance. Curves show mean values for each transformation level. Error bars indicate standard deviations.#
Asymmetric species difference between quadrat pairs across binned distance classes, shown as standard boxplots. Facets represent transformation levels.#
Note
Vertical differences among transformation levels primarily reflect grain effects, whereas changes along the distance axis reflect extent effects. Simpson pairwise dissimilarity may decrease with increasing grain because larger sampling units tend to share a greater proportion of species. In contrast, asymmetric species difference may increase with grain because larger sampling units can contain more species overall. Effects of extent may become apparent only at larger grains6.
Used notation: Q_{3,2}
Richness and extent#
This analysis examines the relationship between spatial extent and cumulative species richness at different grains6. For each transformation level, seal selects all possible subsets of four quadrats forming vertices of a square, creating a subgrid \(S\). The spacing between the selected quadrats is progressively increasing forming a gap \(g\), measured as number of quadrats between them. While the minimal gap is zero when the four quadrats are abutting, the maximum possible gap is constrained by the side of study grid with the least amount of quadrats. For every valid subgrid, cumulative species richness is calculated as the number of unique species occurring across all quadrats in the subgrid \(|\bigcup_{q_i \in S} Q_i|\).
For grids containing single zone (\(z = 1\)) the subset consists of two quadrats forming the endpoints of a line segment with \(g\) observation units in between. This situation commonly occurs after applying transect-based transformation strategies.
spp_total,extent,level
5,50.0,1
9,60.0,2
13,80.0,3
The graphical outputs show the mean cumulative species richness of the four (or two) quadrats at each extent. Spatial extent is determined by the gap between the selected quadrats, meaning that larger gaps correspond to greater extent.
Cumulative species richness across all possible subgrids as a function of spatial extent. Lines show mean values; error bands show standard deviations.#
The leftmost point of each curve represents the minimum possible extent, where the selected quadrats or transects are adjacent. In some nested transformation strategies, this configuration corresponds spatially to a sampling unit of the next transformation level.
Note
A nearly horizontal curve indicates little change in cumulative species richness with increasing extent, whereas an ascending or descending curve indicates a stronger extent effect. Differences among curves representing individual transformation levels primarily reflect grain effects, with higher levels generally corresponding to larger sampling units.
Ratio of observed and expected richness variance#
This analysis examines spatial variation in species richness using the ratio of observed to expected variance6. For every valid subgrid, seal calculates \(\frac{V_o}{V_e}\), where \(V_o\) is the observed richness variance and \(V_e\) is richness variance expected if species were independent. The expected value is calculated as \(\sum P_i \times (1 - P_i)\) with \(P_i\) being proportion of quadrats in the subgrid occupied by species \(i\). The summation is performed over all the species in the study grid.8
Subgrids are created as follows:
Set \(g = 0\).
Select previously unprocessed subgrid \(S\) of \(4 \times 4\) quadrats separated by a gap of \(g\) quadrats.
Compute \(\frac{V_o}{V_e}\), and record the result together with \(g\).
Repeat, starting from step 2, unless every viable \(S\) for the current gap \(g\) is processed.
Increase the gap: \(g = g+1\).
Repeat the procedure for all valid gaps.
Note
In other words, each subgrid contains 16 quadrats arranged in a \(4 \times 4\) pattern with certain gap between them. The gap is measured in quadrats. The observed and expected variance in species richness are calculated for each possible placement of this pattern for each gap. Their ratio is recorded together with gap, and the gap is increased by one observation unit. This process is done until all possible subgrids of all possible gaps are processed. Enlarging the gap increases the spacing among quadrats and therefore the spatial extent represented by the subgrid.
For transect-based transformation strategies, four observation units in a line with a gap between them are analysed as a subgrid.
variance_ratio,gap,level
0.6763,0,1
1.3603,0,2
The graphical outputs show the ratio of observed to expected variance in species richness across transformation levels and extents. The primary plot is a line plot showing the relationship between transformation level and the variance ratio, with separate lines representing different gaps. The secondary plot shows the same data as boxplots, with values grouped by gap and faceted by transformation level. All figures in this section were generated using data of Palmer et al. (2007) :cite:p:` Palmer2007DukeData`.
Ratio of observed to expected variance in species richness for all possible subgrids. Lines represent mean values for subgrids with a given gap; error bars indicate standard deviations.#
Ratio of observed to expected variance in species richness for all possible subgrids. Boxplots show the distribution of values for individual gaps. Facets represent transformation levels.#
Note
A ratio close to 1 indicates that the observed variance is similar to that expected under independent species occurrences. Values above 1 indicate greater-than-expected variation in species richness among quadrats and may reflect positive spatial association or aggregation of species. Values below 1 indicate lower-than-expected variation and may reflect more regular or negatively associated species distributions. Differences among transformation levels primarily reflect grain effects, whereas differences among gaps within a level reflect extent-related patterns.
Dissimilarity analysis#
Note
Unlike the turnover analysis, which focuses specifically on species replacement, this analysis uses standard ecological dissimilarity indices to quantify overall differences between communities. These differences may reflect species replacement as well as differences in species richness or abundance.
This analysis quantifies overall compositional dissimilarity between pairs of quadrats as a function of their spatial distance. It can therefore be used to examine distance decay of community similarity and how this relationship changes across transformation levels4.
For every pair of quadrats, seal calculates their spatial distance using the distance metric specified
in the taskfile. Distances can be grouped into bins using
the interval parameter. Binning is particularly useful for Euclidean distance metrics, whereas it is usually unnecessary for Chebyshev
distance[1].
The available dissimilarity measures are: Jaccard dissimilarity and Sørensen dissimilarity based on presence-absence data,
and Bray–Curtis dissimilarity, based on species abundance. The requested measures are specified using
the formulas parameter in the taskfile. If the parameter is omitted or left empty, jaccard is used by default
because it provides a simple and widely interpretable presence–absence measure of overall compositional dissimilarity.
analyses = [{ type = "dissimilarity", interval = 10, formulas = ["braycurtis", "jaccard", "sorensen"] }]
The calculations are performed for all pairs of quadrats (\(q_1\) and \(q_2\)).
For each pair of quadrats, define:
\[ \begin{align}\begin{aligned}a = |Q_1 \cap Q_2|\\b = |Q_1 \setminus Q_2|\\c = |Q_2 \setminus Q_1|\end{aligned}\end{align} \]
Jaccard dissimilarity: Proportion of species occurring in only one of the two quadrats relative to the total number of species occurring in either quadrat.
\[d_J = 1 - \frac{a}{a+b+c}\]A value of 0 indicates identical species composition, whereas values approaching 1 indicate increasingly dissimilar communities. Unlike Simpson pairwise dissimilarity used in the turnover analysis, Jaccard dissimilarity represents overall compositional difference and is therefore also affected by differences in species richness between quadrats.
Sørensen dissimilarity: A presence–absence measure of compositional dissimilarity that gives greater weight to species shared by both quadrats.
\[d_S = 1 - \frac{2a}{2a+b+c}\]Values range from 0 to 1. A value of 0 indicates identical species composition, while values approaching 1 indicate increasingly dissimilar communities. Like Jaccard dissimilarity, Sørensen dissimilarity measures overall compositional difference rather than species replacement alone.
Bray–Curtis dissimilarity: Incorporates quantitative abundances and therefore requires the input dataset to contain the number of individuals. Two quadrats containing the same species may still have high dissimilarity if their relative abundances differ substantially.
Warning
Bray–Curtis dissimilarity requires quantitative abundance data. The encounters dataset must therefore contain an
individualscolumn or another quantitative column must be specified using thequantity-colkey in the taskfile.Define
\[ \begin{align}\begin{aligned}C_{1,2} = \sum_i \min(x_i^{1}, x_i^{2})\\S_1 = \sum_i x_i^{1}\\S_2 = \sum_i x_i^{2}\end{aligned}\end{align} \]where \(x_i^{1}\) and \(x_i^{1}\) denote the abundance of species \(i\) in quadrats \(q_1\) and \(q_2\), respectively. \(C_{1,2}\) denotes the total abundance shared between quadrats \(q_1\) and \(q_2\). \(S_1\) and \(S_2\) denote the total abundance of all species in quadrats \(q_1\) and \(q_2\), respectively. Here, \(S\) refers to total abundance and is unrelated to the \(S\) notation used elsewhere for subgrids.
Then:
\[BC(q_1,q_2) = 1 - \frac{2C_{1,2}}{S_1 + S_2}\]A value of 0 indicates identical abundance composition, while values approaching 1 indicate increasingly dissimilar communities.
distance,jaccard,log_jaccard,sorensen,braycurtis,distance_bin,level
50.0,1.0,0.0,1.0,1.0,"[50, 60)",1
50.0,1.0,0.0,1.0,1.0,"[50, 60)",1
50.0,1.0,0.0,1.0,1.0,"[50, 60)",1
50.0,1.0,0.0,1.0,1.0,"[50, 60)",1
Default graphical outputs show the relationship between community dissimilarity and spatial distance for each transformation level. For unbinned distances, curves show arithmetic mean dissimilarity at each observed distance, with error bars indicating standard deviations. If distances are binned, distributions within individual distance classes are shown as standard boxplots.
Jaccard dissimilarity for all quadrat pairs plotted against their distance. The lines show mean values for each level. Error bars show standard deviations.#
Jaccard dissimilarity across binned distance classes shown as standard boxplots. Facets represent transformation levels.#
Note
Vertical differences among transformation levels primarily reflect grain effects, whereas changes in dissimilarity with spatial distance reflect extent-related patterns. Coarser grains often show lower dissimilarity because larger sampling units tend to overlap more strongly in community composition, whereas smaller sampling units may share fewer species or differ more strongly in their relative abundances. Increasing dissimilarity with distance corresponds to distance decay of community similarity. Comparing both the vertical separation and the distance-dependent trends among transformation levels therefore allows the influence of grain and extent on patterns of community composition to be examined.
Used notation: Q_{3,2}
Species-abundance distribution#
This analysis examines species-abundance distributions and how they change across transformation levels. It provides a descriptive view of community dominance structure, including the relative representation of common and rare species.
Warning
The analysis requires quantitative abundance data. The encounters dataset must therefore contain
an individuals column or another quantitative column must be specified using the quantity-col key in the taskfile.
For each level, number of individuals for each species is calculated the species are ordered by abundance.
species,individuals,level
H,3,1
C,3,1
L,2,1
B,2,1
The results can optionally be visualized using three complementary plot types.
The first plot provides a direct overview of species abundances, with species ordered by the number of recorded individuals. Species names make it possible to identify the most and least abundant taxa directly. The last column summarizes the singletons.
The second plot summarizes the species-abundance distribution using an empirical complementary cumulative distribution function (ECCDF). For each abundance value (x axis), the curve shows the proportion (y axis) of species whose abundance is greater than or equal to that value. This provides a compact view of dominance and rarity without requiring abundance classes or binning.
The third plot is a bump chart showing how the relative abundance ranks of the most common species change across transformation levels.
Species are ranked by total abundance within each level, and lines connect the same species across levels. Species falling outside
the selected top ranks are grouped as >top_n.
Species abundances ordered from most to least abundant. Bars represent the number of recorded individuals of each species, with singleton species combined in the final bar.#
Species-abundance distribution shown as an empirical complementary cumulative distribution function (ECCDF), representing the proportion of species with abundance greater than or equal to each x-value.#
Bump chart showing changes in the abundance ranks of the ten most common species across transformation levels.#
Together, the three plots provide complementary views of species-abundance structure and its response to changes in spatial scale. The ordered abundance plot allows dominance and rarity to be assessed directly. A community dominated by a few species is characterized by a small number of high bars followed by a rapid decline, whereas a more even community shows a more gradual decrease in abundance. Comparing transformation levels can therefore reveal whether increasing spatial scale strengthens or reduces apparent dominance.
The ECCDF provides a distribution-level view of the same pattern without relying on individual species identities. Curves that decline rapidly indicate that most species have low abundances and only a small proportion are highly abundant, whereas a slower decline indicates a more even abundance distribution. Shifts among transformation levels can thus reveal scale-dependent changes in community evenness and dominance.
The bump chart complements these community-level patterns by showing whether changes are associated with particular dominant species. Stable lines indicate that species retain similar relative abundance ranks across transformation levels, whereas changes in rank indicate that their relative dominance is sensitive to spatial scale.
Footnotes