gnssrefl.utils module

class gnssrefl.utils.FileManagement(station, file_type, year: int | None = None, doy: int | None = None, file_not_found_ok: bool = False, frequency: int | None = None, extension: str = '', snr_type: int | None = None)

Bases: object

FileManagement is designed to easily read the files that this package relies on. Required parameters include station and file_type from FileTypes class. Optional parameters are year, doy, and file_not_found_ok.

find_apriori_rh_file()

Find apriori RH file with backwards compatibility fallback.

Search order: 1. New (registry) format: input/{station}/[{ext}/]{station}_phaseRH_<C>_<label>.txt 2. Pre-registry station-dir format: input/{station}/[{ext}/]{station}_phaseRH_L{1,2,5}.txt 3. Legacy root format: input/{station}_phaseRH[_L1|_L5].txt (L2 has no suffix)

Returns:: (file_path, format_type) where format_type is one of ‘new_format’, ‘preregistry’, ‘legacy’.
Return type:: tuple of (Path, str)

find_daily_avg_phase_file()

Find daily average phase file with backwards compatibility fallback.

Search order: - No extension:

Files/{station}/{station}_phase.txt (new format)

Files/{station}_phase.txt (legacy fallback)

With extension: 1. Files/{station}/{extension}/{station}_phase.txt (new format) 2. Files/{station}_phase.txt (legacy fallback - no extension separation in legacy)

Returns: (Path, str) - (file_path, format_type)

find_json_file()

Find JSON file with backwards compatibility fallback.

Search order (no cross-priority): - No extension:

input/{station}/{station}.json (new format)

input/{station}.json (legacy fallback)

With extension: 1. input/{station}/{extension}/{station}.json (new format) 2. input/{station}.{extension}.json (legacy fallback)

Returns: (Path, str) - (file_path, format_type)

find_snr_file(gzip=None)

Find an SNR file, optionally converting to match the desired storage format.

A .gz is considered trustworthy only when it is non-empty and the uncompressed sibling is absent. A zero-byte .gz, or coexistence of .gz and the uncompressed original, indicates an interrupted gzip run (successful gzip removes the original on completion). In that case the corpse is unlinked and the uncompressed copy is treated as authoritative.

Parameters:: gzip (bool or None) – If None (default): find whatever exists, no conversion. If True: prefer .gz. Compress uncompressed files. If False: prefer uncompressed. Decompress .gz files.
Returns:: tuple
Return type:: (Path, bool) - (file_path, found)

find_volumetric_water_content_file()

Find volumetric water content file with backwards compatibility fallback.

Search order: - No extension:

Files/{station}/{station}_vwc.txt (new format)

Files/{station}_vwc.txt (legacy fallback)

With extension: 1. Files/{station}/{extension}/{station}_vwc.txt (new format) 2. Files/{station}_vwc.txt (legacy fallback - no extension separation in legacy)

Returns: (Path, str) - (file_path, format_type)

get_directory_path(ensure_directory=True)

Get the path of a specific directory from the FileTypes class.

Parameters:: ensure_directory (bool, optional) – If True, creates the directory if it doesn’t exist. Default is True.
Returns:: Directory path requested as a Path object
Return type:: Path

get_file_path(ensure_directory=True)

Get the path of a specific file from the FileTypes class.

Parameters:: ensure_directory (bool, optional) – If True, creates the parent directory if it doesn’t exist. Default is True.
Returns:: File path requested as a Path object
Return type:: Path

get_tracks_file_path()

Path to the multi-GNSS tracks.json file.

Directory structure: - No extension: Files/{station}/tracks.json - With extension: Files/{station}/{extension}/tracks.json

get_vwc_tracks_file_path()

Path to the vwc_tracks.json file written by vwc_input.

Same schema as tracks.json with one added per-epoch field (apriori_RH). Consumed by phase and vwc.

Directory structure: - No extension: Files/{station}/vwc_tracks.json - With extension: Files/{station}/{extension}/vwc_tracks.json

read_file(transpose=False, **kwargs): Reads the requested file amd returns results of file as an array. Can use transpose parameter to transpose the results.

class gnssrefl.utils.FileTypes(value)

Bases: str, Enum

Files to either read from or save to.

apriori_rh_file = 'apriori_rh_file'

arcs_directory = 'arcs_directory'

daily_avg_phase_results = 'daily_avg_phase_results'

directory = 'directory'

gnssir_failqc_result = 'gnssir_failqc_result'

gnssir_result = 'gnssir_result'

individual_tracks = 'individual_tracks'

make_json = 'make_json'

phase_file = 'phase_file'

raw_phase_file = 'raw_phase_file'

snr_file = 'snr_file'

tracks_file = 'tracks_file'

volumetric_water_content = 'volumetric_water_content'

vwc_outputs = 'vwc_outputs'

vwc_tracks_file = 'vwc_tracks_file'

gnssrefl.utils.check_arc_quality(meta, peak_rh, max_amp, noise, station_config): Apply QC filters to a single arc. Returns (passed, fail_reason).

gnssrefl.utils.check_environment()

gnssrefl.utils.circular_distance_deg(a, b)

Shortest angular distance between two azimuths in degrees.

Works with scalars and numpy arrays (via broadcasting).

gnssrefl.utils.circular_mean_deg(angles): Circular mean of angles in degrees, handling the 0/360 wrap correctly.

gnssrefl.utils.format_qc_summary(freq, n_total, qc_counts, n_saved): Build condensed QC summary showing only filters that rejected arcs.

gnssrefl.utils.get_sys()

gnssrefl.utils.pre_check_arc(meta, station_config)

Quick QC check using arc metadata only. Returns (passed, fail_reason).

Checks ediff and delT — no LSP results needed, so call before strip_compute.

gnssrefl.utils.read_files_in_dir(directory, transpose=False): Read all files in a given directory. Directory given must be an absolute path. Returns an n-d array of results. Can use optional parameter transpose to transpose the results.

gnssrefl.utils.set_environment(refl_code, orbits, exe)

gnssrefl.utils.str2bool(args, expected_bools)

gnssrefl.utils.validate_input_datatypes(obj, **kwargs)