Collar Voltage Report — User Guide

This guide walks you through configuring and running the Collar Voltage Report workflow (internal id source_voltage), which pulls GPS relocations and their embedded battery/collar-voltage telemetry from EarthRanger for a named subject group, compares the current period against a configurable previous period, and produces a per-subject historic voltage chart plus a merged Word doc report.

Overview

For each subject in the selected group, the workflow delivers:

• A historic voltage chart — the subject’s current-period voltage plotted against a min/mean/max band derived from the previous period (falls back to the current period’s own band when no previous-period data is available)
• 2 combined GeoParquet exports — all subjects’ current-period and previous-period relocations, each with an extracted voltage column
• A dashboard widget — one merged “Collar Voltage” map/plot widget per subject group run
• A Word doc report (overall_report.docx) — cover page (with organisation logo, prepared-by, and report period) plus every subject’s historic voltage chart, generated from a downloadable template

Prerequisites

Before running the workflow, ensure you have:

• Access to an EarthRanger instance with subject group observations whose observation_details include a battery/voltage field — the workflow looks for battery, mainVoltage, batt, or power (in that order) and uses whichever is present
• (Optional) An organisation logo file (PNG or JPG) to display on the Word report’s cover page — only needed if you enable the Word doc report

Step-by-Step Configuration

Step 1 — Add the Workflow Template

In the workflow runner, go to Workflow Templates and click Add Workflow Template. Paste the GitHub repository URL into the Github Link field:

https://github.com/wildlife-dynamics/wt-source-voltage.git

Then click Add Template.

Step 2 — Configure an EarthRanger Connection

Navigate to Data Sources and click Connect, then select EarthRanger. Fill in the connection form:

• 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.

Click Connect to save.

Step 3 — Select the Workflow

After the template is added, it appears in the Workflow Templates list. Click it to open the workflow configuration form.

The card may show Initializing… briefly while the environment is set up.

Step 4 — Set Workflow Details and Time Range

The configuration form opens with two sections at the top.

Set Workflow Details

Time Range

Grouping is fixed to Subject Name — there is no grouping choice to make.

Step 5 — Connect to EarthRanger and Set Subject Group

Connect to EarthRanger

Select the EarthRanger data source configured in Step 2 from the Data Source dropdown.

Subject Group

Enter the name of the EarthRanger subject group to analyse in the Subject Group Name field (default: Elephants). Each subject in the group is processed individually.

Step 6 — Configure the Previous Period

Previous Period

Every option below computes a comparison period that ends on the same Start Date as your current time range (so the two periods never overlap) — only the comparison period’s own Start Date changes:

The previous period’s relocations are used solely to compute the historic min/mean/max voltage band; if no previous-period data is found, the band collapses to the current period’s own values.

Step 7 — Configure the Word Doc Report

Generate Word Doc Report

Once all parameters are set, click Submit.

Running the Workflow

Once submitted, the runner will:

1. Fetch subject group observations from EarthRanger for the current time range, convert fixtime to the analysis timezone, and derive relocations (dropping points at (180,90), (0,0), and (1,1)).
2. Fetch subject group observations for the computed previous period and process them the same way.
3. Sort both current and previous relocations by fixtime and persist each as GeoParquet (relocations.parquet, previous_period_relocations.parquet).
4. Extract a voltage column from each relocation set’s observation_details JSON, checking the battery, mainVoltage, batt, and power fields in order.
5. Split both relocation sets by subject name and pair each subject’s current and previous slices together.
6. Plot each subject’s historic voltage chart — current-period voltage against the previous period’s min/mean/max band (widened slightly if the band collapses to a single value; falls back to the current period alone when no previous-period data exists).
7. Build each chart’s filename from a safe-string version of the subject’s name (<subject>_historic_voltage.html), persist the chart HTML, and convert it to PNG.
8. Assemble a “Collar Voltage” map widget per subject and merge them into a single dashboard widget.
9. Download the Word report template and, if provided, the organisation logo.
10. Generate the merged Word doc report (overall_report.docx) — cover page (logo, prepared-by, report period) plus every subject’s historic voltage chart.
11. Assemble the interactive dashboard and save all outputs to the directory specified by ECOSCOPE_WORKFLOWS_RESULTS.

Output Files

All outputs are written to $ECOSCOPE_WORKFLOWS_RESULTS/. Files marked with <subject> are produced once per subject in the group.

Per-subject outputs

Combined outputs