Py-Rate 0.1.3

A Python tool for estimating velocity and time-series from Interferometric Synthetic Aperture Radar (InSAR) data.

PyRate - a Python tool for RAte and Time-series Estimation
==========================================================

.. image:: https://travis-ci.org/GeoscienceAustralia/PyRate.svg?branch=master
:target: https://travis-ci.org/GeoscienceAustralia/PyRate
.. image:: https://coveralls.io/repos/github/GeoscienceAustralia/PyRate/badge.svg?branch=master
:target: https://coveralls.io/github/GeoscienceAustralia/PyRate?branch=master
.. image:: https://pyup.io/repos/github/geoscienceaustralia/pyrate/shield.svg
:target: https://pyup.io/repos/github/geoscienceaustralia/pyrate/
.. image:: https://pyup.io/repos/github/geoscienceaustralia/pyrate/python-3-shield.svg
:target: https://pyup.io/repos/github/geoscienceaustralia/pyrate/

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. PyRate is a partial Python translation of
`Pirate <http://homepages.see.leeds.ac.uk/~earhw/software/pirate/>`_, a
MATLAB tool developed at the University of Leeds.

Quickstart
==========

Before you start, make sure your system has the following packages
installed:

.. code-block:: console

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-dev

We strongly recommend using a
`virtualenv <https://gist.github.com/basaks/b33ea9106c7d1d72ac3a79fdcea430eb>`_.

One might need to install a slightly older ``python-daemon`` to install
``PyRate``:

.. code-block:: console

pip install python-daemon==2.1.1

To install, simply run ``setup.py``:

.. code-block:: console

python setup.py install

or install with ``pip``:

.. code-block:: console

pip install git+https://github.com/GeoscienceAustralia/PyRate

The python requirements should automatically be built and installed.

Anaconda setup for ``PyRate``
-----------------------------

For anaconda installation and ``virtualenv`` instruction, `see this
guide <https://github.com/GeoscienceAustralia/PyRate/blob/master/conda.md>`_.

Tests
-----

Tests use `pytest <http://doc.pytest.org/en/latest/>`_ and can be found
in *tests*.

To run the tests, use the following command inside the ``PyRate``
directory:

.. code-block:: console

pip install pytest
cd PyRate
export PYRATEPATH=/path/to/PyRate
pytest tests/

Config file:
------------

TODO

PyRate workflow:
----------------

``PyRate`` installs an executable ``pyrate``.

Use ``help`` for the different command line options:

.. code-block:: console

>> 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
prepifg

As you can see ``pyrate`` has three command line options.

1. prepifg
2. linrate
3. postprocess

Below we discuss these options.

Preparing interferrograms: prepifg
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The first step of PyRate is to convert the unwrapped interforrograms
into geotiffs, followed by multilooking and cropping. Both of these
operations are performed by ``pyrate prepifg`` command:

.. code-block:: console

>> pyrate prepifg --help
Usage: pyrate prepifg [OPTIONS] CONFIG_FILE

Options:
--help Show this message and exit.

So one can use the ``prepfig`` command as the following:

.. code-block:: console

pyrate prepifg /path/to/config_file

The 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)

A GAMMA translation requires a geographic DEM header file (\*.dem.par)
and SLC parameter files (\*.slc.par) for both master and slave images to
extract metadata required for the formatting. Therefore three header
files are needed to format each geocoded unwrapped GAMMA interferogram .
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 same location as the interferogram file and are found
automatically by date string pattern matching.

A ROI\_PAC translation requires a header/resource file (*.rsc*
extension) for the geocoded unwrapped ROI\_PAC interferogram (in the
same directory) and either the geographic projection (e.g. 'WGS84')
specified as an option or a header/resource file for the geographic DEM
containing the geographic projection in the parameter DATUM:

Image transformations: multilooking and cropping
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This ``prepifg`` command will also perform multi-looking (resampling)
and cropping the images.

Two examples of the config files are provided in ``configs`` directory,
with examples of the ``roipac`` and ``gamma`` prepifg configuration.
Both config files can be used with ``prepifg``.

Linear rate and time series analysis: linrate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

>> 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 exit

This is the core of the processing tools, handled by the ``linrate``
command:

.. code-block:: python

pyrate linrate path/to/config_file -c 3 -r 4

This command will does the time series and linear rate analysis, but has
the options to break the interferrograms into tiles of ``r`` rows and
``c`` columns. So this above command will break the interferrograms into
12 tiles and will produce 12 linear rate and time series predictions
corresponding to each tile.

The optional rows and columns help us create smaller ``tiles`` of the
interferrograms that can be accommodated in the memory. The number of
tiles chosen should be as small as possible that fits in the system
memory.

Putting it back together: postprocess
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The last step in ``pyrate`` is to put all the tiles back together from
the ``linrate`` part.

.. code-block:: python

>> 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 with
``postprocess`` as with ``linrate``:

.. code-block:: python

pyrate postprocess path/to/config_file -c 3 -r 4

MPI Support
-----------

``PyRate`` has been designed for supercomputers and instructions to use
an HPC cluster can be found in the `pbs directory <pbs>`_.

Python multiprocessing support
------------------------------

In addition to the MPI support for HPC, ``PyRate`` can be use standard
multiprocessing simply by turning ``parallel: 1`` in the config file to
take advantage of multiple cores on a single PC.

Integrating PyAPS with PyRate
-----------------------------

TODO

Useful Links
============

Home Page https://github.com/GeoscienceAustralia/PyRate

Documentation http://geoscienceaustralia.github.io/PyRate

Issue tracking https://github.com/GeoscienceAustralia/PyRate/issues

Bugs & Feedback
===============

For bugs, questions and discussions, please use `Github
Issues <https://github.com/GeoscienceAustralia/PyRate/issues>`_.


Documentation
-------------

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



History
-------

0.1.0 (2017-01-31)
++++++++++++++++++

* First release on PyPI.