gnssvod.io

The functions in this module are intended for advanced users and are used internally by gnssvod.preprocess(). Regular users do not need to call them directly.

class gnssvod.io.Observation(filename=None, epoch=None, observation=None, approx_position=None, receiver_type=None, antenna_type=None, interval=None, receiver_clock=None, version=None, observation_types=None)[source]

GNSS observation object representing a RINEX (*.*o) file.

This class stores the measurements, metadata, and approximate receiver position for a single station and observation file. Objects of this class are returned by preprocessing functions (e.g., gnssvod.preprocess()) and are intended to be used for analysis, subsetting, or conversion to xarray.Dataset.

filename

Name of the source RINEX observation file.

Type:: str

epoch

Timestamp corresponding to the last observation in the file.

Type:: datetime.datetime

observation

DataFrame containing the GNSS measurements. Indexed by Epoch and SV (satellite), with columns corresponding to measurement types (e.g., S1, S2, Azimuth, Elevation).

Type:: pandas.DataFrame

approx_position

Approximate receiver position as Cartesian coordinates [X, Y, Z].

Type:: list of float

receiver_type

Receiver type from the RINEX metadata, if available.

Type:: str

antenna_type

Antenna type from the RINEX metadata, if available.

Type:: str

interval

Measurement interval in seconds.

Type:: float

receiver_clock

Receiver clock offset, if provided.

Type:: float

version

RINEX file version.

Type:: str

observation_types

Names of the measurement types present in observation.

Type:: list of str

to_xarray()[source]: Converts the observation object into an xarray.Dataset with preserved metadata (filename, observation types, epoch, approximate position). Useful for further analysis or exporting to NetCDF.

gnssvod.io.subset_vars(df: DataFrame, keepvars: list, force_epoch_system: bool = True) → DataFrame[source]

Subset an observation DataFrame to keep only selected columns.

This function filters columns of a pandas DataFrame based on a list of variable patterns. Optionally, it ensures that the ‘epoch’ and ‘SYSTEM’ columns are always retained, as they are required for computing GNSS-derived quantities such as Azimuth and Elevation.

Parameters:

df (pandas.DataFrame) – Observation DataFrame, typically obtained from observation.
keepvars (list of str) – List of variable names or patterns to keep. Pattern matching uses Unix shell-style wildcards (see fnmatch.filter()).
force_epoch_system (bool, optional) – If True (default), always retain the ‘epoch’ and ‘SYSTEM’ columns in addition to keepvars. Set to False to keep only columns matching keepvars.

Returns:

Subset of df containing only the requested columns. Rows with all NaNs in the selected columns are dropped.

Return type:

pandas.DataFrame

gnssvod.io.resample_obs(obs: Observation, interval: str) → Observation[source]

Temporally resample an observation object.

This function averages the variables in an Observation over a specified time interval while preserving the multi-index (Epoch/SV) structure. The ‘epoch’ and ‘SYSTEM’ columns are reconstructed after resampling.

Parameters:

obs (Observation) – Observation object to resample. Data are taken from observation.
interval (str) – Resampling interval as a pandas-compatible frequency string (e.g., ’15s’, ‘1min’).

Returns:

The input observation object with the resampled observation DataFrame and updated interval (in seconds).

Return type:

Observation

gnssvod.io.add_azi_ele(obs: Observation, orbit_data: DataFrame | None = None, aux_path: str | None = None) → tuple[Observation, DataFrame][source]

Adds GNSS azimuth and elevation to an Observation object.

This function computes Azimuth and Elevation for all measurements in the provided Observation object. If necessary, it will download orbit and clock data to the directory specified by aux_path.

Parameters:

obs (Observation) – The GNSS observation object to update.
orbit_data (pandas.DataFrame or None, optional) – Precomputed orbit information. If provided and valid, it will be reused to avoid repeated downloads.
aux_path (str or None, optional) – Directory where auxiliary orbit and clock files will be stored or retrieved from. If None, a temporary directory is used.

Returns:

A tuple containing:

Updated Observation object with Azimuth and Elevation columns.
Orbit data used for the computation (may be newly calculated or reused from a previous call).

Return type:

tuple

gnssvod.io.get_filelist(filepatterns: dict) → dict[source]

Retrieve lists of files matching UNIX-style patterns for one or more stations.

Parameters:: filepatterns (dict) – Dictionary mapping station names to file search patterns. Each pattern should be a valid glob expression (e.g., ‘*.O’).
Returns:: Dictionary mapping each station name to a list of matching files. If no files match a given pattern, an empty list is returned.
Return type:: dict

Examples

Single station:

filepatterns = {
    "station1": "/path/to/files/station1/*.O"
}
get_filelist(filepatterns)
# Output:
# {
#     "station1": [
#         "/path/to/files/station1/obs1.O",
#         "/path/to/files/station1/obs2.O"
#     ]
# }

Multiple stations:

filepatterns = {
    "station1": "/path/to/files/station1/*.O",
    "station2": "/path/to/files/station2/*.O"
}
get_filelist(filepatterns)
# Output:
# {
#     "station1": [
#         "/path/to/files/station1/obs1.O",
#         "/path/to/files/station1/obs2.O"
#     ],
#     "station2": [
#         "/path/to/files/station2/obs1.O",
#         "/path/to/files/station2/obs2.O"
#     ]
# }