Track2Health

Track2Health is a ready-to-run GPS analysis tool for livestock research. Give it a CSV file, a folder of CSV files, or a ZIP archive and it will clean the GPS records, download satellite imagery, calculate movement and social-network features, and produce a relative follow-up ranking.

The ranking is a research screening aid, not a clinical diagnosis.

Files

• main.py: command-line entry point and pipeline orchestration.
• track2health/__init__.py: package version.
• track2health/gps.py: GPS input, timestamp parsing, quality control, and projection.
• track2health/movement.py: trajectory segmentation and movement metrics.
• track2health/social.py: proximity networks, isolation metrics, and follow-up ranking.
• track2health/shelter.py: shelter geometry and TSI calculations.
• track2health/imagery.py: satellite-image requests and metadata.
• track2health/outputs.py: CSV, GeoJSON, report, and demo-data output.
• README.md: quick-start and input/output notes.

Quick start

Python 3.10 or later is required. No third-party Python packages are needed.

python main.py GPS.csv

Results are written to track2health_output. The input may also be a directory or ZIP archive containing CSV files.

Use the built-in example without internet access:

python main.py --demo --skip-imagery

GPS input

Each CSV needs an animal ID, timestamp, latitude, and longitude. Common column names such as animal_id, timestamp, latitude, and longitude are detected automatically. A group or farm column is optional. Run python main.py --help to set non-standard column names and analysis thresholds.

Optional shelter analysis

Provide a reviewed WGS84 Polygon or MultiPolygon GeoJSON to calculate observed shelter use and trajectory shelter interpolation (TSI):

python main.py GPS.csv --shelter-geojson shelter.geojson

Satellite imagery is contextual only; the program does not guess shelter boundaries from image colours.

Main outputs

• cleaned_gps.csv: quality-controlled GPS fixes.
• animal_metrics.csv: movement, shelter, and follow-up metrics by animal.
• daily_movement_metrics.csv: daily movement features.
• daily_social_metrics.csv: daily network and isolation features.
• proximity_edges.csv: pairwise proximity-network edges.
• trajectories.geojson: cleaned trajectory segments.
• imagery/: satellite images and request metadata.
• REPORT.md and run_summary.json: readable and machine-readable summaries.

Satellite imagery and privacy

By default, one image per group is requested from Esri World Imagery. This sends each group's GPS bounding box to Esri. Use --skip-imagery if the GPS locations are sensitive or the computer is offline. Imagery attribution: Esri, Maxar, Earthstar Geographics, and the GIS User Community.