pint.toa.get_TOAs

pint.toa.get_TOAs(timfile, ephem=None, include_bipm=None, bipm_version=None, include_gps=None, planets=None, include_pn=True, model=None, usepickle=False, tdb_method='default', picklefilename=None, limits='warn')[source]

Load and prepare TOAs for PINT use.

This is the primary function for loading TOAs from a file.

Loads TOAs from a .tim file, applies clock corrections, computes key values (like TDB), computes the observatory position and velocity vectors, and pickles the file for later use (if requested).

Although .tim files are intended to be quite specific measurements, selecting one of the optional arguments to this function while loading the .tim file changes the interpretation; the .tim file represents different times if different settings are chosen. For nanosecond-level reproducibility it is necessary to specify the options with which each .tim file was loaded. Observatory clock corrections are also applied, and thus the exact result also depends on the precise values in observatory clock correction files; normally these do not change.

Note also that if usepickle is set, the pickled file will have clock corrections and other values set from when it was loaded and these may not correspond to the values you set here.

See pint.toa.TOAs.apply_clock_corrections() for further information on the meaning of the clock correction flags.

If commands like TIME or EQUAD are present in the .tim file, they are applied to the TOAs upon reading and retained in the .commands attribute. Modern usage is to place EQUAD and EFAC in the .par file instead, where they can be fit; these are supported here for historical reasons.

Parameters:

  • timfile (str or list of strings or file-like) – Filename, list of filenames, or file-like object containing the TOA data.

  • ephem (str or None) – The name of the solar system ephemeris to use; defaults to the EPHEM parameter in the timing model (model) if it is given, otherwise defaults to pint.toa.EPHEM_default.

  • include_bipm (bool or None) – Whether to apply the BIPM clock correction. Defaults to True.

  • bipm_version (str or None) – Which version of the BIPM tables to use for the clock correction. The format must be ‘BIPMXXXX’ where XXXX is a year.

  • include_gps (bool or None) – Whether to include the GPS clock correction. Defaults to True.

  • planets (bool or None) – Whether to apply Shapiro delays based on planet positions. Note that a long-standing TEMPO2 bug in this feature went unnoticed for years. Defaults to False.

  • include_pn (bool, optional) – Whether or not to read in the ‘pn’ column (pulse_number)

  • model (pint.models.timing_model.TimingModel or None) – If a valid timing model is passed, model commands (such as BIPM version, planet shapiro delay, and solar system ephemeris) that affect TOA loading are applied. The solar system ephemeris is superseded by the ephem parameter.

  • usepickle (bool) – Whether to try to use pickle-based caching of loaded clock-corrected TOAs objects.

  • tdb_method (str) – Which method to use for the clock correction to TDB. See pint.observatory.Observatory.get_TDBs() for details.

  • picklefilename (str or None) – Filename to use for caching loaded file. Defaults to adding .pickle.gz to the filename of the timfile, if there is one and only one. If no filename is available, or multiple filenames are provided, a specific filename must be provided.

  • limits ("warn" or "error") – What to do when encountering TOAs for which clock corrections are not available.

Returns:

Completed TOAs object representing the data.

Return type:

TOAs