empyrean.Observers

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

Bases: Table

Precomputed observer states as Cartesian coordinates.

Each row is one MPC observatory at one epoch. The kinematic state lives inside a nested CartesianCoordinates table — same schema as orbit positions — so frame and origin are explicit and consistent with the rest of the API. By default that’s Frame.ICRF and Origin.SSB — the construction basis, and the one every downstream consumer (ephemeris generation, orbit determination) requires. Pass frame / origin to from_code() / from_codes() to get the states in another basis instead, for geometry work that wants one (e.g. heliocentric ecliptic site positions).

Construct via from_code() (single observatory, N epochs) or from_codes() (cartesian product of N observatories × M epochs). The top-level shortcut empyrean.get_observer_states() is the same as from_codes().

observing_night is the YYYYMMDD local calendar date on which the observing night began, or null when unavailable (space-based observers, or a site without a longitude): the UTC epoch is shifted by the site’s east longitude to local mean solar time, and epochs before local noon stamp the previous date. MPC east-of-Greenwich longitudes in [0, 360) are wrapped to signed [-180, 180] before the fold, so a site west of Greenwich (e.g. 289°E in Chile) shifts by −71°, not +19 hours.

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_code(obs_code, epochs[, frame, origin])

Observer states for a single observatory at N epochs.

from_codes(obs_codes, epochs[, frame, origin])

Observer states for the cartesian product of N observatory codes × M epochs.

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

coordinates

A column which represents an embedded quivr table.

obs_code

A column for storing large strings (over 231 bytes long).

observing_night

A column for storing 32-bit integers.

schema

table

Parameters:

  • table (Table)

  • kwargs (AttributeValueType)

obs_code

A column for storing large strings (over 231 bytes long). Large string data is stored in variable-length chunks.

coordinates

A column which represents an embedded quivr table.

Parameters:

  • table_type – The type of the table to embed.

  • nullable – Whether the column can contain null values.

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

observing_night

A column for storing 32-bit integers.

classmethod from_code(obs_code, epochs, frame=Frame.ICRF, origin=Origin(name='SSB'))[source]

Observer states for a single observatory at N epochs.

Returns an N-row table, one row per epoch.

Parameters:

  • obs_code (str) – MPC observatory code (e.g. "W84", "F51", "274").

  • epochs (Epochs) – N observation epochs, converted to TDB internally. Build one with Epochs.from_mjd(values, scale="tdb") (or scale="utc"); a bare array is refused, as it carries no time scale.

  • frame (Frame | str | int) – Reference frame for the returned states. Default Frame.ICRF. See from_codes().

  • origin (Origin | str | int) – Body the states are relative to. Default Origin.SSB. See from_codes().

Return type:

Observers

Returns:

Observers – Length-N table — row i is the observer at epochs[i].

Examples

>>> times = Epochs.from_mjd([60500.0, 60501.0], scale="tdb")
>>> obs = Observers.from_code("W84", times)
>>> len(obs)
2
classmethod from_codes(obs_codes, epochs, frame=Frame.ICRF, origin=Origin(name='SSB'))[source]

Observer states for the cartesian product of N observatory codes × M epochs.

Returns an N * M-row table in code-major order: all M epochs for obs_codes[0], then all M epochs for obs_codes[1], and so on. Indexing into the result is therefore i * M + j for the (code i, epoch j) row.

Parameters:

  • obs_codes (Sequence[str]) – N MPC observatory codes.

  • epochs (Epochs) – M observation epochs, converted to TDB internally. Build one with Epochs.from_mjd(values, scale="tdb") (or scale="utc"); a bare array is refused, as it carries no time scale.

  • frame (Frame | str | int) – Reference frame for the returned states. Default Frame.ICRF.

  • origin (Origin | str | int) – Body the states are relative to. Default Origin.SSB.

Return type:

Observers

Notes

(Frame.ICRF, Origin.SSB) is the construction basis — the one ephemeris generation and orbit determination require, and the one to keep when the observers are headed there. Requesting it takes no transform at all: the states come back exactly as constructed, bit for bit. Any other basis rotates and/or translates them, which is what a consumer plotting observer geometry wants (e.g. heliocentric ecliptic site positions via frame=Frame.ECLIPTICJ2000, origin=Origin.SUN).

The frame / origin stamped on the returned table are read off the states the engine returned, not echoed from the request, so a table always reports the basis that actually produced it.

Return type:

Observers

Returns:

Observers – N * M-row table, code-major.

Parameters:

Examples

>>> times = Epochs.from_mjd([60000.0, 60001.0], scale="tdb")
>>> obs = Observers.from_codes(["W84", "F51", "274"], times)
>>> len(obs)
6
>>> obs.obs_code.to_pylist()
['W84', 'W84', 'F51', 'F51', '274', '274']
schema: ClassVar[Schema] = obs_code: large_string not null coordinates: struct<epoch: double, x: double, y: double, z: double, vx: double, vy: double, vz: double, covarianc (... 410 chars omitted)   child 0, epoch: double   child 1, x: double   child 2, y: double   child 3, z: double   child 4, vx: double   child 5, vy: double   child 6, vz: double   child 7, covariance: struct<cov_x_x: double, cov_x_y: double, cov_y_y: double, cov_x_z: double, cov_y_z: double, cov_z_z: (... 284 chars omitted)       child 0, cov_x_x: double       child 1, cov_x_y: double       child 2, cov_y_y: double       child 3, cov_x_z: double       child 4, cov_y_z: double       child 5, cov_z_z: double       child 6, cov_x_vx: double       child 7, cov_y_vx: double       child 8, cov_z_vx: double       child 9, cov_vx_vx: double       child 10, cov_x_vy: double       child 11, cov_y_vy: double       child 12, cov_z_vy: double       child 13, cov_vx_vy: double       child 14, cov_vy_vy: double       child 15, cov_x_vz: double       child 16, cov_y_vz: double       child 17, cov_z_vz: double       child 18, cov_vx_vz: double       child 19, cov_vy_vz: double       child 20, cov_vz_vz: double   child 8, origin: large_string observing_night: int32