From bfe6dced0103ae60d78d796e85017e22836d5cef Mon Sep 17 00:00:00 2001 From: Nathan <95725385+treefern@users.noreply.github.com> Date: Tue, 21 Jan 2025 07:54:10 +0000 Subject: [PATCH] NPI-3689 fix spelling, update variant selection logic, add preferred_variant option to use when dates can be accomodated by multiple variants --- gnssanalysis/gn_download.py | 84 ++++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 34 deletions(-) diff --git a/gnssanalysis/gn_download.py b/gnssanalysis/gn_download.py index f5f39b3..06aad6a 100644 --- a/gnssanalysis/gn_download.py +++ b/gnssanalysis/gn_download.py @@ -931,17 +931,17 @@ def download_product_from_cddis( return download_filepaths -def download_iau2000_varient( +def download_iau2000_variant( download_dir: _Path, - iau2000_file_varient: Literal["standard", "daily"], + iau2000_file_variant: Literal["standard", "daily"], if_file_present: str = "prompt_user", ) -> Union[_Path, None]: """ - Downloads IAU2000 file based on the varient requested ("daily" or "standard" file). + Downloads IAU2000 file based on the variant requested ("daily" or "standard" file). Added in approximately version 0.0.58 :param _Path download_dir: Where to download file (local directory). - :param Literal["standard", "daily"] iau2000_file_varient: name of file varient to download. Specifies whether to + :param Literal["standard", "daily"] iau2000_file_variant: name of file variant to download. Specifies whether to download the recent "daily" file, or the historical "standard" file. :param str if_file_present: What to do if file already present: "replace", "dont_replace", defaults to "prompt_user" :raises Exception: On download failures. In some cases the underlying exception will be wrapped in the one raised. @@ -951,26 +951,26 @@ def download_iau2000_varient( ensure_folders([download_dir]) filetype = "EOP IAU2000" - if iau2000_file_varient == "daily": + if iau2000_file_variant == "daily": # Daily (recent) file spanning the last three months. Updated daily (as the name suggests). url_dir = "daily/" iau2000_filename = "finals2000A.daily" download_filename = "finals.daily.iau2000.txt" # logging.info("Attempting Download of finals2000A.daily file") - elif iau2000_file_varient == "standard": + elif iau2000_file_variant == "standard": # Standard (historic) IAU2000 file dating back to 1992: url_dir = "standard/" iau2000_filename = "finals2000A.data" download_filename = "finals.data.iau2000.txt" # logging.info("Attempting Download of finals2000A.data file") else: - raise ValueError(f"Unrecognised IAU2000 file varient requested: {iau2000_file_varient}") + raise ValueError(f"Unrecognised IAU2000 file variant requested: {iau2000_file_variant}") # Can we skip this download, based on existing file and value of if_file_present? if not check_whether_to_download( filename=download_filename, download_dir=download_dir, if_file_present=if_file_present ): - return None # No output path for this varient given we didn't download it. + return None # No output path for this variant given we didn't download it. # Default source IERS, then fall back to CDDIS (based on Eugene's comment) try: @@ -1005,13 +1005,16 @@ def download_iau2000_varient( logging.error("Failed to download IAU2000 file from CDDIS.", ex) -def get_iau2000_file_varients_for_dates( +def get_iau2000_file_variants_for_dates( start_epoch: Union[_datetime.datetime, None] = None, end_epoch: Union[_datetime.datetime, None] = None, + preferred_variant: Literal["standard", "daily"] = "daily", ) -> set[Literal["standard", "daily"]]: """ - Works out which varient(s) of IAU2000 files are needed, based on the given start and or end epoch. - The returned varient(s) can be iterated over and passed to the download_iau2000_varient() function to fetch the + Works out which variant(s) of IAU2000 files are needed, based on the given start and or end epoch. If the epoch(s) + entered can be accomodated by both IAU2000 variants, the preferred_variant will be returned (by default this + is 'daily'). + The returned variant(s) can be iterated over and passed to the download_iau2000_variant() function to fetch the file(s). Added in approximately version 0.0.58 @@ -1021,38 +1024,51 @@ def get_iau2000_file_varients_for_dates( :param Union[_datetime.datetime, None] start_epoch: Start of date range. Optional if end_epoch is provided. :param Union[_datetime.datetime, None] end_epoch: End of date range. Optional if start_epoch is provided. - :return set[Literal["standard", "daily"]]: Set of IAU2000 file varient names needed for your date / date range + :param set[Literal["standard", "daily"] preferred_variant: For date ranges where either file variant would work, + which one should be selected. Defaults to the 'daily' file. + :return set[Literal["standard", "daily"]]: Set of IAU2000 file variant names needed for your date / date range """ if not (start_epoch or end_epoch): raise ValueError("start_epoch, end_epoch or both, must be provided") - needed_varients: set[Literal["standard", "daily"]] = set() + needed_variants: set[Literal["standard", "daily"]] = set() now = _datetime.datetime.now() - # TODO double check if they do it by calendar months, or days. If it's calendar months we need to be more conservative; 80 days perhaps. - three_months_ago = now - _datetime.timedelta(days=80) - one_week_ago = now - _datetime.timedelta(weeks=1) - eight_days_ago = now - _datetime.timedelta(days=8) - # To be safe, until we confirm that data makes it into the 'standard' file on day 7 - one_week_ago = eight_days_ago + date_89_days_ago = now - _datetime.timedelta(days=89) + date_8_days_ago = now - _datetime.timedelta(days=8) + # Notes on file variant choice logic: # If the time range overlaps with less than a week ago, you need the daily file (the historical one won't have # new enough data). # Otherwise, the historical file will be more complete. - # TODO but do you actually benefit from the historical file if you're not going more than 3 months back? - # Keeping it simple - # If your timerange includes dates as recent as last week, you need the daily file - # If your timerange includes dates older than three months ago, you need the standard file - # NOTE: you may need both! + # Fundamentally: + # If your timerange includes dates as recent as last week, you need the daily file. + # If your timerange includes dates older than three months ago, you need the standard (historic) file. + # Note that you may need both. - if (start_epoch and start_epoch >= one_week_ago) or (end_epoch and end_epoch >= one_week_ago): - needed_varients.add("daily") + # If start or end epoch within (>=) the date 8 days ago, standard file may not have the data yet, use daily + if (start_epoch and start_epoch >= date_8_days_ago) or (end_epoch and end_epoch >= date_8_days_ago): + needed_variants.add("daily") + # If start or end epoch older (<) the date three months ago, daily file won't have data, use standard file + if (start_epoch and start_epoch <= date_89_days_ago) or (end_epoch and end_epoch <= date_89_days_ago): + needed_variants.add("standard") - if (start_epoch and start_epoch < three_months_ago) or (end_epoch and end_epoch < three_months_ago): - needed_varients.add("standard") + # Default to preferred variant if provided dates weren't within a range that *required* use of one file or the other + if len(needed_variants) == 0: + needed_variants.add(preferred_variant) - return needed_varients + # Is there ambiguity in the date range (start or end not specified)? + + # Start of range was unspecified, we have to assume it may be older than 3 months + if not start_epoch: + needed_variants.add("standard") + + # End of range was unspecified, we have to assume it may be newer than a week + if not end_epoch: + needed_variants.add("daily") + + return needed_variants # TODO DEPRECATED @@ -1065,14 +1081,14 @@ def download_iau2000_file( Compatibility wrapper around new functions DEPRECATED since approximately version 0.0.58 """ - varients = get_iau2000_file_varients_for_dates(start_epoch=start_epoch) - if len(varients) != 1: + variants = get_iau2000_file_variants_for_dates(start_epoch=start_epoch) + if len(variants) != 1: raise NotImplementedError( - "Legacy wrapper for IAU2000 file download failed. Exactly one file varient should be returned based on " + "Legacy wrapper for IAU2000 file download failed. Exactly one file variant should be returned based on " f"a single date ({start_epoch})." ) - varient = varients.pop() - download_iau2000_varient(download_dir=download_dir, iau2000_file_varient=varient, if_file_present=if_file_present) + variant = variants.pop() + download_iau2000_variant(download_dir=download_dir, iau2000_file_variant=variant, if_file_present=if_file_present) def download_atx(