.. image:: docs/PyRate_logo_50.png
   :alt: PyRate logo

Python tool for InSAR Rate and Time-series Estimation
=====================================================

.. image:: https://github.com/GeoscienceAustralia/PyRate/workflows/PyRate%20CI/badge.svg?branch=master
   :target: https://github.com/GeoscienceAustralia/PyRate/actions
.. image:: https://codecov.io/gh/GeoscienceAustralia/PyRate/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/GeoscienceAustralia/PyRate
.. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
   :target: https://opensource.org/licenses/Apache-2.0
.. image:: https://img.shields.io/pypi/pyversions/Py-Rate 
   :target: https://pypi.org/project/Py-Rate/ 

PyRate is a Python tool for estimating the average displacement rate (velocity) and cumulative displacement time-series of surface movements for every pixel in a stack of geocoded unwrapped interferograms generated by Interferometric Synthetic Aperture Radar (InSAR) processing. PyRate uses a "Small Baseline Subset" (SBAS) processing strategy and currently supports input data in the GAMMA or ROI_PAC software formats.
Additionally, the European Space Agency `SNAP software <https://step.esa.int/main/download/snap-download/>`_ version 8 has a "PyRate export" capability that prepares SNAP output data in the GAMMA format for use with PyRate.

The PyRate project started in 2012 as a partial Python translation of "Pirate", a Matlab tool developed by the University of Leeds and the Guangdong University of Technology.

The full PyRate documentation is available at http://geoscienceaustralia.github.io/PyRate

Dependencies
------------

The following system dependencies are required by PyRate:

- `Python <https://www.python.org/downloads/>`_, versions 3.7, 3.8 or 3.9.
- `GDAL <https://gdal.org/download.html>`_, versions 3.0.2 or 3.0.4

The following optional dependency is required for MPI processing capability:

- `Open MPI <https://www.open-mpi.org/software/ompi/v4.0/>`_, versions 2.1.6, 3.0.4, 3.1.4 or 4.0.2

The versions of each package stated above have been tested to work using `GitHub Actions <https://github.com/GeoscienceAustralia/PyRate/actions>`_ continuous integration testing.

Python dependencies for PyRate are::

    joblib==1.0.0
    mpi4py==3.0.3
    networkx==2.5
    numpy==1.19.4
    pyproj==3.0.0
    scipy==1.5.4
    numexpr==2.7.2
    nptyping==1.4.0

Install
-------

Details of all install options are given in the `PyRate documentation <http://geoscienceaustralia.github.io/PyRate>`_.

PyRate and its Python dependencies can be installed directly from the `Python Package Index (PyPI) <https://pypi.org/project/Py-Rate/>`_::

    pip install Py-Rate

Alternatively, to install from source and create an executable program in Linux, enter these commands in a terminal::

    cd ~
    git clone https://github.com/GeoscienceAustralia/PyRate.git
    python3 -m venv ~/PyRateVenv
    source ~/PyRateVenv/bin/activate
    cd ~/PyRate
    python3 setup.py install

This will install the above-listed Python dependencies and compile the executable program ``pyrate``.
To learn more about using PyRate, type ``pyrate`` command in the terminal::

    >> pyrate --help
    usage: pyrate [-h] [-v {DEBUG,INFO,WARNING,ERROR}]
              {conv2tif,prepifg,correct,timeseries,stack,merge,workflow} ...

    PyRate workflow:

        Step 1: conv2tif
        Step 2: prepifg
        Step 3: correct
        Step 4: timeseries
        Step 5: stack
        Step 6: merge

    Refer to https://geoscienceaustralia.github.io/PyRate/usage.html for
    more details.

    positional arguments:
      {conv2tif,prepifg,correct,timeseries,stack,merge,workflow}
        conv2tif            Convert interferograms to geotiff.
        prepifg             Perform multilooking, cropping and coherence masking to interferogram geotiffs.
        correct             Calculate and apply corrections to interferogram phase data.
        timeseries          Timeseries inversion of interferogram phase data.
        stack               Stacking of interferogram phase data.
        merge               Reassemble computed tiles and save as geotiffs.
        workflow            Sequentially run all the PyRate processing steps.

    optional arguments:
      -h, --help            show this help message and exit
      -v {DEBUG,INFO,WARNING,ERROR}, --verbosity {DEBUG,INFO,WARNING,ERROR}
                            Increase output verbosity

Test
----

To run the test suite, enter these commands in the terminal::

   pip install -r requirements-test.txt
   python3 -m pytest -m "not slow" tests/

To run the tests for a single module (e.g. test_timeseries.py), use this command::

   python3 -m pytest tests/test_timeseries.py