STE General Workflow — User Guide
This guide walks you through loading, configuring, and running the STE General Workflow, which generates a comprehensive elephant movement analysis report for Save the Elephants sourced from EarthRanger and Google Earth Engine.
What it produces
The workflow processes GPS observations for a chosen subject group and produces a full suite of spatial, temporal, and ecological analyses:
- Movement maps — Movement Tracks Map (current + previous period overlay), Subject Tracks Map (coloured per individual subject)
- Home range maps — Overall Home Range (ETD 50–99.9%), Filtered Home Range (99th percentile), Protected Areas Home Range, Unprotected Areas Home Range, Seasonal Home Range (per subject)
- Habitat use maps — Recursion Events Raster, Dry Season Mean Speed Raster, Wet Season Mean Speed Raster
- Activity maps — Time of Day Dominance Map, Night Fixes Map
- Event maps — Elephant Sightings / Collaring Events Map
- Charts & tables — Protection Status Bar Chart, Seasonal Windows CSV
- Reports — Word document report (cover page + general section), interactive dashboard
Requirements
- Access to an EarthRanger instance containing the subject group to analyse
- Access to a Google Earth Engine service account (for NDVI-based seasonal window detection and satellite base layers)
- No separate landDx file is needed to get started — the workflow downloads the standard LandDx protected-areas layer automatically for the default Map Overlay option
1. Load the Workflow
In the workflow runner, go to Workflow Templates and click Add Workflow Template. Paste this repository's URL into the Github Link field, then click Add Template:
https://github.com/wildlife-dynamics/ste-general.gitOnce added, it appears in the Workflow Templates list as ste_general. Click it to open the workflow configuration form (the card may show Initializing… briefly while the environment is set up).
2. Configure the Workflow
You'll be prompted to fill in the following parameters before running.
Data Source Connections
Navigate to Data Sources and click Connect. A dialog will prompt you to Select Data Source Type. This workflow requires two connections:
| Data Source Type | Purpose |
|---|---|
| EarthRanger | Pull subject observations and collaring events |
| Google Earth Engine | Fetch satellite imagery and compute NDVI-based seasonal windows |
EarthRanger connection — select EarthRanger, then fill in:
- Data Source Name — a label to identify this connection
- EarthRanger URL — your instance URL (e.g.
your-site.pamdas.org) - EarthRanger Username and EarthRanger Password
Credentials are not validated at setup time — any authentication errors will appear when the workflow runs.
Google Earth Engine connection — select Google Earth Engine, then fill in:
- Data Source Name — a label to identify this connection
- Private Key — click Browse to select your GEE service account private key file (JSON format)
To generate a private key, follow the instructions in the Setup Guide. The key is stored encrypted and used only to authenticate with Google Earth Engine.
Once both connections exist, select them from the Connect to earth ranger and Connect to earth engine dropdowns in the workflow form.
Workflow Details
| Field | Description |
|---|---|
| Workflow Name | A short name to identify this run |
| Workflow Description | Optional notes (e.g. date range or subject group) |
Basemap Layers
The Configure basemap layers step sets the two stacked background tile layers shared by all maps. Pre-filled with sensible defaults, but the URL, opacity, and max zoom of each layer are editable.
| Layer | Default Opacity | Max Zoom |
|---|---|---|
| ESRI World Hillshade | 0.995 | 20 |
| ESRI World Boundaries & Places | 0.35 | 20 |
Analysis Time Range
| Field | Description |
|---|---|
| Timezone | Select the local timezone (e.g. Africa/Nairobi UTC+03:00) |
| Since | Start date and time of the analysis period |
| Until | End date and time of the analysis period |
All subject tracks, home ranges, and activity maps are computed within this window.
Previous Period Range
This period drives the "Previous tracks" layer on the Movement Tracks Map, enabling direct before-and-after comparison alongside the current period tracks. Every mode computes a comparison period that ends on your time range's Start Date, then works backward to determine its own Start Date.
| Offset Mode | Default | Description |
|---|---|---|
| Preset | 1 month back | A common lookback: Same as current period, 1 month back, 3 months back, 6 months back, or 1 year back |
| Calendar | — | Pick an exact Start Date for the comparison period |
| Custom | Years 0, Months 1, Weeks 0, Days 0 | Manually set how far back the comparison period's Start Date should be |
Subject Group
| Field | Default | Description |
|---|---|---|
| Subject Group Name | Elephants | Name of the subject group to pull from EarthRanger (case-sensitive) |
Map Overlay
Choose the overlay layer displayed on every map. This overlay is also used to calculate which GPS fixes fall inside vs. outside protected land, which drives the Protected/Unprotected Home Range maps and the Protection Status Bar Chart. Only protected-area style layers are supported for now.
| Option | When to use | What to provide |
|---|---|---|
| LandDx (Default Protected Areas) — default | Standard use case | Nothing — the workflow automatically downloads and styles the standard LandDx GeoPackage. It is filtered to three area types and coloured as follows: Community Conservancy #a6b697 (sage green), National Reserve #88a78e (muted green), National Park #115631 (dark forest green) |
| EarthRanger Spatial Feature | Your protected areas are maintained as EarthRanger spatial features | One or more layers, each specifying what to load (featureset / type / id) and optional style overrides |
| Custom Local File | You have a local GeoJSON / GeoPackage / GeoParquet file | One or more local files (or split groups within a file), each becoming its own styled layer |
Trajectory Segment Filter
Applied to both the current and previous period trajectories before any analysis. Removes GPS noise and biologically unrealistic movement segments.
| Field | Default | Description |
|---|---|---|
| Minimum Segment Length (m) | 0.001 | Discard segments shorter than this distance |
| Maximum Segment Length (m) | 5000 | Discard segments longer than this distance |
| Minimum Segment Duration (s) | 1 | Discard segments shorter than this duration |
| Maximum Segment Duration (s) | 21600 | Discard segments longer than this duration (6 hours) |
| Minimum Speed (km/h) | 0.01 | Discard segments where average speed falls below this value |
| Maximum Speed (km/h) | 9 | Discard segments where average speed exceeds this value (a sensible ceiling for elephants) |
Map Zoom & Extent
Calculates the geographic extent of the movement tracks and determines an appropriate zoom level and center point, ensuring all tracks are visible and well-framed.
| Field | Default | Description |
|---|---|---|
| Expansion Factor | 1.5 | Factor to expand the bounding box around the tracks (e.g. 1.2 = 20% larger) |
Retrieve All Events
| Field | Default | Description |
|---|---|---|
| Event Types | (empty) | Filter to specific EarthRanger event types (click Add to add entries; leave empty to include all event types) |
| Force Point Geometry | true | If enabled, polygon/multipolygon event geometries are reduced to their centroid; disable to preserve native geometry types |
Report Logo
Optional — provide the logo image to appear on the report cover page. Leave blank to omit a logo.
| Input Method | What to provide |
|---|---|
| Download from URL | Paste the direct download URL into the URL field |
| Use local file | Enter the absolute path to the logo file on the machine running the workflow |
Raster Maps
Configures how the mean speed raster is generated from movement trajectories.
| Field | Default | Description |
|---|---|---|
| Step Length / Grid Size (m) | 2000 | Pixel size (in meters) used to generate the Recursion Events raster and the dry/wet season Mean Speed rasters — one value drives all three. Smaller values are more detailed but slower to generate and produce larger files |
3. Run the Workflow
Once all parameters are configured, click Submit. The runner will:
- Pull subject GPS observations (current and previous period) from EarthRanger.
- Process relocations and apply the trajectory segment filter to both periods.
- Query Google Earth Engine to determine NDVI-derived wet and dry seasonal windows; label each trajectory segment accordingly.
- Load and style the selected Map Overlay layer (LandDx protected areas by default).
- Generate the Movement Tracks Map (current + previous overlay) and the Subject Tracks Map.
- Fetch EarthRanger events and generate the Elephant Sightings map.
- Compute Elliptical Time Density home ranges: overall, filtered 99th percentile, protected/unprotected split, and per-subject seasonal.
- Generate the Recursion Events raster and dry/wet season Mean Speed rasters.
- Compute the Day/Night Dominance grid and Night Fixes grid.
- Render the Protection Status bar chart.
- Assemble the Word report (cover page + general section) and the dashboard.
- Save all outputs to the directory specified by
ECOSCOPE_WORKFLOWS_RESULTS.
Output Files
All outputs are written to $ECOSCOPE_WORKFLOWS_RESULTS/:
| File | Description |
|---|---|
relocations.geoparquet | Current period GPS fix locations with day/night labels |
previous_period_relocations.geoparquet | Previous period GPS fix locations |
trajectories.geoparquet | Current period trajectory segments with season labels |
previous_period_trajectories.geoparquet | Previous period trajectory segments |
homerange_etd.geoparquet | Overall ETD home range polygons (50–99.9th percentiles) |
homerange_protected_etd.geoparquet | ETD home range for fixes inside protected areas |
homerange_unprotected_etd.geoparquet | ETD home range for fixes outside protected areas |
<subject>_seasonal_etd.geoparquet | Seasonal ETD per subject |
seasonal_windows.csv | NDVI-derived wet/dry season date ranges |
weighted_raster.* | Recursion events ecograph raster file |
movement_tracks.html | Interactive movement tracks map (current + previous period) |
subject_tracks.html | Interactive subject tracks map (coloured per individual) |
collared_points.html | Interactive elephant sightings / collaring events map |
overall_homerange.html | Interactive overall home range map |
filtered_homerange.html | Interactive 99th percentile home range map |
protected_areas.html | Interactive protected areas home range map |
unprotected_areas.html | Interactive unprotected areas home range map |
<subject>_seasonal_homerange.html | Interactive seasonal home range map per subject |
recursion_events.html | Interactive recursion events raster map |
dry_mean_speed_raster_map.html | Interactive dry season mean speed raster map |
wet_mean_speed_raster_map.html | Interactive wet season mean speed raster map |
time_of_day_dominance.html | Interactive time of day dominance grid map |
night_fixes.html | Interactive night fixes grid map |
protection_status_bar.html | Interactive protection status bar chart |
*.png (per map above) | 2× resolution screenshot of each interactive map/chart |
general_cover_page.docx | Rendered report cover page (logo, subject count, report period) |
overall_report.docx | Final combined Word report (cover page + general per-subject section) |
Something not working as expected? See Troubleshooting. For a deeper look at the pipeline internals, see the Technical Guide.