KOPR

KOPR documentation

Comet Analyzer automatic range and invalidation

R163 centralizes ownership of manual plot limits and defines when a committed range remains valid as the rendered dataset, transforms, formulas and filters change.

R515 structural note: This page preserves feature/release contracts, but any flat-root Python filenames cited as implementation evidence are historical pre-convergence names. Current implementation ownership is canonical under src/kopr/; use the current package/API policy for imports and extension work.

Status: R163 PASS. Historical R154 and R161 real-PyQt5 gates remain PASS_HEADLESS because PyQt5 was unavailable on the build host.

AUTO, USER X and USER Y modes

AUTO remains the observation-owned view: visible observations define automatic X. Manual intent is tracked separately for X and Y.

An explicit USER X commit authorizes fitted-model extrapolation to the requested interval, bounded by the physical half-width of the selected apparition. It must not cross into a neighbouring return. Single-law fits may extend both outer ends; segmented pre/post or adaptive fits preserve internal breakpoints and change only the outer domain limits.

If X is manual while Y is untouched, Y is recomputed from visible observations plus prepared model points inside the requested X interval. Explicit USER Y remains authoritative.

Immutable rendered-data identity

AnalyzerRangeIdentity fingerprints the data and transformations that can change rendered rows or coordinates. Ordering of targets, channels, observers and returns is normalized, so a pure reorder does not invalidate a manual range. Formula fingerprinting uses the complete sorted per-target document and is independent of the current Editing target.

Inputs that invalidate a USER range

  • loaded-observation fingerprint;
  • selected target set and enabled target/return identities;
  • visible channel IDs and enabled observers;
  • uncertain and negative-observation filters;
  • X-axis projection and magnitude mode;
  • phase-correction state, phase display mode and dust d_90;
  • complete Regular and Additional formula documents for every selected target.

New target selection invalidates explicitly. Reloaded data are detected when the committed observation fingerprint changes.

Inputs deliberately excluded from range identity

  • comet and channel colours or markers;
  • global observation Point size;
  • display-encoding mode and legend layout;
  • FitGroup labels, membership and enabled state;
  • Editing-target navigation;
  • Bortle reference-line visibility.

These changes may rebuild artists or fit organization, but they do not change the coordinates that own the current manual range.

Range-field intent tracking

The four fields record Qt textEdited events without redrawing. This distinguishes deliberate user input from values written programmatically by the renderer.

  • deliberately edited valid values plus Refresh commit USER limits;
  • unedited stale field values are ignored after an identity change, so Refresh requests AUTO limits;
  • programmatic field updates clear the dirty flag.

Central range resolution

  1. Resolve the normalized rendered-data identity and independent X/Y edit intent.
  2. For AUTO X, derive the horizontal interval only from visible observations.
  3. For USER X, clip/validate the requested interval against the selected apparition boundary and prepare the selected fitted model through that bounded interval.
  4. If Y is AUTO, derive its envelope from visible observations plus prepared model points within the resolved X interval; if Y is USER, keep the explicit value.
  5. Style-only edits do not invalidate a committed USER range.

R182 cached Auto range command

Auto range restores the cached automatic view through the current committed dataset and range state. It is view-only and must not reload observations, rerun fits, recompute formula documents or request geometry.

Automatic X/Y envelope

AUTO X is observation-owned and is never extended by a model or Bortle reference. AUTO Y is calculated over the resolved X interval and may include prepared model points in addition to observations. This distinction is important when USER X deliberately extends beyond observation support: model-only regions may change AUTO Y without changing the scientific fit coefficients.

Settings classification

Range invalidation is limited to settings that can change displayed rows or coordinates: uncertain/negative rejection, phase correction, phase display mode, dust d_90, return selection, observer selection and channel Show.

Fit-only settings, Bortle-reference visibility and display-style changes redraw without resetting limits.

Acceptance examples

  1. Leaving only CCD V and CCD R visible discards stale manual limits and repopulates AUTO fields from the new visible content.
  2. Switching display encoding, changing a colour/marker or changing Point size preserves the range.
  3. Newly downloaded observations change the observation fingerprint and recompute AUTO limits.
  4. Changing d_90, phase correction, axis, magnitude mode or formula content recomputes AUTO limits unless the user commits new values.
  5. Changing FitGroup membership or Editing target preserves the range.
  6. Editing only X may extend a fitted model through the requested bounded interval and derive a new Y envelope; editing Y explicitly prevents that automatic Y replacement.

Historical range gates and current overlay

R163/R181/R182/R187 remain historical regression foundations for identity, automatic envelopes and Auto range. Current behavior adds independent X/Y edit intent and bounded manual-X fitted-model extrapolation; tests for new work must protect that current contract rather than reasserting the older “model never extends X” wording for USER mode.