empyrean.PlanMetrics

class PlanMetrics(table, **kwargs)

Bases: Table

Covariance summary metrics bracketing the campaign — two rows.

Mirrors empyrean::CovarianceMetrics, once for the state before any candidate is folded and once for the state after every candidate the engine could fold — including any reported unobservable, since the fold does not consult PlanCandidates.observable. The stage column carries which is which, so the pair can be filtered, joined, or concatenated across plans without unpacking a scalar object; prior() and posterior() are the one-row views.

The per-candidate running totals are the cumulative_* columns on PlanCandidates, which carry the same five quantities after each observation is folded.

The 1σ position ellipsoid has three axes but only the longest and shortest are carried. Recover the intermediate one from the identity that the three semi-axes are the square roots of the position block’s eigenvalues, whose sum is position_sigma_km squared:

b = math.sqrt(max(position_sigma_km**2 - semi_major_km**2 - semi_minor_km**2, 0.0))

The clamp guards the rounding case where the three squares sum a hair past the total.

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.
null_mask()	Return a boolean mask indicating which rows of the entire table are null.
nulls(size, **kwargs)	Create a table with nulls.
posterior()	The "posterior" row — the covariance after every candidate has been folded.
prior()	The "prior" row — the covariance before any candidate.
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.
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

log_det	$\ln \det \Sigma$ over the 6×6 state covariance — the D-optimality criterion.
position_sigma_km	RSS position 1σ (km).
schema
semi_major_km	Semi-major axis of the 1σ position ellipsoid (km).
semi_minor_km	Semi-minor axis of the 1σ position ellipsoid (km).
stage	Which end of the campaign this row describes — "prior" (before any candidate) or "posterior" (after all of them).
velocity_sigma_m_s	RSS velocity 1σ (m/s) at the orbit epoch.
table

Parameters:

• table (Table)

• kwargs (AttributeValueType)

stage

Which end of the campaign this row describes — "prior" (before any candidate) or "posterior" (after all of them).

position_sigma_km

RSS position 1σ (km).

velocity_sigma_m_s

RSS velocity 1σ (m/s) at the orbit epoch.

semi_major_km

Semi-major axis of the 1σ position ellipsoid (km).

semi_minor_km

Semi-minor axis of the 1σ position ellipsoid (km).

log_det

$\ln \det \Sigma$ over the 6×6 state covariance — the D-optimality criterion.

In AU and AU·day⁻¹, unlike the four columns above, which are rescaled to km and m/s. A log-determinant is dimensional, so the absolute value depends on that choice: the same covariance expressed in km and m/s gives a value larger by $6\ln(\mathrm{km/AU}) + 6\ln(\mathrm{(m/s)/(AU/day)}) \approx 199.13$. Differences between two log_det values on this surface are unit-invariant and can be compared directly.

prior()

The "prior" row — the covariance before any candidate.

Return type:

PlanMetrics

schema: ClassVar[Schema] = stage: large_string not null position_sigma_km: double not null velocity_sigma_m_s: double not null semi_major_km: double not null semi_minor_km: double not null log_det: double not null

posterior()

The "posterior" row — the covariance after every candidate has been folded.

Return type:

PlanMetrics