Why did last night go wrong?

A read-only companion for an observatory that already works: NINA, SGP, APT, SharpCap or Ekos taking the frames, PHD2 guiding.

Questions it answers

What it does

companion.py reads the frames your capture program saved, PHD2's guide log (or PHD2 live, through its server) and, if you give it, NINA's own log. Every light frame it can read is measured (FITS, or XISF uncompressed or zlib-compressed); what it cannot read or leaves out (calibration frames, stacks, colour pictures, other compression) is listed, never silently dropped. For each: stars, sharpness (FWHM), roundness, sky brightness, sensor temperature against its target, and the guiding during it. Each is judged against the best frames of the same target and filter that night, so no figure from another telescope is assumed. Frames are then called dimmed, bright sky, soft, trailed, off cooling target or guide star lost, and stretches with no frames are explained from PHD2 and NINA where they can be. What was measured is always said apart from what is only inferred.

It never touches the observatory. It has no command that can move a mount, take a frame, turn a focuser or a wheel, or change a setting.

No images to hand? Start with the logs

The NINA and PHD2 logs alone are enough for a first look, a few megabytes instead of a night's frames:

python companion.py report --nina-log "...\NINA\Logs\DATE.log" --phd2-log "...\PHD2_GuideLog_DATE.txt" --night 2026-09-13

Here is what it said, in full, about a night that another observatory published: NINA 3.2 running a sequence on M 27 with PHD2 guiding and a dome (their logs, 13-14 September 2026), read offline:

lights: M 27 no filter, 600 s: 27 exposures, 270 min of exposure, 21:09-02:24
lights: M 27 L-Pro, 6 s: 2 exposures, 0 min of exposure, 21:50-21:53
autofocus: L-Pro, 6 s: 42 exposures, 4 min of exposure, 20:56-01:50
plate solving: L-Pro, 15 s: 7 exposures, 2 min of exposure, 20:59-21:55
focusing: L-Pro, 6 s: 13 exposures, 1 min of exposure, 21:50-21:53
Science lights: 27 saved of 29 exposures, 270 min saved; 62 more exposures for calibration, snapshots, autofocus, plate solving or focusing, not counted as science
M 27 no filter, 600 s: 23 of 27 frames acceptable by NINA's own star detection (best HFR 2.65 px, 635 stars); 3 with fewer stars (likely cloud or haze), 1 soft
Time in the sequencer's steps: waiting 139 min, dithering 16 min, autofocus 12 min, camera warming 7 min, camera cooling 5 min, starting guiding 3 min, centring (plate solving) 3 min, dome 2 min, slewing 1 min, finding home 1 min, ...
Events: the dome shutter closed (3), the dome shutter opened (3), the safety monitor said safe (1), the safety monitor said unsafe (1)
Errors: 37, the first 21:04: PHD2Guider.cs: PHD2 error:Guiding stopped
Guiding (PHD2's log): 27 of 91 exposures taken while PHD2 was guiding; 20 of those guided all through, 7 with gaps in the guide steps; the star lost 326 time(s) during them
Guide error during exposures: median RMS 1.42 arcsec, worst 4.39
From the logs alone: no frame was measured here; any judgement of the frames is NINA's own star detection, where its log has it.

From the logs alone it told 27 ten-minute lights from 62 autofocus, plate-solving and focusing exposures, found that 7 of the 27 had gaps in their guiding, and put more than two hours down to the sequence waiting. What it could not say without the frames is how sharp each light really was: for that it used NINA's own star counts, and said so. The same observatory's November night, and others' NINA and PHD2 logs, are in What has been tried.

With the frames: the author's own night

Given the frames as well, each is measured itself. The author's night of 5 November 2026 (no guiding then), trimmed:

706 files: 693 light frames measured; 13 left out, no single-plane image (a stack or a colour picture).
M33 L (183m, gain 1500, 16 s) 00:23-01:41: 57 min measured; 37 min acceptable by its own best frames (139 of 213 frames)
    15 min (56 frames) dimmed: likely cloud or haze
    5 min (18 frames) trailed: likely the mount's tracking or the wind (no guiding to compare)
No frames 01:15-01:33 (18 min beyond the usual gap): not known: nothing it reads says
Where the time went: no frames (explained) 44 min, dimmed 38 min, no frames (unexplained) 36 min, trailed 11 min, soft 6 min

Running it

On Windows, with Python 3.11 or newer: download TelescopeYoke-v0.4.2.zip, unpack it and run install.ps1 (no config.toml needed). Then, in its folder:

python companion.py check "C:\path\to\tonights\frames"
python companion.py report "C:\path\to\tonights\frames" --phd2-log "...\PHD2_GuideLog_DATE.txt" --nina-log "...\NINA\Logs\DATE.log"

watch instead of report follows a night as it happens. The full guide, every option and how to read a report: The companion.

How far it is proven. In releases 0.4.1 and later (0.4.2, 20 November 2026, is the current one). Tried on the author's own frames, on made-up nights with known faults, and offline on NINA and PHD2 logs other observatories have published. No other observatory's night with its frames, logs and guiding together has been read yet, and it has not yet run live beside anyone else's observatory.