pint.toa.TOAs
- class pint.toa.TOAs(toafile: str | None = None, toalist: List[TOA] | None = None, toatable: Table | None = None, tzr: bool = False)[source]
Bases:
object
A class of multiple TOAs, loaded from zero or more files.
Normally these objects should be read from a file with
pint.toa.get_TOAs()
. Constructing them with the constructor here does not apply the clock corrections and the resulting TOAs object may not be set up the way one would normally expect.The contents are stored in an
astropy.table.Table
. Not all columns of the table are computed automatically, as their computation can be expensive. Methods of this class are available to populate these additional columns. Methods that return data from the columns do so in the internal order.TOAs objects can accept indices that are boolean, list-of-integer, or slice, to produce a new TOAs object containing a subset of the TOAs in the original. For example, to obtain a new TOAs object containing the entries above 1 GHz:
>>> t[t.table['freq'] > 1*u.GHz]
TOAs objects also accept indexing to select columns or flags, so that for example
t['mjd']
returns theColumn
contained in the object, andt['fish']
returns an array of strings that has the value associated with the flag-fish
for each TOA that has that flag or the empty string for each TOA that doesn’t. TOAs objects also support assignment through these methods:>>> t['high', t['freq'] > 1*u.GHz] = "1"
TOAs used to be grouped by observatory, but currently are not. To iterate over all observatory groups:
>>> for obs,idx in t.get_obs_groups():
Or to actually reorder the TOAs by observatory:
>>> t.table.group_by("obs")
Other sorting is fine too:
>>> t.table.sort("freq")
Columns in .table
Name
Contents
index
location of the TOA in the original input
mjd
the exact time of arrival (an
astropy.time.Time
object)mjd_float
the time of arrival in floating-point (may be microseconds off)
error
the standard error (an
astropy.units.Quantity
describing the claimed uncertainty on the pulse arrival time)freq
the observing frequency (an
astropy.units.Quantity
)obs
the observatory at which the TOA was acquired (a
pint.observatory.Observatory
object)flags
free-form flags associated with the TOA (a dictionary mapping flag to value)
tdb
the pulse arrival time converted to TDB (but not barycentered, that is, not corrected for light travel time; an
astropy.time.Time
object); computed bypint.toa.TOAs.compute_TDBs()
tdbld
a
longdouble
version oftdb
for computational conveniencessb_obs_pos
,ssb_obs_vel
position and velocity of the observatory at the time of the TOA; computed by
pint.toa.TOAs.compute_posvels()
ssb_obs_vel_ecl
velocity of the observatory in ecliptic coordinates at the time of the TOA; computed by
pint.toa.TOAs.add_vel_ecl()
obs_sun_pos
,obs_jupiter_pos
,obs_saturn_pos
,obs_venus_pos
,obs_uranus_pos
,obs_neptune_pos
,obs_earth_pos
position of various celestial objects at the time of the TOA; computed by
pint.toa.TOAs.compute_posvels()
pulse_number
integer number of turns since a fiducial moment; optional; can be computed from a model with
pint.toa.TOAs.compute_pulse_numbers()
or extracted from thepn
entry inflags
withpint.toa.TOAs.phase_columns_from_flags()
. If it is present for some TOAs but not all, missing values are filled withNaN
.delta_pulse_number
number of turns to adjust pulse number by, compared to the model;
PHASE
statements in the.tim
file or thepadd
entry inflags
carry this information, andpint.toa.TOAs.phase_columns_from_flags()
creates the column.- Parameters:
toafile (str, optional) – Filename to load TOAs from.
toalist (list of TOA objects, optional) – The TOA objects this TOAs should contain.
toatable (astropy.table.Table, optional) – An existing TOA table
tzr (bool) – Whether the TOAs object corresponds to a TZR TOA
provided. (Exactly one of these three parameters must be) –
- Variables:
table (astropy.table.Table) – The data for all the TOAs.
commands (list of str) – “Commands” that were written in the file; these will have affected how some or all TOAs were interpreted during loading.
filename (str, optional) – The filename (if any) that the TOAs were loaded from.
planets (bool) – Whether planetary Shapiro delay should be considered.
ephem (object) – The Solar System ephemeris in use.
clock_corr_info (dict) – Information about the clock correction chains in use.
merged (bool) – If this object was merged from several files (and thus the filename of the first is not useful for referring to the whole object).
hashes (dict) – A dictionary of hashes of the files this data was read from (if any). This is used by
check_hashes()
to verify whether the data on disk has changed so that the file can be re-read if necessary.was_pickled (bool) – Whether this file was loaded from a pickle.
alias_translation (dict or None) – Translate observatory names by looking them up in this dictionary; this may be necessary to convert observatory names into something TEMPO can understand, or to cope with different setups using different names for the same observatory or the same name for different observatories. There is a dictionary
tempo_aliases
available to use names as compatible with TEMPO as possible.wideband (bool) – Whether the TOAs also have wideband DM information
tzr (bool) – Whether the TOAs object corresponds to a TZR TOA
Methods
add_vel_ecl
(obliquity)Compute and add a column to self.table with velocities in ecliptic coordinates.
adjust_TOAs
(delta)Apply a time delta to TOAs.
apply_clock_corrections
([include_bipm, ...])Apply observatory clock corrections and TIME statments.
check_hashes
([timfile])Determine whether the input files are the same as when loaded.
compute_TDBs
([method, ephem])Compute and add TDB and TDB long double columns to the TOA table.
compute_posvels
([ephem, planets])Compute positions and velocities of the observatories and Earth.
compute_pulse_numbers
(model)Set pulse numbers (in TOA table column pulse_numbers) based on model.
get_Tspan
()Return a list of all the flags used by any TOA.
get_clusters
([gap_limit, add_column, add_flag])Identify toas within gap limit (default 2h = 0.0833d) of each other as the same cluster.
Get the Wideband DM data error.
get_dms
()Get the Wideband DM data.
Return a numpy array of the TOA errors in us.
get_flag_value
(flag[, fill_value, as_type])Get the requested TOA flag values.
Return a numpy array of the TOA flags.
Return a
Quantity
of the observing frequencies for the TOAs.get_highest_density_range
([ndays])Print the range of mjds (default 7 days) with the most toas
get_mjds
([high_precision])Array of MJDs in the TOAs object.
Return an iterator over the different observatories
get_obss
()Return a numpy array of the observatories for each TOA.
Return a numpy array of the pulse numbers for each TOA if they exist.
Return a short ASCII summary of the TOAs.
Whether or not the data have wideband TOA values
merge
(t, *args[, strict])Merge TOAs instances into the existing object
Create and/or modify pulse_number and delta_pulse_number columns.
Prints self.get_summary().
Delete pulse numbers from TOA data
renumber
([index_order])Recreate the index column so the values go from 0 to len(self)-1.
select
(selectarray)Apply a boolean selection or mask array to the TOA table.
to_TOA_list
([undo_clkcorr])Turn a
pint.toa.TOAs
object into a list ofpint.toa.TOA
objectsunselect
()Return to previous selected version of the TOA table (stored in stack).
update_all_times
([tdb_method])Update the various derived time columns
Update the
mjd_float
column from themjd
columnwrite_TOA_file
(filename[, name, format, ...])Write this object to a
.tim
file.Attributes
The first MJD, in
Time
format.The last MJD, in
Time
format.The number of TOAs.
The set of observatories in use by these TOAs.
Whether or not the data have wideband TOA values
- to_TOA_list(undo_clkcorr: bool = True) List[TOA] [source]
Turn a
pint.toa.TOAs
object into a list ofpint.toa.TOA
objectsThis effectively undoes
pint.toa.get_TOAs_list()
, optionally undoing clock corrections too- Parameters:
clkcorr (bool, optional) – Whether or not to undo any clock corrections
- Returns:
Of
pint.toa.TOA
objects- Return type:
- get_mjds(high_precision: bool = False) Quantity [source]
Array of MJDs in the TOAs object.
With high_precision is True Return an array of the astropy.times (UTC) of the TOAs
With high_precision is False Return an array of toas in mjd as double precision floats
WARNING: Depending on the situation, you may get MJDs in a different scales (e.g. UTC, TT, or TDB) or even a mixture of scales if some TOAs are barycentred and some are not (a perfectly valid situation when fitting both Fermi and radio TOAs)
- get_pulse_numbers() Column | None [source]
Return a numpy array of the pulse numbers for each TOA if they exist.
- get_flag_value(flag: str, fill_value: str | None = None, as_type: type | None = None) Tuple[List[str], List[int]] [source]
Get the requested TOA flag values.
- Parameters:
flag_name (str) – The request flag name.
fill_value – The value to include for missing flags.
as_type (callable or None) – If provided, this is called on each value to convert them from to the desired type. All flag values are stored as strings internally.
- Returns:
values (list) – A list of flag values from each TOA. If the TOA does not have the flag, it will fill up with the fill_value.
valid_index (list) – The indices, in
self.table
, of the places where the flag values occur.
- get_dms() Quantity [source]
Get the Wideband DM data.
Note
This does not handle situations where some but not all TOAs have DM information.
- get_dm_errors() Quantity [source]
Get the Wideband DM data error.
Note
This does not handle situations where some but not all TOAs have DM information.
- get_clusters(gap_limit=<Quantity 2. h>, add_column=False, add_flag=None) ndarray [source]
Identify toas within gap limit (default 2h = 0.0833d) of each other as the same cluster.
Clusters can be larger than the gap limit - if toas are separated by a gap larger than the gap limit, a new cluster starts and continues until another such gap is found.
Cluster info can be added as a
clusters
column to thepint.toa.TOAs.table
object if add_column is True. Cluster info can also be added as a flag with name specified. In those casesself.table.meta['cluster_gap']
will be set to the gap_limit. If the desired clustering corresponds to that inpint.toa.TOAs.table
then that column is returned.- Parameters:
gap_limit (astropy.units.Quantity, optional) – The minimum size of gap to create a new cluster. Defaults to two hours.
add_column (bool, optional) – Whether or not to add a
clusters
column to the TOA table (default: False)add_flag (str, optional) – If not
None
, will add a flag with that name to the TOA table whose value is the cluster number (as a string, starting at 0) (default: None)
- Returns:
clusters – The cluster number associated to each TOA. Clusters are numbered chronologically from zero.
- Return type:
- get_highest_density_range(ndays=<Quantity 7. d>) Tuple[Quantity, Quantity] [source]
Print the range of mjds (default 7 days) with the most toas
- check_hashes(timfile=None) bool [source]
Determine whether the input files are the same as when loaded.
- Parameters:
timfile (str or list of str or file-like or None) – If provided this should match the list of files the TOAs object was loaded from. If this is a string or list of strings, and the number matches the number of files this TOAs object was loaded from, it is assumed that these are supposed to be the same files, re-named or moved; their contents are then checked. If the contents or the number doesn’t match, this function returns False.
- Returns:
True if the contents of the TOAs object matches the content of the files.
- Return type:
- select(selectarray)[source]
Apply a boolean selection or mask array to the TOA table.
Deprecated. Use
toas[selectarray]
to get a new object instead.This operation modifies the TOAs object in place, shrinking its table down to just those TOAs where selectarray is True. This function also stores the old table in a stack.
- unselect()[source]
Return to previous selected version of the TOA table (stored in stack).
Deprecated. Use
toas[selectarray]
to get a new object instead.
- get_summary() str [source]
Return a short ASCII summary of the TOAs.
This includes summary information about the errors and frequencies but is never more than a few lines regardless of how many TOAs there are.
- phase_columns_from_flags()[source]
Create and/or modify pulse_number and delta_pulse_number columns.
Scans pulse numbers from the table flags and creates a new table column. Modifes the
delta_pulse_number
column, if required. Removes the pulse numbers from the flags.
- compute_pulse_numbers(model: TimingModel) None [source]
Set pulse numbers (in TOA table column pulse_numbers) based on model.
Replace any existing pulse numbers by computing phases according to model and then setting the pulse number of each to their integer part, which the nearest integer since Phase objects ensure that.
- Parameters:
model (pint.models.timing_model.TimingModel) – The model defining times of arrival; the pulse numbers assigned will be the nearest integer number of turns to that predicted by the model.
- adjust_TOAs(delta: TimeDelta | Quantity) None [source]
Apply a time delta to TOAs.
Adjusts the time (MJD) of the TOAs by applying delta, which should be a scalar or have the same shape as
self.table['mjd']
. This function does not change the pulse numbers column, if present, but does recomputemjd_float
, the TDB times, and the observatory positions and velocities.- Parameters:
delta (astropy.time.TimeDelta or astropy.units.Quantity) – The time difference to add to the MJD of each TOA
- renumber(index_order=True) None [source]
Recreate the index column so the values go from 0 to len(self)-1.
This modifies the TOAs object and also returns it, for calling convenience.
- Parameters:
index_order (bool) – If True, preserve the order of the index column, but renumber so there are no gaps. If False, number according to the order TOAs occur in the object.
- Return type:
self
- write_TOA_file(filename, name='unk', format='tempo2', commentflag=None, order_by_index=True, *, include_pn=True, include_info=True, comment=None) None [source]
Write this object to a
.tim
file.This function writes the contents of this object to a (single)
.tim
file. IfTEMPO2
format is used, this file is able to represent the contents of this object to nanosecond level. NoTIME
orEFAC
commands are emitted.- Parameters:
filename (str or file-like) – File name to write to; can be an open file object
name (str) – Value to put in the “name” field of tempo2 files, if a “-name” flag is not available.
format (str) – Format specifier for file (‘TEMPO’ or ‘Princeton’) or (‘Tempo2’ or ‘1’); note that not all features may be supported in ‘TEMPO’ mode.
commentflag (str or None) – If a string, and that string is a TOA flag, that TOA will be commented in the output file. If None (or non-string), no TOAs will be commented.
order_by_index (bool) – If True, write the TOAs in the order specified in the “index” column (which is usually the same as the original file); if False, write them in the order they occur in the TOAs object.
include_pn (bool, optional) – Include pulse numbers (if available)
include_info (bool, optional) – Include information string if True
comment (str, optional) – Additional string to include in TOA file
- apply_clock_corrections(include_bipm=True, bipm_version='BIPM2023', limits='warn') None [source]
Apply observatory clock corrections and TIME statments.
Apply clock corrections to all the TOAs where corrections are available. This routine actually changes the value of the TOA, although the correction is also listed as a new flag for the TOA called ‘clkcorr’ so that it can be reversed if necessary. This routine also applies all ‘TIME’ commands (
-to
flags) and treats them exactly as if they were a part of the observatory clock corrections.If the clock corrections have already been applied they will not be re-applied.
A description of how PINT handles clock corrections and timescales is here: https://github.com/nanograv/PINT/wiki/Clock-Corrections-and-Timescales-in-PINT
- compute_TDBs(method='default', ephem: str | None = None) None [source]
Compute and add TDB and TDB long double columns to the TOA table.
This routine creates new columns ‘tdb’ and ‘tdbld’ in a TOA table for TDB times, using the Observatory locations and IERS Earth rotation corrections for UT1.
If these columns are already present, delete and replace them.
- Parameters:
method (str) – Which method to use. See
pint.observatory.Observatory.get_TDBs()
for details.ephem (str or None) – Solar System ephemeris to use for the computation. If not specified use the value in
self.ephem
if available, else usepint.toa.EPHEM_default
If specified, replaceself.ephem
.
- compute_posvels(ephem: str | None = None, planets: bool | None = None)[source]
Compute positions and velocities of the observatories and Earth.
Compute the positions and velocities of the observatory (wrt the Geocenter) and the center of the Earth (referenced to the SSB) for each TOA. The JPL solar system ephemeris can be set using the ‘ephem’ parameter. The positions and velocities are set with PosVel class instances which have astropy units.
If the required columns already exist, they will be replaced.
- Parameters:
ephem (str) – The Solar System ephemeris to use; if not specified, use the default ephemeris for the TOAs object. If specified, replace the TOAs object’s
ephem
attribute with this value and do the computation.planets (bool) – Whether to compute positions for the Solar System planets. If not specified, use the value stored in
self.planets
; if specified, setself.planets
to this value.
- add_vel_ecl(obliquity) None [source]
Compute and add a column to self.table with velocities in ecliptic coordinates.
Called in barycentric_radio_freq() in AstrometryEcliptic (astrometry.py) if ssb_obs_vel_ecl column does not already exist. If compute_posvels() called again for a TOAs object (aka TOAs modified), deletes this column so that this function will be called again and velocities will be calculated with updated TOAs.
- update_all_times(tdb_method: str = 'default') None [source]
Update the various derived time columns
Updates:
mjd_float
tdb
tdbld
ssb_obs_pos
ssb_obs_vel
obs_sun_pos
obs_*_pos
ifplanets
isTrue
ssb_obs_vel_ecl
ifobliquity
is notNone
- Parameters:
tdb_method (str) – Which method to use for the clock correction to TDB. See
pint.observatory.Observatory.get_TDBs()
for details.
- merge(t: TOAs, *args, strict: bool = False) None [source]
Merge TOAs instances into the existing object
In order for a merge to work, each TOAs instance needs to have been created using the same Solar System Ephemeris (EPHEM), the same reference timescale (i.e. CLOCK), the same value of .planets (i.e. whether planetary PosVel columns are in the tables or not), and the same value of the obliquity.
If
pulse_number
, [ssb_obs_pos
,ssb_obs_vel
,obs_sun_pos
], [tdb
,tdbld
] columns are present in some but not all data try to put them in unlessstrict=True
- Parameters:
t (pint.toa.TOAs) –
args (pint.toa.TOAs, optional) – Additional TOAs to merge
strict (bool, optional) – If
strict
, do not add in missing columns to facilitate merging