insar4sm package

Submodules

insar4sm.DS_funcs module

insar4sm.DS_funcs.compare_coherence_matrices(Coh1: array, pixel_comb_mask1: array, Coh2: array, pixel_comb_mask2: array) → tuple[numpy.array, numpy.array]

Compares two coherence matrices and returns the one with largest frobenius norm.

Parameters:

• Coh1 (np.array) – 2D array with (real) coherence values

• pixel_comb_mask1 (np.array) – 1D array of (int) SLC pixel indices that form the first coherence matrix

• Coh2 (np.array) – 2D array with (real) coherence values

• pixel_comb_mask2 (np.array) – 1D array of (int) SLC pixel indices that form the second coherence matrix

Returns:

Selected coherence matrix, corresponding SLC pixel indices

Return type:

tuple[np.array,np.array]

insar4sm.DS_funcs.compute_Covar_Coh_weighted(slc_window_values: array, weights: array, nbands: int) → tuple[numpy.array, numpy.array]

Compute the covariance matrix of the distributed scatterer

Parameters:

• slc_window_values (np.array) – an 2D array with complex values (SARs, DS_pixels)

• weights (np.array) – a 1D array with float values (0-1) (DS_pixels) that contains weights of DS pixels

• nbands (int) – number of SLC SARs that we have

Returns:

Covariance matrix of DS (complex values), coherence matrix of DS (real values)

Return type:

tuple[np.array,np.array]

insar4sm.DS_funcs.find_best_pixels_amp(DS_coords_1: array, DS_coords_2: array, DS_amp_values: array, p_value_thres: float = 0.05, similarity_perc: float = 0.4) → array

Finds a subset of DS_pixels that share the same amplitude temporal behaviour, via Kolmogorov-Smirnov test. All possible pixels combinations are calculated. The pixels that found similar at a defined percentage were keeped.

Parameters:

• DS_coords_1 (np.array) – 1D array of first coordinates (ints) of DS_pixels

• DS_coords_2 (np.array) – 1D array of second coordinates (ints) of DS_pixels

• DS_amp_values (np.array) – 2D array [SARS, selected_pixels] of selected (real) amplitude values

• p_value_thres (float, optional) – p-value threshold. Defaults to 0.05.

• similarity_perc (float, optional) – the percentage of similarities among all pixels. Defaults to 0.4.

Returns:

A boolean 1d array [DS_pixels,] that contains pixels with similar amplitude information

Return type:

np.array

insar4sm.DS_funcs.find_best_pixels_amp_fast(DS_coords_1: array, DS_coords_2: array, DS_amp_values: array, amp_stack: array, p_value_thres: float = 0.05, az_size: int = 0, rg_size: int = 2) → array

Finds a subset of DS_pixels that share the same amplitude temporal behaviour, via Kolmogorov-Smirnov test. Reference amplitude values are considered the ones close to center (at a certain window radius).

Parameters:

• DS_coords_1 (np.array) – 1D array of first coordinates (ints) of DS_pixels

• DS_coords_2 (np.array) – 1D array of second coordinates (ints) of DS_pixels

• DS_amp_values (np.array) – 2D array [SARS, selected_pixels] of selected (real) amplitude values

• amp_stack (np.array) – 3D array (SARs, Ys, Xs) of real (amplitude) values

• p_value_thres (float, optional) – p-value threshold. Defaults to 0.05.

• win_size (int, optional) – radius of window. Window is used to get the reference amplitudes. Defaults to 1.

Returns:

A boolean 1d array [DS_pixels,] that contains pixels with similar amplitude information

Return type:

np.array

insar4sm.DS_funcs.find_best_pixels_ph(DS_coords_1: array, DS_coords_2: array, DS_slc_values: array, Best_pixels_amp: array, keep_percent: float = 0.7) → array

Calculates the subset of pixels (at a given percentage) that yields the highest overall coherence.

Parameters:

• DS_coords_1 (np.array) – 1D array of first coordinates (ints) of DS_pixels

• DS_coords_2 (np.array) – 1D array of second coordinates (ints) of DS_pixels

• DS_slc_values (np.array) – 2D array [SARS, DS_pixels] of selected (complex) SLC values

• Best_pixels_amp (np.array) – a boolean 1d array [DS_pixels,] that contains pixels with similar amplitude information

• keep_percent (float, optional) – the percentage of pixels that we respect. Defaults to 0.7.

Returns:

A boolean 1d array [DS_pixels,] that contains pixels with similar amplitude information

Return type:

np.array

insar4sm.DS_funcs.get_DS_pixels(slc_stack: array, amp_stack: array, lat: array, lon: array, aoi_geometry: Polygon) → tuple[numpy.array, numpy.array, numpy.array, numpy.array, numpy.array]

Calculates the coordinates of SAR SLC pixels that corresponds to given AOI (polygon).

Parameters:

• slc_stack (np.array) – 3D array (SARs, Ys, Xs) of complex (SLC) values

• amp_stack (np.array) – 3D array (SARs, Ys, Xs) of real (amplitude) values

• lat (np.array) – 2D array (Ys, Xs) of real (latitude) values

• lon (np.array) – 2D array (Ys, Xs) of real (longitude) values

• aoi_geometry (Polygon) – Polygon of AOI

Returns:

1D array of first coordinates (ints) of DS_pixels, 1D array of second coordinates (ints) of DS_pixels, 2D array [SARS, DS_pixels] of selected (complex) SLC values, 2D array [SARS, selected_pixels] of selected (real) amplitude values, 2D array (mask) [Ys, Xs] of selected (bool) SLC pixels

Return type:

tuple[np.array,np.array,np.array,np.array,np.array]

insar4sm.DS_funcs.isPD(B: array) → bool

Checks if input array is positive-definite, via Cholesky

Parameters:

B (np.array) – the input array

Returns:

True if positive-definite

Return type:

bool

insar4sm.DS_funcs.is_row_in_array(row: array, arr: array) → bool

Checks if a single row (1D array) exists in an matrix (2D array), rowwise.

Parameters:

• row (np.array) – the 1D array

• arr (np.array) – the 2D array

Returns:

True if given 1D array exists in 2D array, rowwise

Return type:

bool

insar4sm.DS_funcs.llh2xy(lat_data: array, lon_data: array) → tuple[numpy.array, numpy.array]

Convert lat lon information to Xs,Ys of WGS84 UTM projection

Parameters:

• lat_data (np.array) – the latitude information

• lon_data (np.array) – the longitude information

Returns:

Xs, Ys of the best WGS84 UTM projection

Return type:

tuple[np.array, np.array]

insar4sm.DS_funcs.rewrap(data: array) → array

Wraps the data between -pi and pi.

Parameters:

data (np.array) – the data need to be wrapped

Returns:

Wrapped data. Values are between -pi and pi

Return type:

np.array

insar4sm.amp_funcs module

insar4sm.amp_funcs.runCalamp(inputDS: str, output_dir: str) → tuple[pandas.core.frame.DataFrame, numpy.array]

Amplitude calibration factors calculation.

• Read each slc image

• Calculate the number of valid pixels (exclude mask, zero values)

• Calculate sum of amplitudes of valid pixels

• Calculate mean value of valid pixels which is the amplitude calibration factor

• Save Amplitude calibration factor to pandas dataframe with datetime and two columns (Amplitude_factors, Datetime)

• Saves amplitude calibration factors in csv in disk

• Saves SLC SAR stack to npy file in disk

Parameters:

• inputDS (str) – The path of vrt file of SLC SAR stack

• output_dir (str) – the output directory that Amplitude calibration factors and SLC SAR stack in npy format will be saved

Returns:

Amplitude calibration factors, SLC SAR stack

Return type:

tuple[pd.DataFrame, np.array]

insar4sm.calc_SM_index module

insar4sm.calc_SM_index.calc_burgi_sm_index(coh_sm: array, SM_sorting: array, n_dry_bands: int, sm_dry: float, ind_DS: int, band_start: int, band_end: int, temp_thres: int = 0) → tuple[numpy.array, numpy.array, numpy.array, numpy.array]

Calculates the surface soil moisture (SSM) index based on interferometric coherence.

Parameters:

• coh_sm (np.array) – The coherence related to SSM variations for all SAR acquisitions

• SM_sorting (np.array) – The ordering (ascending) of SAR acquisitions based on their SSM levels

• n_dry_bands (int) – The number of SAR acquisitions that will be considered dry (30% of all SAR acquisitions)

• sm_dry (float) – The SSM value that corresponds to driest conditions (default value 0.03 m3/m3)

• ind_DS (int) – Number of distributed scatterer that will be analysed

• band_start (int) – The index of first SAR acquisition to be analyzed

• band_end (int) – The index of last SAR acquisition to be analyzed

• temp_thres (int, optional) – The temporal distance (distance between SARs) that will be considered. If 1 means only the sequential SARs will be used. Defaults to 0.

Returns:

proxy SSM index using all coherence information, proxy SSM index using coherence information over dry SARs, indices of SAR acquisitions considered dry, coherence related to SSM variations for selected SAR acquisitions

Return type:

tuple[np.array, np.array, np.array, np.array]

insar4sm.calc_SM_index.calc_coh_model(SM: array, coh_row_inds: array, coh_col_inds: array) → array

Functionality that calculates the soil moisture index based on Eq. 4 of Burgi et al., 2021

\[log(\gamma_{ij}^{sm})= -abs(log(sm_i) - log(sm_j))\]

Parameters:

• SM (np.array) – Soil moisture

• coh_row_inds (np.array) – Index related with rows of coherence matrix

• coh_col_inds (np.array) – Index related with cols of coherence matrix

Returns:

Modelled coherence values

Return type:

np.array

..References:

Bürgi, P. M., & Lohman, R. B. (2021). High-resolution soil moisture evolution in hyper-arid regions: A comparison of InSAR, SAR, microwave, optical, and data assimilation systems in the southern Arabian Peninsula. Journal of Geophysical Research: Earth Surface, 126, e2021JF006158. https://doi.org/10.1029/2021JF006158

insar4sm.calc_int_data module

insar4sm.calc_int_data.calc_int_amp(input_dir: str, output_dir: str, primary_date: str) → int

Performs interferometric processing

• Restructures the Topstack datasets

• Finds the index of primary SLC SAR

• Finds the Amplitude calibration factors

• Computes and saves to disk the Interferometric Calibrated SLC stack

• Computes and save to disk the normalize Amplitude information

• Updates baseline information, given the primary SLC SAR

Parameters:

• input_dir (str) – Input directory that we have SLCs, geometry, baseline and datetime information is stored

• output_dir (str) – Output directory that SLCs, geometry, baseline and datetime information will be stored

• primary_date (str) – the date of primary image

Returns:

the index of the primary SLC SAR

Return type:

int

insar4sm.classes module

insar4sm.coh_funcs module

insar4sm.coh_funcs.calc_SM_coherences(Datetimes: list, SM_sorting: array, n_bands: int, n_ds: int, ind_DS: int, coh_full_DS: array, band_start: int, band_end: int, n_dry_bands: int, max_coh_flag: bool, simple_exp_model: bool) → tuple[numpy.array, numpy.array, numpy.array]

Calculates the coherence information due to soil moisture variations

Parameters:

• Datetimes (list) – list of SAR acquisition datetimes (datetime.datetime objects)

• SM_sorting (np.array) – Ascending ordering of SAR acquisitions based on their surface soil moisture (SSM) level

• n_bands (int) – number of SAR acquisitions used

• n_ds (int) – number of distributed scatterer that will be computed

• ind_DS (int) – index of distributed scatterer that will be computed

• coh_full_DS (np.array) – 2D array of the raw coherence (real) values

• band_start (int) – index of first SAR acquisition

• band_end (int) – index of last SAR acquisition

• n_dry_bands (int) – number of SAR acquisitions that are considered “dry”

• max_coh_flag (bool) – parameter related with the selection of coherence values for modelling temporal decorrelation. If True maximum coherence values for each time span are selected

• simple_exp_model (bool) – parameter related with the selection of coherence values for modelling temporal decorrelation. If True the simple exponential model is selected.

Returns:

coherence matrix related to soil moisture variations, coherence mean in respect with dry conditions, coherence std in respect with dry conditions

Return type:

tuple[np.array, np.array, np.array]

insar4sm.coh_funcs.exp_fit(x: array, a: float, b: float) → array

Exponential model between time and coherence due to temporal decorrelation.

\[y = a e^{xb}\]

Parameters:

• x (np.array) – known quantity (time spans)

• a (float) – parameter to estimated

• b (float) – parameter to estimated

Returns:

modelled data (coherence due to temporal decorrelation)

Return type:

np.array

insar4sm.coh_funcs.temp_coh__model(t: array, gamma_0: float, tau: float, gamma_k: float) → array

Exponential model between time and coherence due to temporal decorrelation according to Parizzi et al., 2009

\[\gamma_t = (\gamma_0 - \gamma_k)e^{-t/ au} + \gamma_k\]

Parameters:

• t (np.array) – known quantity (time spans)

• gamma_0 (float) – parameter to estimated

• tau (float) – parameter to estimated

• gamma_k (float) – parameter to estimated

Returns:

modelled data (coherence due to temporal decorrelation)

Return type:

np.array

..References:

Parizzi, A., Cong, X., & Eineder, M. (2009). First Results from Multifrequency Interferometry. A comparison of different decorrelation time constants at L, C, and X Band. ESA Scientific Publications, (SP-677), 1-5.

insar4sm.dielectic_models module

insar4sm.forward_modelling_funcs module

insar4sm.gridding module

insar4sm.gridding.WGS84_to_UTM(lon: float, lat: float) → str

Finds the best WGS84 UTM projection given a lon, lat.

Parameters:

• lon (float) – longitude

• lat (float) – latitude

Returns:

the code of CRS (corresponds to WGS84 UTM projection)

Return type:

str

insar4sm.gridding.create_grid_xy(Outdir: str, AOI: str, res: int = 250) → tuple[geopandas.geodataframe.GeoDataFrame, geopandas.geodataframe.GeoDataFrame]

Creates a grid (centroids and borders) for given AOI and grid size.

Parameters:

• Outdir (str) – the output directory that SM_point_grid and sm_polygons_latlon will be saved

• AOI (str) – the path of vector AOI file

• res (int, optional) – the grid size in meters. Defaults to 250.

Returns:

centroids of each grid cell, borders of each grid cell

Return type:

tuple[gpd.GeoDataFrame,gpd.GeoDataFrame]

insar4sm.inversion module

insar4sm.joblib_progress_bar module

insar4sm.joblib_progress_bar.tqdm_joblib(tqdm_object: tqdm) → None

Context manager to patch joblib to report into tqdm progress bar given as argument.

..References:

https://stackoverflow.com/questions/24983493/tracking-progress-of-joblib-parallel-execution/58936697#58936697

insar4sm.meteo_funcs module

insar4sm.meteo_funcs.find_dry_SARs(meteo_df: DataFrame, slc_datetimes: list, days_back: int = 24, orbit_time: str = '02:00:00', lowest_temp_K: float = 273.15, highest_acc_rain_m: float = 0.001) → tuple[str, list, pandas.core.frame.DataFrame]

Finds SAR images that are related to low precipitation activity (low SSM conditions) and not low temperature (snow-free).

Parameters:

• meteo_df (pd.DataFrame) – Contains meteorological data at daily basis. We have three columns (tp__m, skt__K, Datetimes)

• slc_datetimes (list) – list of (datetime.datetime objects) SAR acquisition datetimes

• days_back (int, optional) – number of days to go back in order to accumulate precipitation. Defaults to 24.

• orbit_time (str, optional) – Time of the SAR pass. Defaults to ‘02:00:00’.

Returns:

selected dry SAR acquisition, datetimes of other potential dry SAR acquisitions, meteorological data for SAR acuqisition datetimes

Return type:

tuple[str,list,pd.DataFrame]

insar4sm.phase_closure_funcs module

insar4sm.phase_closure_funcs.Covar_2_phase_closures(DS_Covar: array) → array

Calculates observed phase closures from observed covariance matrix

Parameters:

DS_Covar (np.array) – covariance matrix that contains observed complex interferometric values

Returns:

Observed phase closures

Return type:

np.array

insar4sm.phase_closure_funcs.rewrap(data: array) → array

Wraps the data between -pi and pi.

Parameters:

data (np.array) – the data need to be wrapped

Returns:

Wrapped data. Values are between -pi and pi

Return type:

np.array

insar4sm.prep_meteo module

insar4sm.prep_meteo.cftime_to_datetime(cfdatetime: datetime) → datetime

coverts cftime datetime object to datetime.datetime object

Parameters:

cfdatetime (cftime.datetime) – provided cftime datetime object

Returns:

calculated datetime.datetime object

Return type:

datetime.datetime

insar4sm.prep_meteo.convert_to_df(meteo_file: str, SM_AOI: str, ERA5_flag: bool) → DataFrame

Convert meteo dataset to pandas dataframe at daily basis.

Parameters:

• meteo_file (str) – the path of provided meteo dataset

• SM_AOI (str) – the path of vector AOI

• ERA5_flag (bool) – True if it is an ERA5-Land dataset

Returns:

meteo_df has three columns (Datetimes, tp__m, skt__K) and contains daily information.

Return type:

pd.DataFrame

insar4sm.prep_slc_data module

insar4sm.prep_slc_data.get_SAR_borders(merged_dir: str, AOI_WGS84: str) → tuple[int, int, int, int]

Calculates the SAR Topstack coordinates given a WGS AOI polygon.

Parameters:

• merged_dir (str) – path of Topstack data (merged folder)

• AOI_WGS84 (str) – path of vector AOI file

Returns:

ymin, ymax, xmin, xmax coordinates related with Topstack datasets

Return type:

tuple[int,int,int,int]

insar4sm.prep_slc_data.latlon_2_SAR_coord(lat_data: array, lon_data: array, lat_p: float, lon_p: float, dist: float = 0.001) → tuple[int, int]

finds the SAR coordinates given a lat,lon pair

Parameters:

• lat_data (np.array) – the latitude information of Topstack dataset

• lon_data (np.array) – the longitude information of Topstack dataset

• lat_p (float) – the latitude value of a single point

• lon_p (float) – the longitude value of a single point

• dist (float, optional) – spatial distance in degrees. Defaults to 0.001.

Returns:

x_sar, y_sar the coordinates related to Topstack dataset

Return type:

tuple[int,int]

insar4sm.prep_slc_data.tops_2_vrt(indir: str, outdir: str, stackdir: str, AOI_WGS84: str, geomdir: str) → None

Creates vrt files for subsetting Topstack data (slc data, lat, lon, hgt, shadowMask, los, incLocal, baselines). Saves to disk geometric information (npy format).

Parameters:

• indir (str) – Topstack path

• outdir (str) – directory that vrt files and npy files will be saved

• stackdir (str) – path for slc information of Topstack data

• AOI_WGS84 (str) – path of vector AOI file

• geomdir (str) – path for geometrical information of Topstack data

insar4sm.prep_slc_data.write_to_numpy(geometry_folder: str) → None

Converts geometrical datasets (lat, lon, hgt, shadowMask, los, incLocal, baselines) from vrt to npy format.

Parameters:

geometry_folder (str) – path of vrt files for geometric information

insar4sm.soil_funcs module

insar4sm.soil_funcs.get_soilgrids_value(soilgrid_tiff: str, lon: float, lat: float) → float

Extracts the value from given tiff file at lon, lat

Parameters:

• soilgrid_tiff (str) – The path of soilgrids tiff file

• lon (float) – Longitude (WGS84)

• lat (float) – Latitude (WGS84)

Returns:

The extracted percentage value (from 0-100)

Return type:

float

insar4sm.sorting_funcs module

insar4sm.sorting_funcs.coh_dist_calc(acq_sorted: array, Coh_array: array) → DataFrame

Extracts the coherence values for each observed temporal distance

Parameters:

• acq_sorted (np.array) – sorted indices of SAR acquisitions (earlier to latest)

• Coh_array (np.array) – coherence matrix between SAR acquisitions

Returns:

Temporal distances and observed coherences

Return type:

pd.DataFrame

insar4sm.sorting_funcs.find_sm_sorting(Datetimes: list, coh_full_DS: array, amp_DS: array, ind_DS: int, band_start: int, band_end: int, driest_date: datetime, n_bands: int, n_iters: int, denoise: bool = True) → array

Ascending ordering of SAR acquisitions based on their surface soil moisture level (dry to wet)

Parameters:

• Datetimes (list) – datetime information for the SAR acquisitions

• coh_full_DS (np.array) – the coherence matrix of the distributed scatterer (DS)

• amp_DS (np.array) – the amplitude information of the DS

• ind_DS (int) – the index of the DS that will be analyzed

• band_start (int) – the index of first SAR acqusition

• band_end (int) – the index of last SAR acqusition

• driest_date (datetime.datetime) – the datetime of driest SAR acqusition

• n_bands (int) – number of SARs that will be used

• n_iters (int) – number of iterations related to sorting algorithm

• denoise (bool, optional) – flag for denoising coherence matrix. Defaults to True.

Returns:

Ascending ordering of SAR acquisition based on their surface soil moisture level

Return type:

np.array

Module contents