Skip to content

Download the Jupyter notebook

Assignment 08: Species Distribution Modeling with elapid

BIO597 Spatial Analysis of Biodiversity

Use elapid to prepare spatial data, fit a MaxEnt model, and ask how evaluation changes when we withhold whole geographic areas. You may reuse code from Lab08.

Deliverable

Submit this completed notebook with maps, climate comparisons, ROC curves, an AUC summary table, and short written answers. Save your modeling points and AUC table. Use the lab's model defaults; no parameter search or suitability-raster export is required.

1. Import packages and load the occurrence records

Run this notebook from docs/assignments. The imports are provided so you can focus on the SDM workflow. If elapid is unavailable, use the same environment or installation instructions as the lab.

np.random.seed(597) makes the background draws repeatable when the notebook runs from top to bottom.

import elapid as ela
import numpy as np
import pandas as pd
import geopandas as gpd
import rasterio as rio
from rasterio import plot as rioplot
import matplotlib.pyplot as plt
from sklearn import metrics
from sklearn.metrics import RocCurveDisplay

np.random.seed(597)
amphibians = gpd.read_file("../data/amphibians.geojson")
amphibians["species"].value_counts().head(12)

2. Choose a species

Choose a common Maine amphibian other than the lab's pickerel frog (Lithobates palustris). Start with at least 200 records. Filter the occurrence table to your species and store the result as species_points.

target_species = "YOUR SPECIES HERE"

# Select your species and store a copy as species_points.
# Print the record count and coordinate reference system.

Why this species? Give one biological reason for your choice.

3. Set up the climate rasters

Use the same 19 Maine bioclimatic rasters as the lab. The filenames and readable column names are provided below. Their order matters: each label must describe the corresponding raster.

bioclim_names = {
    'wc2.1_2.5m_bio_1.tif':  'Annual mean temperature',
    'wc2.1_2.5m_bio_2.tif':  'Mean diurnal temperature range',
    'wc2.1_2.5m_bio_3.tif':  'Isothermality',
    'wc2.1_2.5m_bio_4.tif':  'Temperature seasonality',
    'wc2.1_2.5m_bio_5.tif':  'Max temperature, warmest month',
    'wc2.1_2.5m_bio_6.tif':  'Min temperature, coldest month',
    'wc2.1_2.5m_bio_7.tif':  'Annual temperature range',
    'wc2.1_2.5m_bio_8.tif':  'Mean temperature, wettest quarter',
    'wc2.1_2.5m_bio_9.tif':  'Mean temperature, driest quarter',
    'wc2.1_2.5m_bio_10.tif': 'Mean temperature, warmest quarter',
    'wc2.1_2.5m_bio_11.tif': 'Mean temperature, coldest quarter',
    'wc2.1_2.5m_bio_12.tif': 'Annual precipitation',
    'wc2.1_2.5m_bio_13.tif': 'Precipitation, wettest month',
    'wc2.1_2.5m_bio_14.tif': 'Precipitation, driest month',
    'wc2.1_2.5m_bio_15.tif': 'Precipitation seasonality',
    'wc2.1_2.5m_bio_16.tif': 'Precipitation, wettest quarter',
    'wc2.1_2.5m_bio_17.tif': 'Precipitation, driest quarter',
    'wc2.1_2.5m_bio_18.tif': 'Precipitation, warmest quarter',
    'wc2.1_2.5m_bio_19.tif': 'Precipitation, coldest quarter',
}

rasters = [f"../data/bioclim_ME/{var}" for var in bioclim_names]
labels = list(bioclim_names.values())

4. Map the records over temperature

Open rasters[0] (annual mean temperature), plot it with rioplot.show(), and overlay your species' points. Reproject the points to the raster CRS when plotting, as in the lab. Keep this first raster path as mean_temp_raster for sampling.

mean_temp_raster = rasters[0]

# Plot annual mean temperature and overlay species_points.
# Add a title naming your species.

Interpretation: Are records spread across Maine or concentrated in particular places? Why might a gap in records fail to indicate a true absence?

5. Compare two background samples

Draw 1,000 points with ela.sample_raster() and another 1,000 with ela.sample_bias_file(), using annual mean temperature as the bias file. Drop duplicate geometries in each sample, following the lab, and report the remaining counts. Map the two samples side by side.

The biased sample favors cells with larger temperature values. This is a demonstration of sampling bias; temperature alone does not establish where observers actually searched.

count = 1000

# Create pseudoabsence with ela.sample_raster().
# Create pseudoabsence_bias with ela.sample_bias_file().
# Drop duplicate points, print the remaining counts, and map both samples.

Interpretation: How do the two geographic samples differ? Explain why background choice can change the species–climate relationship learned by a model.

Choose one sample for the remaining analysis and keep it fixed. The line below uses the uniform sample; change it to pseudoabsence_bias if you choose the biased sample.

Background choice and justification:

background_points = pseudoabsence

6. Extract climate values with ela.annotate()

Annotate species_points.geometry and your chosen background_points using rasters, labels, drop_na=True, and quiet=True. Store the results as presence and background. Report the number of usable rows in each table.

Annotation means extracting raster values at point locations. drop_na=True removes points falling on raster NoData cells.

# Annotate presence and background points, following Lab08.
# Print the usable counts and display presence.head().

7. Compare recorded and available environments

Use the plotting recipe below to compare annual mean temperature, annual precipitation, and precipitation seasonality. These are the same three variables considered in Lab07. Density-scaled histograms let us compare shapes despite different sample sizes.

comparison_labels = [labels[0], labels[11], labels[14]]
fig, axes = plt.subplots(1, 3, figsize=(15, 4))

for label, ax in zip(comparison_labels, axes):
    ax.hist(presence[label], bins=20, density=True, alpha=0.5, label="Presence")
    ax.hist(background[label], bins=20, density=True, alpha=0.5, label="Background")
    ax.set_title(label)
    ax.set_ylabel("Density")

axes[0].legend()
plt.tight_layout()
plt.show()

Interpretation: Choose one variable. Does your species' recorded environment differ from the sampled background? Describe the pattern without assuming it proves a habitat preference.

8. Calculate geographic sample weights

Following the lab, use ela.distance_weights(..., n_neighbors=-1) to calculate a SampleWeight column separately for presence and background. Pass points projected to EPSG:26919, which uses meters. Plot presence points colored by their weights.

The weights give relatively isolated observations more influence than observations in dense clusters. They do not turn an unobserved location into a confirmed absence.

# Calculate presence["SampleWeight"] using presence.to_crs("EPSG:26919").
# Calculate background["SampleWeight"] the same way.
# Plot the presence weights with a legend.

Interpretation: Where are the largest weights? Why would decimal degrees be a poor unit for the distance calculations?

9. Stack the tables and define predictors

Use ela.stack_geodataframes(presence, background, add_class_label=True) and project the result to EPSG:26919. Call the result merged and display the counts in its class column.

class is 1 for presence and 0 for background. Select only the named climate columns as predictors. SampleWeight, class labels, geometry, and later split labels must stay out of the predictor table.

# Stack presence and background as merged, then project it to EPSG:26919.
# Display the counts of each class.

X = merged[labels]
y = merged["class"]
sample_weight = merged["SampleWeight"]

10. Fit MaxEnt and calculate a training AUC

Create maxent = ela.MaxentModel() and fit it with X, y, and sample_weight=sample_weight. Predict scores for X.

This first check uses the same rows for learning and evaluation, as in the lab's “naive” model. It is a training score, not a test of new locations.

ROC AUC measures how well scores rank presence above background. A value near 0.5 indicates little ranking ability; a higher value indicates better separation of these labels. The ROC curve shows the tradeoff as we change the cutoff for calling a score high: more recorded presences exceed the cutoff, but more background points may exceed it too. AUC does not establish true occupancy probability.

maxent = ela.MaxentModel()
maxent.set_params(n_cpus=4)

# Fit maxent with X, y, and sample_weight.
# Predict X and store the scores as naive_prediction.
# Calculate naive_auc with metrics.roc_auc_score(y, naive_prediction).
# Also calculate naive_weighted_auc using sample_weight=sample_weight.
# Print both scores and plot a ROC curve with RocCurveDisplay.from_predictions().

Interpretation: Why might evaluating the same rows used to fit a model give an overly encouraging impression of performance?

11. Make a geographic train/test split

Use ela.checkerboard_split(merged, grid_size=50_000) to divide points into alternating 50 km squares. This distance is in meters because merged is projected.

Check the class counts in both groups: each needs presence and background rows to calculate AUC. The provided plotting recipe adds a split label for display only.

grid_size = 50_000
train, test = ela.checkerboard_split(merged, grid_size=grid_size)
print("Training labels:")
print(train["class"].value_counts())
print("Test labels:")
print(test["class"].value_counts())

train["split"] = "Train"
test["split"] = "Test"
checker = ela.stack_geodataframes(train, test)
checker.plot(column="split", markersize=2, legend=True)
plt.title("50 km checkerboard split")
plt.show()

12. Refit using training points and evaluate test points

Build training and test predictor tables using only labels, as below. Refit maxent on the training rows and their weights, then predict the test rows. Calculate unweighted and weighted test AUCs, storing them as checker_auc and checker_weighted_auc. Plot the test ROC curve.

In weighted AUC, test weights affect the contribution of each test row. They do not mean the model learned from the test labels.

Xtrain = train[labels]
ytrain = train["class"]
weight_train = train["SampleWeight"]
Xtest = test[labels]
ytest = test["class"]
weight_test = test["SampleWeight"]

# Fit maxent using only Xtrain, ytrain, and weight_train.
# Predict Xtest and calculate checker_auc and checker_weighted_auc.
# Print the scores and plot the test ROC curve.

Apply the trained model to the ME clipped rasters

output_raster = "______________.tif"
# Use ela.apply_model_to_rasters() to apply the fitted model to the raster stack
# and write the result to the output_raster file

# use rio.open() to read the predicted tif back into memory
# and plot it with imshow()

Interpretation: Did test AUC differ from training AUC? Describe what each score evaluates. A lower test score does not automatically prove that spatial autocorrelation caused the difference: the training size and environments also changed. A higher test score does not automatically establish a reliable map.

13. Give the other squares a turn

For a simple two-fold spatial cross-validation, reverse the roles: create a new MaxEnt model, train it using Xtest, ytest, and weight_test, then evaluate its predictions for Xtrain. Store the unweighted and weighted scores as reverse_auc and reverse_weighted_auc.

No new background draw or checkerboard split is needed.

# Create reverse_model with the same settings.
# Fit on Xtest with ytest and weight_test; predict Xtrain.
# Calculate reverse_auc and reverse_weighted_auc against ytrain.
# Print the scores.

Interpretation: Were the two directions equally easy to predict? Suggest one geographic or biological reason for a difference. Swapping the regions gives each group a turn as test data; it does not remove every source of observation bias.

14. Inspect one buffered leave-one-out split

The lab also demonstrates buffered leave-one-out validation. For each test presence, it removes nearby training points so the model must predict farther from its training data.

Run the code below to inspect one split, using a 50 km buffer. No repeated model fitting is required here. next() takes just the first split that the splitter produces. This visualization is not a complete validation or an AUC estimate.

subset = merged.sample(n=min(200, len(merged)), random_state=597).reset_index(drop=True)
distance = 50_000
bloo = ela.BufferedLeaveOneOut(distance=distance)
train_idx, test_idx = next(bloo.split(subset, class_label="class"))
buffer_train = subset.iloc[train_idx]
buffer_test = subset.iloc[test_idx]

fig, ax = plt.subplots(figsize=(6, 6))
subset.plot(ax=ax, color="lightgray", markersize=5, label="All sampled points")
buffer_train.plot(ax=ax, color="teal", markersize=5, label="Retained training points")
buffer_test.buffer(distance).boundary.plot(ax=ax, color="coral")
buffer_test.plot(ax=ax, color="red", markersize=40, label="Test presence")
ax.legend()
ax.set_xlabel("Easting (m)")
ax.set_ylabel("Northing (m)")
ax.tick_params(axis="x", labelrotation=45)
ax.set_title("One held-out presence and its 50 km exclusion buffer")
plt.show()

Interpretation: What happened to points inside the buffer? How does this test a different prediction question from randomly withholding records? Explain why a single held-out presence cannot by itself give a ROC AUC.

15. Summarize and save your results

Make a three-row table with evaluation names, unweighted AUCs, and weighted AUCs:

  • Training rows scored by the all-data model.
  • First checkerboard direction: train on train, evaluate test.
  • Reversed direction: train on test, evaluate train.

Save it as Assignment08_auc_scores.csv, without a DataFrame index. Save merged as Assignment08_modeling_points.gpkg using driver="GPKG", preserving its geometry, climate columns, labels, weights, and projected CRS.

# Build an AUC summary table from the six scores you stored.
# Display it and save it to Assignment08_auc_scores.csv.
# Save merged to Assignment08_modeling_points.gpkg.

Final reflection

Answer each question in two or three sentences, using your results.

  1. Which preparation tasks did elapid simplify compared with earlier labs?
  2. What do background sampling, geographic sample weights, and spatial train/test splitting each change?
  3. Why do high AUC and a convincing ROC curve not establish a probability that your species occurs at a location?
  4. What additional data or evaluation would most improve confidence in predictions for your species?

Submit your work

Restart the kernel and run the notebook from top to bottom. Check your figures, AUC table, saved points, and written answers. Commit and push the completed notebook and the two output files to your class GitHub repository.

git add docs/assignments/Assignment-08-SDM-Software.ipynb docs/assignments/Assignment08_auc_scores.csv docs/assignments/Assignment08_modeling_points.gpkg
git commit -m "Complete elapid SDM assignment"
git push

References