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: Iterable[datetime, datetime])#

Bases: object

Pair class for one pair.

__init__(pair: Iterable[datetime, datetime]) → None#

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

property values: ndarray[Any, dtype[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: datetime64#: the primary dates of all pairs

property secondary: datetime64#: the secondary dates of all pairs

primary_string(date_format='%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='%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 = {}) → 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

Pairs#

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

Bases: object

Pairs class to handle pairs

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: Iterable[Iterable[datetime, datetime]] | Iterable[Pair], sort: bool = True) → None#

initialize the pairs class

Parameters:

pairs (Iterable) – Iterable object of pairs. Each pair is an Iterable 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[Any, dtype[datetime64]]#: return the numpy array of the pairs

property names: ndarray[Any, dtype[str_]]#: return the names (string format) of the pairs

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

property days: ndarray[Any, dtype[int64]]#: return the time span of all pairs in days

property primary: DatetimeIndex#: return the primary dates of all pairs

property secondary: DatetimeIndex#: return the secondary dates of all pairs

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

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='%Y%m%d') → Index#

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.

property edge_index: ndarray[Any, dtype[int64]]#: return the index of the pairs in the dates coordinate (edge index in graph theory)

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

classmethod from_names(names: Iterable[str], parse_function: Callable | None = None, date_args: dict = {}) → 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:

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:

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_] | None#

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: list[str] | list[Pair] | '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 union of the pairs. All pairs that in self and input pairs. A more robust operation than addition.

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

difference(pairs: list[str] | list[Pair] | 'Pairs') → 'Pairs' | None#

return the difference of the pairs. The pairs in self but not in pairs. A more robust operation than 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: list | Literal['pairs', 'primary', 'secondary', 'days'] = 'pairs', ascending: bool = True, inplace: bool = True) → tuple[Pairs, ndarray[Any, dtype[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[Any, dtype[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_frame() → DataFrame#: return the pairs as a DataFrame

to_matrix(dtype=None) → ndarray[Any, dtype[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.