ephemeris_downloader module

Functions to download Rinex, SP3, and CLK ephemeris files.

Rinex Navigation

Rinex navigation files are pulled from one of five sources. More about rinex files can be found in the CDDIS documentation [1].

If rinex for the current day is requested or if rinex for the previous is requested and it is too early in the UTC day for yesterday’s combined rinex file to be uploaded, then the BRDC00WRD_S rinex 3 file is downloaded from IGS and includes: GPS+GLO+GAL+BDS+QZSS+SBAS.

If only GPS is requested, then the brdc<dddd>.<yy>n rinex 2 file is downloaded from CDDIS and includes: GPS.

If only Glonass is requested, then the brdc<dddd>.<yy>g rinex 2 file is downloaded from CDDIS and includes: GLO.

If the request is for multi-gnss and for a date before Nov. 25, 2019, but after Jan 1, 2013 (the start of multi-gnss) then the BRDM00DLR_R rinex 3 file is downloaded from CDDIS. If multi-gnss is requested for Nov. 25, 2019 or later, then the BRDM00DLR_S rinex 3 file is downloaded from CDDIS. These multi-gnss files include: GPS+GLO+GAL+BDS+QZSS+IRNSS+SBAS. For more information on multi-gnss combined rinex navigation files, see MGEX documentation [2].

SP3 and CLK within Two Weeks

SP3 and CLK files are obtained from CDDIS and produced by either the Center for Orbit Determination in Europe (CODE), GeoForschungsZentrum Potsdam (GFZ) or Wuhan University. Products are available through the MGEX data program [4]. Details on the MGEX precise orbit and clock products can be found on the IGS website [4].

If the SP3 or CLK date requested is within the three days, then the rapid solution from CODE is downloaded (COD0OPSRAP). The CODE rapid solution includes: GPS+GLO+GAL.

If the SP3 or CLK date requested is within the last two weeks, then the rapid solution from GFZ is downloaded (GFZ0MGXRAP). The GFZ rapid solution became available starting GPS week 2038 or Jan 27, 2019. The GFZ rapid solution includes: GPS+GLO+GAL+BDS+QZS. More about the GFZ solution can be found on their MGEX website [8].

SP3 Older than Two Weeks

If the SP3 date requested is more than two weeks previous to the current date and GPS week 1962 or later, then the CODE final solution is downloaded (COD0MGXFIN). The CODE final SP3 solutions became available starting GPS week 1962 or Aug 13, 2017. The CODE final solution includes: GPS+GLO+GAL+BDS+QZS. More about the CODE solution can be found in their papers [6] [7].

If the SP3 date requested is between GPS week 1690 and 1961 or between May 25, 2012 and Aug 12, 2017, then the CODE ‘com’ short name solution is downloaded. More about the CODE ‘com’ solution can be found in their papers [9] [10].

CLK Older than Two Weeks

If the CLK date requested is more than two weeks previous to the current date and GPS week 2113 or later, then the CODE final solution is downloaded (COD0MGXFIN). The CODE final CLK solutions became available starting GPS week 2113 or July 5th, 2020. The CODE final solution includes: GPS+GLO+GAL+BDS+QZS. More about the CODE solution can be found in their papers [6] [7].

If the CLK date requested is between GPS week 2034 and 2112 or between Jan 1, 2019 and July 4th, 2020, then the Wuhan University final solution is downloaded (WUM0MGXFIN). More about the WUM0MGXFIN solution can be found in their documention [11].

If the CLK date requested is week GPS week 2034 and between Dec 30, 2018 and Dec 31, 2018, then the GFZ short name solution is downloaded (gbm). More about the GFZ ‘gbm’ solution can be found in their documentation [13] [14].

If the CLK date requested is between GPS week 1962 and 2033 or between Aug 13, 2017 and Dec 29th, 2018 then the Wuhan University short name solution is downloaded (wum). More about the “wum” solution can be found in their paper [12].

If the CLK date requested is between GPS week 1710 and 1961 or between Oct 14, 2012 and Aug 12, 2017, then the CODE ‘com’ short name solution is downloaded. More about the CODE ‘com’ solution can be found in their papers [9] [10].

IGS Resources

IGS network station information can be found at [3]. IGS files can be viewed online using their file browser [5].

References

ephemeris_downloader.FTP_DOWNLOAD_SOURCECODE = 'FTP_DOWNLOAD_SOURCECODE'

Private FTP functions were pulled from class code.

The functions _ftp_download, _ftp_login, _decompress_file, and _get_rinex_extension were modified from code at: https://github.com/johnsonmitchelld/gnss-analysis/blob/main/gnssutils/ephemeris_manager.py

The associated license is copied below:

BSD 3-Clause License

Copyright (c) 2021, Mitchell D Johnson All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ephemeris_downloader._decompress_file(filepath, remove_compressed=True)[source]

Decompress ephemeris file in same destination.

Parameters:

  • filepath (string) – Local filepath where the compressed ephemeris file is stored and subsequently decompressed.

  • remove_compressed (bool) – If true, will delete the compressed file.

ephemeris_downloader._download_ephemeris(file_type, needed_files, download_directory, verbose=False)[source]

Download ephemeris files.

Parameters:

  • file_type (string) – File type to download either “rinex_nav”, “sp3”, or “clk”.

  • needed_files (list) – List of files to download for ephemeris.

  • download_directory (string or path-like) – Directory where ephemeris files are downloaded if necessary.

  • verbose (bool) – Prints extra debugging statements if true.

Returns:

downloaded_paths – Paths to downloaded and/or existing ephemeris files.

Return type:

string

ephemeris_downloader._extract_ephemeris_dates(file_type, dt_timestamps)[source]

Figure out which dates ephemeris is needed for from datetimes.

Rinex files are only guaranteed to have data for between 02:00 and 22:00. If the timestamp is bewteen 00:00 and 02:00, the previous day will also be included. If after 22:00, the next day will also be included.

To appropriately compute fit satellite position and clock esimates, sp3 and clk files are also pulled for the previous or next day if the timestamps are close to the start or end of the day.

Parameters:

  • file_type (string) – File type to download either “rinex_nav”, “sp3”, or “clk”.

  • dt_timestamps (np.ndarray) – Datetime timestamps.

Returns:

needed_dates – List of datetime.date objects of the days in UTC for which ephemeris needs to be retrieved in order sorted by date.

Return type:

List

ephemeris_downloader._ftp_download(url, ftp_path, dest_filepath, verbose=False)[source]

Copy ephemeris file from FTP filepath to local directory.

Also decompresses file.

Parameters:

  • url (string) – FTP server url.

  • ftp_path (string) – Path to ephemeris file stored on the FTP server.

  • dest_filepath (string) – File path to downloaded ephemeris file are stored locally.

  • verbose (bool) – Prints extra debugging statements if true.

ephemeris_downloader._ftp_login(url, secure=False)[source]

Connect to given FTP server

Parameters:

  • url (String) – URL of FTP server where ephemeris files are stored

  • secure (Bool) – Flag for secure FTP connection

Returns:

ftp – FTP connection object

Return type:

FTP_TLS

ephemeris_downloader._get_rinex_extension(timestamp)[source]

Get file extension of rinex file based on timestamp.

GPS and Glonass Rinex files switched from .Z to .gz on December 1, 2020 [15].

But brdc actually switched on November 30, 2020.

Parameters:

timestamp (datetime.date) – Date of ephemeris file.

Returns:

extension – Extension of compressed ephemeris file.

Return type:

string

References

ephemeris_downloader._valid_ephemeris_in_paths(date, possible_types, file_paths=None)[source]

Check whether a valid ephemeris already exists in file_paths.

See file header for detailed documentation on the methodology on the sources used to downloaded files.

Parameters:

  • date (datetime.date) – Days in UTC for which ephemeris needs to be retrieved.

  • possible_types (list) – What file types would fulfill the requirement in preference order.

  • file_paths (string or path-like) – Paths to existing ephemeris files if they exist.

Returns:

  • valid (bool) – Whether or not a valid ephemeris already exists. If true, then the correct ephemeris file already exists in file_paths. If false, a new file will be downloaded unless file already exists in the download directory.

  • recommended_file (string) – Path to existing file if valid is True, otherwise a tuple containing the url and filepath to the file that should be downloaded.

ephemeris_downloader._verify_ephemeris(file_type, gps_millis, constellations=None, file_paths=None, verbose=False)[source]

Check what ephemeris files to download and if they already exist.

Parameters:

  • file_type (string) – File type to download either “rinex_nav”, “sp3”, or “clk”.

  • gps_millis (float or array-like of floats) – GPS milliseconds for which downloaded ephemeris should be obtained.

  • constellations (list, set, or array-like) – Constellations for which to download ephemeris, i.e. [“gps”].

  • file_paths (string or path-like) – Paths to existing ephemeris files if they exist.

  • verbose (bool) – Prints extra debugging statements if true.

Returns:

  • existing_paths (list) – List of existing paths to files from input that will be used.

  • needed_files (list) – List of files to download for ephemeris.

ephemeris_downloader.load_ephemeris(file_type, gps_millis, constellations=None, file_paths=None, download_directory='/home/docs/checkouts/readthedocs.org/user_builds/gnss-lib-py/checkouts/latest/docs/source/data/ephemeris', verbose=False)[source]

Verify which ephemeris to download if not in file_paths.

Parameters:

  • file_type (string) – File type to download either “rinex_nav”, “sp3”, or “clk”.

  • gps_millis (float or np.ndarray of floats) – GPS milliseconds for which downloaded ephemeris should be obtained.

  • constellations (list, set, or array-like) – Constellations for which to download ephemeris, i.e. [“gps”].

  • file_paths (list, string or path-like) – Paths to existing ephemeris files if they exist.

  • download_directory (string or path-like) – Directory where ephemeris files are downloaded if necessary.

  • verbose (bool) – Prints extra debugging statements if true.

Returns:

file_paths – Paths to downloaded and/or existing ephemeris files. Only files that need to be used are returned. Superfluous path inputs that are not needed are not returned

Return type:

list