empyrean.WideCross

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

Bases: Table

Row-aligned cross-covariance terms beyond the state+Marsden 9x9.

Attached to each orbit table as a nullable sub-table column, so every existing table and round trip is unchanged: an orbit with no cross terms carries nulls in these columns.

Storage follows the package’s existing variable-width idiom (see ObservationSensitivities): flat LargeListColumn payloads with the width recoverable from the data. Here the width IS len(columns) and every entry is self-identifying, so no companion width column is carried — a second source of truth for a number already in the data. Rows may differ in width freely, because nothing indexes across them.

Absence

A nullable sub-table column is never None — quivr returns a table of parent length regardless — so absence is per-row nulls, not a null sub-table. Test row_is_empty or the per-row accessors, never orbits.wide_cross is None.

A supplied entry whose six values are all zero is a supplied zero correlation, not an absence: it engages the engine’s definiteness gate. To mean absent, omit the entry.

Cross terms travel with the blocks they condition

A cross term is one half of a matrix whose other half is a parameter block, and the engine refuses the half without the whole: a state-Marsden border supplied on an orbit carrying no non-grav covariance is an error, not an ignored field. The same holds for the carrier’s columns — a state-DT column needs the DT prior variance, a state-AMRAT column needs the SRP AMRAT prior variance.

This matters when chaining a propagation. A propagated state carries the propagated cross terms but not the parameter blocks, which propagation passes through unchanged rather than restating on every output row, so a second leg is assembled from the output row plus the parameter blocks of the orbit that started the chain.

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_entries(state_cross, param_cross)

Build a table from per-row dicts, nulling rows that carry nothing.

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.

param_cross(i)

Row i's parameter-parameter terms, keyed by (a, b).

row_is_empty(i)

Whether row i carries no cross terms at all.

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

state_cross(i)

Row i's state-parameter columns, keyed by parameter tag.

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

columns

A column for storing large lists of values (over 231 objects).

pair_a

A column for storing large lists of values (over 231 objects).

pair_b

A column for storing large lists of values (over 231 objects).

pair_value

A column for storing large lists of values (over 231 objects).

schema

state

A column for storing large lists of values (over 231 objects).

table

columns

A column for storing large lists of values (over 231 objects).

Unless you need to represent data with more than 2**31 elements, prefer ListColumn.

The values in the list can be of any type.

Note that all quivr Tables are storing lists of values, so this column type is only useful for storing lists of lists.

Parameters:

  • value_type – The type of the values in the list.

  • nullable – Whether the list can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

  • validator – A validator to run against the column’s values.

state

A column for storing large lists of values (over 231 objects).

Unless you need to represent data with more than 2**31 elements, prefer ListColumn.

The values in the list can be of any type.

Note that all quivr Tables are storing lists of values, so this column type is only useful for storing lists of lists.

Parameters:

  • value_type – The type of the values in the list.

  • nullable – Whether the list can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

  • validator – A validator to run against the column’s values.

pair_a

A column for storing large lists of values (over 231 objects).

Unless you need to represent data with more than 2**31 elements, prefer ListColumn.

The values in the list can be of any type.

Note that all quivr Tables are storing lists of values, so this column type is only useful for storing lists of lists.

Parameters:

  • value_type – The type of the values in the list.

  • nullable – Whether the list can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

  • validator – A validator to run against the column’s values.

pair_b

A column for storing large lists of values (over 231 objects).

Unless you need to represent data with more than 2**31 elements, prefer ListColumn.

The values in the list can be of any type.

Note that all quivr Tables are storing lists of values, so this column type is only useful for storing lists of lists.

Parameters:

  • value_type – The type of the values in the list.

  • nullable – Whether the list can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

  • validator – A validator to run against the column’s values.

pair_value

A column for storing large lists of values (over 231 objects).

Unless you need to represent data with more than 2**31 elements, prefer ListColumn.

The values in the list can be of any type.

Note that all quivr Tables are storing lists of values, so this column type is only useful for storing lists of lists.

Parameters:

  • value_type – The type of the values in the list.

  • nullable – Whether the list can contain null values.

  • metadata – A dictionary of metadata to attach to the column.

  • validator – A validator to run against the column’s values.

row_is_empty(i)[source]

Whether row i carries no cross terms at all.

The per-row absence test. WideCross itself is never None on a parent table, so this is what “this orbit has no joint” looks like.

Return type:

bool

Parameters:

i (int)

state_cross(i)[source]

Row i’s state-parameter columns, keyed by parameter tag.

Each value is the 6-vector of covariances between the six state elements and that parameter, in the coordinate’s own element order and units. Returns an empty dict when the row carries none.

Reshaping accessor for the flat state payload — the same shape ObservationSensitivities.jacobians_array() provides for its flat matrices, minus the homogeneity guard: identity tags let rows differ in width, because nothing indexes across them.

Return type:

dict[str, NDArray[double]]

Parameters:

i (int)

param_cross(i)[source]

Row i’s parameter-parameter terms, keyed by (a, b).

The key is canonicalized so (a, b) and (b, a) are one entry — the term is symmetric, and carrying it twice would be two numbers for one covariance.

Return type:

dict[tuple[str, str], float]

Parameters:

i (int)

classmethod from_entries(state_cross, param_cross)[source]

Build a table from per-row dicts, nulling rows that carry nothing.

state_cross[i] maps a parameter tag to that row’s 6-vector; param_cross[i] maps a canonical (a, b) pair to its value. Either may be None or empty for a row with no cross terms, which is written as nulls rather than as empty lists — empty lists would read as “supplied, and empty”.

Return type:

WideCross

Parameters:
schema: ClassVar[Schema] = columns: large_list<item: large_string>   child 0, item: large_string state: large_list<item: double>   child 0, item: double pair_a: large_list<item: large_string>   child 0, item: large_string pair_b: large_list<item: large_string>   child 0, item: large_string pair_value: large_list<item: double>   child 0, item: double
Parameters:

  • table (Table)

  • kwargs (AttributeValueType)