faninsar.Pairs#

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

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[source]#

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.

Methods

`__init__`(pairs[, sort])	Initialize the pairs class.
`copy`()	Return a copy of the pairs.
`difference`(pairs)	Return the difference of the pairs.
`from_names`(names[, parse_function, date_args])	Initialize the pair class from a pair name.
`intersect`(pairs)	Return the intersection of the pairs.
`parse_gaps`([pairs_removed])	Parse network gaps where the acquisitions are not connected by pairs.
`primary_string`([date_format])	Return the primary dates of all pairs in string format.
`secondary_string`([date_format])	Return the secondary dates of all pairs in string format.
`sort`([order, ascending, inplace])	Sort the pairs.
`to_frame`()	Return the pairs as a DataFrame.
`to_loops`([max_acquisition, max_days, ...])	Return all possible loops from the pairs.
`to_matrix`([dtype])	Return the SBAS matrix.
`to_names`([prefix])	Generate pairs names string with prefix.
`to_numpy`([dtype])	Return the pairs as a numpy array.
`to_triplet_loops`()	Return all possible triplet loops from the pairs.
`to_xarray`()	Return the pairs as a xarray DataArray.
`union`(pairs)	Return the unique, sorted union of the pairs.
`where`(pairs[, return_type])	Return the index of the pairs.

Attributes

`dates`	The sorted dates array of all pairs in type of np.datetime64[D].
`days`	The time span of all pairs in days.
`edge_index`	The index of the pairs in the dates coordinate.
`names`	The names (string format) of the pairs.
`primary`	The primary dates of all pairs.
`secondary`	The secondary dates of all pairs.
`shape`	The shape of the pairs array.
`values`	The numpy array of the pairs.
`xindexes`	The xarray indexes of the pairs.

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

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

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

difference(pairs: PairsLike) → Pairs | None[source]#

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.

intersect(pairs: PairLike) → Pairs | None[source]#

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.

parse_gaps(pairs_removed: Pairs | None = None) → DatetimeIndex[source]#

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

primary_string(date_format: str = '%Y%m%d') → Index[source]#

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') → Index[source]#

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.

sort(order: PairsOrder = 'pairs', ascending: bool = True, inplace: bool = True) → tuple[Pairs, NDArray[np.int64]] | None[source]#

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_frame() → DataFrame[source]#: Return the pairs as a DataFrame.

to_loops(max_acquisition: int = 5, max_days: int | None = None, edge_pairs: Pairs | None = None, edge_days: int | None = None) → Loops[source]#

Return all possible loops from the pairs.

Important

The pairs in the loops may be fewer than the input pairs. You can use the Pairs.where() method to get the index/mask of the pairs in the loops from the input pairs.

Example:

>>> loops = pairs.to_loops()
>>> mask = pairs.where(loops.pairs, return_type="mask")

Parameters:

max_acquisition (int) –
The maximum number of acquisitions in the loops. It should be at least 3.

Note

The number of acquisitions is equal to the number of intervals + 1 \(n (acquisition) = n (edge\ pairs) + 1 (diagonal\ pair) = n (intervals) + 1\).
max_days (int, optional) – The maximum number of days for the pairs in the loops. If None, all available pairs will be used. Default is None.
edge_pairs (Pairs, optional) – The edge pairs to form loops. If None, edge_days must be provided.
edge_days (int, optional) –
The maximum number of days used to identify the edge pairs. If None, edge_pairs must be provided. Default is None.

Note

This parameter will be ignored if edge_pairs is provided.

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

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.

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

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][source]#: Return the pairs as a numpy array.

to_triplet_loops() → TripletLoops[source]#: Return all possible triplet loops from the pairs.

to_xarray() → DataFrame[source]#: Return the pairs as a xarray DataArray.

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

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.

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

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’.

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

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

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 names: NDArray[np.str_]#: The names (string format) of the pairs.

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

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

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

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

property xindexes: Indexes#: The xarray indexes of the pairs.

faninsar.Pairs#

This Page