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.

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

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_result = 'gnssir_result'

individual_tracks = 'individual_tracks'

make_json = 'make_json'

phase_file = 'phase_file'

snr_file = 'snr_file'

volumetric_water_content = 'volumetric_water_content'

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)