Quickstart

This page walks through the most common ways to use groundtrack. For a deeper explanation of what each step does, see Concepts.

Minimal Run

The simplest call downloads waveform data for a re-entry event without any processing:

from groundtrack import run_pipeline

results = run_pipeline(
    norad_id=56873,
    start="2024-04-02T08:40:00Z",
    end="2024-04-02T09:00:00Z",
    cache_dir="data/cache",
    output_dir="data/outputs",
    event_name="shenzhou15_reentry",
)

This runs the full pipeline — fetching the TLE, propagating the ground track, tiling it into download boxes, querying FDSN providers for nearby stations, and downloading the raw waveforms. Everything gets written to data/outputs/shenzhou15_reentry/.

The results dictionary contains:

results["track"] — the propagated ground track and TLE metadata
results["boxes"] — the list of BoxWindow objects that were used
results["manifest"] — a record of what was downloaded and where

With Processing

Pass apply_processing=True to also remove instrument response and apply a bandpass filter after downloading:

results = run_pipeline(
    norad_id=56873,
    start="2024-04-02T08:40:00Z",
    end="2024-04-02T09:00:00Z",
    cache_dir="data/cache",
    output_dir="data/outputs",
    event_name="shenzhou15_reentry",
    apply_processing=True,
    freqmin=1.0,
    freqmax=20.0,
)

The default processing chain is: demean → detrend → 5% cosine taper → instrument response removal (output in velocity, m/s) → 1–20 Hz bandpass. All parameters are configurable — see pipeline for the full list.

Two-Step Workflow

If you want to download once and experiment with different processing parameters without re-downloading, use the two-step workflow:

from groundtrack import run_pipeline, process_boxes

# Step 1 — download only
results = run_pipeline(
    norad_id=56873,
    start="2024-04-02T08:40:00Z",
    end="2024-04-02T09:00:00Z",
    cache_dir="data/cache",
    output_dir="data/outputs",
    event_name="shenzhou15_reentry",
)

# Step 2 — process with custom parameters
process_boxes(
    boxes_root=results["manifest"]["boxes_root"],
    freqmin=1.0,
    freqmax=10.0,
)

run_pipeline() is idempotent for the download step — if waveforms already exist for a box, it skips them. This means you can safely re-run it after a partial download or network interruption.

Visualizing Results

groundtrack includes plotting utilities for inspecting what was downloaded and validating the processing. These require the [plotting] extras.

Plot the ground track and download boxes:

from groundtrack import plot_track_and_boxes

plot_track_and_boxes(
    track_points=results["track"]["track_points"],
    box_windows=results["boxes"],
)

Compare raw vs. processed waveforms for a single station:

from groundtrack import plot_waveform_comparison
from pathlib import Path

plot_waveform_comparison(
    boxes_root=Path(results["manifest"]["boxes_root"]),
    network="CI",
    station="SMI",
    t_start_utc="2024-04-02T08:44:00Z",
    t_end_utc="2024-04-02T08:54:00Z",
)

Plot all processed waveforms across every downloaded station:

from groundtrack import plot_all_waveforms
from pathlib import Path

plot_all_waveforms(
    boxes_root=Path(results["manifest"]["boxes_root"]),
    t_start_utc="2024-04-02T08:44:00Z",
    t_end_utc="2024-04-02T08:54:00Z",
)

See plotting for the full plotting API.