I/O Adapters API¶
load_galap¶
sars.load_galap ¶
Load the Galapagos plant species-area dataset.
Returns the Preston (1962) 16-island dataset as shipped in the R sars package (Albemarle/Isabela excluded).
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with columns 'area' and 'species'. |
from_csv¶
sars.from_csv ¶
Load species-area data from a CSV file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str or Path
|
Path to the CSV file. |
required |
area_col
|
str
|
Name of the column containing area values. |
'area'
|
species_col
|
str
|
Name of the column containing species richness values. |
'species'
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with columns 'area' and 'species'. |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the file does not exist. |
KeyError
|
If the specified columns are not found. |
from_pyinaturalist¶
sars.from_pyinaturalist ¶
from_pyinaturalist(observations: list[dict], area_key: str = 'area', species_key: str = 'species_count') -> pd.DataFrame
Convert pyiNaturalist observation summaries to SAR format.
Expects a list of dicts where each dict represents an island or site with area and species count fields. This is not raw iNaturalist observation data — it should be pre-aggregated by site.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
observations
|
list[dict]
|
List of dicts, each with at least an area field and a species count field. |
required |
area_key
|
str
|
Key in each dict for the area value. |
'area'
|
species_key
|
str
|
Key in each dict for the species richness value. |
'species_count'
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with columns 'area' and 'species'. |
Raises:
| Type | Description |
|---|---|
KeyError
|
If the specified keys are not found in the observation dicts. |
from_geodataframe¶
sars.from_geodataframe ¶
from_geodataframe(gdf: GeoDataFrame, species_col: str = 'species', area_col: str | None = None, crs_units: str = 'km2') -> pd.DataFrame
Convert a GeoDataFrame of polygons to SAR format.
Computes area from polygon geometries if no area column is specified.
Requires geopandas and shapely (install with pip install sars[geo]).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gdf
|
GeoDataFrame
|
GeoDataFrame with polygon geometries and a species count column. |
required |
species_col
|
str
|
Column name for species richness values. |
'species'
|
area_col
|
str
|
Column name for pre-computed area values. If None, area is computed from geometries. |
None
|
crs_units
|
str
|
Unit conversion for computed areas. "km2" divides by 1e6 (assumes CRS in metres), "m2" uses raw area, "ha" divides by 1e4. |
'km2'
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with columns 'area' and 'species'. |
Raises:
| Type | Description |
|---|---|
ImportError
|
If geopandas is not installed. |
KeyError
|
If the specified columns are not found. |
ValueError
|
If geometries are not polygons or CRS units are invalid. |