Main workflow for KFTS-InSAR
================================

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. 

.. literalinclude:: refconfigfile.ini 
    :end-before: [FOR TESTING]

.. note:: see section 3 for details about model syntax. 

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


.. automodule:: kfts
.. autoclass:: RunKalmanFilter
    :members: 

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