Explicit phase offset as a fittable parameter

[abhisrkckl]

This PR implements a PhaseOffset component that applies an overall phase offset (PHOFF) between physical TOAs and the TZR TOA. This works by using a new attribute tzr in the TOAs class that distinguishes between physical and TZR TOAs.

The sign of PHOFF is set to be the same as that of the implicit Offset. The design matrix entries for PHOFF and Offset should be identical.

If the PhaseOffset component is present in the timing model, implicit offset (Offset) will not be included in the design matrix and the correlation matrix, and the mean will not be subtracted from the residuals.

See issues #38 and #431 and PR #443.
#1550 was an attempt to do this that didn't work.

[codecov]

Codecov Report

Patch coverage: 100.00% and project coverage change: +0.05 🎉

Comparison is base (f52b06d) 67.96% compared to head (6df7a08) 68.01%.

❗ Current head 6df7a08 differs from pull request most recent head 27cee18. Consider uploading reports for the commit 27cee18 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1557      +/-   ##
==========================================
+ Coverage   67.96%   68.01%   +0.05%     
==========================================
  Files          97       98       +1     
  Lines       22538    22557      +19     
  Branches     3866     3866              
==========================================
+ Hits        15317    15343      +26     
+ Misses       6274     6268       -6     
+ Partials      947      946       -1     

Impacted Files	Coverage Δ
src/pint/models/absolute_phase.py	95.83% <ø> (ø)
src/pint/models/__init__.py	100.00% <100.00%> (ø)
src/pint/models/phase_offset.py	100.00% <100.00%> (ø)
src/pint/models/timing_model.py	83.39% <100.00%> (+0.01%)	⬆️
src/pint/pint_matrix.py	68.83% <100.00%> (+0.16%)	⬆️
src/pint/residuals.py	74.33% <100.00%> (+0.34%)	⬆️
src/pint/toa.py	86.38% <100.00%> (+0.01%)	⬆️

... and 3 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[paulray]

• show what happens if you try to fit for both TZRMJD and PHOFF

I didn't think TZRMJD was ever a fittable parameter. Is it?

[paulray]

Maybe in the doc paragraph you can say that once you have a non-zero PHOFF, you can make it zero by computing d_phase/d_TOA at the time of the TZR TOA and turning that into a time difference required to zero out the PHOFF? I assume that is how TEMPO and Tempo2 output their updated TZR TOAs after a fit?

[abhisrkckl]

I think the tests should:

show what happens if you try to fit for both TZRMJD and PHOFF

This is not possible since TZRMJD is not a fittable parameter.

show how the residuals change when you change PHOFF
show that the residuals are not mean subtracted

Added tests for these.

[abhisrkckl]

@dlakaplan Added the example phase_offset_example.py

[dlakaplan]

The example looks great. Probably that's sufficient. I don't know if we also want a few lines in the docstring for PhaseOffset showing how to add one. Maybe just a link to the example?

[abhisrkckl]

The process of adding the explicit offset is pretty much the same as any other component/parameter. i.e., add PHOFF to the par file or add PhaseOffset to the model using the add_component method. Do we need separate instructions for that?

[dlakaplan]

Probably not. so maybe just a link to the example in the docstring.

[dlakaplan]

OK, great. I can merge as soon as it passes (note it seems like there are GitHub errors)