space_packet_parser.xarr
========================

.. py:module:: space_packet_parser.xarr

.. autoapi-nested-parse::

   Extras package that supports generating an `xarray.Dataset` directly



Attributes
----------

.. autoapisummary::

   space_packet_parser.xarr.logger
   space_packet_parser.xarr.ReadableBinaryPacket


Functions
---------

.. autoapisummary::

   space_packet_parser.xarr._min_dtype_for_encoding
   space_packet_parser.xarr._get_minimum_numpy_datatype
   space_packet_parser.xarr.create_dataset


Module Contents
---------------

.. py:data:: logger

.. py:data:: ReadableBinaryPacket

.. py:function:: _min_dtype_for_encoding(data_encoding: space_packet_parser.xtce.encodings.DataEncoding)

   Find the minimum data type capable of representing an XTCE data encoding.

   This only works for raw values and does not apply to calibrated or otherwise derived values.

   :param data_encoding: The raw data encoding.
   :type data_encoding: encodings.DataEncoding

   :returns: The numpy dtype string for the minimal representation of the data encoding.
   :rtype: str


.. py:function:: _get_minimum_numpy_datatype(name: str, definition: space_packet_parser.xtce.definitions.XtcePacketDefinition, use_raw_value: bool = False) -> str | None

   Get the minimum datatype for a given variable.

   :param name: The variable name.
   :type name: str
   :param definition: The XTCE packet definition. Used to examine data types to infer their niminal numpy representation.
   :type definition: xtce.definitions.XtcePacketDefinition
   :param use_raw_value: Default False. If True, uses the data type of the raw value for each parameter.
   :type use_raw_value: bool

   :returns: **datatype** -- The minimum numpy dtype for the parameter.
             Returns None to indicate that numpy should use default dtype inference.
   :rtype: Optional[str]


.. py:function:: create_dataset(packet_files: ReadableBinaryPacket | collections.abc.Iterable[ReadableBinaryPacket], xtce_packet_definition: str | os.PathLike | space_packet_parser.xtce.definitions.XtcePacketDefinition, use_raw_values: bool = False, packet_bytes_generator: collections.abc.Callable | None = None, generator_kwargs: dict | None = None, parse_bytes_kwargs: dict | None = None, packet_filter: collections.abc.Callable[[bytes], bool] | None = None) -> dict[int, xarray.Dataset]

   Create a dictionary of xarray Datasets (per APID) from a set of packet files

   .. rubric:: Notes

   This function only handles packet definitions with the same variable structure
   across all packets with the same APID. For example, this cannot be used for polymorphic
   packets whose structure changes based on previously parsed values.
   If you are parsing muxed APID data and wish to filter it, you can either omit the unwanted
   APID packet definitions from your XTCE (fastest) or you can parse everything and
   filter after creation of the Dataset for each APID.

   :param packet_files: Packet files or file-like objects opened in binary mode. Accepts file paths (`str`, `Path`, `PathLike`), file-like objects (`io.BufferedIOBase`, `io.RawIOBase`), or raw bytes.
   :type packet_files: Union[str, Path, PathLike, io.BufferedIOBase, io.RawIOBase, bytes, Iterable[Union[str, Path, PathLike, io.BufferedIOBase, io.RawIOBase, bytes]]]
   :param xtce_packet_definition: Packet definition for parsing the packet data
   :type xtce_packet_definition: Union[str, Path, PathLike, xtce.definitions.XtcePacketDefinition]
   :param use_raw_values: Default False. If True, saves parameter raw values to the resulting Dataset.
                          e.g. enumerated lookups will be saved as their encoded integer values.
   :type use_raw_values: bool
   :param packet_bytes_generator: The generator function to use for yielding packet bytes. Defaults to
                                  ccsds.ccsds_generator. Can be set to fixed_length_generator or any
                                  other generator that yields bytes-like objects.
   :type packet_bytes_generator: Optional[callable]
   :param generator_kwargs: Keyword arguments passed to the packet bytes generator.
   :type generator_kwargs: Optional[dict]
   :param parse_bytes_kwargs: Keyword arguments passed to `XtcePacketDefinition.parse_bytes()`.
   :type parse_bytes_kwargs: Optional[dict]
   :param packet_filter: Optional function to filter items returned from the packet generator (e.g. `lambda pkt: pkt.apid == 100`)
   :type packet_filter: Optional[Callable[[bytes], bool]]

   :returns: Dataset objects parsed from the iterable of packets, keyed by APID.
   :rtype: dict[int, xr.Dataset]