Threshold Models API¶

sar_threshold¶

sars.sar_threshold ¶

sar_threshold(data: DataFrame, models: list[str] | None = None, interval: float = 0.1) -> ThresholdFit

Fit threshold / piecewise SAR models.

Fits up to three piecewise models to the data and selects the best by AICc:

ContOne: continuous two-slope model with one breakpoint
ZslopeOne: left-horizontal + right slope (small island effect)
Linear: simple linear model (no breakpoint, baseline)

Area is log-transformed before fitting (consistent with R sars default).

Breakpoint selection uses a two-level procedure. Within each piecewise model class (ContOne, ZslopeOne), a grid search over log(area) selects the breakpoint that minimises residual sum of squares (RSS). Then, across model classes — including the no-breakpoint Linear baseline — the best candidate from each class is ranked by AICc to choose the overall best model. Because the models differ in parameter count (Linear: k=3, ZslopeOne: k=4, ContOne: k=5), AICc penalises complexity appropriately at the cross-model level.

Meaningful threshold detection requires at least 7 observations. The breakpoint grid search needs a minimum of 3 data points on each side of a candidate breakpoint (min_points=3), so with fewer than 7 observations the piecewise models may find zero valid candidates and only the Linear baseline will be returned. A UserWarning is emitted when n < 7.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	DataFrame with columns 'area' and 'species'.	required
`models`	`list[str]`	Which models to fit. Default is all three: ["ContOne", "ZslopeOne", "Linear"].	`None`
`interval`	`float`	Grid spacing for breakpoint search in log(area) space. Default 0.1.	`0.1`

Returns:

Type	Description
`ThresholdFit`	Result with best model, breakpoint, segments, and comparison table.

Warns:

Type	Description
`UserWarning`	If the dataset has fewer than 7 observations.

References

Matthews TJ & Rigal F (2021). Thresholds and the species-area relationship. Frontiers of Biogeography 13(1), e49404.

ThresholdFit¶

sars.ThresholdFit `dataclass` ¶

Result of fitting threshold / piecewise SAR models.

Attributes:

Name	Type	Description
`best_model`	`str`	Name of the best model by AICc ("ContOne", "ZslopeOne", or "Linear").
`best_breakpoint`	`float \| None`	Breakpoint in log(area) space, or None for the linear model.
`best_segments`	`list[dict]`	Segment parameters as list of dicts with keys 'intercept', 'slope', 'x_min', 'x_max' (in log-area space).
`summary`	`DataFrame`	Comparison table with columns: model, breakpoint, AIC, AICc, BIC, R2.
`all_fits`	`dict[str, dict]`	Detailed fit results keyed by model name.
`data`	`DataFrame`	Original data (columns: area, species).
`log_area`	`bool`	Whether area was log-transformed (always True currently).

predict ¶

predict(area: float | ndarray) -> np.ndarray

Predict species richness for given area value(s).