pygnss 2.1.2__cp314-cp314t-macosx_11_0_arm64.whl

pygnss/gnss/edit.py

@@ -0,0 +1,66 @@
+import numpy as np
+import pandas as pd
+
+ARC_ID_FIELD = 'arc_id'
+
+
+def compute_phase_arc_id(data: pd.DataFrame) -> pd.DataFrame:
+    """
+    Computes the phase arc ID, that can be used later to perform operations
+    on a per-arc basis (compute arc bias, ...)
+    """
+
+    data[ARC_ID_FIELD] = data.groupby('signal')['slip'].transform('cumsum')
+
+    return data
+
+
+def mark_time_gap(data: pd.DataFrame, threshold_s: float = 5) -> pd.DataFrame:
+    """
+    Mark a phase cycle slip when the time series show a time gap
+    of a given threshold
+    """
+
+    # Function to mark epochs with a difference > threshold
+    def mark_epochs(group):
+        EPOCH_FIELD = 'epoch'
+        marked = group[EPOCH_FIELD].diff() > pd.Timedelta(seconds=threshold_s)
+        return marked
+
+    # Apply the function per group using groupby
+    marked_epochs = data.groupby('signal').apply(mark_epochs)
+
+    data['slip'] = np.any([data['slip'], marked_epochs], axis=0)
+
+    data = compute_phase_arc_id(data)
+
+    return data
+
+
+def detrend(data: pd.DataFrame, observable: str, n_samples: int) -> pd.DataFrame:
+    """
+    Detrend a given observable by using a rolling window of a certain number of
+    samples
+    """
+
+    trend_column = f'{observable}_trend'
+    detrended_column = f'{observable}_detrended'
+
+    trend = data.groupby(['signal', ARC_ID_FIELD])[observable].transform(lambda x: x.rolling(n_samples).mean())
+    data[trend_column] = trend
+    data[detrended_column] = data[observable] - data[trend_column]
+
+    return data
+
+
+def remove_mean(data: pd.DataFrame, observable: str) -> pd.DataFrame:
+
+    bias_field = f'{observable}_bias'
+    aligned_field = f'{observable}_aligned'
+
+    # For each arch id, compute the median
+    data[bias_field] = data.groupby(['signal', ARC_ID_FIELD])[observable].transform('mean')
+
+    data[aligned_field] = data[observable] - data[bias_field]
+
+    return data

pygnss/gnss/observables.py

@@ -0,0 +1,43 @@
+import pandas as pd
+from .types import ConstellationId, TrackingChannel
+
+def compute_geometry_free(data: pd.DataFrame, constellation: ConstellationId, channel_a: TrackingChannel, channel_b: TrackingChannel) -> pd.DataFrame:
+    """
+    Compute the geometry (ionospheric free combination)
+    """
+
+    columns = ['epoch', 'constellation', 'sat', 'channel', 'signal', 'range', 'phase', 'slip']
+
+    # Create a new dataframe
+    df = data[columns].copy()
+
+    # Create subsets of the DataFrame corresponding to the constellation and each of
+    # the channels selected to build the ionospheric combination
+    df_a = df[(df['constellation'] == constellation.value) & (df['channel'] == str(channel_a))]
+    df_b = df[(df['constellation'] == constellation.value) & (df['channel'] == str(channel_b))]
+
+    # Compute the wavelength of the two tracking channels
+    wl_a = channel_a.get_wavelength(constellation)
+    wl_b = channel_b.get_wavelength(constellation)
+
+    # Use merge to join the two tables
+    df_out = pd.merge(df_a, df_b, on=['epoch', 'sat'], how='inner', suffixes=('_a', '_b'))
+    df_out['li_m'] = df_out['phase_a'] * wl_a - df_out['phase_b'] * wl_b
+    df_out['pi_m'] = df_out['range_b'] - df_out['range_a']
+
+    return df_out
+
+def compute_code_minus_carrier(data: pd.DataFrame) -> pd.DataFrame:
+    """
+    Compute the geometry (ionospheric free combination)
+    """
+
+    # Create a new dataframe
+    df = data.copy()
+
+    # Compute the wavelength
+    df['wl'] = df.apply(lambda row : TrackingChannel.from_string(row['channel']).get_wavelength(row['constellation']), axis=1)
+
+    df['cmc'] = df['range'] - df['phase'] * df['wl']
+
+    return df

pygnss/gnss/residuals.py

@@ -0,0 +1,43 @@
+import datetime
+from typing import List, Tuple, Dict
+
+import pandas as pd
+
+CONSTELLATION_FIELD_STR = 'constellation'
+SAT_FIELD_STR = 'sat'
+EPOCH_FIELD_STR = 'epoch'
+AZIMUTH_FIELD_STR = 'az'
+ELEVATION_FIELD_STR = 'el'
+SNR_FIELD_STR = 'snr_dbHz'
+
+
+class Residuals(object):
+
+    def __init__(self, dataframe):
+        self.df = dataframe
+
+    def get_sat_visibility(self) -> Dict[str, List[Tuple[float, float]]]:
+
+        out = {}
+
+        for sat, group in self.df.groupby(SAT_FIELD_STR):
+            # FIXME this should take into account channel to avoid overwriting the info from different channels
+            out[sat] = list(zip(group[AZIMUTH_FIELD_STR], group[ELEVATION_FIELD_STR], group[SNR_FIELD_STR]))
+
+        return out
+
+    def get_constellation_count(self) -> List[Tuple[datetime.datetime, dict]]:
+
+        n_sats = []
+
+        for epoch, epoch_group in self.df.groupby(EPOCH_FIELD_STR):
+            n_sats_per_epoch = {}
+            for constellation, df in epoch_group.groupby(CONSTELLATION_FIELD_STR):
+                n_sats_per_epoch[constellation] = len(pd.unique(df[SAT_FIELD_STR]))
+
+            n_sats.append((epoch.to_pydatetime(), n_sats_per_epoch))
+
+        return n_sats
+
+    def __len__(self):
+        return len(self.df)

pygnss/gnss/types.py

@@ -0,0 +1,359 @@
+from enum import Enum
+from dataclasses import dataclass
+from typing import List, Union
+
+from pygnss.constants import SPEED_OF_LIGHT
+from pygnss.decorator import deprecated
+
+
+class ConstellationId(Enum):
+    UNKNOWN: str = '0'
+    GPS: str = 'G'
+    GALILEO: str = 'E'
+    GLONASS: str = 'R'
+    BEIDOU: str = 'C'
+    QZSS: str = 'J'
+    IRNSS: str = 'I'
+    SBAS: str = 'S'
+    LEO: str = 'L'
+    XONA: str = 'P'
+    GEELY: str = 'Y'
+    STARLINK: str = 'X'
+    ONEWEB: str = 'O'
+    SPIRE: str = 'V'
+    CENTISPACE: str = 'Z'
+
+    @staticmethod
+    def from_string(constellation_char: str) -> 'ConstellationId':
+        """
+        Returns the corresponding ConstellationId from input character
+
+        >>> ConstellationId.from_string('E')
+        <ConstellationId.GALILEO: 'E'>
+        """
+        try:
+            return ConstellationId(constellation_char)
+        except ValueError:
+            raise ValueError(f"Invalid constellation character: {constellation_char}")
+
+    def to_char(self):
+        """
+        Constellation representation as character
+
+        >>> c = ConstellationId.GPS
+        >>> c.to_char()
+        'G'
+        """
+
+        return self.value
+
+    def __lt__(self, other):
+        """
+        Less operator for the ConstellationId class
+
+        >>> c1 = ConstellationId.GPS
+        >>> c2 = ConstellationId.IRNSS
+        >>> c1 < c2
+        True
+        >>> c2 < c1
+        False
+        >>> c2 < 0
+        Traceback (most recent call last):
+        ...
+        TypeError: '<' not supported between instances of 'ConstellationId' and 'int'
+        """
+
+        if isinstance(other, ConstellationId):
+            return self.value < other.value
+        return NotImplemented
+
+
+class Band:
+    """
+    Namespace to define the supported bands (center frequency in Hz)
+    """
+
+    L1 = 1575420000
+    L2 = 1227600000
+    L5 = 1176450000
+    L6 = 1278750000
+    G1 = 1602000000
+    G1a = 1600995000
+    G2 = 1246000000
+    G2a = 1248060000
+    G3 = 1202025000
+    E1 = 1575420000
+    E5a = 1176450000
+    E5b = 1207140000
+    E5 = 1191795000
+    E6 = 1278750000
+    B1_2 = 1561098000
+    B1 = 1575420000
+    B2a = 1176450000
+    B2b = 1207140000
+    B2 = 1191795000
+    B3 = 1268520000
+    S = 2492028000
+
+    def __init__(self):
+        """
+        Init the class (does nothing)
+        """
+        pass
+
+    @staticmethod
+    def get_freq_from_rinex_band(constellation: Union[ConstellationId, str], rinex_band: int) -> int:
+        """
+        Get the band from the RINEX band number (and constellation)
+
+        >>> Band.get_freq_from_rinex_band(ConstellationId.GPS, 1)
+        1575420000
+        >>> Band.get_freq_from_rinex_band('G', 1)
+        1575420000
+        >>> Band.get_freq_from_rinex_band(ConstellationId.GALILEO, 5)
+        1176450000
+        >>> Band.get_freq_from_rinex_band('E', 5)
+        1176450000
+        >>> Band.get_freq_from_rinex_band(ConstellationId.GPS, 8)
+        Traceback (most recent call last):
+        ...
+        ValueError: Invalid band 8 for constellation ConstellationId.GPS
+        """
+
+        band = None
+
+        if isinstance(constellation, ConstellationId) == True:
+            constellation = constellation.value
+
+        if constellation == ConstellationId.GPS.value:
+            if rinex_band == 1:
+                band = Band.L1
+            elif rinex_band == 2:
+                band = Band.L2
+            elif rinex_band == 5:
+                band = Band.L5
+            elif rinex_band == 6:
+                band = Band.L6
+
+        elif constellation == ConstellationId.GLONASS.value:
+            if rinex_band == 1:
+                band = Band.G1
+            elif rinex_band == 4:
+                band = Band.G1a
+            elif rinex_band == 2:
+                band = Band.G2
+            elif rinex_band == 6:
+                band = Band.G2a
+            elif rinex_band == 3:
+                band = Band.G3
+
+        elif constellation == ConstellationId.GALILEO.value:
+            if rinex_band == 1:
+                band = Band.E1
+            elif rinex_band == 5:
+                band = Band.E5a
+            elif rinex_band == 7:
+                band = Band.E5b
+            elif rinex_band == 8:
+                band = Band.E5
+            elif rinex_band == 6:
+                band = Band.E6
+
+        elif constellation == ConstellationId.BEIDOU.value:
+            if rinex_band == 2:
+                band = Band.B1_2
+            elif rinex_band == 1:
+                band = Band.B1 = 1575420000
+            elif rinex_band == 5:
+                band = Band.B2a = 1176450000
+            elif rinex_band == 7:
+                band = Band.B2b = 1207140000
+            elif rinex_band == 8:
+                band = Band.B2 = 1191795000
+            elif rinex_band == 6:
+                band = Band.B3 = 1268520000
+
+        elif constellation == ConstellationId.IRNSS.value:
+            if rinex_band == 5:
+                band = Band.L5
+            elif rinex_band == 9:
+                band = Band.S
+
+        elif constellation == ConstellationId.SBAS.value:
+            if rinex_band == 1:
+                band = Band.L1
+            elif rinex_band == 5:
+                band = Band.L5
+
+        elif constellation == ConstellationId.QZSS.value:
+            if rinex_band == 1:
+                band = Band.L1
+            elif rinex_band == 2:
+                band = Band.L2
+            elif rinex_band == 5:
+                band = Band.L5
+            elif rinex_band == 6:
+                band = Band.L6
+
+        if not band:
+            raise ValueError(f'Invalid band {rinex_band} for constellation {ConstellationId.from_string(constellation)}')
+
+        return band
+
+
+@dataclass
+class TrackingChannel(object):
+    band: int
+    attribute: str
+
+    @staticmethod
+    @deprecated("from_rinex3_code")
+    def from_observable_type(observable_type: str) -> 'TrackingChannel':
+        """
+        Deprecated: This function is deprecated and will be removed in the future.
+        Use the from_rinex3_code() method instead.
+
+        Extract the tracking channel from a RINEX3 observable type
+        """
+
+        return TrackingChannel.from_rinex3_code(observable_type)
+
+    @staticmethod
+    def from_rinex3_code(observable_code: str) -> 'TrackingChannel':
+        """
+        Extract the tracking channel from a RINEX3 observable type
+
+        >>> TrackingChannel.from_rinex3_code('C1C')
+        1C
+        """
+
+        return TrackingChannel.from_string(observable_code[1:])
+
+    @staticmethod
+    def from_string(observable_code: str) -> 'TrackingChannel':
+        """
+        Extract the tracking channel from a string that indicates the tracking
+        channel based on the last two characters of the corresponding RINEX3
+        code
+
+        >>> TrackingChannel.from_string('1C')
+        1C
+        """
+
+        band = int(observable_code[0])
+        attribute = observable_code[1]
+        return TrackingChannel(band, attribute)
+
+    def get_frequency(self, constellation: Union[ConstellationId, str]) -> int:
+        """
+        Get the frequency (in Hz) from the tracking channel band
+
+        >>> ch = TrackingChannel(1, 'C')
+        >>> ch.get_frequency(ConstellationId.GPS)
+        1575420000
+        >>> ch.get_frequency('G')
+        1575420000
+        """
+        return Band.get_freq_from_rinex_band(constellation, self.band)
+
+    def get_wavelength(self, constellation: Union[ConstellationId, str]) -> Band:
+        """
+        Get the wavelength (in meters) from the tracking channel band
+
+        >>> ch = TrackingChannel(1, 'C')
+        >>> wl_m = ch.get_wavelength(ConstellationId.GPS)
+        >>> int(wl_m * 100)
+        19
+        >>> wl_m = ch.get_wavelength('G')
+        >>> int(wl_m * 100)
+        19
+        """
+        return SPEED_OF_LIGHT / self.get_frequency(constellation)
+
+    def __eq__(self, other: 'TrackingChannel') -> bool:
+        return self.band == other.band and self.attribute == other.attribute
+
+    def __lt__(self, other: 'TrackingChannel') -> bool:
+        return self.attribute < other.attribute if self.band == other.band else self.band < other.band
+
+    def __repr__(self):
+        return f'{self.band:1d}{self.attribute:1s}'
+
+    def __hash__(self) -> int:
+        return hash((self.band, self.attribute))
+
+
+INVALID_TRACKING_CHANNEL = TrackingChannel(0, '0')
+
+
+class ChannelCode(Enum):
+    c_1C: str = "1C"
+    c_5Q: str = "5Q"
+
+
+@dataclass
+class Satellite:
+    constellation: ConstellationId
+    prn: int
+
+    @staticmethod
+    def from_string(satellite: str) -> 'Satellite':
+        constellation = ConstellationId.from_string(satellite[0])
+        prn = int(satellite[1:3])
+        return Satellite(constellation, prn)
+
+    def __lt__(self, other: 'Satellite') -> bool:
+        return self.prn < other.prn if self.constellation == other.constellation else self.constellation < other.constellation
+
+    def __eq__(self, other: 'Satellite') -> bool:
+        return self.constellation == other.constellation and self.prn == other.prn
+
+    def __hash__(self):
+        return hash(self.constellation) + self.prn
+
+    def __repr__(self) -> str:
+        return f"{self.constellation.value:1s}{self.prn:02d}"
+
+
+@dataclass
+class Signal:
+    satellite: Satellite
+    channel: ChannelCode
+
+    def __repr__(self) -> str:
+        return f"{self.satellite}{self.channel.value}"
+
+
+class GnssSystem:
+    constellation_id: ConstellationId
+    number_satellites: int
+    channels: List[ChannelCode]
+    signals: List[Signal]
+
+    def __init__(self, constellation_id: ConstellationId, number_satellites: int, channels: List[ChannelCode]):
+        self.constellation_id = constellation_id
+        self.number_satellites = number_satellites
+        self.channels = channels
+        self.signals = self.get_signals()
+
+    def get_signals(self) -> List[Signal]:
+        signals = []
+        for index in range(1, self.number_satellites + 1):
+            for channel in self.channels:
+                signals.append(Signal(Satellite(self.constellation_id, index), channel))
+
+        return signals
+
+
+@dataclass
+class GnssSystems:
+    gnss_systems: List[GnssSystem]
+
+    def get_constellations(self) -> List[str]:
+        return [system.constellation_id.value for system in self.gnss_systems]
+
+    def get_signals(self) -> List[Signal]:
+        signals = []
+        for system in self.gnss_systems:
+            signals.extend(system.get_signals())
+        return signals

pygnss/hatanaka.py

@@ -0,0 +1,70 @@
+import gzip
+import pandas as pd
+import tempfile
+
+try:
+    from pygnss._c_ext import _read_crx  # compiled C extension for fast CRX parsing
+except Exception as exc:  # pragma: no cover - environment-specific
+    _import_err = exc
+
+    def _read_crx(*args, **kwargs):
+        """Fallback stub when the compiled extension is missing.
+
+        The real implementation lives in the compiled extension module
+        ``pygnss._c_ext``. If that extension isn't available (for example on
+        CI or when the package wasn't built/installed), attempting to read a
+        CRX file will raise a clear ImportError with instructions.
+        """
+        raise ImportError(
+            "pygnss C extension 'pygnss._c_ext' is not available.\n"
+            "To enable Hatanaka (.crx) parsing, build and install the package so\n"
+            "that the compiled extension is present (e.g. running 'pip install .',\n"
+            "or building the wheel in your CI).\n"
+            f"Original import error: {type(_import_err).__name__}: {_import_err}"
+        ) from _import_err
+
+def to_dataframe(filename:str, station:str = "none", strict_lli: bool = True) -> pd.DataFrame:
+    """
+    Convert a Compressed (crx.gz) or uncompressed (crx) Hatanaka file into a
+    DataFrame
+
+    :param filename: Hatanaka [gzip compressed] filename
+    :param station: force station name
+    :param strict_lli: Mark cycle slips only when Phase LLI is 1 (as per RINEX convention).
+    If False, any value of Phase LLI will trigger a cycle slip flag
+    """
+
+    if filename.endswith('crx.gz') or filename.endswith('crx.Z') or filename.endswith('crz'):
+        try:
+            with gzip.open(filename, 'rb') as f_in:
+                with tempfile.NamedTemporaryFile(delete=False) as f_out:
+                    f_out.write(f_in.read())
+                    f_out.seek(0)
+                    array = _read_crx(f_out.name)
+        except gzip.BadGzipFile:
+            raise ValueError(f"{filename} is not a valid gzip file.")
+
+    else:
+        array = _read_crx(filename)
+
+    df = pd.DataFrame(array, columns=['epoch', 'sat', 'rinex3_code', 'value', 'lli'])
+    df['channel'] = df['rinex3_code'].str[-2:]
+    df['signal'] = df['sat'] + df['channel']
+    MAPPING = {'C': 'range', 'L': 'phase', 'D': 'doppler', 'S': 'snr'}
+    df['obstype'] = df['rinex3_code'].str[0].map(lambda x: MAPPING.get(x, 'Unknown'))
+    df = df.pivot_table(index=['epoch', 'signal', 'sat', 'channel'], columns=['obstype'], values=['value', 'lli'])
+
+    # Remove all LLI columns except for the phase (for the cycle slips)
+    if strict_lli:
+        df['cslip'] = (df.loc[:, pd.IndexSlice['lli', 'phase']] % 2) == 1
+    else:
+        df['cslip'] = df.loc[:, pd.IndexSlice['lli', 'phase']] > 0
+
+    df.drop('lli', axis=1, inplace=True)
+    df.columns = [v[1] if v[0] == 'value' else v[0] for v in df.columns.values]
+
+    df.reset_index(inplace=True)
+
+    df['station'] = station
+
+    return df