Interpreting PMTRAS Diagnostic Plots

If the PMTRAS software will issue a "WARNING PMTRAS solution is suspect message" if any one of several internal checks is not satisfactory.  Generating a complete set of diagnostic plots by using "pmtras_diagnostic=-1" keyword may help identify the reason for the problem.  In response to pmtras_diagnostic=-1, you will typically get some extra screen output and 11 plots, of which 5 may be relevant in this context.
The purpose of this writeup is to  suggest how these diagnostics might be interpreted to help resolve the problem.

The 4th plot, "Blip Total vs Time"  should be examined for any gaps (>=1 minute).  Such gaps are probably due to missing packets, in which case obs_time_interval and/or ras_time_extension should be modified to avoid inclusion of such a  gap.  (PMTRAS packets starting within +-ras_time_interval of the obs_time_interval are used for the roll solution.  Default value of ras_time_interval is +-1400s.)

The 6th plot, "Preliminary Estimates of Rotation Period" has data points which are normally spaced at 3 minute intervals.  This should also be checked for any missing data points.  Gaps here indicate a virtually blank star field for that part of the orbit.  Again, obs_time_interval and/or ras_time_extension should be modified to avoid inclusion of this time gap.

Over an orbit, the range of the Rotation Periods should typically be ~2 milliseconds.  Except for characteristic hiccups at sunrise and sunset, the successive periods should represent a reasonably smooth curve (with 'noise' at the 0.1 millisecond level).  If this is not the case, using the blip_min=x keyword, where x is higher or lower than the Blip Intensity cutoff indicated in the output might help.  Alternatively, obs_time_interval or ras_time_extension might be modified to avoid inclusion of the offending point.

The last (11th) plot, "File-Averaged Phase Residuals" shows the residual phase of all the star-associated blips, after removing the
best fit uniform rotation period.  Since all stars should lie on the same curve, this plot must be single valued for a reliable solution.  Double-values anywhere suggest that the entire solution may be suspect (due to star mis-identification).  Red +'s represent discarded outliers and can be disregarded.  Gaps are ok here as long as they do not include times that overlap with the actual imaging time_range.  If there are gaps or double-values,  then again, obs_time_interval and/or  ras_time_extension should  be modified to try to alleviate the problem.  (The time range has some affect on which stars are identified and then used in the final solution.)

The 9th plot, "Intensity/Phase Grouping" is very  instructive for getting insight into what is actually happening, although there is no one-to-one correlation between plot characteristics and "fixes".   In the plots, individual star blips are shown as white dots, plotted as their intensity vs relative rotational phase (or position angle).  A given star will always have the same phase and a (~x2) range of intensities and so will show up as a narrow vertical bar.   (PMTRAS is not a good photometer!)   The orange boxes surround groups of blips that are then assumed to come from the same star.  The diamonds represent the expected stars that might be observed, shifted in phase to best match the observed groups of blips.  When a star has been associated with a blip group, a red X is plotted as well.  The predicted and observed star intensities should agree to within ~x3.  The robustness of the star association (viz. correctness of the position angle of your image) can be judged by the number of associated stars and the (undesirable) potential for alternate but equally valid associations.  In this regard, more associated stars is good,
Closely spaced stars or blip groups in not good.

The 7th  plot (Preliminary Timing Residuals) shows individual blip phases as a function of a timing residuals, assuming the preliminary
rotation periods.  (The timing residuals are closely linked to the relative rotational phase in the Intensity/Phase Grouping.)  All blips for
an individual real star should show up as a horizontal line.  (Diagonal lines may be city lights.)   When interpreted in conjuction with the other plots, it can provide insight into why gaps may have have occurred at different phases in the orbit.

Questions concerning interpretation of pmtras data should be sent to ghurford@ssl.berkeley.edu