empyrean.StateSensitivities

class StateSensitivities(table, **kwargs)[source]

Bases: Table

Per-(orbit, epoch) state-transition matrices and tensors.

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 accessors:

chain = sens.select("orbit_id", "2020 CD3")
phi = chain.stms_array()[chain.index_at(60750.0)]

Notes

Matrices are stored row-major flattened in LargeListColumn s:

  • stm is the 6×6 STM Φ flattened to length 36 (stm[6·r + c] = Φ[r, c]). None per row when STMs were not computed for that row.

  • stt is the 6×6×6 STT Ψ flattened to length 216 (stt[36·k + 6·a + b] = Ψ[k, a, b]). None when the propagation method did not carry STTs (anything other than UncertaintyMethod.SECOND_ORDER).

The accessors below operate on whatever rows are present — typically a single chain after select("orbit_id", oid), but work on the full table too when shapes are uniform.

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.

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.

kappa(cov_in, *[, i])

Jet2 nonlinearity diagnostic κ.

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.

propagate_covariance(cov_in, *[, i, order])

Forward-propagate a covariance through the chain.

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).

stms_array()

Reshape stm to (n_t, 6, 6).

stts_array()

Reshape stt to (n_t, 6, 6, 6).

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

Output epoch (MJD TDB).

object_id

Object metadata label, if carried on the input orbit.

orbit_id

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

resolved_kind

Resolved covariance kind at this output epoch (CovarianceKind value: linear / second_order / …), or None if the propagation did not resolve a covariance for this row.

schema

stm

Row-major flattened 6×6 STM (length 36 per row), or None.

stt

Row-major flattened 6×6×6 STT (length 216 per row), or None.

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).

stm

Row-major flattened 6×6 STM (length 36 per row), or None.

stt

Row-major flattened 6×6×6 STT (length 216 per row), or None.

resolved_kind

Resolved covariance kind at this output epoch (CovarianceKind value: linear / second_order / …), or None if the propagation did not resolve a covariance for this row.

orbit_ids_unique()[source]

Unique orbit_id values, in first-seen order.

Return type:

list[str]

stms_array()[source]

Reshape stm to (n_t, 6, 6).

Returns None when every row has a null STM. Null rows within an otherwise-populated chain are filled with NaN. Raises ValueError if the table holds more than one unique orbit_id — filter via select first.

Return type:

ndarray | None

stts_array()[source]

Reshape stt to (n_t, 6, 6, 6).

Returns None when every row has a null STT. Raises ValueError if the table holds more than one unique orbit_id — filter via select first.

Return type:

ndarray | None

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

Row index at the given epoch.

epoch is converted to MJD TDB and matched within atol. Raises ValueError if no row matches, or if the table holds more than one unique orbit_id — filter via select first.

Return type:

int

Parameters:
up_to(epoch)[source]

Subset including rows with epoch_mjd_tdb ≤ the target.

Return type:

StateSensitivities

Parameters:

epoch (float | str | datetime | Epochs)

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

Forward-propagate a covariance through the chain.

Filter to a single chain via select("orbit_id", oid) first — this method assumes the chain’s STMs share a common t₀.

Parameters:

  • cov_in (ndarray) – Input 6×6 covariance at the chain’s start epoch.

  • i (int | None) – Row index to evaluate at. None (default) returns the covariance at every chain epoch, shape (n_t, 6, 6).

  • order (Literal[1, 2, 'auto']) – 1: linear (Σ = Φ Σ_0 Φᵀ, Δμ = 0). 2: Jet2 second-order Gaussian correction (requires STTs). "auto": order 2 when STTs are present, else order 1.

Return type:

tuple[ndarray, ndarray]

Returns:

(cov_out, delta_mu) ((np.ndarray, np.ndarray)) – (6, 6) / (6,) for scalar i; (n_t, 6, 6) / (n_t, 6) for i=None.

kappa(cov_in, *, i=None)[source]

Jet2 nonlinearity diagnostic κ.

Approximates the departure of the true distribution from a Gaussian centered at the nominal state. Small κ (≲ 0.1) means first-order covariance is adequate; larger κ warrants Jet2 SOG or Gaussian-mixture splitting. Requires STTs. Filter to one chain first.

Return type:

float | ndarray

Parameters:
schema: ClassVar[Schema] = orbit_id: large_string not null object_id: large_string epoch_mjd_tdb: double not null stm: large_list<item: double>   child 0, item: double stt: large_list<item: double>   child 0, item: double resolved_kind: large_string