PHASE (Persistent scatterer Highly Automated Suite for Environmental monitoring)

PHASE (Persistent scatterer Highly Automated Suite for Environmental monitoring) is a MATLAB-based software suite for automated InSAR Persistent Scatterer Interferometry (PSI) processing and advanced geospatial analysis. Built on the foundation of snap2stamps and StaMPS, PHASE introduces enhanced automation, user-friendly interactive map interfaces, and a powerful geospatial modeling module to interpret and visualize displacement time series, making it ideal for environmental and infrastructure monitoring.

SAR Satellites compatibility

• Sentinel-1 (from European Space Agency)
• COSMO-SkyMed (from Agenzia Spaziale Italiana - automatically supports both CSK and CSG generations)

Required Software

• SNAP (version 9.x is mandatory)
• MATLAB
• StaMPS
• Python 3.x with openpyxl (for geospatial module report generation)

Required OS

• Linux: supported end-to-end, including StaMPS, for the complete PSI pipeline.
• Windows: supported end-to-end for the SNAP-based workflow (preprocessing, StaMPS, and geospatial analysis) via the Windows-native StaMPS fork pyccino/StaMPS. PHASE auto-discovers the StaMPS Windows install through StaMPS_CONFIG.ps1 and shares the Python interpreter with StaMPS via %APPDATA%\PHASE\python.txt.
• macOS: supports preprocessing and geospatial analysis modules.

Installation and Setup

Note

A detailed, step-by-step guide is available in the provided user manual.
Before using PHASE, please carefully read the entire manual!

Preliminary Steps

1. Install SNAP Software
   Download and install SNAP 9.x from the European Space Agency website.
   
   Verify that the following mandatory SNAP plugin module is installed:

   • Sentinel-1 Toolbox
     (Note: Previous versions required multiple toolboxes like Optical or SMOS, but these are no longer needed).
     

   After installing SNAP, it is highly recommended to optimize your memory settings:

   • Edit $HOME/snap/bin/gpt.vmoptions and modify the -Xmx parameter according to your RAM (e.g., -Xmx12G).
   • Edit $HOME/snap/etc/snap.properties and add/verify:
     • #snap.home=
     • #snap.userdir=
     • snap.jai.tileCacheSize = 1024
     • snap.jai.defaultTileSize = 512

2. Install Required Python Modules:
   Install Python 3.x on your machine. Ensure Python is added to your system's PATH. The PHASE suite utilizes standard built-in Python libraries, so you only need to install the external Excel library. Run the following command in your terminal:

   pip install openpyxl
   

3. Install xterm (only Linux Users):
   Install xterm by running sudo apt-get install xterm in the terminal.

4. Install StaMPS:
   Install StaMPS from the official GitHub repository.

   git clone https://github.com/dbekaert/StaMPS/releases/tag/v4.1-beta
   

5. Install PHASE suite

   • Download the latest release of the PHASE suite repository.
   • Move or extract the downloaded folder into your desired project directory.
   • Execute the PHASE_Preprocessing.mlapp MATLAB application.
   • Tune the configurable parameters across the available tabs (including the interactive geographic map for AOI selection).
   • Once the preprocessing is complete, execute the PHASE_StaMPS.mlapp MATLAB application (on Linux, it will open automatically upon completion).
   • For geospatial analysis, run PHASE_model.mlapp to process the final displacement time series.

Processing Steps

Module 1: InSAR PSI Processing

1. Automated SAR Images Download:
   Retrieve Sentinel-1 images via the generated Python script from the Alaska SAR Facility. For COSMO-SkyMed, use the Images tab in the Cosmo-SkyMed panel to import your .h5 files (they are copied into the slaves directory automatically).
2. Interactive AOI & Automated Master Selection:
   Define your precise Area of Interest (AOI) by drawing a bounding box directly on the GUI's geographic map interface. Let PHASE automatically query the Open-Meteo historical weather API to select the optimal, driest master image for your stack.
3. Master & Slave Pre-Processing:
   Automated splitting, precise orbit correction, coregistration, and interferogram formation. For Sentinel-1, optimal swaths and bursts are dynamically calculated from your AOI. Includes StaMPS export, average scene intensity computation, and local incidence angle/coherence calculations.
4. StaMPS Processing:
   Automated data preparation, parameter definition, metadata auto-detection, and StaMPS PS analysis. Includes integration with TRAIN for GACOS tropospheric corrections, exporting displacement time series in Excel format.

Module 2: Geospatial PSI Data Analysis

The geospatial module enhances PHASE by providing advanced interpolation and modeling of PS displacement time series, tailored for Sentinel-1 data but compatible with any SAR data in the same table format. It offers flexible processing options for environmental and infrastructure monitoring, with user-configurable parameters for experts and automated settings for beginners. Key features include:

• Area of Interest (AOI) Definition: Specify the AOI via shapefiles (preferred for arbitrary shapes) or bounding boxes, with automatic detection and transformation of geographic (WGS84) or projected (UTM) coordinates. PS outside the AOI are filtered to focus analysis.
• Geometry Options: Supports 1D modeling for linear features (e.g., roads, railways) using centerline interpolation and 2D modeling for expansive areas (e.g., volcanoes, large infrastructures) using grid-based meshes, with user-defined resolutions.
• Temporal Modeling: Independently interpolates each time series using cubic splines for outlier removal, trend, and periodic component modeling, followed by least-squares collocation for residuals. Optional nearest-neighbor interpolation extends results spatially for visualization.
• Deterministic Spatio-Temporal Modeling: Creates a continuous displacement field using temporal cubic splines for data cleaning and multi-dimensional splines for spatial interpolation, with per-epoch GIF visualizations.
• Stochastic Spatio-Temporal Modeling: Combines deterministic cubic spline-based cleaning with Least Squares Collocation for deformation modeling, incorporating covariance modeling for robust uncertainty estimates.
• Stability Analysis: Evaluates PS stability via a thresholding procedure based on average velocity and cumulative displacement, assigning risk levels using standardized statistical criteria and exponential/linear risk scaling.

The module generates a comprehensive Excel report across multiple sheets:

• General Sheet: Summarizes project metadata (title, date, location, modeling approach), unwrapping parameters, PS statistics, and visualizations (logo, AOI map, PS plot).
• Raw Displacement Sheet: Presents adjusted raw displacement time series with coordinates and a figure of average scene displacement with velocity annotation.
• Modeled Displacement Sheet: Details modeled displacements with average velocity and a geoscatter plot of velocity across the AOI.
• Uncertainty Sheet: Provides uncertainty estimates with a geoscatter plot of time-averaged uncertainty.
• Alerts Sheet: Reports stability analysis with velocity, cumulative displacement, and global risk percentages.
• Interpolation Sheet (Optional): Includes extrapolated time series at user-specified coordinates with individual displacement plots.

A shapefile and .mat file are generated in WGS84 (EPSG:4326) coordinates, including PS data, velocities, uncertainties, and risks for GIS compatibility.

Possible Errors and Solutions

The procedure has been tested on SNAP 9.x and 13.x, Python 2.7, Python 3.11, Python 3.13, Ubuntu 20.04, Windows 10, macOS Sequoia (15.1), and MATLAB 2025a/2026a.

Tip

Refer to the manual for solutions to common errors encountered during the StaMPS processing.

SNAP version selection (Sentinel-1A/1B/1C/1D)

PHASE preprocessing supports both SNAP 9.x (legacy) and SNAP 13.x (recommended). Choose based on which Sentinel-1 satellites your dataset includes:

• SNAP 9.x: supports Sentinel-1A and Sentinel-1B only. Sentinel-1C (launched Dec 2024) and Sentinel-1D are not supported by the SNAP 9 product readers.
• SNAP 13.x: supports the full Sentinel-1A/1B/1C/1D constellation natively. Required for any dataset containing S1C or S1D acquisitions.

Point GPTBIN_PATH in your project.conf to the SNAP version you want PHASE to use:

GPTBIN_PATH = C:/Program Files/snap13/bin/gpt.exe   # SNAP 13 (S1A/B/C/D)
# GPTBIN_PATH = C:/Program Files/snap/bin/gpt.exe   # SNAP 9  (S1A/B only)

Important: do not mix SNAP-9 and SNAP-13 .dim products

SNAP 13's StampsExport operator raises NullPointerException on tie-point grids written by SNAP 9 (the BEAM-DIMAP TPG format changed between majors). The error is silent — StaMPS later hangs mid-PSI without a clear diagnostic.

PHASE's SEN_stamps_export.py automatically detects this mismatch and prints an actionable warning before launching gpt. The fix is to re-run the full preprocessing pipeline (split + coregistration + interferogram) from the original .SAFE.zip files using the same SNAP version that will run StampsExport.

SRTM 3Sec auto-cache

StampsExport has SRTM 3Sec hardcoded for the lat/lon geocoding output, regardless of the DEM chosen for coregistration. When the auto-download fails (offline, mirror down, or — on SNAP 13 — silently for some inputs), the geo files are partially corrupted and StaMPS hangs mid-PSI. PHASE pre-caches the required SRTM tiles into %USERPROFILE%/.snap/auxdata/dem/SRTM 3Sec/ automatically before each StampsExport run, eliminating that failure mode.

This requires the project AOI to be present in project.conf as LATMIN, LATMAX, LONMIN, LONMAX. If the keys are absent the pre-cache is skipped (with a warning) and StampsExport falls back to the standard SNAP auto-download path.

Verifying TRAIN on Windows

After the TRAIN Windows port, verify your install with these three checks.

1. Degradation path (TRAIN missing)

1. Open MATLAB. Run which('aps_linear'). Expected: empty string.
2. Launch PHASE_StaMPS.mlapp. Tick "TRAIN atmospheric correction". Press Save, then Start.
3. Expected:
   • Warning id StaMPS:phase:trainNotAvailable in diary / smoketest.log.
   • The TRAIN checkbox STAYS TICKED (intentional — preserves intent for re-run).
   • Processing continues through STEP 1 → STEP 2 → export.
   • Output contains no Atmosphere_* columns.
   • Exit code 0.

2. Linear correction (a_linear)

1. Install TRAIN (Windows-patched fork): git clone https://github.com/pyccino/TRAIN.git C:/TRAIN.
2. In MATLAB: addpath(genpath('C:/TRAIN/matlab')); savepath.
3. Verify: which('aps_linear') returns C:\TRAIN\matlab\aps_linear.m.
4. Launch PHASE_StaMPS.mlapp. Tick TRAIN. Set tropo_method='a_linear'. Save, Start.
5. Expected:
   • No degradation warning.
   • aps_linear runs (console output contains "loading the data").
   • Output contains Atmosphere_a_linear_AOI_PS.mat and Atmosphere_a_linear_*.csv.
   • Velocity values differ from a run with TRAIN unchecked.

Note on the Windows fork. pyccino/TRAIN (default branch main) is forked from dbekaert/TRAIN at the audited commit 6c93feb plus the following Windows-specific additions:

• get_gmt_version.m: actionable error on Windows when GMT is not on PATH (the upstream loop manipulates Linux-only library env vars).
• aps_gacos_files.m: replaces Unix & background launch with synchronous system() call on Windows (cmd.exe parses & differently).
• gacosDownloadDialog.m: new helper that shows the GACOS request parameters in a copy-paste dialog (called from PHASE_StaMPS.mlapp).

Unix/Mac behavior is unchanged. Use upstream dbekaert/TRAIN directly on Linux/macOS if preferred.

3. GACOS correction (a_gacos) — optional, requires gacos.net data request

1. Same TRAIN install as above. Additionally install GMT for Windows and ensure C:\Program Files\GMT\bin (or your install dir) is on PATH; verify with gmt --version in a fresh terminal.
2. Launch PHASE_StaMPS.mlapp. Tick TRAIN. Set tropo_method='a_gacos'. Save, Start.
3. Expected:
   • A "Download GACOS maps" window opens (the gacos.net site and the GACOS/ folder open automatically). It shows the request parameters (UTC, bounding box, dates) ready to copy into the form at gacos.net — select Binary grid as the file type.
   • Download the .tar.gz files from gacos.net, place them in GACOS/ (do not extract), then press Continue in the window.
   • MATLAB extracts/distributes .ztd files.
   • Output contains Atmosphere_a_gacos_AOI_PS.mat and Atmosphere_a_gacos_*.csv.

Updates

• April 2026: Added interactive geographic map GUI for automatic AOI sub-setting. Introduced meteorologically-aware master image selection using Open-Meteo API. Automated parameter metadata detection for StaMPS. Dropped legacy Python 2.7 support.
• March 2026: Introduced Module 2 for geospatial PSI data analysis with deterministic and stochastic modeling.
• September 2024: Added macOS compatibility to the preprocessing application and improved master error handling.

Planned updates

• Improve border constraints based on user selection.
• Introduce the handling of jumps in the displacement models.
• Introduce the possibility for a NRT processing.
• Native integration of Alaska Vertex API for direct Sentinel-1 image downloads.

Acknowledgments

Special thanks to Jose Manuel Delgado Blasco and Dr. Michael Foumelis for the snap2stamps¹ tool, and Prof. Andy Hooper for the StaMPS² development.

When using this software, please refer to:
Monti, R., & Rossi, L. (2025). PHASE: a Matlab-based software for the DInSAR PS processing. Geodesy and Cartography, 51(2), 88–99. https://doi.org/10.3846/gac.2025.21995

Footnotes

1. Foumelis, M., Delgado Blasco, J. M., Desnos, Y. L., Engdahl, M., Fernández, D., Veci, L. Lu, J. and Wong, C. “SNAP - StaMPS Integrated processing for Sentinel-1 Persistent Scatterer Interferometry”. In Geoscience and Remote Sensing Symposium (IGARSS), 2018 IEEE International, IEEE.
   ↩

2. Hooper, A., A multi-temporal InSAR method incorporating both persistent scatterer and small baseline approaches, Geophys. Res. Lett., 35, L16,302, doi:10.1029/2008GL03465, 2008. ↩