faninsar.TripletLoops

class faninsar.TripletLoops(loops: Sequence[Sequence[datetime, datetime, datetime]] | Sequence[TripletLoop], sort: bool = True)

Bases: object

TripletLoops class to handle loops with three pairs/acquisitions.

__init__(loops: Sequence[Sequence[datetime, datetime, datetime]] | Sequence[TripletLoop], sort: bool = True) → None

Initialize the triplet loops class.

Parameters:

• loops (Sequence) – Sequence object of triplet loops. Each loop is an Sequence object of three dates with format of datetime or TripletLoop object. For example, [(date1, date2, date3), …].

• sort (bool, optional) – Whether to sort the loops. Default is True.

Methods

__init__(loops[, sort])	Initialize the triplet loops class.
from_names(names[, parse_function, date_args])	Initialize the loops class from a list of loop file names.
sort([order, ascending, inplace])	Sort the loops.
to_frame([target])	Return the loops as a DataFrame.
to_matrix()	Return loop matrix (containing 1, -1, 0) from pairs.
to_names([prefix])	Return the string name of each loop.
to_seasons()	Return the season of each loop.
where(loop[, return_type])	Return the index of the loop.

Attributes

dates	Sorted dates of the loops with format of datetime.
days12	The time span of the first pair in days.
days13	The time span of the third pair in days.
days23	The time span of the second pair in days.
index	The index of the loops in dates coordinates.
names	The names (sting format) of the loops.
pairs	All sorted pairs of the loops.
pairs12	The first pairs of the loops.
pairs13	The third pairs of the loops.
pairs23	The second pairs of the loops.
shape	The shape of the loop array.
values	Return the values of the loops.

classmethod from_names(names: list[str], parse_function: Callable | None = None, date_args: dict | None = None) → TripletLoops

Initialize the loops class from a list of loop file names.

Parameters:

• names (list) – list of loop file names.

• parse_function (Callable, optional) – Function to parse the date strings from the loop file name. If None, the loop file name will be split by ‘_’ and the last 3 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:

loops – unsorted TripletLoops object.

Return type:

TripletLoops

sort(order: str | list = 'pairs', ascending: bool = True, inplace: bool = True) → tuple[TripletLoops, NDArray[np.int64]] | None

Sort the loops.

Parameters:

• order (str or list of str, optional) –

  By which fields to sort the loops. this argument specifies which fields to compare first, second, etc. Default is ‘pairs’.

  The available options are one or a list of:

  • date:: ‘date1’, ‘date2’, ‘date3’

  • pairs: ‘pairs12’, ‘pairs23’, ‘pairs13’

  • days: ‘days12’, ‘days23’, ‘days13’

  • short name: ‘date’, ‘pairs’, ‘days’. short name will be

    treated as a combination of the above options. For example, ‘date’ is equivalent to [‘date1’, ‘date2’, ‘date3’].

• ascending (bool, optional) – Whether to sort ascending. Default is True.

• inplace (bool, optional) – Whether to sort the loops inplace. Default is True.

Returns:

sorted – if inplace is True, return the sorted loops and the index of the sorted loops in the original loops. Otherwise, return None.

Return type:

(TripletLoops, np.ndarray) | None

to_frame(target: Literal['pairs', 'dates'] = 'pairs') → DataFrame

Return the loops as a DataFrame.

Parameters:

target (str, one of ['pairs', 'dates']) – Target of the DataFrame. Default is ‘pairs’.

to_matrix() → NDArray[np.int8]

Return loop matrix (containing 1, -1, 0) from pairs.

Returns:

matrix – TripletLoop matrix with the shape of (n_loop, n_pair). The values of each loop/row in matrix are:

• 1: pair12 and pair23

• -1: pair13

• 0: otherwise

Return type:

np.ndarray

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

Return the string name of each loop.

Parameters:

prefix (str, optional) – Prefix of the output loop names. Default is None.

Returns:

names – String names of the loops.

Return type:

np.ndarray

to_seasons() → NDArray[np.int8]

Return the season of each loop.

Returns:

seasons –

list of seasons of each loop.

0: not the same season 1: spring 2: summer 3: fall 4: winter

Return type:

list

where(loop: str | TripletLoop, return_type: Literal['index', 'mask'] = 'index') → int | None

Return the index of the loop.

Parameters:

• loop (str or TripletLoop) – TripletLoop name or TripletLoop object.

• return_type (str, optional) – Whether to return the index or mask of the loop. Default is ‘index’.

property dates: NDArray[np.datetime64]

Sorted dates of the loops with format of datetime.

property days12: NDArray[np.int64]

The time span of the first pair in days.

property days13: NDArray[np.int64]

The time span of the third pair in days.

property days23: NDArray[np.int64]

The time span of the second pair in days.

property index: NDArray[np.int64]

The index of the loops in dates coordinates.

property names: NDArray[np.str_]

The names (sting format) of the loops.

property pairs: Pairs

All sorted pairs of the loops.

property pairs12: Pairs

The first pairs of the loops.

property pairs13: Pairs

The third pairs of the loops.

property pairs23: Pairs

The second pairs of the loops.

property shape: tuple[int, int]

The shape of the loop array.

property values: NDArray[np.datetime64]

Return the values of the loops.

Returns:

values – Values of the loops with format of datetime.

Return type:

np.ndarray