spinifex.ionospheric.ionex_parser
=================================

.. py:module:: spinifex.ionospheric.ionex_parser

.. autoapi-nested-parse::

   Module to parse the IONosphere map EXchange (IONEX) data format,
   as described in Schaer and Gurtner (1998)



Classes
-------

.. autoapisummary::

   spinifex.ionospheric.ionex_parser.IonexData
   spinifex.ionospheric.ionex_parser.IonexHeader


Functions
---------

.. autoapisummary::

   spinifex.ionospheric.ionex_parser._fill_data_record
   spinifex.ionospheric.ionex_parser._read_ionex_data
   spinifex.ionospheric.ionex_parser._read_ionex_header
   spinifex.ionospheric.ionex_parser._replace_midnight_data
   spinifex.ionospheric.ionex_parser.read_ionex
   spinifex.ionospheric.ionex_parser.unique_days_from_ionex
   spinifex.ionospheric.ionex_parser.unique_days_from_ionex_files


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

.. py:class:: IonexData

   Bases: :py:obj:`NamedTuple`


   Object containing all necessary information from Ionex data


   .. py:attribute:: dims
      :type:  int

      dimension of the heights (usually 1)



   .. py:attribute:: h
      :type:  numpy.typing.NDArray[numpy.float64]

      available heights (km)



   .. py:attribute:: lats
      :type:  numpy.typing.NDArray[numpy.float64]

      array with available latitude values (degrees)



   .. py:attribute:: lons
      :type:  numpy.typing.NDArray[numpy.float64]

      array with available longitude values (degrees)



   .. py:attribute:: rms
      :type:  numpy.typing.NDArray[numpy.float64]

      array with rms of tecvalues times x lons x lats (TECU, if available, nan otherwise)



   .. py:attribute:: tec
      :type:  numpy.typing.NDArray[numpy.float64]

      array with tecvalues times x lons x lats (TECU)



   .. py:attribute:: times
      :type:  astropy.time.Time

      available times



.. py:class:: IonexHeader

   Bases: :py:obj:`NamedTuple`


   Object containing header information from ionex file


   .. py:attribute:: dims
      :type:  int

      dimension of the heights (usually 1)



   .. py:attribute:: h
      :type:  numpy.typing.NDArray[numpy.float64]

      available heights (km)



   .. py:attribute:: lats
      :type:  numpy.typing.NDArray[numpy.float64]

      array with available latitude values (degrees)



   .. py:attribute:: lons
      :type:  numpy.typing.NDArray[numpy.float64]

      array with available longitude values (degrees)



   .. py:attribute:: mfactor
      :type:  float

      multiplication factor for tec values



   .. py:attribute:: times
      :type:  astropy.time.Time

      available times



.. py:function:: _fill_data_record(data: numpy.typing.NDArray[numpy.float64], filep: TextIO, stop_label: str, timeidx: int, ionex_header: IonexHeader) -> None

   Helper function to parse a data block of a single map in ionex.
   Puts filepointer to the end of the map

   Parameters
   ----------
   data : NDArray
       pre allocated array to store the datablock
   filep : TextIO
       _description_
   stop_label : str
       end of the data block indicator
   timeidx : int
       index of time of the data block
   ionex_header : namedtuple
       header information


.. py:function:: _read_ionex_data(filep: TextIO, options: spinifex.ionospheric.tec_data.IonexOptions | None = None) -> IonexData

   This function parses the IONEX file.
   Some fixed structure (like data records being strings of exactly 80 characters) of the file
   is assumed. This structure is described in Schaer and Gurtner (1998).

   Parameters
   ----------
   filep : TextIO
       pointer to an ionex file
   options : IonexOptions | None, optional
       options for ionex model, by default None

   Returns
   -------
   IonexData
       ionex object


.. py:function:: _read_ionex_header(filep: TextIO) -> IonexHeader

   Read header from ionex file. Put filepointer to the end of the header.


.. py:function:: _replace_midnight_data(ionex: IonexData, next_day_ionex: IonexData) -> IonexData

   mtigate jumps in tec value at midnight by inserting the tec value of the next day

   Parameters
   ----------
   ionex : IonexData
       ionex data object
   next_day_ionex : IonexData
       ionex data of the next day

   Returns
   -------
   IonexData
       ionex data object with the data of last timeslot replaced by the data of the next day


.. py:function:: read_ionex(ionex_filename: pathlib.Path, next_day_ionex_filename: pathlib.Path | None = None, options: spinifex.ionospheric.tec_data.IonexOptions | None = None) -> IonexData

   Read and parse a ionex file. Returns a ionex object.

   Parameters
   ----------
   ionex_filename : str
       name of the ionex data file
   next_day_ionex_filename : str| None
       name of the ionex data file for the next day (to remove midnight jumps)
   options : IonexOptions
       Options for the ionex model.
   Returns
   -------
   IonexData
       ionex object with data and grid



.. py:function:: unique_days_from_ionex(ionex_data: IonexData | list[IonexData]) -> astropy.time.Time

   Get unique days from a ionex object or list of ionex objects.

   Parameters
   ----------
   ionex_data : IonexData | list[IonexData]
       ionex object or list of ionex objects

   Returns
   -------
   Time
       unique days


.. py:function:: unique_days_from_ionex_files(ionex_files: list[pathlib.Path] | pathlib.Path) -> astropy.time.Time

   Get unique days from a list of ionex files.

   Parameters
   ----------
   ionex_files : list[Path]
       list of ionex files

   Returns
   -------
   Time
       unique days