Annotation Engine#

Overview#

App features#

With the Annotation Engine App, you can

Annotate movement data with environmental variables from gridded environmental datasets.
Load movement data and environmental data from supported formats such as NetCDF and GeoTIFF.
Select environmental variables for annotation.
Match movement records with environmental values by location and time.
Use different annotation approaches for continuous variables and categorical or quality-control variables.
Apply spatial and temporal matching or interpolation methods where supported.
Optionally apply scale factor and offset corrections to continuous variables.
Export annotated movement data for further analysis or visualization.

Using the app#

If you haven’t already, prepare a local movement data file and the environmental datasets you want to use for annotation.
Launch the Annotation Engine App.
Select the movement data file. The file should contain location and time information compatible with the ECODATA movement data format.
Load the environmental dataset or datasets. Depending on the workflow, these may be NetCDF or GeoTIFF files.
Select the environmental variables that should be added to the movement records.
Specify whether selected variables should be treated as continuous variables or categorical / quality-control variables.
Select the annotation method and, if available, the spatial or temporal interpolation options.
If using continuous variables with scale factor or offset values, set these options before running the annotation.
Run the annotation process.
Review the status messages and save the annotated movement data file.

Annotation Engine App Manual#

The Annotation Engine App contains four working tabs: Annotation engine - .nc, Annotation engine - .tif, Crop & interpolate csv, and Merge csv. The first two tabs annotate Movebank-style movement data with environmental variables. Crop & interpolate csv prepares movement CSV files before annotation. Merge csv merges CSV outputs into one file.

Tab #1: Annotation engine - .nc#

View of the user interface: Annotation engine - .nc tab.

Purpose#

The Annotation engine - .nc tab annotates animal movement tracks from a Movebank-style CSV file using environmental variables from one NetCDF (.nc) file. Each movement point is matched by timestamp, latitude, and longitude to selected environmental variables.

The current version supports separate handling of continuous variables and categorical/QC variables. Continuous variables can be interpolated, while categorical flags, quality-control layers, land-cover classes, and similar data remains as raw codes.

Spatial filtering by an optional vector boundary (.shp or .geojson).
Automatic boundary from the NetCDF extent if no vector boundary is selected.
Manual selection of the Time, Latitude, and Longitude coordinate variables from the NetCDF file.
Support for 3D variables with dimensions such as time/lat/lon and for common vertical level dimensions. If a variable contains pressure/vertical levels, the app exposes labels such as variable_1000, variable_975, etc.
Saving one main annotated CSV and separate per-individual CSV files.

Overview#

Step 1. Load environmental data (.nc)#

Select one NetCDF file in the Environmental data (.nc) selector.
Press Load environmental data.
The app reads the file name, time range, spatial range, available variables, and candidate coordinate variables.
Check the Time variable, Latitude variable, and Longitude variable selectors. Adjust them manually if the automatic choice is not correct.
Choose environmental variables in the Continuous selector and/or in the Categorical/QC selector. The same variable cannot be used as both continuous and categorical/QC.

Annotation engine - .nc tab after environmental data, movement data, and boundary data are loaded.

Step 2. Load movement data (.csv)#

Select a Movebank-style CSV file in the Movebank data (.csv) selector.
Press Load movement data.
The app extracts taxon names, individual IDs, the movement time range, and the movement spatial range.
Optionally filter by Select Taxon, then select one or more IDs in Select ID.

Step 2a. Configure annotation options#

Bottom/control part of the Annotation engine - .nc tab.

Option	Meaning in the current app
Continuous variables	Numeric environmental variables that may be spatially interpolated and linearly interpolated in time.
Categorical/QC variables	Class, flag, mask, quality control, land cover or similar variables that are sampled by nearest spatial grid cell and nearest available timestep.
Time / Latitude / Longitude variable	NetCDF coordinate mapping used to standardize the dataset before annotation (some files might use names such as `valid_time`, `y`, `x`, `latitude`, or `longitude`).
Interpolation method (spatial)	Nearest neighbor or Inverse Distance Weighting (IDW). The selected method applies to continuous variables. Categorical/QC variables always use nearest-neighbor logic.
Number of nearest grid points	Used for IDW. Available values are 2, 4, 6, and 8. For Nearest neighbor, the value is forced to 1 internally.
Output path	Path to the main annotated CSV. The default is in the user Downloads folder.

Interpolation behavior#

Variable type	Nearest neighbor selected	IDW selected
Continuous	Nearest spatial grid cell + linear interpolation in time.	k nearest spatial grid cells + linear interpolation in time for each grid cell + IDW spatial weighting.
Categorical/QC	Nearest spatial grid cell + nearest available timestep.	Still uses nearest spatial grid cell + nearest available timestep. It is not IDW-averaged and not linearly interpolated in time.

Step 3. Load boundary data (optional)#

Select a .shp or .geojson boundary in the Boundary data (.shp/.geojson) selector.
Press Load boundary data.
The app displays the boundary file name and spatial range.
If no boundary is selected, the NetCDF spatial extent is used automatically during annotation.
Use (!) Reset boundary to return to the automatic NetCDF boundary.

Step 4. Run annotation#

Press Make annotated file in the 4. Start annotation block.
The app filters movement records by selected ID(s).
The app applies the selected boundary. If no boundary is loaded, it uses the NetCDF extent.
The app prefilters movement points to the union time window of the selected NetCDF variables.
The app annotates each point with the selected continuous and categorical/QC variables using the rules described above.
The app saves the main CSV to Output path and creates an annotated_individuals folder next to it.

Output scenarios#

Boundary not loaded: automatic boundary from the NetCDF extent is used.
Boundary loaded: only movement points inside the polygon are kept.
Continuous + Nearest neighbour.
Continuous + IDW.
Categorical/QC variables: nearest spatial cell and nearest timestep, regardless of the selected interpolation method for continuous variables.
Movement points outside the NetCDF spatial or temporal coverage are removed by filtering.

Expected results#

Main annotated CSV saved to the selected Output path.
A subfolder named annotated_individuals containing one annotated CSV per individual ID, if the individual ID column is available.