Observations

py_outfit.observations.Observations

Read-only Python view over a single trajectory (list of astrometric observations).

Highlights

• Vector exports: to_numpy() and to_list()
• Row access / iteration: __getitem__, __iter__
• Pretty display helpers:
  • show(...) – compact, fixed-width table
  • table_wide(...) – diagnostic table with JD, radians, distances (AU)
  • table_iso(...) – timestamp-centric (ISO TT / ISO UTC)
  • *_with_env(env, ...) – same as above, but resolves observer names using PyOutfit

to_numpy

to_numpy() -> tuple[
    NDArray[float64],
    NDArray[float64],
    NDArray[float64],
    NDArray[float64],
    NDArray[float64],
]

Export arrays to NumPy (rad / days).

RETURNS	DESCRIPTION
tuple[ndarray, ndarray, ndarray, ndarray, ndarray]	Five 1D arrays of dtype float64: (mjd_tt, ra_rad, dec_rad, sigma_ra, sigma_dec).

to_list

to_list() -> list[tuple[float, float, float, float, float]]

Return a Python list of observation tuples.

RETURNS	DESCRIPTION
list[tuple[float, float, float, float, float]]	Each tuple is (mjd_tt, ra_rad, dec_rad, sigma_ra, sigma_dec).

show

show(*, sorted: bool = False, sec_prec: int = 3) -> str

Render a compact, fixed-width table.

PARAMETER	DESCRIPTION
sorted	Sort rows by MJD(TT) ascending (default: False). TYPE: bool DEFAULT: False
sec_prec	Fractional digits for sexagesimal seconds (default: 3). TYPE: int DEFAULT: 3

RETURNS	DESCRIPTION
str	Formatted table.

show_with_env

show_with_env(env: PyOutfit, *, sorted: bool = False, sec_prec: int = 3) -> str

Compact table, resolving observer names via env.

PARAMETER	DESCRIPTION
env	Global environment used to resolve site names. TYPE: PyOutfit
sorted	Sort rows by MJD(TT) ascending (default: False). TYPE: bool DEFAULT: False
sec_prec	Fractional digits for sexagesimal seconds (default: 3). TYPE: int DEFAULT: 3

RETURNS	DESCRIPTION
str	Formatted table (with site names when available).

table_wide

table_wide(*, sorted: bool = False, sec_prec: int = 3, dist_prec: int = 6) -> str

Diagnostic table (Unicode) with JD, radians, and AU distances.

Columns

# | Site | MJD (TT) | JD (TT) | RA±σ[arcsec] | RA [rad] | DEC±σ[arcsec] | DEC [rad] | |r_geo| AU | |r_hel| AU

PARAMETER	DESCRIPTION
sorted	Sort rows by MJD(TT) ascending (default: False). TYPE: bool DEFAULT: False
sec_prec	Fractional digits for sexagesimal seconds (default: 3). TYPE: int DEFAULT: 3
dist_prec	Fixed-point digits for AU distances (default: 6). TYPE: int DEFAULT: 6

RETURNS	DESCRIPTION
str	Unicode table (box drawing).

table_wide_with_env

table_wide_with_env(
    env: PyOutfit, *, sorted: bool = False, sec_prec: int = 3, dist_prec: int = 6
) -> str

Diagnostic table (Unicode) using env to resolve observer names.

See table_wide for columns and knobs.

PARAMETER	DESCRIPTION
env	Global environment used to resolve site names. TYPE: PyOutfit
sorted	Sort rows by MJD(TT) ascending (default: False). TYPE: bool DEFAULT: False
sec_prec	Fractional digits for sexagesimal seconds (default: 3). TYPE: int DEFAULT: 3
dist_prec	Fixed-point digits for AU distances (default: 6). TYPE: int DEFAULT: 6

RETURNS	DESCRIPTION
str	Unicode table (box drawing).

table_iso

table_iso(*, sorted: bool = False, sec_prec: int = 3) -> str

ISO-centric table (Unicode) with TT & UTC timestamps.

Columns

# | Site | ISO (TT) | ISO (UTC) | RA±σ[arcsec] | DEC±σ[arcsec]

PARAMETER	DESCRIPTION
sorted	Sort rows by MJD(TT) ascending (default: False). TYPE: bool DEFAULT: False
sec_prec	Fractional digits for seconds (applied to ISO & sexagesimal, default: 3). TYPE: int DEFAULT: 3

RETURNS	DESCRIPTION
str	Unicode table (box drawing).

table_iso_with_env

table_iso_with_env(env: PyOutfit, *, sorted: bool = False, sec_prec: int = 3) -> str

ISO-centric table (Unicode) using env to resolve observer names.

See table_iso for columns and knobs.

PARAMETER	DESCRIPTION
env	Global environment used to resolve site names. TYPE: PyOutfit
sorted	Sort rows by MJD(TT) ascending (default: False). TYPE: bool DEFAULT: False
sec_prec	Fractional digits for seconds (applied to ISO & sexagesimal, default: 3). TYPE: int DEFAULT: 3

RETURNS	DESCRIPTION
str	Unicode table (box drawing).

estimate_best_orbit

estimate_best_orbit(
    env: PyOutfit, params: IODParams, seed: Optional[int] = ...
) -> Tuple[GaussResult, float]

Estimate the best orbit for this observation set using Gauss IOD.

PARAMETER	DESCRIPTION
env	Global environment providing ephemerides and the error model. TYPE: PyOutfit
params	IOD configuration (triplet constraints, noise realizations, filters). TYPE: IODParams
seed	Optional RNG seed for deterministic runs. TYPE: Optional[int] DEFAULT: None

Notes

Due to a known bug in the Rust backend (Outfit) within apply_batch_rms_correction, the per-observation uncertainties (sigma_ra, sigma_dec) are modified in place and the changes persist on the same Observations instance. Calling estimate_best_orbit multiple times on the same object can therefore accumulate these changes and yield different RMS values across calls. This behavior is unintended and will be fixed upstream. As a temporary workaround, construct a fresh Observations object for each call or use a copy that restores the original uncertainties. Providing a seed only makes noise sampling deterministic and does not prevent this mutation.

RETURNS	DESCRIPTION
(GaussResult, float)	The orbit result and the RMS value (radians).