utils#

This module contains classes and functions of general utility used in multiple places throughout data_downloader.

pairs module#

This module contains the Pair and Pairs classes to handle pairs of InSAR data, which are the simplified versions from the FanInSAR package.

Class	Description
`Pair`	A class to handle one pair of InSAR data.
`Pairs`	A class to handle multiple pairs of InSAR data.

Pair#

class data_downloader.utils.Pair(pair: ArrayLike)#

Bases: object

Pair class for one pair.

__init__(pair: ArrayLike) → None#

Initialize the Pair class.

Parameters:: pair (Sequence[datetime, datetime]) – Sequence object of two dates. Each date is a datetime object. For example, (date1, date2).

property values: NDArray[np.datetime64]#: The values of the pair with format of datetime.

property name: str#: String of the pair with format of ‘%Y%m%d_%Y%m%d’.

property days: int#: The time span of the pair in days.

property primary: Timestamp#: The primary dates of all pairs.

property secondary: Timestamp#: The secondary dates of all pairs.

primary_string(date_format: str = '%Y%m%d') → str#

Return the primary dates of all pairs in string format.

Parameters:: date_format (str) – Format of the date string. Default is ‘%Y%m%d’. See more at strftime Format Codes.

secondary_string(date_format: str = '%Y%m%d') → str#

Return the secondary dates of all pairs in string format.

Parameters:

date_format (str) –

Format of the date string. Default is ‘%Y%m%d’. See more at strftime Format Codes.

classmethod from_name(name: str, parse_function: Callable | None = None, date_args: dict | None = None) → Pair#

Initialize the pair class from a pair name.

Parameters:

name (str) – Pair name.
parse_function (Callable, optional) – Function to parse the date strings from the pair name. If None, the pair name will be split by ‘_’ and the last 2 items will be used. Default is None.
date_args (dict, optional) – Keyword arguments for pd.to_datetime() to convert the date strings to datetime objects. For example, {‘format’: ‘%Y%m%d’}. Default is {}.

Returns:

pair – Pair class.

Return type:

Pair

to_numpy(dtype: DTypeLike = None) → NDArray[np.datetime64]#: Return the pair as a numpy array.

Pairs#

class data_downloader.utils.Pairs(pairs: Sequence[Sequence[datetime, datetime]] | Sequence[Pair], sort: bool = True)#

Bases: object

Pairs class to handle pairs.

Note

Each pair will be sorted in the acquisition order. The primary date will be always earlier than the secondary date.
The pairs will be sorted by the primary date.

Examples

prepare dates and pairs for examples:

>>> dates = pd.date_range("20130101", "20231231").values
>>> n = len(dates)
>>> pair_ls = []
>>> loop_ls = []
>>> for i in range(5):
...     np.random.seed(i)
...     pair_ls.append(dates[np.random.randint(0, n, 2)])

initialize pairs from a list of pairs

>>> pairs = Pairs(pair_ls)
>>> print(pairs)
    primary  secondary
0 2013-06-24 2016-02-21
1 2013-08-24 2015-11-28
2 2017-08-16 2018-03-14
3 2020-01-20 2021-11-15
4 2020-02-21 2020-06-25

select pairs by date slice

>>> pairs1 = pairs["2018-03-09":]
>>> print(pairs1)
    primary  secondary
0 2020-01-20 2021-11-15
1 2020-02-21 2020-06-25

pairs can be added (union) and subtracted (difference)

>>> pairs2 = pairs - pairs1
>>> pairs3 = pairs1 + pairs2
>>> print(pairs2)
    primary  secondary
0 2013-06-24 2016-02-21
1 2013-08-24 2015-11-28
2 2017-08-16 2018-03-14
>>> print(pairs3)
    primary  secondary
0 2013-06-24 2016-02-21
1 2013-08-24 2015-11-28
2 2017-08-16 2018-03-14
3 2020-01-20 2021-11-15
4 2020-02-21 2020-06-25

pairs can be compared with ==`and `!=

>>> print(pairs3 == pairs)
>>> print(pairs3 != pairs)
True
False

__init__(pairs: Sequence[Sequence[datetime, datetime]] | Sequence[Pair], sort: bool = True) → None#

Initialize the pairs class.

Parameters:

pairs (Sequence) – Sequence object of pairs. Each pair is an Sequence or Pair object of two dates with format of datetime. For example, [(date1, date2), …].
sort (bool, optional) – Whether to sort the pairs. Default is True.

property values: NDArray[np.datetime64]#: The numpy array of the pairs.

property names: NDArray[np.str_]#: The names (string format) of the pairs.

property dates: DatetimeIndex#: The sorted dates array of all pairs in type of np.datetime64[D].

property days: Index#: The time span of all pairs in days.

property primary: Index#: The primary dates of all pairs.

property secondary: Index#: The secondary dates of all pairs.

property edge_index: NDArray[np.int64]#

The index of the pairs in the dates coordinate.

This is useful to construct the edge index in graph theory.

property shape: tuple[int, int]#: The shape of the pairs array.

classmethod from_names(names: Sequence[str | None], parse_function: Callable | None = None, date_args: dict | None = None) → Pairs#

Initialize the pair class from a pair name.

Note

The pairs will be in the order of the input names. If you want to sort the pairs, you can call the Pairs.sort() method to achieve it.

Parameters:

names (str) – Pair names.
parse_function (Callable, optional) – Function to parse the date strings from the pair name. If None, the pair name will be split by ‘_’ and the last 2 items will be used. Default is None.
date_args (dict, optional) – Keyword arguments for pd.to_datetime() to convert the date strings to datetime objects. For example, {‘format’: ‘%Y%m%d’}. Default is {}.

Returns:

pairs – unsorted Pairs object.

Return type:

Pairs

where(pairs: list[str] | list[Pair] | Pairs, return_type: Literal['index', 'mask'] = 'index') → NDArray[np.int64 | np.bool_]#

Return the index of the pairs.

Parameters:

pairs (list of str or Pair, or Pairs) – Pair names or Pair objects, or Pairs object.
return_type (str, optional) – Whether to return the index or mask of the pairs. Default is ‘index’.

intersect(pairs: Pairs) → Pairs | None#

Return the intersection of the pairs.

The pairs both in self and input pairs.

Parameters:: pairs (list of str or Pair, or Pairs) – Pair names or Pair objects, or Pairs object.

union(pairs: list[str] | list[Pair] | Pairs) → Pairs#

Return the unique, sorted union of the pairs.

All pairs that in self and input pairs. Same as addition.

Parameters:: pairs (list of str or Pair, or Pairs) – Pair names or Pair objects, or Pairs object.

difference(pairs: Pairs) → Pairs | None#

Return the difference of the pairs.

The pairs in self but not in pairs. Same as subtraction.

Parameters:: pairs (list of str or Pair, or Pairs) – Pair names or Pair objects, or Pairs object.

copy() → Pairs#: Return a copy of the pairs.

sort(order: Literal['pairs', 'primary', 'secondary', 'days'] | list[str] = 'pairs', ascending: bool = True, inplace: bool = True) → tuple[Pairs, NDArray[np.int64]] | None#

Sort the pairs.

Parameters:

order (str or list of str, optional) –
By which fields to sort the pairs. This argument specifies which fields to compare first, second, etc. Default is ‘pairs’.

The available options are one or a list of: [‘pairs’, ‘primary’, ‘secondary’, ‘days’].
ascending (bool, optional) – Whether to sort ascending. Default is True.
inplace (bool, optional) – Whether to sort the pairs inplace. Default is True.

Returns:

None or (Pairs, np.ndarray). if inplace is True, return the sorted pairs
and the index of the sorted pairs in the original pairs. Otherwise,
return None.

to_names(prefix: str | None = None) → NDArray[np.str_]#

Generate pairs names string with prefix.

Parameters:: prefix (str) – Prefix of the pair file names. Default is None.
Returns:: names – Pairs names string with format of ‘%Y%m%d_%Y%m%d’.
Return type:: np.ndarray

to_numpy(dtype: DTypeLike = None) → NDArray[np.datetime64]#: Return the pairs as a numpy array.

to_dataframe() → DataFrame#: Return the pairs as a DataFrame.

to_xarray() → Variable#: Return the pairs as a xarray DataArray.

to_matrix(dtype: DTypeLike = None) → NDArray[np.number]#

Return the SBAS matrix.

Parameters:

matrix (np.ndarray) – SBAS matrix in shape of (n_pairs, n_dates-1). The dates between pairs are set to 1, otherwise 0.
dtype (np.dtype, optional) – Data type of the matrix. Default is None.

parse_gaps(pairs_removed: Pairs | None = None) → ndarray#

Parse network gaps where the acquisitions are not connected by pairs.

The gaps are detected by the dates that are not present in the secondary acquisition of the pairs.

Note

Theoretically, the gaps should be the temporal spans (or intervals) between the consecutive acquisitions. For simplicity, the end dates of the gaps are returned here.

Parameters:: pairs_removed (Pairs, optional) – Pairs that are removed from the original pairs. Default is None, which means all pairs are used.
Returns:: gaps – Acquisition/date gaps that are not covered by any pairs.
Return type:: pd.DatetimeIndex

plot(baseline: Baselines | None = None, ax: Axes | None = None, **kwargs) → Axes#: Plot the pairs.

utils#

pairs module#

Pair#

Pairs#

This Page