empyrean.TaggedCovariances

class TaggedCovariances(table, **kwargs)

Bases: Table

Per-(orbit, epoch) provenance-tagged covariance readback.

One row per output epoch; rows are grouped contiguously by orbit_id (matching propagation’s orbit-major output). Filter to one chain with quivr’s standard select before calling the per-chain accessor:

chain = tagged.select("orbit_id", "2024 YR4")
series = chain.to_series()

Notes

The 6×6 matrix rides as 21 lower-triangular cov_{i}_{j} columns (same layout as CartesianCovariance). The co-located nominal state and the optional mean-shift vectors ride as six scalar columns each, paired with a presence flag for the optional vectors.

has_tagged is False on rows where the underlying orbit carried no covariance — those rows are zero-filled placeholders that keep the table aligned 1:1 with the propagated states.

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.
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.
invalid_mask()	Return a boolean mask indicating which rows are invalid.
is_valid()	Validate the table against the schema.
matrices()	Reshape the lower-tri cov_* columns to (n, 6, 6).
null_mask()	Return a boolean mask indicating which rows of the entire table are null.
nulls(size, **kwargs)	Create a table with nulls.
orbit_ids_unique()	Unique orbit_id values, in first-seen order.
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_series()	Materialize this table as a list of TaggedCovariance.
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.
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

cov_vx_vx	A column for storing 64-bit floating point numbers.
cov_vx_vy	A column for storing 64-bit floating point numbers.
cov_vx_vz	A column for storing 64-bit floating point numbers.
cov_vy_vy	A column for storing 64-bit floating point numbers.
cov_vy_vz	A column for storing 64-bit floating point numbers.
cov_vz_vz	A column for storing 64-bit floating point numbers.
cov_x_vx	A column for storing 64-bit floating point numbers.
cov_x_vy	A column for storing 64-bit floating point numbers.
cov_x_vz	A column for storing 64-bit floating point numbers.
cov_x_x	A column for storing 64-bit floating point numbers.
cov_x_y	A column for storing 64-bit floating point numbers.
cov_x_z	A column for storing 64-bit floating point numbers.
cov_y_vx	A column for storing 64-bit floating point numbers.
cov_y_vy	A column for storing 64-bit floating point numbers.
cov_y_vz	A column for storing 64-bit floating point numbers.
cov_y_y	A column for storing 64-bit floating point numbers.
cov_y_z	A column for storing 64-bit floating point numbers.
cov_z_vx	A column for storing 64-bit floating point numbers.
cov_z_vy	A column for storing 64-bit floating point numbers.
cov_z_vz	A column for storing 64-bit floating point numbers.
cov_z_z	A column for storing 64-bit floating point numbers.
epoch_mjd_tdb	Output epoch (MJD TDB).
frame	Reference frame of the basis (canonical name).
has_mean_shift_input	Whether mean_shift_input_* carries a value on this row.
has_mean_shift_prop	Whether mean_shift_prop_* carries a value on this row.
has_tagged	False on zero-filled placeholder rows where the underlying orbit carried no covariance.
kind	Resolved covariance kind (CovarianceKind value).
mc_seed	Monte-Carlo run seed; null unless kind is monte_carlo.
mean_shift_input_vx	A column for storing 64-bit floating point numbers.
mean_shift_input_vy	A column for storing 64-bit floating point numbers.
mean_shift_input_vz	A column for storing 64-bit floating point numbers.
mean_shift_input_x	A column for storing 64-bit floating point numbers.
mean_shift_input_y	A column for storing 64-bit floating point numbers.
mean_shift_input_z	A column for storing 64-bit floating point numbers.
mean_shift_prop_vx	A column for storing 64-bit floating point numbers.
mean_shift_prop_vy	A column for storing 64-bit floating point numbers.
mean_shift_prop_vz	A column for storing 64-bit floating point numbers.
mean_shift_prop_x	A column for storing 64-bit floating point numbers.
mean_shift_prop_y	A column for storing 64-bit floating point numbers.
mean_shift_prop_z	A column for storing 64-bit floating point numbers.
non_grav_a1	A column for storing booleans.
non_grav_a2	A column for storing booleans.
non_grav_a3	A column for storing booleans.
non_grav_cross	6×3 row-major state-to-(A1, A2, A3) cross covariance, 18 values, in the Cartesian basis of the cov_* columns above.
object_id	Object metadata label, if carried on the input orbit.
orbit_id	Orbit primary key (matches the input Orbits.orbit_id).
origin	Canonical origin (center body) name of the basis.
quality	Definiteness (CovarianceQuality value).
quality_kappa_state	κ_state behind an expansion_suspect tag; NaN for every other quality.
quality_min_eig	Minimum eigenvalue for indefinite / repaired matrices; NaN for every other quality.
schema
solved_width	Solved width (6 / 9 / 12 / …).
state_vx	A column for storing 64-bit floating point numbers.
state_vy	A column for storing 64-bit floating point numbers.
state_vz	A column for storing 64-bit floating point numbers.
state_x	A column for storing 64-bit floating point numbers.
state_y	A column for storing 64-bit floating point numbers.
state_z	A column for storing 64-bit floating point numbers.
target_functional	The functional this second moment describes (TargetFunctional value).
thrust_segments	Thrust Δv segments solved for.
wide_cross	Cross terms beyond the state+Marsden 9x9 — state↔DT, state↔AMRAT, state↔Δv, and every mixed parameter pair.
table

Parameters:

• table (Table)

• kwargs (AttributeValueType)

orbit_id

Orbit primary key (matches the input Orbits.orbit_id).

object_id

Object metadata label, if carried on the input orbit.

epoch_mjd_tdb

Output epoch (MJD TDB).

state_x

A column for storing 64-bit floating point numbers.

state_y

A column for storing 64-bit floating point numbers.

state_z

A column for storing 64-bit floating point numbers.

state_vx

A column for storing 64-bit floating point numbers.

state_vy

A column for storing 64-bit floating point numbers.

state_vz

A column for storing 64-bit floating point numbers.

kind

Resolved covariance kind (CovarianceKind value).

quality

Definiteness (CovarianceQuality value).

quality_min_eig

Minimum eigenvalue for indefinite / repaired matrices; NaN for every other quality.

quality_kappa_state

κ_state behind an expansion_suspect tag; NaN for every other quality. Read-only provenance — check np.isfinite first.

mc_seed

Monte-Carlo run seed; null unless kind is monte_carlo.

mean_shift_prop_x

A column for storing 64-bit floating point numbers.

mean_shift_prop_y

A column for storing 64-bit floating point numbers.

mean_shift_prop_z

A column for storing 64-bit floating point numbers.

mean_shift_prop_vx

A column for storing 64-bit floating point numbers.

mean_shift_prop_vy

A column for storing 64-bit floating point numbers.

mean_shift_prop_vz

A column for storing 64-bit floating point numbers.

has_mean_shift_prop

Whether mean_shift_prop_* carries a value on this row.

mean_shift_input_x

A column for storing 64-bit floating point numbers.

mean_shift_input_y

A column for storing 64-bit floating point numbers.

mean_shift_input_z

A column for storing 64-bit floating point numbers.

mean_shift_input_vx

A column for storing 64-bit floating point numbers.

mean_shift_input_vy

A column for storing 64-bit floating point numbers.

mean_shift_input_vz

A column for storing 64-bit floating point numbers.

has_mean_shift_input

Whether mean_shift_input_* carries a value on this row.

non_grav_a1

A column for storing booleans.

non_grav_a2

A column for storing booleans.

non_grav_a3

A column for storing booleans.

thrust_segments

Thrust Δv segments solved for.

solved_width

Solved width (6 / 9 / 12 / …).

target_functional

The functional this second moment describes (TargetFunctional value).

origin

Canonical origin (center body) name of the basis.

frame

Reference frame of the basis (canonical name).

cov_x_x

A column for storing 64-bit floating point numbers.

cov_x_y

A column for storing 64-bit floating point numbers.

schema: ClassVar[Schema] = orbit_id: large_string not null object_id: large_string epoch_mjd_tdb: double not null state_x: double not null state_y: double not null state_z: double not null state_vx: double not null state_vy: double not null state_vz: double not null kind: large_string not null quality: large_string not null quality_min_eig: double quality_kappa_state: double mc_seed: uint64 mean_shift_prop_x: double mean_shift_prop_y: double mean_shift_prop_z: double mean_shift_prop_vx: double mean_shift_prop_vy: double mean_shift_prop_vz: double has_mean_shift_prop: bool not null mean_shift_input_x: double mean_shift_input_y: double mean_shift_input_z: double mean_shift_input_vx: double mean_shift_input_vy: double mean_shift_input_vz: double has_mean_shift_input: bool not null non_grav_a1: bool not null non_grav_a2: bool not null non_grav_a3: bool not null thrust_segments: uint32 not null solved_width: uint32 not null target_functional: large_string not null origin: large_string not null frame: large_string not null cov_x_x: double cov_x_y: double cov_y_y: double cov_x_z: double cov_y_z: double cov_z_z: double cov_x_vx: double cov_y_vx: double cov_z_vx: double cov_vx_vx: double cov_x_vy: double cov_y_vy: double cov_z_vy: double cov_vx_vy: double cov_vy_vy: double cov_x_vz: double cov_y_vz: double cov_z_vz: double cov_vx_vz: double cov_vy_vz: double cov_vz_vz: double has_tagged: bool not null non_grav_cross: large_list<item: double>   child 0, item: double wide_cross: struct<columns: large_list<item: large_string>, state: large_list<item: double>, pair_a: large_list< (... 98 chars omitted)   child 0, columns: large_list<item: large_string>       child 0, item: large_string   child 1, state: large_list<item: double>       child 0, item: double   child 2, pair_a: large_list<item: large_string>       child 0, item: large_string   child 3, pair_b: large_list<item: large_string>       child 0, item: large_string   child 4, pair_value: large_list<item: double>       child 0, item: double

cov_y_y

A column for storing 64-bit floating point numbers.

cov_x_z

A column for storing 64-bit floating point numbers.

cov_y_z

A column for storing 64-bit floating point numbers.

cov_z_z

A column for storing 64-bit floating point numbers.

cov_x_vx

A column for storing 64-bit floating point numbers.

cov_y_vx

A column for storing 64-bit floating point numbers.

cov_z_vx

A column for storing 64-bit floating point numbers.

cov_vx_vx

A column for storing 64-bit floating point numbers.

cov_x_vy

A column for storing 64-bit floating point numbers.

cov_y_vy

A column for storing 64-bit floating point numbers.

cov_z_vy

A column for storing 64-bit floating point numbers.

cov_vx_vy

A column for storing 64-bit floating point numbers.

cov_vy_vy

A column for storing 64-bit floating point numbers.

cov_x_vz

A column for storing 64-bit floating point numbers.

cov_y_vz

A column for storing 64-bit floating point numbers.

cov_z_vz

A column for storing 64-bit floating point numbers.

cov_vx_vz

A column for storing 64-bit floating point numbers.

cov_vy_vz

A column for storing 64-bit floating point numbers.

cov_vz_vz

A column for storing 64-bit floating point numbers.

has_tagged

False on zero-filled placeholder rows where the underlying orbit carried no covariance.

non_grav_cross

6×3 row-major state-to-(A1, A2, A3) cross covariance, 18 values, in the Cartesian basis of the cov_* columns above.

The off-diagonal half of the matrix those columns are the state block of. Null on a row whose orbit declared no Marsden block — never a block of zeros, which would read as a supplied zero correlation.

wide_cross

Cross terms beyond the state+Marsden 9x9 — state↔DT, state↔AMRAT, state↔Δv, and every mixed parameter pair.

Populated on every uncertainty method that produces a joint, including the sampled ones, which recover the state-parameter columns from the propagated cloud. Absence is per-row nulls; see WideCross.row_is_empty().

orbit_ids_unique()

Unique orbit_id values, in first-seen order.

Return type:

list[str]

matrices()

Reshape the lower-tri cov_* columns to (n, 6, 6).

Rows with has_tagged=False come back zero-filled. Works on the full table or a filtered single chain.

Return type:

ndarray

to_series()

Materialize this table as a list of TaggedCovariance.

One entry per row, in table order. Filter to a single chain via select("orbit_id", oid) first to get one orbit’s series.

Return type:

list[TaggedCovariance]