empyrean.ImpactProbabilities

class ImpactProbabilities(table, **kwargs)

Bases: Table

Probabilistic impact assessments tagged by uncertainty method.

One row per (method × orbit × body) close-approach encounter. Mirrors empyrean.propagation.events.PossibleImpacts plus a method column and the Monte-Carlo bookkeeping (sample count, impact count) that’s nullable on the per-encounter table but populated when MC is among the requested methods.

The closest-approach time is carried as an Epochs sub-table (always emitted in TDB) rather than a raw MJD float so consumers can do ips.epochs.to_utc() and get back the same row alignment.

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

agm_components	Number of mixture components used by the adaptive Gaussian-mixture IP refinement.
body	Body name as the canonical Origin string ("Earth" / "Moon" / "asteroid_99942").
distance_hessian	Second derivatives ∂²d/∂x₀ᵢ∂x₀ⱼ of the closest-approach distance — a length-36 row-major flattened 6×6 symmetric matrix per row (same initial-state units as gradient).
effective_radius_au	Body radius inflated for atmospheric capture / gravitational focusing (AU): $R_\mathrm{eff}^2 = R^2(1 + (v_\mathrm{esc}/v_\infty)^2)$.
effective_radius_km	Effective radius in km.
epochs	Closest-approach epoch as an Epochs sub-table (TDB).
gradient	Gradient ∂d/∂x₀ of the closest-approach distance with respect to the initial Cartesian state — a length-6 list per row (position components dimensionless, velocity components in days).
impact_altitude_km	Altitude of the closest-approach point above the reference ellipsoid (km).
impact_latitude_deg	Geodetic latitude of the closest-approach surface point on the body's reference ellipsoid (degrees, north positive).
impact_longitude_deg	Geodetic longitude of the closest-approach surface point (degrees, east positive, [-180, 180]).
ip_agm	Adaptive Gaussian-mixture impact probability.
ip_linear	Linear (Φ Σ Φᵀ-mapped) impact probability.
ip_mc	Monte-Carlo impact probability — mc_n_impacts / mc_n_samples.
ip_second_order	Park-Scheeres second-order Gaussian impact probability.
mc_confidence_interval	Half-width of the 95% binomial (normal-approximation) confidence interval on ip_mc: the interval is ip_mc ± mc_confidence_interval.
mc_n_impacts	Sample count that intersected the effective-radius sphere (MC rows only).
mc_n_samples	Number of virtual-asteroid samples drawn (MC rows only).
mean_distance_second_order_au	Second-order corrected mean miss distance (AU).
method	Uncertainty method that produced this row.
miss_distance_au	Closest-approach geocentric (or body-centric) distance at the nominal trajectory, in AU.
miss_distance_km	Closest-approach distance in km — convenience copy.
nonlinearity	Local nonlinearity diagnostic at the close-approach epoch — a scalar measure of how much the second-order STT contribution would shift the propagated mean relative to the linear map.
object_id	Object metadata label, if carried on the input orbit.
orbit_id	Orbit primary key — matches the input Orbits.orbit_id.
relative_velocity_au_day	Hyperbolic-excess velocity magnitude at the close approach (AU/day).
schema
sigma_distance_au	1σ uncertainty along the miss-distance direction (AU); linearised even for Monte-Carlo rows.
sigma_distance_km	1σ miss-distance uncertainty in km.
sigma_distance_second_order_au	Second-order corrected 1σ miss-distance uncertainty (AU).
skewness	Skewness γ₁ of the miss-distance distribution under the second-order expansion (dimensionless).
table

Parameters:

• table (Table)

• kwargs (AttributeValueType)

method

Uncertainty method that produced this row. One of "first_order" / "second_order" / "sigma_point" / "monte_carlo" / "auto" / "gaussian_mixture".

orbit_id

Orbit primary key — matches the input Orbits.orbit_id.

object_id

Object metadata label, if carried on the input orbit.

body

Body name as the canonical Origin string ("Earth" / "Moon" / "asteroid_99942"). Use Origin.from_string() to lift the column value into a typed Origin.

epochs

Closest-approach epoch as an Epochs sub-table (TDB).

miss_distance_au

Closest-approach geocentric (or body-centric) distance at the nominal trajectory, in AU.

miss_distance_km

Closest-approach distance in km — convenience copy.

effective_radius_au

Body radius inflated for atmospheric capture / gravitational focusing (AU): $R_\mathrm{eff}^2 = R^2(1 + (v_\mathrm{esc}/v_\infty)^2)$. Impact requires the orbit pierce a sphere of this radius.

effective_radius_km

Effective radius in km.

sigma_distance_au

1σ uncertainty along the miss-distance direction (AU); linearised even for Monte-Carlo rows.

sigma_distance_km

1σ miss-distance uncertainty in km.

ip_linear

Linear (Φ Σ Φᵀ-mapped) impact probability. Always populated.

relative_velocity_au_day

Hyperbolic-excess velocity magnitude at the close approach (AU/day). Independent of method.

ip_second_order

Park-Scheeres second-order Gaussian impact probability. Populated when the propagation carried STTs (i.e. method is "second_order" or higher).

nonlinearity

Local nonlinearity diagnostic at the close-approach epoch — a scalar measure of how much the second-order STT contribution would shift the propagated mean relative to the linear map. Populated when STTs are available. Treat qualitatively: large values indicate ip_linear may disagree with sample-based estimates.

ip_agm

Adaptive Gaussian-mixture impact probability. Populated when the requested method enables the AGM refinement ("auto", or an explicit Gaussian-mixture request) AND the encounter’s nonlinearity exceeded the mixture threshold; null otherwise.

Coalescing contract: use ip_agm when finite, otherwise ip_linear. A null here is not a failure — it means the AGM splitter did not fire (the encounter’s nonlinearity was below threshold), so no mixture correction was warranted and the linear estimate on the same row stands. Never back-fill this column with the linear IP: a null is what lets a consumer tell “AGM ran” from “AGM was a no-op”.

ip_mc

Monte-Carlo impact probability — mc_n_impacts / mc_n_samples. Populated only when method = "monte_carlo".

mc_n_samples

Number of virtual-asteroid samples drawn (MC rows only).

mc_n_impacts

Sample count that intersected the effective-radius sphere (MC rows only).

impact_latitude_deg

Geodetic latitude of the closest-approach surface point on the body’s reference ellipsoid (degrees, north positive). Null when no surface projection was available for this encounter (no body-orientation coverage, unmatched close approach, or the body has no registered ellipsoid).

impact_longitude_deg

Geodetic longitude of the closest-approach surface point (degrees, east positive, [-180, 180]). Null when unavailable.

impact_altitude_km

Altitude of the closest-approach point above the reference ellipsoid (km). Null when unavailable.

mc_confidence_interval

Half-width of the 95% binomial (normal-approximation) confidence interval on ip_mc: the interval is ip_mc ± mc_confidence_interval. Null on non-MC rows.

mean_distance_second_order_au

Second-order corrected mean miss distance (AU). On Monte-Carlo rows carries the sample-mean miss distance instead. Null when the producing method computed neither.

sigma_distance_second_order_au

Second-order corrected 1σ miss-distance uncertainty (AU). Null when the producing method carried no second-order derivatives.

skewness

Skewness γ₁ of the miss-distance distribution under the second-order expansion (dimensionless). Null when not computed.

gradient

Gradient ∂d/∂x₀ of the closest-approach distance with respect to the initial Cartesian state — a length-6 list per row (position components dimensionless, velocity components in days). All-zero on Monte-Carlo rows and on degenerate zero-miss encounters.

distance_hessian

Second derivatives ∂²d/∂x₀ᵢ∂x₀ⱼ of the closest-approach distance — a length-36 row-major flattened 6×6 symmetric matrix per row (same initial-state units as gradient). Null when the producing method carried no second-order derivatives.

agm_components

Number of mixture components used by the adaptive Gaussian-mixture IP refinement. Null when the refinement did not run (matches ip_agm null).

schema: ClassVar[Schema] = method: large_string not null orbit_id: large_string not null object_id: large_string body: large_string not null epochs: struct<mjd: double>   child 0, mjd: double miss_distance_au: double not null miss_distance_km: double not null effective_radius_au: double not null effective_radius_km: double not null sigma_distance_au: double not null sigma_distance_km: double not null ip_linear: double not null relative_velocity_au_day: double not null ip_second_order: double nonlinearity: double ip_agm: double ip_mc: double mc_n_samples: uint64 mc_n_impacts: uint64 impact_latitude_deg: double impact_longitude_deg: double impact_altitude_km: double mc_confidence_interval: double mean_distance_second_order_au: double sigma_distance_second_order_au: double skewness: double gradient: large_list<item: double> not null   child 0, item: double distance_hessian: large_list<item: double>   child 0, item: double agm_components: uint64