Multi-model Inference API

sar_multi

sars.sar_multi

sar_multi(data: DataFrame, models: str | list[str] = 'all') -> MultiSARFit

Fit multiple SAR models to a dataset.

Parameters:

Name	Type	Description	Default
data	DataFrame	DataFrame with columns 'area' and 'species'.	required
models	str or list[str]	Model names to fit. Use "all" for all 20 models.	'all'

Returns:

Type	Description
MultiSARFit	Container with all converged fits and a summary table.

MultiSARFit

sars.MultiSARFit dataclass

Result of fitting multiple SAR models to one dataset.

Attributes:

Name	Type	Description
fits	list[SARFit]	Individual model fits (converged only).
data	DataFrame	Original data.
summary	DataFrame	Summary table with columns: model, R2, AIC, AICc, BIC, delta_AICc, weight, shape, asymptote. Sorted by AICc ascending. The shape column is a static classification based on each model's typical curvature (see _MODEL_SHAPE), not a dynamic assessment of the fitted curve.

sar_average

sars.sar_average

sar_average(data: DataFrame, models: str | list[str] = 'all', ic: str = 'AICc') -> AveragedSAR

Compute model-averaged SAR predictions using information-theoretic weights.

Parameters:

Name	Type	Description	Default
data	DataFrame	DataFrame with columns 'area' and 'species'.	required
models	str or list[str]	Model names to fit. Use "all" for all 20 models.	'all'
ic	str	Information criterion for weighting: "AICc" (default), "AIC", or "BIC". AICc may be infinite when the sample size is small relative to the number of parameters; in that case "AIC" or "BIC" can be used instead.	'AICc'

Returns:

Type	Description
AveragedSAR	Model-averaged SAR with weighted predictions.

AveragedSAR

sars.AveragedSAR dataclass

Model-averaged species-area relationship.

Attributes:

Name	Type	Description
multi	MultiSARFit	The underlying multi-model fit.
ic	str	Information criterion used for weighting ("AICc", "AIC", or "BIC").
weights	dict[str, float]	Model weights keyed by model name.

predict

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

Weighted-average prediction across models.

Parameters:

Name	Type	Description	Default
area	float or array - like	Area value(s) to predict for.	required

Returns:

Type	Description
ndarray	Model-averaged predicted species richness.

bootstrap_ci

sars.bootstrap_ci

bootstrap_ci(data: DataFrame, models: str | list[str] = 'all', n_boot: int = 1000, conf: float = 0.95, area_grid: ndarray | None = None, rng: Generator | None = None, method: str = 'fast', ic: str = 'AICc') -> BootstrappedCI

Compute bootstrap confidence intervals for model-averaged predictions.

Resamples rows of the data with replacement, fits all models, computes model-averaged predictions at each area value, then returns percentile-based confidence intervals.

Parameters:

Name	Type	Description	Default
data	DataFrame	DataFrame with columns 'area' and 'species'.	required
models	str or list[str]	Model names to use. "all" for all 20 models.	'all'
n_boot	int	Number of bootstrap replicates.	1000
conf	float	Confidence level (default 0.95).	0.95
area_grid	ndarray	Area values at which to predict. If None, uses 100 points spanning the range of the data.	None
rng	Generator	Random number generator for reproducibility.	None
method	str	Bootstrap fitting strategy. "fast" (default) fits all models once on the original data with full grid search, then uses those converged parameters as warm starts for each resample (~2000x faster). "full" runs the complete grid search on every resample (slow but maximally robust).	'fast'
ic	str	Information criterion for weighting: "AICc" (default), "AIC", or "BIC".	'AICc'

Returns:

Type	Description
BootstrappedCI

BootstrappedCI

sars.BootstrappedCI dataclass

Bootstrap confidence intervals for model-averaged predictions.

Attributes:

Name	Type	Description
area_grid	ndarray	Area values at which predictions were made.
mean	ndarray	Mean prediction across bootstrap replicates.
lower	ndarray	Lower confidence bound.
upper	ndarray	Upper confidence bound.
conf	float	Confidence level (e.g. 0.95).
n_boot	int	Number of bootstrap replicates completed.
convergence_counts	list[int]	Number of models that converged in each successful replicate. Length equals n_boot. Empty when no replicates succeeded.
n_models_attempted	int	Number of models attempted per replicate (i.e. the number that converged on the original data).

Helper functions

sars.aicc

aicc(k: int, n: int, rss: float) -> float

Compute AICc from residual sum of squares.

Parameters:

Name	Type	Description	Default
k	int	Number of estimated parameters (including sigma).	required
n	int	Number of observations.	required
rss	float	Residual sum of squares.	required

Returns:

Type	Description
float	AICc value.

sars.akaike_weights

akaike_weights(ic_values: ndarray) -> np.ndarray

Compute Akaike weights from a vector of information criterion values.

The weighting formula w_i = exp(-0.5 * delta_i) / sum(exp(-0.5 * delta)) applies identically to AIC, AICc, and BIC (Burnham & Anderson 2002).

Parameters:

Name	Type	Description	Default
ic_values	array - like	Information criterion values (AIC, AICc, or BIC) for each candidate model.	required

Returns:

Type	Description
ndarray	Model weights (sum to 1). Non-finite inputs produce 0 weight.