2. Main workflow for KFTS-InSAR

2.1. Configuration file

Configuration parameters for KFTS are defined in a text file that will be read using the configparser module of python. Below is a reference configuration file.

########################################
###### Config file for KFTS-InSAR ###### 
########################################

[INPUT]

# Reference directory from which other paths are defined
workdir = /share/user/Yourfolder/

# File containing interferograms
infile  = Stack/PROC-STACK.h5

# Format of infile (ISCE,RAW or Mintpy)
# Only used to adjust the name of the interferograms key in "infile"
fmtfile = ISCE

# File containing previously computed TS (used only if UPDT is True)
instate = States.h5 

# File containing information about earthquake (used only if EQ is True)
# X Y (in pxl number) time (in decimal year since start) radius_of_influence (in km) dx dy 
eqinfo  = EQ_list.txt

#####################################
[OUTPUT]

# Directory for output h5 file (States.h5 and Phases.h5)
# The absolute path will be: workdir+outdsir
outdir  = KF/

# Directory for saving figures (used only if PLOT is True)
# The absolute path will be: workdir+figdir
figdir  = Figs/     

#####################################
[MODEL SETUP]

# Is there earthquake to model? (if True, eqinfo required)
EQ      = True

# Frequency of oscillating signal (rad/year)
freq    = 6.283185

# Std of unmodeled phase delay 
# (same unit as unwrapped interferograms (often mm))
sig_y   = 10.0

# Std of interferometric network misclosure 
# (same unit as unwrapped interferograms)
sig_i   = 0.01

# Functional element of descriptiv model
# see https://manondls.github.io/KFTS-InSAR/func.html
model  = [('POLY',1),('SIN',${freq}),('COS',${freq})]

# A priori std estimate of model parameters (mm)
sig_a  = 25.,8.,8.,8.

# Time delta after which temporally focused functions are not optimized anymore 
# for steps in time (earthquakes) and constant terms (polynomial of order zero) 
Dtime_max = 3.0 

#####################################
[KALMAN FILTER SETUP]

# Print details?
VERBOSE = False 

# Create and save plots?
PLOT    = False 

# Start from previously computed state (in instate)?
UPDT    = False

# Minimum number of valid acquisition on a pixel
pxlTh   = 1

#####################################

Note

see section 3 for details about model syntax.

2.2. Routine workflow

kfts.py is the main file of KFTS-InSAR. It reads the configuration file (.ini) and run the full KFTS-InSAR processing chain. Separate components are detailed in subsequent sections. A typical command to run the algorithm is

python -u kfts.py -c myconfigfile.ini

To speed up the computation, we recommend to run the code in parallel with openMPI (pixel will be divided between processors). This requires a build of H5py and numpy modules of python with openMPI. For instance, using 30 processors :

mpirun -n 30 python -u kfts.py -c myconfigfile.ini

class kfts.RunKalmanFilter(config)

Class to run the full KFTS-InSAR processing chain Read configuration and data. Setup parameters. Run KF for each pixel.

earthquakeIntegration(data)

Add step function to the functional model of deformation to model coseismic displacement due to earthquakes. Require a file containing earthquake properties in the track reference frame (see earthquake2step.py).

initCovariances(L)

Create arrays for the initial state Covariance matrix (P0) and the process noise covariance (Q).

L:

Initial length of the state vector (number of model parameter + 1 (for reference phase))

initMpi()

Initiate communication of the Message Passing Interface (MPI)

initPlot(data, figdir)

Draw quick plots to visualize input data: * Data plot * baseline plot * spatial mask on pixel

isTraceOn()

Print only if verbose activated and first parallel worker

launch()

Combine procedures to prepare data and model, then launch the Kalman filter class on each pixel row by row

loadcheck_pastoutputs(data, tfct)

Check input file consitency when restarting and frame time series update

• data : initiated data class (new interferograms)

• tfct : initiated model class

readData()

Initiate the data class dealing with interferograms, time, spatial grid and mask. It

1. reads data

2. divide the grid between workers (if MPI)

3. build data covariance and

4. store information

setConfiguration(config)

Read configuration file and convert to python objects. :config: open config file (.ini format)

2.3. Outputs

There are 3 output HDF5 files containing the following datasets. For N interferograms with (Y, X) pixels over M timesteps, we have * the time series of phase change with respect to the first acquisition in Phases.h5:

dates                    Dataset {M}              Ordinal values of the SAR acquisition dates
idx0                     Dataset {SCALAR}         Index of first phase in file with respect to first reference date of time series
rawts                    Dataset {Y, X, M}        Reconstructed phases
rawts_std                Dataset {Y, X, M}        Reconstructed phases standard deviation (sqrt of diag(state_cov))
tims                     Dataset {M}              Decimal years of the SAR acquisition dates

• the state information at the last time step States.h5. This contains the L optimized parameters, as well as the m last phase observations (indices M, M-1, M-2, …, M-m+1), usefull to restart KFTS for later updates and associated covariances:

  indx Dataset {m} Indexes (with respect to first acquisition) of the phases kept in the state misclosure Dataset {SCALAR} Misclosure error included in data covariance (sig_i) mismodeling Dataset {SCALAR} Mismodeling error added as process noise on last phase estimate (sig_y) processnoise Dataset {L} Process noise for functional model parameters (default is ok) state Dataset {Y, X, L+m} State vectors for each pixel state_cov Dataset {Y, X, L+m, L+m} Covariances of state for each pixel tims Dataset {m} Times corresponding to phases in state in decimal years with respect to first phase

• metadata useful to evaluate the quality of the dataset, estimates and chosen parameters Updates.h5:

  mean_innov Dataset {Y, X, M} Mean innovation (or residual) for the last phase estimate at each time step param_gain Dataset {Y, X, M, L} Norm of the gain for the L model parameters at each time step