measures_update

measures_update(path=None, version=None, force=False, measures_site=None, logger=None, auto_update_rules=False, use_astron_obs_table=False, verbose=None)[source]

Update or install the IERS data used for measures calculations from measures_site into path.

Original IERS data source used by each of the recommended measures sites is here: https://www.iers.org/IERS/EN/DataProducts/data.html

If no update is necessary then this function will silently return.

The verbose argument controls the level of information provided by this function when the data are unchanged for expected reasons. A level of 0 outputs nothing. A value of 1 sends any output to the logger and a value of 2 logs and prints the information. The default value of the verbose argument is taken from the casaconfig_verbose config value (defaults to 1). Error messages are always logged and printed.

CASA maintains a separate Observatories table which is available in the casarundata collection through pull_data and data_update. The Observatories table found at measures_site is not installed by measures_update and any Observatories file at path will not be changed by using this function. This behavior can be changed by setting force and use_astron_obs_table both to True (use_astron_obs_table is ignored when force is False).

A text file (readme.txt in the geodetic directory in path) records the measures version string, the measures site that was used and the date when that version was installed in path.

If path is None then config.measurespath is used.

If the version requested matches the one in that text file then this function does nothing unless force is True.

If a specific version is not requested (the default) and the modification time of that text file is less than the measures_update_interval config value (days) before now then this function does nothing unless force is True. When this function checks for a more recent version and finds that the installed version is the most recent one then the modification time of that text file is changed to the current time even though nothing has changed in path. This limits the number of attempts to update the measures data (including checking for more recent data) to once every measures_update_interval days. When the force argument is True and a specific version is not requested then this function always checks for the latest version. The measures_update_interval is always used as an int type (including any truncation of the actual value in config if not an integer).

The measures_site is a single URL or a list of URLs to use to find the measures tar file to use in the update. See measures_available for more details on how that parameter is used.

If a specific version is requested then that must match a file in the list returned by measures_available. The version is usually unique at each measures_site and so care may need to be taken when requesting a specific version to ensure that it’s available at measures_site. If measures_site is a list and a specific version is requested then measures_update will try and find that version in each measures_site in that list, using the first site that has that version.

When auto_update_rules is True then path must exist and contain the expected readme.txt file. Path must be owned by the user, force must be False, and the version must be None. This option is used during casatools initialization when measures_auto_update is True. Automatic updating happens during casatools initialization so that the updated measures are in place before any tool needs to use them.

Using measures_update after casatools has started should always be followed by exiting and restarting casa (or the casatools module if modular casa components are being used).

A file lock is used to prevent more that one data update (pull_data, measures_update, or data_update) from updating any files in path at the same time. When locked, the lock file (data_update.lock in path) contains information about the process that has the lock. When measures_update gets the lock it checks the readme.txt file in path to make sure that an update is still necessary (if force is True then an update always happens). If the lock file is not empty then a previous update of path (pull_data, data_update, or measures_update) did not exit as expected and the contents of path are suspect. In that case, an error will be reported and nothing will be updated. The lock file can be checked to see the details of when that file was locked. The lock file can be removed and measures_update can be tried again. It may be safest in that case to remove path completely or use a different path and use pull_data to install a fresh copy of the desired version.

Care should be used when using measures_update outside of the normal automatic update that other casa sessions are not using the same measures at the same time, especially if they may also be starting at that time. If a specific version is requested or force is True there is a risk that the measures may be updated while one of those other sessions are trying to load the same measures data, leading to unpredictable results. The lock file will prevent simultaneous updates from happening but if each simultaneous update eventually updates the same measures location (because force is True or the updates are requesting different versions) then the measures that any of those simultaneous casatools modules sees is unpredictable. Avoid multiple, simultaneous updates outside of the automatic update process.

Note: during auto updates, measures_update requires that the expected readme.txt file already exists in the geodetic directory at path. If that file does not exist or can not be interpreted as expected then measures_update will return without updating any data.

Note: if auto_update_rules is True the user must own path (in addition to having read and write permissions there). The version must then also be None and the force option must be False.

Note: During use outside of auto updates, if path does not exist it will be created by this function.

Note: During use outside of auto updates, if the readme.txt file exists but can not be read as expected OR that file does not exist but the contents of path appear to contain measures data (table names in the expected locations) then this function will print messages describing that and exit without changing anything at path. Using a force value of True will disable this check and install measures at path even if path is not empty or the readme.txt file can not be read. This use of force should be used with caution.

Parameters

  • path (str=None) - Folder path to place updated measures data. Must contain a valid geodetic/readme.txt. If not set then config.measurespath is used.

  • version (str=None) - Version of measures data to retrieve (usually in the form of WSRT_Measures_yyyymmdd-160001.ztar, see measures_available). Default None retrieves the latest.

  • force (bool=False) - If True, always re-download the measures data. Default False will not download measures data if updated within the past day unless the version parameter is specified and different from what was last downloaded.

  • measures_site(str or list of str = None) - Each value is a URL where measures tar files are found. If measures_site is a list then the elements are used in order until a list can be assembled. Default None uses config.measures_site.

  • logger (casatools.logsink=None) - Instance of the casalogger to use for writing messages. Default None writes messages to the terminal

  • auto_update_rules (bool=False) - If True then the user must be the owner of path, version must be None, and force must be False.

  • use_astron_obs_table (bool=False) - If True and force is also True then keep the Observatories table found in the Measures tar tarball (possibly overwriting the Observatories table from casarundata).

  • verbose (int=None) - Level of output, 0 is none, 1 is to logger, 2 is to logger and terminal, defaults to config.casaconfig_verbose.

Returns

None

Raises

  • casaconfig.AutoUpdatesNotAllowed - raised when path does not exists as a directory or is not owned by the user when auto_update_rules is True

  • casaconfig.BadLock - raised when the lock file was not empty when found

  • casaconfig.BadReadme - raised when something unexpected is found in the readme or the readme changed after an update is in progress

  • casaconfig.NoReadme - raised when the readme.txt file is not found at path (path also may not exist)

  • casaconfig.NotWritable - raised when the user does not have permission to write to path

  • casaconfig.NoNetwork - raised by measuers_available or when getting the lock file if there is no network.

  • casaconfig.RemoteError - raised by measures_available when the remote list of measures could not be fetched, not due to no network.

  • casaconfig.UnsetMeasurespath - raised when path is None and has not been set in config

  • Exception - raised when something unexpected happened while updating measures