empyrean.ObservationSensitivities

class ObservationSensitivities(table, **kwargs)

Bases: Table

Per-(orbit, observer, epoch) observation Jacobians and Hessians.

Holds ∂h/∂x₀ at every ephemeris epoch for each (orbit, observer) pair, plus the observation Hessians when the underlying propagation carried STTs. The Jacobian composes ∂(obs)/∂(state at t_obs) · Φ(t_obs, t₀) and omits the light-time terms (the −v·∂τ/∂x partial; the STM is sampled at t_obs rather than emission t_obs − τ): both are O(τ), landing in the velocity columns of the angle rows with fractional error ≈ τ/Δt (τ ≈ 0.006–0.017 d) — negligible for multi-night arcs, growing as the arc shrinks toward intra-night. Filter to one chain via two select calls before using the per-chain accessors:

chain = obs.select("orbit_id", oid).select("obs_code", "F51")
H = chain.jacobians_array()[chain.index_at(60750.0)]

Notes

Matrix payloads are row-major flattened LargeListColumn values:

• jacobian is (6, n_params) flattened to length 6·n_params (jacobian[n_params·r + c] = J[r, c]).

• hessian is (6, n_params, n_params) flattened to length 6·n_params².

The n_params column documents which: 6 for a state-only DC, 9 when non-gravitational parameters (A1, A2, A3) are also free variables. All rows within a single chain share the same n_params. Columns 0:6 are the input Cartesian state; any further columns are the extra solved-for parameters.

The leading axis — of both the Jacobian and the Hessian — is the topocentric spherical observable, in this order:

row	constant	observable	unit per input unit
0	SENSITIVITY_ROW_RANGE	range	AU
1	SENSITIVITY_ROW_RA	RA	deg
2	SENSITIVITY_ROW_DEC	Dec	deg
3	SENSITIVITY_ROW_VRANGE	range rate	AU/day
4	SENSITIVITY_ROW_VRA	RA rate	deg/day
5	SENSITIVITY_ROW_VDEC	Dec rate	deg/day

The RA rate is dRA/dt, not scaled by cos(Dec). Projecting an input covariance onto the sky plane therefore contracts rows 1 and 2; row 0 is range, and reading it as RA gives a number in the wrong observable and the wrong unit. Index with the module-level SENSITIVITY_ROW_* constants rather than with literals:

from empyrean import SENSITIVITY_ROW_DEC, SENSITIVITY_ROW_RA

J = chain.jacobians_array()[chain.index_at(60750.0)]
h_ra = J[SENSITIVITY_ROW_RA, :6]
h_dec = J[SENSITIVITY_ROW_DEC, :6]

Methods

__init__(table, **kwargs)
apply_mask(mask)	Return a new table with rows filtered to match a boolean mask.
as_column([nullable, metadata])	Embed the Table as a column in another Table.
attributes()	Return a dictionary of the table's attributes.
chain_keys()	Unique (orbit_id, obs_code) pairs, in first-seen order.
chunk_counts()	Returns the number of discrete memory chunks that make up each of the Table's underlying arrays.
column(column_name)	Returns the column with the given name as a raw pyarrow ChunkedArray.
drop_duplicates([subset, keep])	Drop duplicate rows from a ~quivr.Table.
empty(**kwargs)	Create an empty instance of the table.
flattened_table()	Completely flatten the Table's underlying Arrow table, taking into account any nested structure, and return the data table itself.
fragmented()	Returns true if the Table has any fragmented arrays.
from_csv(input_file[, validate])	Read a table from a CSV file.
from_dataframe(df[, validate])	Load a DataFrame into the Table.
from_feather(path[, validate])	Read a table from a Feather file.
from_flat_dataframe(df[, validate])	Load a flattened DataFrame into the Table.
from_kwargs([validate, permit_nulls])	Create a Table instance from keyword arguments.
from_parquet(path[, memory_map, ...])	Read a table from a Parquet file.
from_pyarrow(table[, validate, permit_nulls])	Create a new table from a pyarrow Table.
hessians_array()	Reshape hessian to (n_t, 6, n_params, n_params).
index_at(epoch, *[, atol])	Row index at the given epoch.
invalid_mask()	Return a boolean mask indicating which rows are invalid.
is_valid()	Validate the table against the schema.
jacobians_array()	Reshape jacobian to (n_t, 6, n_params).
null_mask()	Return a boolean mask indicating which rows of the entire table are null.
nulls(size, **kwargs)	Create a table with nulls.
propagate_covariance(cov_in, *[, i, order])	Map an initial-state covariance into observation-frame covariance.
select(column_name, value)	Select from the table by exact match, returning a new Table which only contains rows for which the value in column_name equals value.
separate_invalid()	Separates rows that have invalid data from those that have valid data.
set_column(name, data)	Return a copy of the table with a particular column replaced with new data.
sort_by(by)	Sorts the Table by the given column name (or multiple columns).
take(row_indices)	Return a new Table with only the rows at the given indices.
to_csv(path[, attribute_columns])	Write the table to a CSV file.
to_dataframe([flatten, attr_handling])	Returns self as a pandas DataFrame.
to_feather(path, **kwargs)	Write the table to a Feather file.
to_parquet(path, **kwargs)	Write the table to a Parquet file.
to_structarray()	Returns self as a StructArray.
unique_indices([subset, keep])	Get the indices of the first or last occurrence of each unique row in the table.
up_to(epoch)	Subset including rows with epoch_mjd_tdb ≤ the target.
validate()	Validate the table against the schema, raising an exception if invalid.
where(expr)	Return a new table with rows filtered to match an expression.
with_table(table)

Attributes

epoch_mjd_tdb	Observation epoch (MJD TDB).
hessian	Row-major flattened (6, n_params, n_params) Hessian.
jacobian	Row-major flattened (6, n_params) Jacobian.
n_params	Last-axis dimension of Jacobian / Hessian.
object_id	Object metadata label.
obs_code	MPC observatory code.
orbit_id	Orbit primary key.
schema
table

Parameters:

• table (Table)

• kwargs (AttributeValueType)

orbit_id

Orbit primary key.

object_id

Object metadata label.

obs_code

MPC observatory code.

schema: ClassVar[Schema] = orbit_id: large_string not null object_id: large_string obs_code: large_string not null epoch_mjd_tdb: double not null n_params: uint8 not null jacobian: large_list<item: double>   child 0, item: double hessian: large_list<item: double>   child 0, item: double

epoch_mjd_tdb

Observation epoch (MJD TDB).

n_params

Last-axis dimension of Jacobian / Hessian. 6 for state-only DC, 9 when non-grav A1/A2/A3 are free. Constant within a chain.

jacobian

Row-major flattened (6, n_params) Jacobian.

hessian

Row-major flattened (6, n_params, n_params) Hessian.

chain_keys()

Unique (orbit_id, obs_code) pairs, in first-seen order.

Return type:

list[tuple[str, str]]

jacobians_array()

Reshape jacobian to (n_t, 6, n_params).

Axis 1 is the observable, in SENSITIVITY_ROW_* order (range, RA, Dec, and their rates); axis 2 is the input parameter, state first. Returns None when every row has a null Jacobian.

Return type:

ndarray | None

hessians_array()

Reshape hessian to (n_t, 6, n_params, n_params).

Axis 1 is the observable, in the same SENSITIVITY_ROW_* order as jacobians_array(). Returns None when every row has a null Hessian.

Return type:

ndarray | None

index_at(epoch, *, atol=1e-09)

Row index at the given epoch.

Filter to a single chain via two select calls first if epochs repeat across chains.

Return type:

int

Parameters:

• epoch (float | str | datetime | Epochs)

• atol (float)

up_to(epoch)

Subset including rows with epoch_mjd_tdb ≤ the target.

Return type:

ObservationSensitivities

Parameters:

epoch (float | str | datetime | Epochs)

propagate_covariance(cov_in, *, i=None, order='auto')

Map an initial-state covariance into observation-frame covariance.

Filter to a single (orbit_id, obs_code) chain first.

Returns (Σ_obs, Δμ_obs) with shapes: i=None: (n_t, 6, 6), (n_t, 6) i=int: (6, 6), (6,)

Both are in the observable basis — the SENSITIVITY_ROW_* order (range, RA, Dec, and their rates), with AU on the range axes and degrees on the angle axes. A sky-plane 2×2 is the [SENSITIVITY_ROW_RA, SENSITIVITY_ROW_DEC] submatrix of Σ_obs, in deg², before any cos(Dec) scaling.

Return type:

tuple[ndarray, ndarray]

Parameters:

• cov_in (ndarray)

• i (int | None)

• order (Literal[1, 2, 'auto'])