libera_utils.l1a.packet_ordering.sort_by_sequence_counter#

libera_utils.l1a.packet_ordering.sort_by_sequence_counter(packet_ds: Dataset, packet_time_coordinate: str, *, ground_data: bool = False, verbose: bool = False) → Dataset#

Order the PACKET axis by SRC_SEQ_CTR and drop repeated packets.

The key is each packet’s SRC_SEQ_CTR with its wraps counted, as _unwrap_sequence_counter returns it. Packets with the same key are the same packet counter: when every PACKET data variable agrees they are one packet received twice, and the first is kept. The rows are compared here rather than by _drop_duplicates because the key is not a coordinate of the dataset and the error names the raw counter and packet times.

packet_ds is consumed: each PACKET variable is removed from it as its reordered copy is made, so at most one variable is held twice. Use the returned dataset.

A packet whose packet time would place it a counter wrap away from both of its neighbors in the input, whose counters continue its own, has a wrong packet time: it is dropped, with a UserWarning and a logged warning.

Parameters:

  • packet_ds (xr.Dataset) – Single-APID packet dataset with SRC_SEQ_CTR and packet_time_coordinate on PACKET.

  • packet_time_coordinate (str) – Name of the packet time coordinate.

  • ground_data (bool, optional) – If True, a repeated counter whose packets differ keeps its first packet instead of raising. Default is False.

  • verbose (bool, optional) – If True and ground_data is True, warn for each repeated counter whose packets differ. Default is False.

Returns:

The packets in SRC_SEQ_CTR order, one per counter.

Return type:

xr.Dataset

Raises:

ValueError – If packet_ds has no SRC_SEQ_CTR or no packet_time_coordinate variable, if packets adjacent in the input with consecutive counters would be placed a counter wrap apart other than around one such dropped packet, or, with ground_data False, if packets with the same counter differ.