Integration with Pandas

py_outfit.pandas_pyoutfit

Pandas accessor for batch Initial Orbit Determination (IOD) with Outfit.

This module adds a DataFrame.outfit accessor exposing a vectorized entry-point to run Gauss IOD on a flat, columnar table of astrometric measurements.

Examples:

>>> df = pd.DataFrame({
...     "tid":  [0, 0, 0, 1, 1, 1],
...     "mjd":  [60000.0, 60000.01, 60000.02, 60000.0, 60000.01, 60000.02],
...     "ra":   [10.1, 10.2, 10.3, 33.4, 33.5, 33.6],   # degrees by default
...     "dec":  [-5.0, -4.9, -4.8,  2.0,  2.1,  2.2],  # degrees by default
... })
>>> env = PyOutfit(ephem="horizon:DE440", error_model="FCCT14")
>>> params = IODParams() # default settings
>>> obs = PyOutfit.get_observer_from_mpc_code("I41") # ZTF
>>> orb_pdf = pandas_traj.outfit.estimate_orbits(
...     env, params, obs, ra_error=0.5, dec_error=0.5
... )
>>> orb_pdf.columns[:5]
Index(['object_id', 'variant', 'element_set', 'rms', ...], dtype='object')

Design

Schema: maps your column names to the expected fields (tid/mjd/ra/dec).
Vector ingestion: we assemble a TrajectorySet directly from NumPy arrays.
Units: units="degrees" (default) interprets RA/DEC in degrees and uncertainties in arcseconds; "radians" expects everything in radians.

Schema `dataclass`

Schema(tid: str = 'tid', mjd: str = 'mjd', ra: str = 'ra', dec: str = 'dec')

Column schema used to map a DataFrame to py_outfit's vector ingestion.

ATTRIBUTE	DESCRIPTION
`tid`	Column containing object/trajectory IDs (int or str). Repeated per-row. TYPE: `str`
`mjd`	Modified Julian Date (TT, days). TYPE: `str`
`ra`	Right Ascension values (degrees if `units='degrees'`, else radians). TYPE: `str`
`dec`	Declination values (degrees if `units='degrees'`, else radians). TYPE: `str`

Notes

Only these four columns are required for the accessor.
If your DataFrame uses different names, override the defaults: schema=Schema(tid="object", mjd="epoch", ra="alpha", dec="delta").

OutfitAccessor

OutfitAccessor(pandas_obj: DataFrame)

Pandas accessor for running Gauss IOD from a DataFrame.

Use via the attribute accessor DataFrame.outfit. It exposes :meth:estimate_orbits to run a vectorized Initial Orbit Determination over a flat table of astrometric measurements.

Examples:

Basic usage with degrees and arcseconds

>>> out = df.outfit.estimate_orbits(env, params, observer, ra_error=0.5, dec_error=0.5)

Radians workflow

>>> out = df.outfit.estimate_orbits(
...     env, params, observer,
...     ra_error=1e-6, dec_error=1e-6,
...     units="radians",
... )

estimate_orbits

estimate_orbits(
    env: PyOutfit,
    params: IODParams,
    observer: Observer,
    ra_error: float,
    dec_error: float,
    *,
    schema: Schema = Schema(),
    units: Literal["degrees", "radians"] = "degrees",
    rng_seed: Optional[int] = None
) -> DataFrame

Run Gauss IOD on a flat astrometry table and return a one-row-per-object summary.

The input DataFrame must at least provide a trajectory/object identifier, Modified Julian Date in TT, and right ascension/declination angles. The names of these columns are defined by schema (defaults are tid, mjd, ra, dec).

PARAMETER	DESCRIPTION
`env`	Configured computation engine, including ephemerides, the error model and the available observers. TYPE: `PyOutfit`
`params`	IOD configuration controlling triplet search, Monte Carlo perturbations, filters, and tolerances. TYPE: `IODParams`
`observer`	Default observer applied to all rows. This covers the common single-station use case. TYPE: `Observer`
`ra_error`	Uncertainty on right ascension. When `units="degrees"`, the value is interpreted in arcseconds; when `units="radians"`, the value is in radians. TYPE: `float`
`dec_error`	Uncertainty on declination. Follows the same unit convention as `ra_error`. TYPE: `float`
`schema`	Column mapping for the current DataFrame. Use this to adapt to non-standard column names. The default expects `tid`, `mjd`, `ra`, and `dec`. TYPE: `Schema` DEFAULT: `Schema()`
`units`	Angle units for `ra`/`dec` and the corresponding uncertainties. Degrees imply RA/DEC are in degrees and uncertainties are in arcseconds. Radians imply both values and uncertainties are already expressed in radians. TYPE: `('degrees', 'radians')` DEFAULT: `"degrees"`
`rng_seed`	Optional seed to make randomized internals deterministic. TYPE: `int or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`DataFrame`	A summary DataFrame with one row per object containing the RMS value, the detected orbital element set, the orbit variant, and the native orbital elements returned by the engine. The `object_id` column mirrors the original identifier from `schema.tid`. When some trajectories fail, additional rows are included with `object_id` and an `error` message; successful rows include `status="ok"`.

RAISES	DESCRIPTION
`ValueError`	Raised when required columns are missing in the DataFrame, or when `units` is not one of {"degrees", "radians"}.