risenyard/egms-qa-encoder

EGMS-QA Encoder

The encoder maps persistent-scatterer displacement histories within a 7 km tile to 256-dimensional point representations. Spatial pooling produces 65 EGMS tokens, comprising one tile-summary token and 64 spatial-cell tokens. The pretrained encoder remains frozen during translator training.

Code · Dataset · Translator

Quick start

Install the code and extract tokens from the released Dataset:

git clone https://github.com/risenyard/egms-qa
cd egms-qa
pip install -e .
python -m egms_encoder.extract_tokens \
    --encoder-repo risenyard/egms-qa-encoder \
    --dataset-repo risenyard/egms-qa-dataset \
    --output-dir outputs/tokens

The command downloads the required artifacts into the HF cache and records their resolved revisions. The full collection produces outputs/tokens/egms_tokens_10k.pt with shape [10000,65,256], validity masks, and tile identifiers. Add --max-tiles 1 for a small check. GPU execution is recommended for the full collection. The Dataset also includes a precomputed token cache for translator use.

Input requirements

input or output	contract
tile displacement	vertical displacement in mm, [N,294]
coordinates	EPSG:3035 easting and northing in meters, [N,2]
model preprocessing	checkpoint normalization and centered coordinates
point representations	[N,256]
pooled tokens	[65,256] and a 65-element validity mask

The Dataset stores [0,294), corresponding to [8,302) on the 304-step source-preparation axis. Its data config retains the source offset and six-day cadence for physical-time calculations.

A new NPZ collection must match the displacement component, units, temporal sampling, preprocessing, and coordinate geometry. Keep this checkpoint's normalization when applying the frozen encoder, and validate performance on new distributions. For a new encoder trained on another corpus, fit normalization on that corpus's training split and retain it with the new checkpoint. Local input flags are documented in the Encoder guide.

Reproduce training

After the code installation above, install the Dataset and obtain the model configuration and training recipe:

hf download risenyard/egms-qa-dataset --repo-type dataset \
    --local-dir release/egms-qa-dataset
python -m egms_encoder.install_data \
    --release-dir release/egms-qa-dataset --target-root .
hf download risenyard/egms-qa-encoder --include '*.json' \
    --local-dir data/encoder/checkpoint
python -m egms_encoder.pretrain \
    --output-dir outputs/my_encoder --device cuda:0

Training reads config.json, training_args.json, and the train-fitted normalization.json from data/encoder/checkpoint/. These files specify the architecture, masking, sampling, loss, optimization, and validation settings. The output includes best.safetensors for inference, latest.pt for resuming, and the matching configuration and normalization files. The Encoder guide provides resume and token-extraction commands for the trained model.

Checkpoint selection uses validation loss. Numerical reproduction depends on the software, hardware, and random state.

Evaluation

Evaluation covers 1,000 held-out tiles with 2,047,451 point histories. A central 88-step interval, approximately 30% of the 294-step input, is masked at the same positions for every point in a tile.

metric	value
normalized MSE	0.0702
MSE	2.279 mm²
RMSE	1.510 mm
MAE	1.007 mm
pooled EGMS residual	1.433 mm
per-point RMSE P10 / P50 / P90	0.54 / 1.03 / 2.43 mm

These values describe reconstruction of held-out observations under the specified masking protocol.

Files

file	purpose
encoder.safetensors	encoder weights
config.json	model architecture and input dimensions
normalization.json	input mean, standard deviation, and residual scale
training_args.json	training recipe and checkpoint-selection record
eval_results.json	masked-reconstruction metrics

Inference requires the weights, model config, and normalization. The Dataset repository provides the measurements and split manifest.

Scope and license

The encoder consumes prepared EGMS-QA tiles. Official-product downloading, format conversion, and preparation of another reference period require a separate workflow. Its outputs describe observed deformation and do not establish causes, predict future motion, or certify structural safety.

The encoder is released under CC-BY-4.0.