UniversityOfMontanaSAL/Rebekahs_VEDU_Model

Rebekahs VEDU Model

This folder contains a notebook workflow for building a Ventenata dubia (VEDU) model from survey points and satellite imagery.

The project currently has two main notebooks:

• Cheatgrass.ipynb: the original notebook
• Cheatgrass copy.ipynb: the working copy that has been patched to be safer to rerun locally

There is also one helper notebook:

• Create_Depend_for_Rebekahs_VEDU_Model.ipynb: builds the dependency shapefiles used by the main workflow

What The Original Notebook Does

Cheatgrass.ipynb does four big things:

1. Loads VEDU presence and absence shapefiles and assigns them to spatial boxes.
2. Queries NASA HLS imagery for each box and extracts reflectance values at the point locations.
3. Builds a tabular modeling dataset with vegetation indices and seasonal period labels.
4. Trains classifiers and then uses them to predict over raster imagery.

The original notebook assumes:

• the legacy presence file is point-based
• Shapefiles/VEDU_abs.shp exists and is readable
• several long-running steps complete in one pass
• some intermediate products live only in memory

That makes it fragile on a local workstation, especially when a long STAC or raster step hangs.

What The Copy Does Differently

Cheatgrass copy.ipynb keeps the same overall workflow, but it has been modified to be more restart-friendly.

Important differences in the copy:

• smaller local Dask settings to reduce RAM pressure
• extraction progress is checkpointed to Shapefiles/VEDU_ref_checkpoint.csv
• the full extracted table is written to Shapefiles/VEDU_ref.csv
• model tuning and evaluation results are cached in Models
• trained models are saved under Models/trained_models
• later steps try to reuse cached outputs instead of recomputing them
• some plotting/modeling cells now skip gracefully when an upstream result is empty instead of crashing immediately

Step By Step

1. Load Presence And Absence Data

The notebook reads:

• presence points from VEDU_pres/VEDU_pres.shp, filtered to NRCS_PLANT == "VEDU" and NAME == "MISSOULA", and labeled presence = 1
• absence points from Shapefiles/VEDU_abs.shp, which already carry presence = 0

These are points, not polygons. Current counts:

• 536 presence points (presence = 1)
• 1,624 absence points (presence = 0)
• 2,160 points total (roughly a 3:1 absence:presence imbalance, which is why the classifiers use class_weight="balanced")

Both classes are used together. This is a binary classification problem and presence is the target column: the absence points are the negative class the model learns to distinguish VEDU against. They are not auxiliary — without them there is no "not-VEDU" to contrast.

The notebook reprojects both to EPSG:5070, concatenates them into one table, and assigns each point to a bounding box for imagery lookup.

2. Search For NASA HLS Imagery

For each bounding box, the notebook searches the NASA STAC catalog for HLS scenes (collections HLSS30_2.0 and HLSL30_2.0) in the May 1 – September 30, 2023 window, filtered to eo:cloud_cover < 20.

Bands pulled from each HLS scene

The notebook requests seven assets per scene (BANDS). Because Landsat (HLSL30) and Sentinel‑2 (HLSS30) number their bands differently, a BAND_CROSSWALK renames them to a common set:

Model band	~Wavelength	HLSL30 (Landsat 8/9)	HLSS30 (Sentinel‑2)
blue	0.49 µm	B02	B02
green	0.56 µm	B03	B03
red	0.66 µm	B04	B04
nir_narrow	0.86 µm	B05	B8A
swir_1	1.61 µm	B06	B11
swir_2	2.20 µm	B07	B12
Fmask	— (QA)	Fmask	Fmask

The six reflectance bands are scaled (÷10000) and used to compute the vegetation indices (NDVI, EVI, GNDVI, SAVI, reCl, NDWI, OSAVI, SIPI, ARVI, GCI). Fmask is the HLS quality band, not a reflectance band — its bits flag cloud, cloud shadow, and adjacent‑cloud pixels, which are masked out before extraction.

Dates pulled

• Window: May 1 – September 30 (the growing season), filtered to eo:cloud_cover < 20.
  • Cheatgrass copy.ipynb: fixed to 2023.
  • Rebekahs_Model_Revisited: matched to each point's survey year (2023 or 2024).
• HLS harmonizes Sentinel‑2 (HLSS30, ~5‑day revisit) and Landsat 8/9 (HLSL30, ~8‑day) onto a common 30 m grid, so the combined cadence is ~2–4 days; after the < 20% cloud filter you typically keep on the order of ~10–40 usable dates per box across the season.
• With MAX_STAC_ITEMS = None every qualifying scene is kept (the full time series). The exact acquisition dates are recorded in the time column of VEDU_ref.csv. (The original single‑scene run kept only one date per box — all in early May 2023.)

Note on scene count: the copy notebook now sets MAX_STAC_ITEMS = None, so it keeps every low-cloud scene per box across the whole window — the full multi-date time series, matching the original Cheatgrass.ipynb. This is what gives real early/mid/late (ES/MS/LS) coverage so all three seasonal models can train. Set MAX_STAC_ITEMS to an integer to cap scenes per box for a quick/light run.

The cached Shapefiles/VEDU_ref_checkpoint.csv and Shapefiles/VEDU_ref.csv were built under the old single-scene setting and contain only early-May rows. To regenerate a true all-seasons table, delete those two CSVs (or set FORCE_REBUILD_EXTRACTION = True for one run, then set it back to False).

In the copy notebook, this extraction step is resumable:

• completed boxes are inferred from box_id values already written to VEDU_ref_checkpoint.csv
• rerunning the cell continues with the remaining boxes

3. Extract Pixel Values At Survey Points

For each selected HLS item:

• the imagery is loaded
• cloud/shadow masking is applied from Fmask
• the nearest pixel is extracted for each point in the current box
• the results are appended to the checkpoint CSV

This creates the reflectance reference table used for modeling.

4. Build The Modeling Table

The notebook reads VEDU_ref.csv, turns geometry text back into real geometry, and joins the extracted pixels back to the source points.

It then:

• scales reflectance bands
• computes vegetation indices such as NDVI, EVI, GNDVI, SIPI, and GCI
• converts dates into seasonal periods: ES, MS, and LS
• aggregates duplicate observations by geometry and period (median per point per period)
• collapses duplicate pixels and creates a weight column
• one-hot encodes period into period_ES, period_MS, period_LS

Why the seasonal periods? Ventenata is an annual grass that greens up and senesces on a different schedule than the surrounding perennial vegetation, so the spectral contrast that makes it detectable is strongest at particular times of year. Instead of mixing all dates together, the workflow buckets each observation into a phenological window and trains a separate model per window:

• ES (early season): May–June
• MS (mid season): July–August 1
• LS (late season): August 2–September

Each point therefore contributes one aggregated feature row per period it was observed in.

The model-ready table is also cached as Shapefiles/model_ready_result.pkl when that stage is reached.

5. Tune And Evaluate Models

The notebook tunes several classifiers and then evaluates them by seasonal period:

• Random Forest
• Histogram Gradient Boosting
• AdaBoost
• Logistic Regression
• Stacked Ensemble

The copy notebook caches these stages:

• tuning parameters in Models/mod_pars.joblib
• evaluation bundles in Models/eval_all_features.joblib and Models/eval_selected_features.joblib

It also now imputes missing feature values during model fitting, because some classifiers do not accept NaN input directly.

How validation is done

All validation happens inside this training step — there is no separate held-out test set.

• Hyperparameter tuning (tune_models) uses 3-fold RandomizedSearchCV scored on f1_macro.
• Model evaluation (evaluate_models_by_period_dummies) runs 5-fold StratifiedKFold cross-validation, separately for each period and each classifier, recording F1-macro, accuracy, balanced accuracy, AUC, and log-loss per fold. It then refits each model on all rows for that period and saves it.

This is row-level cross-validation, not a spatial or temporal hold-out. Because ground points are spatially autocorrelated (and many share the same imagery), train and validation folds can contain very similar samples, so the reported metrics are likely optimistic relative to true field generalization.

What actually got trained and the results

The cached run below was produced under the old single-scene extraction, so it only had early-season imagery: only the ES model was trained and validated. MS and LS had no rows and were skipped — this is why Models/trained_models currently contains only an ES/ folder. After re-extracting with MAX_STAC_ITEMS = None (see Step 2), MS and LS will have rows and the per-period loop in cell 48 will train and save those models automatically.

Early-season (ES) 5-fold cross-validation, all features:

Classifier	F1 macro	Accuracy	Balanced accuracy	AUC
Random Forest	0.828	0.880	0.842	~0.93
Histogram Gradient Boosting	0.807	0.876	0.793	~0.92
AdaBoost	0.792	0.871	0.772	~0.91
Stacked Ensemble	0.804	0.850	0.854	~0.90
Logistic Regression	0.577	0.629	0.651	~0.69

Random Forest is the strongest early-season model. These numbers are higher than the PlanetScope run below (F1 ~0.57–0.65), but they come from a single early-season snapshot and non-spatial CV, so treat them as optimistic.

Input data summary (HLS)

• 2,160 input points (536 presence + 1,624 absence) → 2,111 extracted reflectance rows across 74 boxes
• Dates pulled: search window May 1 – Sep 30, 2023; in practice 6 sampling days, all in early May 2023 (MAX_STAC_ITEMS = 1)
• Features: 6 HLS bands (red, green, blue, nir_narrow, swir_1, swir_2) + vegetation indices (ndvi, evi, gndvi, savi, recl, ndwi, osavi, sipi, arvi, gci) + period dummies
• Target: presence (1 = VEDU, 0 = absence)

6. Save Trained Models

Per-period trained models are written under:

• Models/trained_models/ES
• Models/trained_models/MS
• Models/trained_models/LS

This lets later prediction cells reuse saved models instead of retraining every time.

7. Build Seasonal Composites And Predict Over Raster Imagery

The final section:

• loads HLS imagery for a larger prediction extent
• applies land-cover masking
• builds seasonal composites
• loads trained models
• predicts class probabilities across the raster

What "builds seasonal composites" means here: this is the raster-side equivalent of the seasonal periods used in training. seasonal_composites takes the full stack of HLS scenes over the season, tags each scene ES/MS/LS with assign_period, then computes a per-pixel median across all scenes within each window (groupby("period").median(...)). The result is one cloud-reduced median image per period; the median across multiple dates fills cloud gaps and suppresses noise. Each per-period model then predicts on its matching composite. (With the current early-season-only training, only the ES composite has a model to apply.)

These steps depend on additional raster inputs, especially:

• Shapefiles/MSO_LC_Mask.tif

If that file is missing, the copy notebook now skips the masking/prediction section instead of failing immediately.

Practical Guidance

• Use Cheatgrass.ipynb as the untouched reference.
• Use Cheatgrass copy.ipynb for actual local runs.
• If a long extraction run stalls, restart the kernel and rerun the copy notebook. It should resume from VEDU_ref_checkpoint.csv.
• If you want to rebuild the point-based dependencies, use Create_Depend_for_Rebekahs_VEDU_Model.ipynb.

Key Outputs

• Shapefiles/VEDU_abs.shp: point-based absence dependency
• Shapefiles/VEDU_ref_checkpoint.csv: resumable extraction checkpoint
• Shapefiles/VEDU_ref.csv: extracted point-by-date reflectance table
• Models/mod_pars.joblib: cached tuning results
• Models/trained_models: saved trained models

PlanetScope Workflow

There is now a separate PlanetScope workflow under Using_Planetscope.

The PlanetScope workflow is split into three notebooks:

• Using_Planetscope/Planetscope_Imagery_Prep_for_Rebekahs_Vedu_Model.ipynb: prepares PlanetScope imagery samples and creates the extracted reference table
• Using_Planetscope/Cheatgrass_copy_planet.ipynb: trains and evaluates the PlanetScope VEDU models
• Using_Planetscope/Cheatgrass_copy_predict_planet.ipynb: predicts over raster imagery from the saved PlanetScope models, following the same overall role as Cheatgrass_copy_predict.ipynb

The copied PlanetScope imagery under /home/rusty/Documents/Planet Scope/PlanetScope/Mission Valley appears to contain Git LFS pointer files rather than full readable rasters. The readable Mission Valley PlanetScope GeoTIFFs were found on the external drive at:

/media/rusty/FEA2-3F09/Imagery/Planetscope_Imagery/Mission Valley

Processed outputs are still written inside this project under Using_Planetscope.

The useful PlanetScope training run uses the merge2324 label source from:

/home/rusty/Documents/Planet Scope/PlanetScope_VEDU/Ventenata_Files/merge2324.shp

The earlier PlanetScope attempt that reused the old HLS point labels found only absence samples inside the PlanetScope footprint, so the merge2324 run is the one to trust.

Full PlanetScope run notes, paths, exact validation metrics, confusion counts, and caveats are saved in Using_Planetscope/PLANETSCOPE_MODEL_RUN_LOG.md.

Short version of the last useful PlanetScope validation run:

Season	Best selected-feature model	F1 macro	Balanced accuracy	AUC	Accuracy
Early season (ES)	Random Forest	0.574	0.573	0.639	0.606
Mid season (MS)	Histogram Gradient Boosting	0.651	0.646	0.726	0.706
Late season (LS)	AdaBoost	0.568	0.571	0.645	0.637

The PlanetScope model trained successfully and saved models, but its validation performance is moderate. Mid-season imagery performed best. Early- and late-season results are better than random, but not strong. These metrics come from 5-fold row-level cross-validation, not a clean spatial holdout, so they may be somewhat optimistic where nearby samples are similar.

Main PlanetScope model outputs:

• Using_Planetscope/Shapefiles/VEDU_planetscope_merge2324_ref.csv: extracted PlanetScope reference table
• Using_Planetscope/Shapefiles/model_ready_planetscope_merge2324_result.pkl: model-ready PlanetScope table
• Using_Planetscope/Models/planetscope_merge2324_eval_selected_features.joblib: selected-feature validation results
• Using_Planetscope/Models/trained_models_merge2324: saved trained PlanetScope models
• Using_Planetscope/Predictions: saved PlanetScope probability rasters and PNG quicklooks

Current Caveat

The copy notebook is much safer than the original for restart/resume, but the NASA imagery load can still hang on remote I/O. The checkpointing is there so that a restart does not throw away finished boxes.