PyRate is a Python tool for estimating the average rate (velocity) and incremental time-series of surface movement for every pixel in a stack of images generated by interferometric processing of Synthetic Aperture Radar (InSAR) data. It has been designed to use GAMMA or ROI_PAC format geocoded unwrapped interferograms.
PyRate is a partial Python translation of Pirate, a Matlab tool developed by the University of Leeds and the Guangdong University of Technology.
Home Page: https://github.com/GeoscienceAustralia/PyRate
Documentation: http://geoscienceaustralia.github.io/PyRate
Issue tracking: https://github.com/GeoscienceAustralia/PyRate/issues
Before you start, you will need to have a number of packages installed on your Linux system. These can either be installed directly onto the system, or you can use a virtual environment.
Make sure your system has the following packages installed. If not, run the command:
sudo apt-get install gdal-bin libgdal-dev libpng12-dev libblas-dev liblapack-dev libatlas-dev libatlas-base-dev gfortran libproj-dev openmpi-bin libopenmpi-dev netcdf-bin libnetcdf11 libnetcdf-devYou can use one of the two virtual environment options below:
Note: if you are using a HPC environment, refer to these instructions instead.
Virtualenv
- Install virtualenv.
- You may need to install a slightly older python-daemon to install PyRate:
pip install python-daemon==2.1.1- Install PyRate by using one of the following options.
- Run
setup.py:
python setup.py install- Install the latest version of PyRate with
pipfrom github:
pip install git+https://github.com/GeoscienceAustralia/PyRate- PyRate is also on
pypi, the Python package manager. To install, run:
pip install Py-RateThe Python requirements should automatically be built and installed.
If matplotlib does not install easily in a virtualenv, use this:
sudo apt-get -y build-dep matplotlibThen re-install matplotlib in your virtualenv.
Anaconda
For using PyRate in an Anaconda environment use this guide.
A suite of tests have been developed for use in testing PyRate functionality and for further code development. The tests use pytest and can be found in the tests/ directory. A small test dataset is included in the tests/test_data/ directory.
To run the tests, use the following command inside the top level PyRate/ directory:
pip install pytest
cd PyRate
export PYRATEPATH=/path/to/PyRate
pytest tests/Example configuration files for running PyRate with GAMMA or ROI_PAC format interferograms are contained in the configs/ directory.
After following the steps under Installation, an executable program
pyrate is created.
Use help for the different command line options:
>> pyrate --help
Usage: pyrate [OPTIONS] COMMAND [ARGS]...
Options:
-v, --verbosity [DEBUG|INFO|WARNING|ERROR]
Level of logging
--help Show this message and exit.
Commands:
linrate
postprocess
prepifgThe pyrate program has three command line options corresponding to
different parts of the PyRate workflow:
prepifglinratepostprocess
Below we discuss these options.
The first step of PyRate is to convert the GAMMA or ROI_PAC format
unwrapped interferograms into geotiff format, followed by applying
multi-looking and cropping operations. These procedures are all
performed by the pyrate prepifg command:
>> pyrate prepifg --help
Usage: pyrate prepifg [OPTIONS] CONFIG_FILE
Options:
--help Show this message and exit.The prepifg command is used as follows:
pyrate prepifg /path/to/config_fileThe two major steps during the prepifg operation are described
below.
Data formatting: convert to geotiff
The prepifg command will determine the input format from the value
specified at the processor: keyword in the config file (0: ROI_PAC;
1: GAMMA)
Each GAMMA geocoded unwrapped interferogram requires three header files to extract metadata required for data formatting: a geocoded DEM header file (*.dem.par), and the master and slave epoch SLC parameter files (*.slc.par).
The path and name of the DEM header file are specified in the config file under the demHeaderFile: keyword.
The SLC parameter files should be in the directory specified in the config file under the slcFileDir: keyword. SLC parameter files for a particular interferogram are found automatically by date-string pattern matching.
Each ROI_PAC geocoded unwrapped interferogram requires its own header/resource file (*.unw.rsc). These header files need to be stored in the same directory as the interferograms.
In addition, the geocoded DEM header file (*.dem.rsc) is required and its path and name are specified in the config file under the demHeaderFile: keyword. The geographic projection in the parameter DATUM: is extracted from the DEM header file.
Image transformations: multi-looking and cropping
The prepifg command will also perform multi-looking (image
sub-sampling) and cropping of the input interferograms.
Two example configuration files are provided in the configs/ directory, one
each for ROI_PAC and GAMMA prepifg configuration. Either configuration file
can be used with prepifg.
>> pyrate linrate --help
Usage: pyrate linrate [OPTIONS] CONFIG_FILE
Options:
-r, --rows INTEGER divide ifgs into this many rows
-c, --cols INTEGER divide ifgs into this many columns
--help Show this message and exitThis is the core of the PyRate processing workflow, handled by the linrate
command:
pyrate linrate path/to/config_file -c 3 -r 4This command will perform the time series and linear rate analysis and has
the option to break the interferograms into a number of tiles in r rows and
c columns. For example, the above command will break the interferograms
into 12 tiles and will produce 12 linear rate and time series products
corresponding to each tile.
The optional rows and columns arguments can be used to create smaller tiles
of the full size interferograms. This enables large interferograms to be more
easily be accommodated in memory. The number of tiles chosen should be as small
as possible that fits in the system memory.
Optionally, an orbital error correction and a spatio-temporal filter operation to estimate and remove atmospheric phase screen signals is applied to the interferograms prior to time series and linear rate analysis. The corrected interferograms are updated on disk and the corrections are not re-applied upon subsequent runs. This functionality is controlled by the orbfit: and apsest: options in the configuration file.
Non-optional pre-processing steps include: - Minimum Spanning Tree matrix calculation - Identification of a suitable reference pixel - Removal of reference phase from interferograms - Calculation of interferogram covariance - Assembly of the variance-covariance matrix
The last step of the PyRate workflow is to re-assemble the tiles and save geotiff files of the final time series and linear rate products.
>> pyrate postprocess --help
Usage: pyrate postprocess [OPTIONS] CONFIG_FILE
Options:
-r, --rows INTEGER divide ifgs into this many rows
-c, --cols INTEGER divide ifgs into this many columns
--help Show this message and exit.Make sure to use the same number of rows and columns that was used in the
previous linrate step:
pyrate postprocess path/to/config_file -c 3 -r 4PyRate has been designed for use on High Performance Computers and instructions to use a HPC cluster can be found in the hpc directory.
In addition to the MPI support for HPC, PyRate can use standard
multi-threading simply by turning parallel: 1 in the configuration file
to take advantage of multiple cores on a single PC.
For bugs, questions and discussions, please use Github Issues.
PyRate is licensed under Apache License 2.0. See the License deed in this repository for details.
Matt Garthwaite InSAR Team Lead, Geoscience Australia matt.garthwaite@ga.gov.au
Sudipta Basak Lead Developer basaks@gmail.com