doco updates

Author: Matt Garthwaite

docs/installation.rst

@@ -2,7 +2,7 @@ Installation
 ===============
 
 This is a quick guide to getting the PyRate software up and running in various platforms.
-Step by step guide to install Pyrate and run toy example.
+Step by step guide to install Pyrate and run a toy example.
 
 .. include:: ubuntu.rst
 .. include:: docker.rst

docs/usage.rst

@@ -12,23 +12,22 @@ format interferograms are contained in the example configuration file *input_par
 File Discovery
 ~~~~~~~~~~~~~~
 
-To allow flexibility in the file types the can be processed, PyRate requires
-file lists to be provided. This allow PyRate to identify what files are of
-which type without relying on file extensions. The path to
-these lists are provided under the following keywords in the configuration
-file:
+To allow flexibility in the file types that can be processed, PyRate requires
+file lists to be provided. This allows PyRate to identify files of each
+type without relying on file extensions. The path to these lists are 
+provided under the following keywords in the configuration file:
 
 .. note::
 
-    Filenames should be provided without the preceding path, wtih each
+    Filenames should be provided without the preceding path, with each
     name on a separate line.
 
 ``ifgfilelist``: this is the list of interferograms to be processed.
 
 .. note::
 
-    Interferogram filenames must contain an epoch pair. Any naming convention
-    is appropriate so long as an epoch pair of format ``XXXXXXXX-YYYYYYYY``
+    Interferogram filenames must contain a pair of epochs. Any naming convention
+    is appropriate so long as an epoch pair of format ``YYYYMMDD-YYYYMMDD``
     exists in the filename.
 
     Example of an interferogram file list:
@@ -39,14 +38,14 @@ file:
         20160202-20160415_interferogram
 
 ``slcfilelist``: this is the list which contains the pool of available
-GAMMA headers.
+GAMMA SLC header files.
 
 .. note::
 
     Header filenames must contain an epoch. The epoch must be
-    in the format ``XXXXXXXXX``.
+    in the format ``YYYYMMDD``.
 
-    Example of a GAMMA header file list:
+    Example of a GAMMA SLC header file list:
     ::
 
         20150702_header
@@ -57,12 +56,12 @@ GAMMA headers.
         20160415_header
 
 ``cohfilelist``: this is the list which contains the pool of available
-coherence files (used in optional coherence masking).
+coherence files (used during optional coherence masking).
 
 .. note::
 
-    Coherence filenames must contain an epoch pair. The epoch pair must be
-    in the format ``XXXXXXX-YYYYYYYY``.
+    Coherence filenames must contain a pair of epochs. The epoch pair must be
+    in the format ``YYYYMMDD-YYYYMMDD``.
 
     Example of a coherence file list:
     ::
@@ -74,8 +73,8 @@ coherence files (used in optional coherence masking).
 The epochs in filenames are used to match the corresponding header or coherence
 files to each interferogram. It is recommended to provide all available headers/coherence
 files in their respective lists, as only the necessary files will be
-used. This allows you to process a subset of interferograms by reducing
-the names in ``ifgfilelist`` without needing to modify anything else.
+used. This allows you to process a subset of interferograms by removing
+entries in ``ifgfilelist`` without needing to modify anything else.
 
 
 Workflow
@@ -110,8 +109,8 @@ Use ``--help`` for the different command line options:
       --help                          Show this message and exit.
 
     Commands:
-      conv2tif  		Convert interferograms to geotiff.
-      merge       Reassemble computed tiles and save as geotiffs.
+      conv2tif  	Convert interferograms to geotiff.
+      merge             Reassemble computed tiles and save as geotiffs.
       prepifg           Perform multilooking and cropping on geotiffs.
       process           Time series and linear rate computation.
 
@@ -125,11 +124,11 @@ different parts of the PyRate workflow:
 
 Below we discuss these options.
 
-conv2tif: Converting input intergerograms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+conv2tif: Converting input interferograms to Geotiff format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Before PyRate can process GAMMA or ROI\_PAC intergerograms, they need to be
-converted into geotiff format by the ``conv2tif`` command.
+Before PyRate can process GAMMA or ROI\_PAC interferograms, they need to be
+converted into geotiff format using the ``conv2tif`` command.
 
 ::
 
@@ -148,13 +147,13 @@ specified at the *processor:* keyword in the config file (0: ROI\_PAC;
 Each GAMMA geocoded unwrapped interferogram requires three header files
 to extract metadata required for data formatting: a geocoded DEM header
 file (``demHeaderFile`` in config) and the master and slave epoch SLC
-parameter files (supplied by ``slcfilelist`` in config).
+header files (supplied by ``slcfilelist`` in config).
 
-The SLC parameter files should be in the directory specified in the
+The SLC header files should be in the directory specified in the
 config file under ``slcFileDir``. SLC files for a
 particular interferogram are found automatically by date-string pattern
 matching based on epochs. If ``slcFileDir`` is not provided, PyRate will
-fallback to looking in the observations direcotry (``obsdir`` in config).
+look in the observations directory by default (``obsdir`` in config).
 
 Each ROI\_PAC geocoded unwrapped interferogram requires its own
 header/resource file. These header files need to be
@@ -174,8 +173,8 @@ prepifg: Preparing input interferograms
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The second step of PyRate is applying multi-looking and cropping
-operations to the converted interferograms.
-These procedures are all performed by the ``pyrate prepifg`` command:
+operations to the geotiff interferograms.
+These procedures are all performed by the ``prepifg`` command:
 
 ::
 
@@ -194,19 +193,20 @@ The ``prepifg`` command is used as follows:
 Coherence masking
 ^^^^^^^^^^^^^^^^^
 
-If specified, ``prepifg`` will perform coherence masking of the unwrapped
+If specified, ``prepifg`` will perform coherence masking on the
 interferograms before multilooking and cropping is performed. This requires
-corresponding coherence images for each unwrapped interferogram. The purpose
-of this is to filter the phase observations to a set of high-quality pixels.
-Pixels with coherence values below a certain threshold will be set to the
-NoDataValue. Note that the number of valid pixels in each interferogram will
-be different after coherence masking.
+corresponding coherence images for each interferogram. The purpose
+of this is to remove the poor quality phase observations to leave a set of 
+high-quality pixels. Pixels with coherence values below a certain threshold 
+will be set to the NoDataValue. Note that the number of valid pixels (i.e. 
+pixels not equal to NoDataValue) in each interferogram will be different 
+after coherence masking.
 
 Coherence masking is enabled  by setting the ``cohmask`` argument to ``1`` in
 the configuration file. A threshold, ``cohthresh`` needs to be provided. If
 ``cohfiledir`` is provided, this is where PyRate will look for coherence
-images. If not provided it will look in observations directory where the
-unwrapped interferograms exist (``obsdir`` in config). The available coherence
+images. If not provided it will look in the observations directory where the
+interferograms exist (``obsdir`` in config). The available coherence
 filenames need to be specified in a file list and provided as the
 ``cohfilelist`` parameter.
 
@@ -217,12 +217,12 @@ The ``prepifg`` command will perform multi-looking (image
 sub-sampling) and cropping of the input interferograms in geotiff format.
 The purpose of this is to reduce the resolution of the interferograms to
 reduce the computational complexity of performing the time series and
-linear rate analysis.
+stacking analysis.
 
 An example configuration file is provided in the root source directory
 as ``input_parameters.conf``.
 
-process: Main workflow and linear rate and time series analysis
+process: Main workflow, including stacking and time series analysis
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
@@ -243,20 +243,20 @@ This is the core of the PyRate processing workflow, handled by the
 
     pyrate process -f path/to/config_file -c 3 -r 4
 
-This command will perform the time series and linear rate analysis and
+This command will perform the time series and stacking 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
+the interferograms into 12 tiles and will produce 12 stacking 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.
+The optional rows and columns arguments can be used to split the full-size
+interferograms into smaller tiles. This enables large interferograms
+to be more easily accommodated in memory. The number of tiles chosen
+should be as small as possible that fits within the available 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
+operation to estimate and remove atmospheric phase screen (APS) signals is
+applied to the interferograms prior to time series and stacking
 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
@@ -271,7 +271,7 @@ merge: Putting the tiles back together
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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.
+save geotiff files of the final time series and stacking products.
 
 ::
 

input_parameters.conf

@@ -74,7 +74,7 @@ ifgylast:     -34.22
 
 #------------------------------------
 # Reference pixel search options
-# refx/y: coordinate of reference pixel. If left blank then search for best pixel will be performed
+# refx/y: Lon/Lat coordinate of reference pixel. If left blank then search for best pixel will be performed
 # refnx/y: number of search grid points in x/y direction
 # refchipsize: chip size of the data window at each search grid point
 # refminfrac: minimum fraction of valid (non-NaN) pixels in the data window

pyrate/core/aps.py

@@ -65,7 +65,7 @@ def spatio_temporal_filter(tsincr, ifg, params, preread_ifgs):
     """
     Applies a spatio-temporal filter to remove the atmospheric phase screen
     (APS) and saves the corrected interferograms. Before performing this step,
-    the time series must be computed using the SVD method. This function then
+    the time series iscomputed using the SVD method. This function then
     performs temporal and spatial filtering.
 
     :param ndarray tsincr: incremental time series array of size

pyrate/core/config.py

@@ -57,22 +57,22 @@
 OUT_DIR = 'outdir'
 #: STR; Name of Digital Elevation Model file
 DEM_FILE = 'demfile'
-#: STR; Name of the header for the DEM
+#: STR; Name of the DEM header file
 DEM_HEADER_FILE = 'demHeaderFile'
-#: STR; Name of directory containing GAMMA SLC parameter files
+#: STR; Name of directory containing GAMMA SLC header files
 SLC_DIR = 'slcFileDir'
-# STR; Name of the file list containing the pool of available SLC headers
+#: STR; Name of the file list containing the pool of available SLC headers
 SLC_FILE_LIST = 'slcfilelist'
 
 
-#: STR; The projection of the input interferograms.
+# STR; The projection of the input interferograms.
+# TODO: only used in tests; deprecate?
 INPUT_IFG_PROJECTION = 'projection'
 #: FLOAT; The no data value in the interferogram files.
 NO_DATA_VALUE = 'noDataValue'
 #: FLOAT; No data averaging threshold for prepifg
 NO_DATA_AVERAGING_THRESHOLD = 'noDataAveragingThreshold'
-#: BOOL (1/2/3); Re-project data from Line of sight, 1 = vertical,
-# 2 = horizontal, 3 = no conversion
+# BOOL (1/2/3); Re-project data from Line of sight, 1 = vertical, 2 = horizontal, 3 = no conversion
 #REPROJECTION = 'prjflag' # NOT CURRENTLY USED
 #: BOOL (0/1): Convert no data values to Nan
 NAN_CONVERSION = 'nan_conversion'
@@ -94,33 +94,31 @@
 IFG_YLAST = 'ifgylast'
 
 # reference pixel parameters
-#: INT; Coordinate in x of reference pixel OR -1 = perform search
+#: INT; Longitude (decimal degrees) of reference pixel, or if left blank a search will be performed
 REFX = 'refx'
-#: INT; Coordinate in y of reference pixel OR -1 = perform search
+#: INT; Latitude (decimal degrees) of reference pixel, or if left blank a search will be performed
 REFY = 'refy'
 #: INT; Number of reference pixel grid search nodes in x dimension
 REFNX = "refnx"
 #: INT; Number of reference pixel grid search nodes in y dimension
 REFNY = "refny"
-#: INT; Dimension of reference pixel search window
+#: INT; Dimension of reference pixel search window (in number of pixels)
 REF_CHIP_SIZE = 'refchipsize'
 #: FLOAT; Minimum fraction of observations required in search window for pixel to be a viable reference pixel
 REF_MIN_FRAC = 'refminfrac'
-#: BOOL (1/2); Reference phase estimation method
+#: BOOL (1/2); Reference phase estimation method (1: median of the whole interferogram, 2: median within the window surrounding the reference pixel)
 REF_EST_METHOD = 'refest'
 
-# coherence masking parameters
 # coherence masking parameters
 #: BOOL (0/1); Perform coherence masking (1: yes, 0: no)
 COH_MASK = 'cohmask'
-#: FLOAT; Threshold for coherence values
+#: FLOAT; Coherence threshold for masking
 COH_THRESH = 'cohthresh'
-#: STR; Directory containing coherence .cc files; defaults to OBS_DIR if not provided
+#: STR; Directory containing coherence files; defaults to OBS_DIR if not provided
 COH_FILE_DIR = 'cohfiledir'
 #: STR; Name of the file list containing the pool of available coherence files
 COH_FILE_LIST = 'cohfilelist'
 
-
 #atmospheric error correction parameters NOT CURRENTLY USED
 APS_CORRECTION = 'apscorrect'
 APS_METHOD = 'apsmethod'
@@ -130,41 +128,40 @@
 APS_ELEVATION_EXT = 'APS_ELEVATION_EXT'
 
 # orbital error correction/parameters
-#: BOOL (1/0); Flag controlling whether to apply orbital error correction
+#: BOOL (1/0); Perform orbital error correction (1: yes, 0: no)
 ORBITAL_FIT = 'orbfit'
-#: BOOL (1/2); Method for orbital error correction, 1: independent, 2: network
+#: BOOL (1/2); Method for orbital error correction (1: independent, 2: network)
 ORBITAL_FIT_METHOD = 'orbfitmethod'
-#: BOOL (1/2/3) Order of orbital error model, 1 = planar in x and y (2 parameter model, 2 = quadratic in x and y (5 parameter model), 3 = quadratic in x and cubic in y (part-cubic 6 parameter model)
+#: BOOL (1/2/3) Polynomial order of orbital error model (1: planar in x and y - 2 parameter model, 2: quadratic in x and y - 5 parameter model, 3: quadratic in x and cubic in y - part-cubic 6 parameter model)
 ORBITAL_FIT_DEGREE = 'orbfitdegrees'
 #: INT; Multi look factor for orbital error calculation in x dimension
 ORBITAL_FIT_LOOKS_X = 'orbfitlksx'
 #: INT; Multi look factor for orbital error calculation in y dimension
 ORBITAL_FIT_LOOKS_Y = 'orbfitlksy'
 
-# Linear rate/stacking parameters
-#: FLOAT; Threshold ratio between 'model minus observation' residuals and a-priori observation standard deviations for linear rate estimate acceptance (otherwise remove furthest outlier and re-iterate)
+# Stacking parameters
+#: FLOAT; Threshold ratio between 'model minus observation' residuals and a-priori observation standard deviations for stacking estimate acceptance (otherwise remove furthest outlier and re-iterate)
 LR_NSIG = 'nsig'
-#: INT; Number of required observations per pixel for the linear rate inversion
+#: INT; Number of required observations per pixel for stacking to occur
 LR_PTHRESH = 'pthr'
-#: FLOAT; Maximum allowable standard error for pixels in linear rate inversion.
+#: FLOAT; Maximum allowable standard error for pixels in stacking
 LR_MAXSIG = 'maxsig'
 
 # atmospheric delay errors fitting parameters NOT CURRENTLY USED
 # atmfitmethod = 1: interferogram by interferogram; atmfitmethod = 2, epoch by epoch
 #ATM_FIT = 'atmfit'
 #ATM_FIT_METHOD = 'atmfitmethod'
 
-#: BOOL (0/1) Do spatio-temporal filter
+# APS correction parameters
+#: BOOL (0/1) Perform APS correction (1: yes, 0: no)
 APSEST = 'apsest'
-
 # temporal low-pass filter parameters
 #: INT (1/2/3); Method for temporal filtering (1: Gaussian, 2: Triangular, 3: Mean filter)
 TLPF_METHOD = 'tlpfmethod'
 #: FLOAT; Cutoff time for gaussian filter in years;
 TLPF_CUTOFF = 'tlpfcutoff'
 #: INT; Number of required input observations per pixel for temporal filtering
 TLPF_PTHR = 'tlpfpthr'
-
 # spatially correlated noise low-pass filter parameters
 #: INT (1/2); Method for spatial filtering(1: butterworth; 2: gaussian)
 SLPF_METHOD = 'slpfmethod'
@@ -178,20 +175,20 @@
 SLPF_NANFILL_METHOD = 'slpnanfill_method'
 
 # Time series parameters
-#: BOOL (1/0); Do Time series calculation
+#: BOOL (1/0); Perform time series calculation (1: yes, 0: no)
 TIME_SERIES_CAL = 'tscal'
 #: INT (1/2); Method for time series inversion (1: Laplacian Smoothing; 2: SVD)
 TIME_SERIES_METHOD = 'tsmethod'
 #: INT; Number of required input observations per pixel for time series inversion
 TIME_SERIES_PTHRESH = 'ts_pthr'
-#: INT (1/2); Order of Laplacian smoothing operator, first or # second order
+#: INT (1/2); Order of Laplacian smoothing operator, first or second order
 TIME_SERIES_SM_ORDER = 'smorder'
 #: FLOAT; Laplacian smoothing factor (values used is 10**smfactor)
 TIME_SERIES_SM_FACTOR = 'smfactor'
 # tsinterp is automatically assigned in the code; not needed in conf file
 #TIME_SERIES_INTERP = 'tsinterp'
 
-#: BOOL (0/1/2); Use parallelisation/Multi-threading
+#: BOOL (0/1/2); Use parallelisation/Multi-threading (0: in serial, 1: in parallel by rows, 2: in parallel by pixel)
 PARALLEL = 'parallel'
 #: INT; Number of processes for multi-threading
 PROCESSES = 'processes'